@k8ordo/ui 1.0.0 → 2.1.0

package/README.md

@@ -1,8 +1,13 @@
 # @k8ordo/ui
 
-A modern React UI component library built with TypeScript, Tailwind CSS, and accessibility in mind.
+React components from [k8ordo](https://ordo.k8o.me) — semantic design
+tokens, built-in wording that follows `@k8ordo/i18n` (Japanese and English included), and adapters that let an LLM generate
+on-brand UIs.
 
-- **Documentation**: https://ordo.k8o.me
+Like every k8ordo package it assumes React 19 and Server Components, uses only
+what has reached Baseline, and ships no polyfills or legacy fallbacks.
+
+- **Documentation**: https://ordo.k8o.me/ui
 - **Storybook**: https://main--687a213c85e2e4589d8db1bb.chromatic.com
 
 ## Installation
@@ -17,45 +22,75 @@ yarn add @k8ordo/ui
 
 ## Peer Dependencies
 
-Make sure you have the following peer dependencies installed:
+Only React and `@k8ordo/i18n` are required:
 
 ```bash
-npm install react react-dom typescript
+npm install react react-dom @k8ordo/i18n
 ```
 
-Required versions:
-
-- React ≥19.0.0
-- TypeScript ≥6.0.0
-- Tailwind CSS ≥4.0.0 — **optional**, only if you import the `tailwind.css` entry (see below)
+Everything else is an optional peer, needed only for the entry point that uses
+it. Install one when you import the entry it belongs to.
+
+<!-- peers -->
+
+| Package                 | Version         | Required | Needed for                                        |
+| ----------------------- | --------------- | -------- | ------------------------------------------------- |
+| `react`                 | ≥19.3.0         | yes      | the components and hooks                          |
+| `react-dom`             | ≥19.3.0         | yes      | portals and `useFormStatus`                       |
+| `@k8ordo/i18n`          | ^1.0.0          | yes      | the locale the components' own wording is read in |
+| `typescript`            | ≥7.0.0          | optional | the shipped type declarations                     |
+| `@types/react`          | ≥19.3.0         | optional | the shipped type declarations                     |
+| `@types/react-dom`      | ≥19.3.0         | optional | the shipped type declarations                     |
+| `zod`                   | ^4.4.3          | optional | generative-UI schemas                             |
+| `@json-render/core`     | ≥0.21.0 <0.22.0 | optional | `@k8ordo/ui/json-render`                          |
+| `@json-render/react`    | ≥0.21.0 <0.22.0 | optional | `@k8ordo/ui/json-render`                          |
+| `@openuidev/lang-core`  | ≥0.3.0 <0.4.0   | optional | `@k8ordo/ui/openui`, `@k8ordo/ui/openui/prompt`   |
+| `@openuidev/react-lang` | ≥0.3.0 <0.4.0   | optional | `@k8ordo/ui/openui`                               |
+| `ai`                    | ≥7.0.51         | optional | `@k8ordo/ui/ai-sdk`                               |
+| `streamdown`            | ≥2.5.0          | optional | `@k8ordo/ui/ai/response`                          |
+
+<!-- /peers -->
+
+The generative-UI peers are 0.x, where a minor bump is a breaking release, so
+the declared range stops at the next minor: `@k8ordo/ui` only claims the line it
+is tested against. Resolve exactly **one copy** of each — the adapters read the
+framework's own React context, so two copies let every schema check and the
+build pass while the form views throw at render time.
+
+The components need no CSS tooling of their own: they are written in CSS Modules
+and ship compiled CSS, which each component imports. The package does not
+depend on `tailwindcss`, not even for the optional `tailwind.css` entry, which
+reads the Tailwind your project already has.
 
 ## Quick Start
 
 1. Import the CSS and set up the provider.
 
-**No Tailwind in your project?** Import the prebuilt stylesheet — this single
-line is all you need. It works with CSS Modules or plain CSS: every library
-rule sits in `@layer`, so your own (unlayered) CSS takes precedence, and the
-design tokens are available as CSS custom properties (`var(--fg-mute)`, …).
+Import `styles.css` once — the layer order, the design tokens, a reset, and the
+page-wide defaults. Each component brings its own CSS through its JavaScript
+import, so a page loads only the CSS of the components it uses. Every library
+rule sits in a cascade layer (`components` for the components), so your own
+(unlayered) CSS takes precedence, and the design tokens are available as CSS
+custom properties (`var(--color-fg-mute)`, `calc(var(--spacing) * 6)`, …).
 
 ```css
 @import '@k8ordo/ui/styles.css';
 ```
 
-**Using Tailwind CSS 4?** Import the source entry instead. It includes
-`@import 'tailwindcss'`, and it keeps the design tokens usable as Tailwind
-classes (`bg-bg-base`, …) in your own markup. Append your sources after the
-import to add your own utility classes:
+**Using Tailwind CSS 4?** Import the bridge after Tailwind, instead of
+`styles.css`. It includes `styles.css`, and its theme makes the design tokens
+usable as Tailwind classes (`bg-bg-base`, `text-md`, `p-6`, …) in your own
+markup:
 
 ```css
+@import 'tailwindcss';
 @import '@k8ordo/ui/tailwind.css';
-@source './src';
 ```
 
-Note that either entry applies a document-wide base: Tailwind preflight plus
-the library base layer (margins/list styles/heading sizes reset, `b`/`strong`
-weight and `i`/`em` style unset, `body` typography defaults). Adding it to an
-existing app restyles more than the library components.
+Note that `styles.css` applies a document-wide base: a reset with the same
+rules as Tailwind's preflight, plus the library base layer (`b`/`strong` weight
+and `i`/`em` style unset, `body` typography defaults). Adding it to an existing
+app restyles more than the library components.
 
 ```tsx
 // In your app entry point
@@ -89,40 +124,20 @@ function MyPage() {
 
 ## Internationalization (i18n)
 
-The wording that components own internally — "close", "required", "loading", and so on — comes from a message dictionary. **It defaults to Japanese**, and that default applies even without a provider, so a Japanese app needs no setup at all.
-
-To switch to English, pass the `en` dictionary from `@k8ordo/ui/i18n`:
-
-```tsx
-import { UIProvider } from '@k8ordo/ui';
-import { en } from '@k8ordo/ui/i18n';
-
-function App() {
-  return (
-    <UIProvider messages={en}>
-      <YourApp />
-    </UIProvider>
-  );
-}
-```
-
-`messages` takes a `Partial<Messages>`, so you can spread a dictionary and override only the keys you care about:
+The wording that components own internally — "close", "required", "loading", and so on — is read in [`@k8ordo/i18n`](https://ordo.k8o.me/i18n)'s current locale. There is no provider and nothing to pass:
 
-```tsx
-<UIProvider messages={{ ...en, close: 'Dismiss' }}>
-  <YourApp />
-</UIProvider>
-```
+- an application that defines its locale set with `defineLocales` gets the locale its messages render in;
+- an application that defines none gets **English**, whatever its URL starts with.
 
-Resolution order is **component prop > provider dictionary > built-in default (Japanese)**. Components that expose a wording prop of their own — `Spinner`'s `label`, `Alert`'s `closeLabel`, `PasswordInput`'s `showLabel` / `hideLabel`, `Pagination`'s `prevLabel` / `nextLabel` — take that prop over the dictionary.
+`ja` and `en` ship with the library. Register any other locale, or replace a built-in one, next to where the set is defined:
 
-The subpath exports both dictionaries and the type:
+```ts
+import { en, registerMessages } from '@k8ordo/ui/i18n';
 
