|
2 | 2 |
|
3 | 3 | Reusable React components and interactive interface patterns for TypeSafe AI projects, built with shadcn/ui, Base UI, and Tailwind CSS. |
4 | 4 |
|
5 | | -**Small parts. Clear interfaces.** An independent community project maintained under `TypeSafeAI`, not an official TypeSafe AI component library or SDK. |
| 5 | +**Small parts. Clear interfaces.** This is an independent community project under `TypeSafeAI`, not an official TypeSafe AI component library or SDK. The community organization was created by VC Moderator [@BunsDev](https://github.com/BunsDev). |
6 | 6 |
|
7 | | -[Contributing](CONTRIBUTING.md) · [Agent guide](AGENTS.md) · [TypeSafe API documentation](https://docs.typesafe.ai/api) |
| 7 | +[Developer guide](docs/discovery/README.md) · [Contributing](CONTRIBUTING.md) · [Agent instructions](AGENTS.md) · [Jev Labs](docs/jev-labs.md) · [Official API documentation](https://docs.typesafe.ai/introduction/quickstart) |
8 | 8 |
|
9 | | -## What this repository provides |
| 9 | + |
10 | 10 |
|
11 | | -A Turborepo + pnpm workspace with a Next.js component browser, source previews, install/import examples, and an interactive Lab. The UI uses the shadcn `base-nova` style, Base UI primitives, Tailwind v4, and RTL-aware components. |
| 11 | +## What is here |
12 | 12 |
|
13 | | -The site pairs an original optical-glass photographic introduction with an OpenCoven-inspired workspace: a sticky topbar, grouped component rail, per-component Preview/Source and Install/Import tabs, and an “On this page” outline. Its TypeSafe-inspired theme uses pink primary, teal live-state accents, dark mode by default, IBM Plex typography, a dot-grid background, and softly illuminated preview surfaces. |
| 13 | +A Turborepo and pnpm workspace with a Next.js component browser, source previews, install/import examples, and an interactive Lab. It uses the shadcn `base-nova` style, Base UI primitives, Tailwind v4, and RTL-aware components. The interface supports light/dark themes and TypeSafe-inspired pink/teal styling. |
14 | 14 |
|
15 | | -`@workspace/ui` is a **private workspace package**, not a published npm package. The imports below work inside this monorepo. For another application, deliberately port the components, styles, dependencies, and aliases you need; do not assume `npm install typesafe-ui` or a hosted registry exists. A visual “live” state is not proof of a real Jev API call. |
| 15 | +`@workspace/ui` is a **private workspace package**, not a published npm package. Imports work inside this monorepo. For another application, deliberately port the components, styles, dependencies, and aliases you need; do not assume `npm install typesafe-ui` or a hosted registry exists. |
16 | 16 |
|
17 | | -## Getting started |
| 17 | +The Jev Labs guide describes the upstream catalog examples, workspace scenarios, and interface patterns. Outputs in these previews are local fixtures. A visual live-state indicator is not proof of a Jev API call. |
18 | 18 |
|
19 | | -Use the pnpm version pinned in [package.json](package.json), currently `10.33.4`. The root manifest declares Node.js `>=20`; use a Node version supported by the checked-in Next.js dependency as well. Node.js 22+ is a practical development baseline. |
| 19 | +## Run locally |
| 20 | + |
| 21 | +Use the exact pnpm version declared in [package.json](package.json). The manifest declares Node.js `>=20`; use a version supported by the checked-in Next.js dependency as well. Node.js 22+ is a practical development baseline. |
20 | 22 |
|
21 | 23 | ```sh |
22 | 24 | git clone https://github.com/TypeSafeAI/typesafe-ui.git |
23 | 25 | cd typesafe-ui |
24 | | -# Install/activate the pnpm version declared in package.json. |
25 | | -# Where Corepack is installed, `corepack enable` enables its package-manager shims. |
| 26 | +# Activate the pnpm version declared in package.json. |
| 27 | +# Corepack can enable package-manager shims where it is installed. |
26 | 28 | pnpm install --frozen-lockfile |
27 | 29 | pnpm dev |
28 | 30 | ``` |
29 | 31 |
|
30 | | -The [Jev Labs guide](docs/jev-labs.md) covers 169 local examples: all 110 upstream catalog examples, 56 workspace scenarios, and three interface patterns. Labs share the library’s sidebar, source inspection, and installation/import workflow. All outputs are explicitly local fixtures. |
31 | | - |
32 | | -Open the address printed by the development server, normally `http://localhost:3000`. The library is at `/`, and interactive scenes are at `/lab`. Press `d` to toggle dark mode and `⌘K` to search components. |
| 32 | +Open the address printed by the development server, normally `http://localhost:3000`. The library is at `/` and the interactive scenes are at `/lab`. Press `d` to toggle dark mode and `Cmd+K` to search components. No provider credentials are needed to browse local fixtures. |
33 | 33 |
|
34 | 34 | | Command | Purpose | |
35 | 35 | | --- | --- | |
36 | | -| `pnpm dev` | Run the web application through Turborepo. | |
37 | | -| `pnpm build` | Build the workspace. | |
38 | | -| `pnpm lint` | Run workspace lint tasks. | |
39 | | -| `pnpm typecheck` | Run workspace TypeScript checks. | |
40 | | -| `pnpm test:e2e` | Run Playwright browser checks for the catalog, Lab, navigation, themes, and motion. | |
41 | | -| `pnpm format` | Format source files; this writes changes. | |
| 36 | +| `pnpm dev` | Run the web application through Turborepo | |
| 37 | +| `pnpm build` | Build the workspace | |
| 38 | +| `pnpm lint` | Run workspace lint tasks | |
| 39 | +| `pnpm typecheck` | Run workspace TypeScript checks | |
| 40 | +| `pnpm test:e2e` | Run Playwright browser checks | |
| 41 | +| `node --test scripts/social-metadata.test.mjs` | Check sharing-source invariants without installing dependencies | |
| 42 | +| `pnpm format` | Format source files; this writes changes | |
42 | 43 |
|
43 | | -There is no root unit-test script. `pnpm test:e2e` runs the checked-in Playwright suite (local Google Chrome; bundled Chromium in CI). Browser checks complement visual and keyboard inspection; they do not prove accessibility. |
| 44 | +There is no root `pnpm test` script. The E2E suite uses local Google Chrome, or bundled Chromium in CI. Source checks do not prove that a deployed image loads, and browser automation does not establish complete accessibility. |
44 | 45 |
|
45 | | -## Layout |
| 46 | +## Project map |
46 | 47 |
|
47 | 48 | ```text |
48 | 49 | apps/web/ |
49 | | - app/ Next.js routes, layout, fonts, and metadata |
50 | | - components/ Site shell, component cards, demos, and Lab scenes |
51 | | - lib/ Site config, component registry, source loader, and shiki |
| 50 | + app/ routes, layout, fonts, and social metadata |
| 51 | + components/ shell, component cards, previews, and Lab scenes |
| 52 | + lib/ site configuration, registries, source loader, and shiki |
52 | 53 | packages/ |
53 | | - ui/ @workspace/ui: components, hooks, utilities, and styles |
54 | | - eslint-config/ Shared lint configuration |
55 | | - typescript-config/ Shared TypeScript configuration |
| 54 | + ui/ @workspace/ui components, hooks, utilities, and styles |
| 55 | + eslint-config/ shared lint configuration |
| 56 | + typescript-config/ shared TypeScript configuration |
56 | 57 | ``` |
57 | 58 |
|
58 | | -## Adding a component |
| 59 | +## Add a component or lab |
59 | 60 |
|
60 | | -1. Add a component against the web app. The existing shadcn configuration places reusable components in `packages/ui/src/components`. |
| 61 | +1. Add a component against the web app; the shadcn configuration places reusable components in `packages/ui/src/components`. |
61 | 62 |
|
62 | 63 | ```sh |
63 | 64 | pnpm dlx shadcn@latest add popover -c apps/web |
64 | 65 | ``` |
65 | 66 |
|
66 | | - This is a generator operation that can change source and dependencies. Review its diff and the lockfile rather than treating it as a read-only command. |
| 67 | + This is a generator operation that can modify source and dependencies. Review its complete diff and lockfile changes; it is not a read-only command. |
67 | 68 |
|
68 | | -2. Register the component in `apps/web/lib/registry.ts`: id, title, group, description, exports, and supported states. |
69 | | -3. Add a demo using the same id in `apps/web/components/demos.tsx`. |
70 | | -4. Verify its preview, source, import example, keyboard behavior, themes, narrow layout, and RTL behavior. |
| 69 | +2. Register the component in `apps/web/lib/registry.ts` with its ID, group, description, exports, and supported states. |
| 70 | +3. Add its demo using the same ID in `apps/web/components/demos.tsx`. |
| 71 | +4. Verify preview, displayed source, imports, keyboard behavior, themes, narrow layout, and RTL. |
71 | 72 |
|
72 | | -The library reads component source from disk at build time and highlights it with shiki. Keep registry ids, exported paths, source paths, and demos aligned. |
| 73 | +For a Jev Lab, follow [the Lab guide](docs/jev-labs.md) and preserve upstream IDs, declared A/B differences, local-fixture labels, and attribution. The library reads component source at build time and highlights it with shiki; keep registry IDs, source paths, exports, and demos aligned. |
73 | 74 |
|
74 | | -## Using components |
| 75 | +## Use components |
75 | 76 |
|
76 | 77 | ```tsx |
77 | 78 | import { Button } from "@workspace/ui/components/button" |
78 | 79 | ``` |
79 | 80 |
|
80 | | -Base UI triggers compose through the `render` prop rather than Radix-style `asChild`. A `Button` rendered as a link needs `nativeButton={false}`. Keep provider credentials and application-specific network clients out of reusable client components. |
| 81 | +Base UI triggers compose through `render`, rather than Radix-style `asChild`. A Button rendered as a link needs `nativeButton={false}`. Keep provider credentials and application-specific network clients out of reusable client components. |
| 82 | + |
| 83 | +## Themes and RTL |
| 84 | + |
| 85 | +Tokens live in `packages/ui/src/styles/globals.css`: light values in `:root` and dark values in `.dark`. TypeSafe-oriented tokens include `--teal`, `--success`, `--warning`, and `--dot`. Fonts are wired through `next/font` in `apps/web/app/layout.tsx` and exposed as `--font-sans` and `--font-mono`. |
| 86 | + |
| 87 | +Site identity, links, navigation, language, and direction live in `apps/web/lib/site.ts`. The shadcn configuration has `rtl: true`. Set `dir` and `lang` deliberately for a locale, preserve DirectionProvider, and prefer logical CSS properties. |
81 | 88 |
|
82 | | -## Theming and RTL |
| 89 | +## Sharing and screenshots |
83 | 90 |
|
84 | | -Tokens live in `packages/ui/src/styles/globals.css`: light values in `:root`, dark values in `.dark`. TypeSafe-oriented tokens include `--teal`, `--success`, `--warning`, and `--dot`. Fonts are wired through `next/font` in `apps/web/app/layout.tsx` and exposed as `--font-sans` and `--font-mono`. |
| 91 | +`apps/web/app/opengraph-image.tsx` renders a public editorial PNG. Twitter metadata uses the same route. Verify the rendered tags and image response after building and deploying; do not claim production publication from a source diff alone. The SVG shown above is editable artwork, not an application screenshot. |
85 | 92 |
|
86 | | -Site name, tagline, links, navigation, language, and direction live in `apps/web/lib/site.ts`. The shadcn configuration has `"rtl": true`. Set `dir` to `"rtl"` and `lang` to the intended locale to update the root layout and `DirectionProvider`. Prefer logical CSS properties so components work in both directions. |
| 93 | +The [developer guide](docs/discovery/README.md) links publishing and screenshot protocols. Use synthetic local previews, keep fixture labels visible, and record the source revision, viewport, theme, direction, and capture environment. Review media for private data. `repository-metadata.json` documents proposed About text/topics; it does not apply GitHub settings. |
87 | 94 |
|
88 | 95 | ## Related community projects |
89 | 96 |
|
90 | 97 | | Repository | Role | |
91 | 98 | | --- | --- | |
92 | | -| [typesafe-ai-playground](https://github.com/BunsDev/typesafe-ai-playground) | Interactive Jev experiments and integration demos. | |
93 | | -| [clarity-judge](https://github.com/BunsDev/clarity-judge) | Separate, named writing-quality checks. | |
94 | | -| [typesafe-router](https://github.com/BunsDev/typesafe-router) | Closed-set tool and model routing, separate from execution. | |
95 | | -| [typesafe-ui](https://github.com/TypeSafeAI/typesafe-ui) | Reusable components and interface patterns. | |
| 99 | +| [typesafe-playground](https://github.com/TypeSafeAI/typesafe-playground) | Interactive Jev experiments and integration demos | |
| 100 | +| [clarity-judge](https://github.com/TypeSafeAI/clarity-judge) | Separate named writing-quality checks | |
| 101 | +| [typesafe-router](https://github.com/TypeSafeAI/typesafe-router) | Closed-set selection, separate from authorization and execution | |
| 102 | +| [jev-harness](https://github.com/TypeSafeAI/jev-harness) | Proposal-review evidence and synthetic fixtures | |
96 | 103 |
|
97 | | -These are separate repositories, not an automatically integrated or officially supported product suite. The proposed GitHub description and discovery topics are recorded in [repository-metadata.json](repository-metadata.json); that file does not change GitHub settings automatically. |
| 104 | +These are independent community projects, not an automatically integrated or officially supported suite. Preserve shadcn/ui and Base UI attribution, TypeSafe-inspired branding, the OpenCoven layout inspiration, and existing source/license notices. Review the applicable licenses before reusing code; this change does not alter licensing. |
0 commit comments