# ui

Shared web primitives: responsibilities, supported exports and extension points.

## Purpose [#purpose]

The web component library puts the shadcn API, with the repository’s neutral tokens, over [ui-sdk](https://ui-sdk.dev) (`@ui-sdk/react` and `@ui-sdk/core`), which supplies keyboard, focus, popups and ARIA. It includes buttons, dialogs, sidebar, tables, command, code blocks and the shared runtime highlighter. Docs use build-time highlighting instead.

Shadcn `trace` and `code-block` components support execution details and code displays. The public ReUI registry adds free `time-picker`, `color-picker`, `signature-pad`, `file-type`, `emoji-picker` and `cascader` components. These are installed source files in this package. Pro blocks require a license and are not included. See the [ReUI registry](https://reui.io/docs/registry) for access rules.

EmojiPicker fetches `emojibase-data@17.0.0` from jsDelivr by default; pass local `data` when external loading is unwanted. Fumadocs is confined to `/docs`, with headless source/search and build-time MDX. It does not replace application components or install `fumadocs-ui`.

## Public exports [#public-exports]

| Subpath | Target |
| --- | --- |
| `./globals.css` | `./src/styles/globals.css` |
| `./lib/*` | `./src/lib/*.ts` |
| `./lib/highlighter` | `./src/lib/highlighter.tsx` |
| `./components/*` | `./src/components/*.tsx` |
| `./components/reui/*` | `./src/components/reui/*.tsx` |
| `./components/reui/time-picker` | `./src/components/reui/time-picker.tsx` |
| `./components/reui/color-picker` | `./src/components/reui/color-picker.tsx` |
| `./components/reui/signature-pad` | `./src/components/reui/signature-pad.tsx` |
| `./components/reui/file-type` | `./src/components/reui/file-type.tsx` |
| `./components/reui/emoji-picker` | `./src/components/reui/emoji-picker.tsx` |
| `./components/reui/cascader/cascader` | `./src/components/reui/cascader/cascader.tsx` |
| `./components/reui/cascader/cascader-async` | `./src/components/reui/cascader/cascader-async.tsx` |
| `./components/reui/cascader/cascader-columns` | `./src/components/reui/cascader/cascader-columns.tsx` |
| `./components/reui/cascader/cascader-context` | `./src/components/reui/cascader/cascader-context.tsx` |
| `./components/reui/cascader/cascader-footer` | `./src/components/reui/cascader/cascader-footer.tsx` |
| `./components/reui/cascader/cascader-i18n` | `./src/components/reui/cascader/cascader-i18n.tsx` |
| `./components/reui/cascader/cascader-item` | `./src/components/reui/cascader/cascader-item.tsx` |
| `./components/reui/cascader/cascader-lib` | `./src/components/reui/cascader/cascader-lib.tsx` |
| `./components/reui/cascader/cascader-nav` | `./src/components/reui/cascader/cascader-nav.tsx` |
| `./components/reui/cascader/cascader-types` | `./src/components/reui/cascader/cascader-types.tsx` |
| `./components/reui/cascader/cascader-virtual` | `./src/components/reui/cascader/cascader-virtual.tsx` |
| `./hooks/*` | `./src/hooks/*.ts` |
| `./postcss.config` | `./postcss.config.mjs` |

These paths come from `packages/ui/package.json`. A `.` entry is the package root. Conditional targets distinguish platform or type resolution; consumers should import the subpath, not its source file.

## How to extend [#how-to-extend]

Reuse an existing primitive before adding one. A component ui-sdk ships that is missing here gets a wrapper on its ui-sdk entry, built like the others; only this package imports `@ui-sdk/*`. `lib/agent` re-exports ui-sdk's `createAgent` and `registerTools`, for the agent tests of web screens and the one [agent on the live page](/docs/development/design#agent-on-the-live-page). Each wrapper ported from another library keeps its shadcn or ReUI props and adapts them to ui-sdk's model in the wrapper (cmdk's `shouldFilter`, react-day-picker's `mode`/`selected`/`disabled`, embla's `opts` and `setApi`, react-resizable-panels' sizes and layouts, headless-tree's `tree`), and has a `*.agent.test.tsx` beside it that finds it in `createAgent().snapshot()` and checks an agent's change; `src/test-setup.ts` loads ui-sdk's jsdom stubs and strict mode for every test here. See [Build a screen with ui-sdk](/docs/development/design#build-a-screen-with-ui-sdk). Put feature data, effects and navigation in application hooks. Preserve accessible labels, keyboard behavior and visible focus. Existing component/lib export patterns are local to this UI package; they do not permit server barrels.

Read the [shared web primitives guide](/docs/development/conventions) for the full flow.

## Key files [#key-files]

- [`packages/ui/package.json`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/packages/ui/package.json)