-```tsx
-import { en, ja, type Messages } from '@k8ordo/ui/i18n';
+registerMessages('en', { ...en, close: 'Dismiss' });
 ```
 
-`ja` / `en` live behind `@k8ordo/ui/i18n` rather than the root entry so the dictionaries stay out of the main bundle. See [docs/references/components.md](docs/references/components.md) for the full key list.
+Resolution order is **component prop > registered dictionary > built-in dictionary**. Components that expose a wording prop of their own — `Spinner`'s `label`, `Alert`'s `closeLabel`, `PasswordInput`'s `showLabel` / `hideLabel`, `Pagination`'s `prevLabel` / `nextLabel` — take it over the dictionary. `getMessages()` returns the wording in effect for elements you draw yourself; it is not a hook, so a Server Component calls it too. See [docs/references/components.md](docs/references/components.md) for the full key list.
 
 ## AI Agent Documentation
 
@@ -136,8 +151,9 @@ Point your agent at it once by pasting this into your project's `CLAUDE.md` /
 Use `@k8ordo/ui` for UI. Before writing or changing UI, read
 `node_modules/@k8ordo/ui/docs/GUIDE.md`, then follow only the
 `docs/references/*.md` links it lists that the task actually needs.
-Colors, spacing, radii and font weights go through semantic tokens —
-never raw values such as `bg-teal-500` or `font-semibold`.
+Colors, spacing, radii and font weights go through the semantic tokens
+(`var(--color-fg-mute)`, `calc(var(--spacing) * 6)`) — never raw values or
+the palette (`--teal-500`).
 Look up component props in `docs/references/components.md` instead of
 recalling them; a component that is not listed there does not exist.
 ```
@@ -168,71 +184,113 @@ stories and rendered props rather than relying on trained knowledge:
 
 ## Component Categories
 
+Every component, grouped by its folder in `src/components/`. Each links to its
+entry in [docs/references/components.md](docs/references/components.md).
+
+<!-- generated:component-categories -->
+
 ### Buttons
 
-- **Button** - Primary action button (use `renderItem` to render as a link)
-- **IconButton** - Button with icon only (use `renderItem` to render as a link)
+- [Button](docs/references/components.md#button)
+- [CopyButton](docs/references/components.md#copybutton)
+- [IconButton](docs/references/components.md#iconbutton)
+- [Toolbar](docs/references/components.md#toolbar)
 
 ### Navigation
 
-- **Anchor** - Text link with external-link awareness
-- **Breadcrumb** - Navigation path indicator
-- **Pagination** - Page navigation controls
-- **Tabs** - Tab-based content organization
-
-### Form Controls
-
-- **Autocomplete** - Search with suggestions
-- **Checkbox** / **CheckboxCard** / **CheckboxGroup** - Multi-selection inputs
-- **FileField** - File upload with composite pattern
-- **Form** / **FormControl** - Form wrapper and field with label/validation
-- **NumberField** - Numeric input with controls
-- **PasswordInput** - Password input with show/hide toggle
-- **Radio** / **RadioCard** - Single-selection inputs
-- **Select** - Dropdown selection
-- **Slider** - Slider input control
-- **Switch** - Toggle switch
-- **TextField** - Single-line text input
-- **Textarea** - Multi-line text input
-
-### Data Display
-
-- **Accordion** - Collapsible content panels
-- **Avatar** - User/entity avatar
-- **Badge** - Status/label indicator
-- **Card** - Flexible content container (hover interaction via `interactive`)
-- **Code** - Formatted code display
-- **Heading** - Typography heading component
-- **Table** - Tabular data display
+- [Anchor](docs/references/components.md#anchor)
+- [Breadcrumb](docs/references/components.md#breadcrumb)
+- [Pagination](docs/references/components.md#pagination)
+- [SideNav](docs/references/components.md#sidenav)
+- [Stepper](docs/references/components.md#stepper)
+- [TableOfContents](docs/references/components.md#tableofcontents)
+- [Tabs](docs/references/components.md#tabs)
+
+### Forms
+
+- [Autocomplete](docs/references/components.md#autocomplete)
+- [Calendar](docs/references/components.md#calendar)
+- [Checkbox](docs/references/components.md#checkbox)
+- [CheckboxCard](docs/references/components.md#checkboxcard)
+- [CheckboxGroup](docs/references/components.md#checkboxgroup)
+- [ColorPicker](docs/references/components.md#colorpicker)
+- [Combobox](docs/references/components.md#combobox)
+- [DateField](docs/references/components.md#datefield)
+- [DatePicker](docs/references/components.md#datepicker)
+- [FileField](docs/references/components.md#filefield)
+- [Form](docs/references/components.md#form)
+- [FormControl](docs/references/components.md#formcontrol)
+- [NumberField](docs/references/components.md#numberfield)
+- [PasswordInput](docs/references/components.md#passwordinput)
+- [Radio](docs/references/components.md#radio)
+- [RadioCard](docs/references/components.md#radiocard)
+- [RangeSlider](docs/references/components.md#rangeslider)
+- [Select](docs/references/components.md#select)
+- [Slider](docs/references/components.md#slider)
+- [Switch](docs/references/components.md#switch)
+- [Textarea](docs/references/components.md#textarea)
+- [TextField](docs/references/components.md#textfield)
+
+### Data display
+
+- [Accordion](docs/references/components.md#accordion)
+- [Avatar](docs/references/components.md#avatar)
+- [Badge](docs/references/components.md#badge)
+- [Card](docs/references/components.md#card)
+- [Carousel](docs/references/components.md#carousel)
+- [Code](docs/references/components.md#code)
+- [CodeBlock](docs/references/components.md#codeblock)
+- [DataTable](docs/references/components.md#datatable)
+- [Heading](docs/references/components.md#heading)
+- [Kbd](docs/references/components.md#kbd)
+- [Prose](docs/references/components.md#prose)
+- [Table](docs/references/components.md#table)
+- [Tree](docs/references/components.md#tree)
 
 ### Feedback
 
-- **Alert** - Important messages and notifications
-- **Progress** - Progress indication
-- **Skeleton** - Content loading placeholder
-- **Spinner** - Loading indicator
-- **ToastProvider** / **useToast** - Temporary notification messages
+- [Alert](docs/references/components.md#alert)
+- [Callout](docs/references/components.md#callout)
+- [EmptyState](docs/references/components.md#emptystate)
+- [Progress](docs/references/components.md#progress)
+- [Skeleton](docs/references/components.md#skeleton)
+- [Spinner](docs/references/components.md#spinner)
+- [ToastProvider](docs/references/components.md#toastprovider)
 
 ### Overlays
 
-- **Dialog** - Modal dialog boxes
-- **Drawer** - Slide-out panel
-- **DropdownMenu** - Action menu component
-- **ListBox** - Selectable list component
-- **Modal** - Overlay modal component
-- **Popover** - Floating content container
-- **Tooltip** - Contextual help text
+- [CommandPalette](docs/references/components.md#commandpalette)
+- [ContextMenu](docs/references/components.md#contextmenu)
+- [Dialog](docs/references/components.md#dialog)
+- [Drawer](docs/references/components.md#drawer)
+- [DropdownMenu](docs/references/components.md#dropdownmenu)
+- [ListBox](docs/references/components.md#listbox)
+- [Modal](docs/references/components.md#modal)
+- [Popover](docs/references/components.md#popover)
+- [Tooltip](docs/references/components.md#tooltip)
 
 ### Layout
 
-- **ScrollLinked** - Scroll progress indicator
-- **Separator** - Visual content divider
+- [Grid](docs/references/components.md#grid)
+- [ResizablePanels](docs/references/components.md#resizablepanels)
+- [Separator](docs/references/components.md#separator)
+- [Stack](docs/references/components.md#stack)
+
+### Observers
+
+- [InView](docs/references/components.md#inview)
+- [Resize](docs/references/components.md#resize)
+
+### Icons
 
-### Utilities
+- [Icons](docs/references/components.md#icons) — decorative icon components (`CloseIcon`, `ChevronIcon`, …)
 
-- **UIProvider** - Root provider for the library
-- **PortalRootProvider** / **usePortalRoot** - Customize the portal mount root
-- **Icons** - Icon component collection
+### Providers
+
+- [PortalRootProvider](docs/references/components.md#portalrootprovider)
+- [UIProvider](docs/references/components.md#uiprovider)
+
+<!-- /generated:component-categories -->
 
 ## Usage Examples
 
@@ -314,40 +372,44 @@ function MyComponent() {
 
 ## Imports & Bundle Size
 
-All components and hooks ship from a single ESM entry point — there are no per-component subpaths. The package is tree-shakeable (`sideEffects` is limited to CSS), so bundlers drop everything you don't import:
+The core UI components ship from the root entry — there are no per-component subpaths; the AI chat components live under `@k8ordo/ui/ai`, with `Response` under `@k8ordo/ui/ai/response`, and `CodeBlock` under `@k8ordo/ui/code-block` so the highlighter stays out of everything else. The package is tree-shakeable (`sideEffects` is limited to CSS), so bundlers drop everything you don't import — the CSS too, since each component imports its own stylesheet:
 
 ```tsx
 // Named imports from the root entry — unused exports are tree-shaken away
-import { Button, Card, useClickAway, useLocalStorage } from '@k8ordo/ui';
+import { Button, Card, Stack } from '@k8ordo/ui';
 ```
 
 Optional features live behind dedicated subpath exports:
 
-| Subpath                           | Contents                                                        |
-| --------------------------------- | --------------------------------------------------------------- |
-| `@k8ordo/ui`                      | All components and hooks                                        |
-| `@k8ordo/ui/tokens`               | Design token definitions                                        |
-| `@k8ordo/ui/i18n`                 | Message dictionaries (`ja` / `en`) and the `Messages` type      |
-| `@k8ordo/ui/ai`                   | AI chat components                                              |
-| `@k8ordo/ui/ai/response`          | `Response` Markdown renderer (needs optional peer `streamdown`) |
-| `@k8ordo/ui/ai-sdk`               | AI SDK adapter (needs optional peer `ai`)                       |
-| `@k8ordo/ui/json-render`          | json-render catalog (server-safe)                               |
-| `@k8ordo/ui/json-render/registry` | json-render registry (`'use client'`)                           |
-| `@k8ordo/ui/openui`               | OpenUI library (`'use client'`)                                 |
-| `@k8ordo/ui/openui/prompt`        | OpenUI prompt generation (server-safe)                          |
-| `@k8ordo/ui/styles.css`           | Prebuilt stylesheet (no Tailwind required)                      |
-| `@k8ordo/ui/tailwind.css`         | Tailwind source entry (requires Tailwind CSS 4)                 |
+| Subpath                           | Contents                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------- |
+| `@k8ordo/ui`                      | Core UI components, their types, and provider hooks                                       |
+| `@k8ordo/ui/tokens`               | Design tokens as a DTCG resolver document                                                 |
+| `@k8ordo/ui/props.json`           | Every component's props as JSON, generated from the types                                 |
+| `@k8ordo/ui/i18n`                 | `ja` / `en`, `registerMessages`, `getMessages`, `messageUsage`, and the `Messages` type   |
+| `@k8ordo/ui/ai`                   | AI chat components                                                                        |
+| `@k8ordo/ui/ai/response`          | `Response` Markdown renderer (needs optional peer `streamdown`)                           |
+| `@k8ordo/ui/ai-sdk`               | AI SDK adapter (needs optional peer `ai`)                                                 |
+| `@k8ordo/ui/code-block`           | `CodeBlock`, highlighted on the server with shiki (Server Component)                      |
+| `@k8ordo/ui/json-render`          | json-render catalog (server-safe)                                                         |
+| `@k8ordo/ui/json-render/registry` | json-render registry (`'use client'`)                                                     |
+| `@k8ordo/ui/openui`               | OpenUI library (`'use client'`)                                                           |
+| `@k8ordo/ui/openui/prompt`        | OpenUI prompt generation (server-safe)                                                    |
+| `@k8ordo/ui/styles.css`           | Layer order, tokens, reset and base (required)                                            |
+| `@k8ordo/ui/tailwind.css`         | Tailwind CSS 4 bridge, imported after Tailwind: `styles.css` and utilities for the tokens |
 
 ## AI Chat Components
 
 `@k8ordo/ui/ai` ships building blocks for chat UIs:
 
 - **Conversation** (`Root` / `Messages` / `ScrollButton`) - Scroll container with stick-to-bottom behavior and a scroll-to-bottom button
-- **Message** (`Root` / `Content`) - Chat bubble, styled by `from="user" | "assistant"`
-- **PromptInput** (`Root` / `Textarea` / `Submit`) - Message input form with IME-aware Enter-to-send and a stop button while streaming
+- **Message** (`Root` / `Content` / `Actions` / `Action` / `Copy` / `Regenerate` / `Feedback`) - Chat bubble, styled by `from="user" | "assistant"`, with an optional `avatar`; `Actions` holds copy, regenerate, and good/bad feedback under the message
+- **PromptInput** (`Root` / `Attachments` / `Attach` / `Textarea` / `Submit`) - Message input form with IME-aware Enter-to-send and a stop button while streaming; pass `accept` to take attachments from a file picker, drag and drop, or paste
 - **Reasoning** - Collapsible display of the model's thinking text
 - **Suggestion** (`List` / `Item`) - Suggested prompt chips
-- **ToolInvocation** - Tool call display with input/output and `state` (`'input-streaming' | 'input-available' | 'output-available' | 'output-error'`)
+- **ToolInvocation** - Tool call display with input/output and `state` (`'input-streaming' | 'input-available' | 'approval-requested' | 'approval-responded' | 'output-available' | 'output-error' | 'output-denied'`); with `approval` and `onApprovalResponse` it asks the user to allow or deny the call and answers with the approval `id`
+- **Attachment** (`List` / `Item`) - Files attached to a message: image thumbnails, or a name and media-type chip
+- **Source** (`List` / `Item`) - The sources a response cites, as links (http(s) only) or document titles
 - **Response** (from `@k8ordo/ui/ai/response`) - Streaming-safe Markdown renderer built on streamdown
 
 Two of these need optional peer dependencies:
@@ -396,18 +458,17 @@ function Chat() {
 }
 ```
 
-To render assistant Markdown, wrap it in `Response` (children must be a string). Besides installing `streamdown`, import its stylesheet once and register its classes with Tailwind. Note that `Response` is the one component that requires a Tailwind CSS 4 build (the `tailwind.css` entry plus the `@source` line below) — streamdown's styling lives in its own class names, which the prebuilt `styles.css` does not include:
+To render assistant Markdown, wrap it in `Response` (children must be a string). It styles what streamdown renders itself, through the `data-streamdown` attribute on each element, so no Tailwind is involved; import `streamdown/styles.css` only if you turn on streamdown's `animated` option:
 
 ```tsx
 import { Response } from '@k8ordo/ui/ai/response';
-import 'streamdown/styles.css';
 
 <Message.Content>
   <Response isStreaming>{markdownText}</Response>
 </Message.Content>;
 ```
 
-`Response` forwards the rest of streamdown's props (`translations`, `controls`, `linkSafety`, `plugins`, …); only `className` and `mode` are owned by the library. Built-in labels come from the message dictionary, so they follow the app's language by default.
+`Response` forwards the rest of streamdown's props (`translations`, `controls`, `linkSafety`, `plugins`, …); only `className`, `mode` and `portal` are owned by the library. Built-in labels come from the message dictionary, so they follow the app's language by default.
 
 `linkSafety` defaults to **disabled** here, unlike streamdown. With it enabled, links render as `<button>` instead of `<a>`, which loses ⌘-click, middle-click, "copy link address", and the `link` role for assistive tech. Dangerous schemes such as `javascript:` are neutralized by rehype-harden regardless, so links stay safe with the default. Opt in when you want the confirmation dialog:
 
@@ -415,12 +476,7 @@ import 'streamdown/styles.css';
 <Response linkSafety={{ enabled: true }}>{markdownText}</Response>
 ```
 
-```css
-/* In your CSS entry (path is relative to the CSS file) */
-@source '../node_modules/streamdown/dist/*.js';
-```
-
-With the [AI SDK](https://ai-sdk.dev), `mapMessageParts` from `@k8ordo/ui/ai-sdk` converts a `UIMessage` into a flat array of `{ kind: 'text' | 'reasoning' | 'tool', ... }` parts that map 1:1 onto `Response`, `Reasoning`, and `ToolInvocation`.
+With the [AI SDK](https://ai-sdk.dev), `mapMessageParts` from `@k8ordo/ui/ai-sdk` converts a `UIMessage` into a flat array of `{ kind: 'text' | 'reasoning' | 'tool' | 'file' | 'source' | 'data', ... }` parts that map onto `Response`, `Reasoning`, `ToolInvocation`, `Attachment`, and `Source`; `data` parts are yours to render. A tool part keeps its `approval`, so `onApprovalResponse={addToolApprovalResponse}` answers the SDK directly.
 
 ## Generative UI integrations
 
@@ -431,19 +487,22 @@ These integrations are exposed as optional subpath exports. Install the framewor
 ```bash
 # json-render
 pnpm add @json-render/core @json-render/react zod
-# OpenUI
-pnpm add @openuidev/react-lang zod
-# OpenUI server-safe prompt entry (@k8ordo/ui/openui/prompt) additionally needs:
-pnpm add @openuidev/lang-core
+# OpenUI (both entries import lang-core directly, so install both packages)
+pnpm add @openuidev/react-lang @openuidev/lang-core zod
 ```
 
-Supported components (**all 49**, both frameworks):
+Supported components (both frameworks):
 
-- **Layout / containers**: `Stack`, `Grid`, `Card`, `Form`
-- **Buttons / nav**: `Button`, `IconButton`, `Anchor`, `Breadcrumb`, `Pagination`
-- **Display**: `Badge`, `Heading`, `Avatar`, `Code`, `Icon`, `ChevronIcon`, `StatusIcon`, `Alert`, `Spinner`, `Progress`, `Skeleton`, `Separator`, `Tabs`, `Accordion`, `Table`, `ScrollLinked`
+- **Layout / containers**: `Stack`, `Grid`, `Card`, `Form`, `Carousel`
+- **Buttons / nav**: `Button`, `IconButton`, `CopyButton`, `Toolbar`, `Anchor`, `Breadcrumb`, `Pagination`, `Stepper`, `SideNav`
+- **Display**: `Badge`, `Heading`, `Avatar`, `Code`, `Kbd`, `EmptyState`, `Icon`, `ChevronIcon`, `StatusIcon`, `Alert`, `Callout`, `Spinner`, `Progress`, `Skeleton`, `Separator`, `Tabs`, `Accordion`, `Table`, `DataTable`, `Tree`
 - **Overlays (self-contained widgets)**: `Modal`, `Dialog`, `Drawer`, `Popover`, `Tooltip`, `DropdownMenu`, `Toast`
-- **Form**: `TextField`, `Textarea`, `PasswordInput`, `NumberField`, `Slider`, `Checkbox`, `Switch`, `Select`, `Radio`, `RadioCard`, `CheckboxCard`, `ListBox`, `CheckboxGroup`, `Autocomplete`, `FileField`, `FormControl`
+- **Form**: `TextField`, `Textarea`, `PasswordInput`, `NumberField`, `Slider`, `RangeSlider`, `DateField`, `DatePicker`, `Calendar`, `ColorPicker`, `Combobox`, `Checkbox`, `Switch`, `Select`, `Radio`, `RadioCard`, `CheckboxCard`, `ListBox`, `CheckboxGroup`, `Autocomplete`, `FileField`, `FormControl`
+
+The rest of the exports — `CommandPalette`, `ContextMenu`, `ResizablePanels`, the
+observers, the providers, and the AI chat components — are left out on purpose;
+[docs/references/generative-ui.md](docs/references/generative-ui.md#what-the-catalog-leaves-out)
+says why.
 
 Overlays are exposed as **self-contained widgets**: a `Modal`/`Dialog`/`Drawer`/`Popover` declares its own trigger button via `triggerLabel`, manages open/close internally, and renders the supplied children inside the surface. This lets a model generate UIs that include overlays without modelling imperative open/close state. `Tooltip`/`DropdownMenu`/`Toast` follow the same self-contained pattern (trigger + content).
 
@@ -465,9 +524,10 @@ const systemPrompt = catalog.prompt({ customRules: [...uiRules] });
 // `JsonRenderUI` wires JSONUIProvider + Renderer and the registry for you —
 // just pass a spec. Pass `onStateChange` to collect form values.
 'use client';
+import type { UISpec } from '@k8ordo/ui/json-render';
 import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';
 
-export function GenUi({ spec }: { spec: unknown }) {
+export function GenUi({ spec }: { spec: UISpec }) {
   return <JsonRenderUI spec={spec} />;
 }
 ```
@@ -535,35 +595,8 @@ To generate the prompt inside the client bundle instead, `library.prompt()` stil
 > **Notes**
 >
 > - Make sure `@k8ordo/ui/styles.css` (or `tailwind.css` in Tailwind CSS 4 projects) is loaded and the app is wrapped in `UIProvider`.
-> - `@k8ordo/ui/openui/prompt` needs the optional peer `@openuidev/lang-core` (React-free).
+> - Both OpenUI entries need `@openuidev/lang-core` — `openui/prompt` is the React-free one, and `openui` builds its component library with it. Install it alongside `@openuidev/react-lang`: pnpm will not resolve it for you just because `react-lang` depends on it.
 > - `Tabs` panels are text content (`tabs: [{ label, content }]`); rich-component panels are a future enhancement.
-> - In OpenUI, `Card` can contain a `Stack` or `Grid`, but `Stack`/`Grid` cannot directly nest a `Stack`/`Grid`/`Card` (no self-referential schemas) — put nested layout inside a `Card`. json-render nests freely (slots-based).
-
-## Custom Hooks
-
-The library includes several useful hooks:
-
-- **useBreakpoint** - Tailwind breakpoint matcher
-- **useClickAway** - Detect clicks outside an element
-- **useClient** - Client-side rendering detection
-- **useClipboard** - Clipboard operations
-- **useControllableState** - Controlled/uncontrolled state pattern
-- **useDebouncedTransition** - Rate-limited transition with `AbortSignal`
-- **useDeferredDebounce** - `useDeferredValue` with pending flag
-- **useDisclosure** - Open/close/toggle disclosure state
-- **useHash** - URL hash management
-- **useHover** - Element hover detection
-- **useIntersectionObserver** / **useInView** - Element visibility
-- **useInterval** - Interval timer management
-- **useLocalStorage** / **useSessionStorage** - Web Storage with React state
-- **useResize** - Element resize detection (ResizeObserver)
-- **useScrollDirection** - Scroll direction detection
-- **useScrollLock** - Body/element scroll lock
-- **useStep** - Step-based state management
-- **useTimeout** - Timeout management
-- **useWindowResize** - Window resize events
-- **useWindowSize** - Window size tracking
-- **useWritingMode** - Detect horizontal/vertical `writing-mode`
 
 ## Accessibility
 
@@ -578,11 +611,13 @@ All components follow WCAG accessibility guidelines:
 
 ## Styling & Customization
 
-Components are built with Tailwind CSS and support customization through:
+Components are written in CSS Modules and placed in the `components` cascade
+layer. Customize them through:
 
-- CSS custom properties (semantic design tokens)
-- Tailwind utility classes
-- Light / Dark mode via semantic color tokens
+- CSS custom properties (semantic design tokens), overridden after `styles.css`
+- `renderItem` / `renderAnchor`, which hand you the component's `className`
+- Light / Dark mode via semantic color tokens (`.dark`)
+- Tailwind utility classes on your own markup, through `tailwind.css`
 
 ## Development
 

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/components/_internal/focus-ring.css

@@ -0,0 +1,37 @@
+@layer properties, theme, base;
+
+@layer components {
+  .XbmKcG_ring:focus-visible {
+    box-shadow: var(--shadow-ring-info);
+    border-color: #0000;
+    outline-style: none;
+
+    @media (forced-colors: active) {
+      outline-offset: 2px;
+      outline: 2px solid #0000;
+    }
+  }
+
+  .XbmKcG_ringNoBorder:focus-visible {
+    box-shadow: var(--shadow-ring-info);
+    outline-style: none;
+
+    @media (forced-colors: active) {
+      outline-offset: 2px;
+      outline: 2px solid #0000;
+    }
+  }
+
+  .XbmKcG_ringWithin:focus-within {
+    box-shadow: var(--shadow-ring-info);
+    border-color: #0000;
+    outline-style: none;
+
+    @media (forced-colors: active) {
+      outline-offset: 2px;
+      outline: 2px solid #0000;
+    }
+  }
+}
+
+@layer utilities;

package/dist/components/_internal/focus-ring.module.mjs

@@ -0,0 +1,9 @@
+import './focus-ring.css';
+//#region src/components/_internal/focus-ring.module.css
+var focus_ring_module_default = {
+	"ring": "XbmKcG_ring",
+	"ringNoBorder": "XbmKcG_ringNoBorder",
+	"ringWithin": "XbmKcG_ringWithin"
+};
+//#endregion
+export { focus_ring_module_default as default };

package/dist/components/_internal/form-value.d.mts

@@ -0,0 +1,33 @@
+import { FC, RefObject } from "react";
+//#region src/components/_internal/form-value.d.ts
+type Props = {
+  name: string | undefined;
+  /** What the visible control holds now. */
+  values: readonly string[];
+  /**
+   * What a reset goes back to, and what the form measures dirtiness against.
+   * `undefined` for a controlled caller: the values it mounted with.
+   */
+  defaultValues: readonly string[] | undefined;
+  multiple: boolean;
+  required: boolean;
+  disabled: boolean;
+  /**
+   * Put the visible control's own state back to `defaultValues`. The browser
+   * restores this element itself.
+   */
+  onReset: () => void;
+  /** Where focus goes when the form focuses this element after a failure. */
+  focusTarget: RefObject<HTMLElement | null>;
+};
+/**
+ * The named control a composite component submits through. `type="hidden"`
+ * would not do: it is barred from constraint validation, it cannot take focus
+ * when the form moves to a failure, and with nothing selected there would be
+ * no element carrying the name at all — so neither `required` nor a rule could
+ * reach it. A `<select>` is always present, validates natively (`required`
+ * means "at least one"), restores itself on reset, and keeps the baseline in
+ * each option's `defaultSelected`, where dirtiness is read from.
+ */
+export declare const FormValue: FC<Props>;
+//#endregion