@k8ordo/ui 1.0.0 → 2.1.0

package/docs/references/generative-ui.md

@@ -1,66 +1,182 @@
-# 生成 UI（json-render / OpenUI）
+# Generative UI (json-render / OpenUI)
 
-k8ordo UI は、LLM が k8ordo UI コンポーネントだけで UI を生成できる公式アダプタを同梱している。生成される UI はデザイントークンに固定され、ブランドから外れない。フレームワークは [json-render](https://json-render.dev) と [OpenUI](https://www.openui.com) の 2 つ。
+`@k8ordo/ui` ships official adapters that let an LLM generate UI out of
+`@k8ordo/ui` components only. The generated UI is pinned to the design tokens,
+so it cannot drift off-brand. Two frameworks are supported:
+[json-render](https://json-render.dev) and [OpenUI](https://www.openui.com).
 
-いずれも optional peer dependency なので、使うフレームワークだけインストールする。
+Both are optional peer dependencies — install only the one you use.
 
 ```bash
 # json-render
 pnpm add @json-render/core @json-render/react zod
-# OpenUI
-pnpm add @openuidev/react-lang zod
-# OpenUI のサーバー安全な prompt エントリを使う場合は追加で:
-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
+```
+
+`@openuidev/lang-core` is not optional for OpenUI: `@k8ordo/ui/openui` builds its
+component library with it and `@k8ordo/ui/openui/prompt` is the React-free entry
+on top of it. `@openuidev/react-lang` depends on it as well, but pnpm will not
+let your app resolve a dependency of a dependency — declare it yourself.
+
+Both frameworks are 0.x, where a minor bump is a breaking release, so
+`@k8ordo/ui` declares a range that stops at the next minor. The peer table in
+the package's README (`node_modules/@k8ordo/ui/README.md` when installed via
+npm) lists the current range for each package. Pick a version inside it.
+
+Within that range, resolve exactly **one copy** of each framework. The adapters
+read the framework's own React context — `useStateField` for OpenUI,
+`useBoundProp` for json-render — so if your app and `@k8ordo/ui` end up on two
+different copies, the context objects are different objects: every schema check,
+the types, and the build all pass, and the form views throw
+`useOpenUI must be used within a <Renderer /> component.` at render time. With
+pnpm this happens as soon as your version differs from the one `@k8ordo/ui`
+resolves, even when both satisfy the range.
+
+## What the catalog covers
+
+Both adapters register the same components, and the prompts they generate list
+them. Most are the exported component of the same name. A few are shaped for a
+model instead:
+
+- **Icons** are one `Icon` entry whose `name` picks the glyph from a curated
+  set of icons that need nothing but a size. `ChevronIcon` has an entry of its
+  own, and `AlertIcon` is the `StatusIcon` entry.
+- **Toasts** are a `Toast` entry, standing in for `ToastProvider` and
+  `useToast`: a self-contained widget whose `triggerLabel` button shows the
+  toast.
+- **Overlays** (`Modal`, `Dialog`, `Drawer`, `Popover`, `Tooltip`,
+  `DropdownMenu`) are self-contained widgets too. Each declares its own trigger
+  with `triggerLabel` and handles opening and closing itself.
+- **Compound components** (`Tabs`, `Accordion`, `Table`, `Breadcrumb`, …) are
+  one entry each, with their parts flattened into data such as
+  `tabs: [{ label, content }]`. `Carousel` is one container entry whose
+  children are its slides, one child per slide.
+- **Kbd** takes `keys: string[]` and draws the whole shortcut, one key cap per
+  entry, where the component itself is one key.
+
+Every other component the package exports is either in the catalog or in the
+list below, and the package's tests keep it that way.
+
+## What the catalog leaves out
+
+These exports are left out on purpose, so a model cannot place them:
+
+- `ContextMenu` — it opens on a right-click, which nothing on screen invites,
+  so actions put in it would be hidden in a generated UI. It belongs on your
+  application's own content (a file, a row).
+- `InView`, `Resize` — they report to a callback and draw nothing of their own,
+  and a spec has no code to receive the report.
+- `UIProvider` — your application mounts it once, around the generated UI as
+  well.
+- `PortalRootProvider`, `usePortalRoot` — wiring for your own `createPortal`
+  calls. The generated overlays open their own surfaces.
+- `Conversation`, `Message`, `PromptInput`, `Reasoning`, `Suggestion`,
+  `ToolInvocation`, `Attachment`, and `Source` from `@k8ordo/ui/ai`, and
+  `Response` from
+  `@k8ordo/ui/ai/response` — the chat the generated UI is shown in. Your
+  application builds it from its message stream; a spec does not place it.
+- `CodeBlock` from `@k8ordo/ui/code-block` — it highlights on the server, as an
+  async Server Component. The generated UI renders on the client, where it
+  cannot run, and placing it there would ship the highlighter to the browser.
+  `Code` (inline code) is in the catalog.
+- `CommandPalette` — every item runs a function of your application, which a
+  spec cannot write, and it is chrome your application opens from a shortcut
+  rather than something placed in a reply. For actions inside the generated UI,
+  use `Button` or `DropdownMenu`.
+- `ResizablePanels` — it divides a parent of fixed size into a workspace, the
+  frame an application draws around its content. The generated UI flows inside
+  a message and has no height to divide; to set things side by side, use
+  `Grid`.
+- `Prose` — it typesets the bare HTML that Markdown renders to. A spec places
+  components, which keep their own look, so it would have nothing to typeset;
+  lay a flow out with `Stack`.
+- `TableOfContents` — it points at the ids of the document's headings and
+  follows the scroll. The headings a spec places carry no id, so there would be
+  nothing to point at.
+
+## Prompt language
+
+Everything the adapters hand the model — component descriptions, `uiRules`,
+schema descriptions, and the repair prompt — is English, whatever your
+application's locale. The model reads it; your users never see it. To pin the
+language of the text the model writes into the UI, add a rule of your own:
+
+```tsx
+// json-render
+catalog.prompt({ customRules: [...uiRules, 'Write all UI text in Japanese.'] });
+// OpenUI
+prompt({ additionalRules: ['Write all UI text in Japanese.'] });
 ```
 
 ## json-render
 
-catalog（スキーマ・プロンプト）と registry（描画）が分かれており、catalog は**サーバー安全**。
+The catalog (schemas and prompt) is separate from the registry (rendering), and
+the catalog is **server-safe**.
 
-### 1. サーバーでプロンプトを生成する
+### 1. Generate the prompt on the server
 
 ```tsx
 import { catalog, uiRules } from '@k8ordo/ui/json-render';
 
-// customRules は LLM が破りやすい横断制約を注入する
-// （Table のセル数を columns に一致 / href の形式 / Tabs・Accordion の content はテキストのみ）。
+// customRules injects the cross-cutting constraints an LLM most often breaks
+// (cell count matching columns in Table, href format, text-only content in
+// Tabs and Accordion).
 const systemPrompt = catalog.prompt({ customRules: [...uiRules] });
 ```
 
-### 2. クライアントで描画する
+### 2. Render on the client
 
-`JsonRenderUI` が `JSONUIProvider` + `Renderer` + registry を内部結線済みなので、spec を渡すだけでよい。フォーム値を回収するときは `onStateChange` を渡す。
+`JsonRenderUI` already wires up `JSONUIProvider` + `Renderer` + registry
+internally, so passing the spec is enough. Pass `onStateChange` when you need to
+collect form values.
 
 ```tsx
 '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} />;
 }
 ```
 
-高度な構成（独自の `navigate` / `handlers` / `validationFunctions`）が必要なら、低レベルの `registry` を `@json-render/react` の `JSONUIProvider` / `Renderer` に直接渡す。
+Props:
 
-### 3. LLM 出力を検証して描画 or 修復する
+- `spec`: `Spec | null` (required; a `UISpec` is assignable to json-render's `Spec` without a cast, and `null` renders nothing)
+- `loading`: boolean (passed to `Renderer`: set it while the spec is still streaming in, so children that have not arrived yet are skipped without a warning)
+- `onStateChange`: `(changes: Array<{ path: string; value: unknown }>) => void` (called once per state update with every changed path and its new value)
 
-`validateGeneratedSpec` は機械修正 → 構造検証 → コンポーネントごとの props 検証を行い、失敗時はそのまま LLM に投げ返せる修復プロンプトを返す。`catalog.validate()` は現行の上流バージョンで正常 spec を誤って弾くため、こちらを使う。
+For an advanced setup (your own `navigate`, `handlers`, or
+`validationFunctions`), pass the low-level `registry` straight to
+`@json-render/react`'s `JSONUIProvider` / `Renderer`.
+
+### 3. Validate LLM output, then render or repair it
+
+`validateGeneratedSpec` applies mechanical fixes, validates the structure, then
+validates props per component. On failure it returns the `issues` it found (each
+a `message`, plus the `elementKey` of the offending element when there is one)
+and a repair prompt built from them that you can send straight back to the LLM.
+Use it instead of `catalog.validate()`, which rejects valid specs in the current
+upstream version. The result and issue types are exported as
+`ValidateGeneratedSpecResult` and `GeneratedSpecIssue`.
 
 ```tsx
 import { validateGeneratedSpec } from '@k8ordo/ui/json-render';
 
 const result = validateGeneratedSpec(JSON.parse(llmOutput));
 if (result.ok) {
-  // result.fixes に自動修正の内容
+  // result.fixes lists what was auto-corrected
   return <JsonRenderUI spec={result.spec} />;
 }
-// 壊れていたら修復プロンプトで再生成させる
+// If it is broken, regenerate with the repair prompt
 const retried = await llm(result.repairPrompt);
 ```
 
-### 4. 型付き spec（任意）
+### 4. Typed specs (optional)
 
-`satisfies UISpec` で書くと、component 名・props の typo がコンパイルエラーになり、`as unknown as Spec` が不要になる。
+Writing `satisfies UISpec` turns a typo in a component name or prop into a
+compile error, and removes the need for `as unknown as Spec`.
 
 ```tsx
 import type { UISpec } from '@k8ordo/ui/json-render';
@@ -74,11 +190,14 @@ const spec = {
 } satisfies UISpec;
 ```
 
-`ComponentName` / `ComponentProps<K>` も export されており、特定コンポーネントの props 型を取り出せる。
+`UISpecElement` (one element of a `UISpec`), `ComponentName`, and
+`ComponentProps<K>` are exported as well, so you can pull out the props type of a
+specific component.
 
 ## OpenUI
 
-子要素を型付きサブコンポーネント（`z.array(Child.ref)`）で表すモデル。描画は `'use client'`。
+A model where children are expressed as typed subcomponents
+(`z.array(Child.ref)`). Rendering is `'use client'`.
 
 ```tsx
 'use client';
@@ -90,23 +209,33 @@ export function GenUi({ response }: { response: string }) {
 }
 ```
 
-システムプロンプトはサーバー安全な専用エントリで生成できる（json-render の `catalog.prompt()` と対称）。
+The system prompt comes from a dedicated server-safe entry, mirroring
+json-render's `catalog.prompt()`.
 
 ```tsx
 import { prompt } from '@k8ordo/ui/openui/prompt';
 
-const systemPrompt = prompt(); // React 非依存。RSC / API ルートから呼べる
+const systemPrompt = prompt(); // No React dependency — callable from RSC or an API route
 ```
 
-OpenUI では `Stack` / `Grid` の直下に `Stack` / `Grid` / `Card` を置けない（自己参照スキーマ非対応）。入れ子レイアウトが必要なら `Card` の中に `Stack` / `Grid` を入れる。json-render は slots ベースで自由に入れ子にできる。
+`prompt` takes an optional `PromptOptions` from `@openuidev/lang-core`
+(`preamble`, `additionalRules`, `examples`, …) and passes it straight through to
+the library's prompt generation.
 
-## エクスポート早見表
+Containers nest freely in OpenUI, as they do in json-render: `Stack`, `Grid`,
+`Card`, `Form`, `Modal`, `Dialog`, `Drawer`, and `Popover` each list every
+container among their children, so a `Card` can sit inside a `Stack` and a
+`Stack` inside another `Stack`.
 
-| エクスポート                      | 区分           | 内容                                                               |
-| --------------------------------- | -------------- | ------------------------------------------------------------------ |
-| `@k8ordo/ui/json-render`          | サーバー安全   | `catalog`, `validateGeneratedSpec`, `uiRules`, 型（`UISpec` など） |
-| `@k8ordo/ui/json-render/registry` | `'use client'` | `JsonRenderUI`（事前結線）, `registry`（低レベル）                 |
-| `@k8ordo/ui/openui`               | `'use client'` | `library`（描画）                                                  |
-| `@k8ordo/ui/openui/prompt`        | サーバー安全   | `prompt()`（プロンプト生成）                                       |
+## Exports at a glance
 
-> いずれも `@k8ordo/ui/styles.css`（Tailwind CSS 4 のプロジェクトは代わりに `@k8ordo/ui/tailwind.css`）の読み込みと `UIProvider` でのラップが前提。
+| Export                            | Kind           | Contents                                                           |
+| --------------------------------- | -------------- | ------------------------------------------------------------------ |
+| `@k8ordo/ui/json-render`          | server-safe    | `catalog`, `validateGeneratedSpec`, `uiRules`, types (`UISpec`, …) |
+| `@k8ordo/ui/json-render/registry` | `'use client'` | `JsonRenderUI` (pre-wired), `registry` (low level)                 |
+| `@k8ordo/ui/openui`               | `'use client'` | `library` (rendering)                                              |
+| `@k8ordo/ui/openui/prompt`        | server-safe    | `prompt(options?)` (prompt generation)                             |
+
+> All of them assume you have loaded `@k8ordo/ui/styles.css` (or
+> `@k8ordo/ui/tailwind.css` after Tailwind, in a Tailwind CSS 4 project) and
+> wrapped the tree in `UIProvider`.

package/docs/references/interaction-design.md

@@ -1,77 +1,106 @@
-# インタラクションデザイン
-
-k8ordo UI のインタラクションは「静かな変化」を原則とする。
-
-## インタラクティブ状態
-
-8つの状態を意識して設計する。
-
-| 状態     | スタイル                                              |
-| -------- | ----------------------------------------------------- |
-| Default  | 基本スタイル                                          |
-| Hover    | `hover:bg-bg-mute` — 穏やかな色変化                   |
-| Focus    | `focus-visible:ring-2 focus-visible:ring-border-info` |
-| Active   | `active:bg-bg-emphasize`                              |
-| Disabled | `opacity-50 cursor-not-allowed`                       |
-| Loading  | スピナーまたはスケルトン                              |
-| Selected | `bg-primary-bg-subtle`                                |
-| Error    | `border-border-error` + `text-fg-error`               |
-
-## トランジション
-
-控えめで自然な動き。
-
-| 用途                 | 推奨設定                                   |
-| -------------------- | ------------------------------------------ |
-| ホバー色変化         | `transition-colors duration-150 ease-out`  |
-| 透過度変化           | `transition-opacity duration-200 ease-out` |
-| サイズ変化を伴う場合 | `transition-all duration-150 ease-out`     |
-
-### タイミングの原則
-
-- **100ms**: 即時フィードバック（ボタンプレス）
-- **150–200ms**: 標準トランジション（ホバー、フォーカス）
-- **300ms**: 開閉アニメーション（Accordion, Drawer の限度）
-- **300ms を超えない** — 重く感じる
-
-### アニメーションの選択
-
-```tsx
-// Good: transition-colors（色だけ変わる）
-className = 'transition-colors hover:bg-bg-mute';
-
-// OK: transition-all（複数のプロパティが変わる場合のみ）
-className = 'transition-all hover:bg-bg-mute hover:scale-[1.02]';
-
-// Bad: bounce, spring 系のイージング
-className = 'animate-bounce';
+# Interaction design
+
+Interaction in `@k8ordo/ui` follows one principle: quiet change.
+
+## Interactive states
+
+Design with these eight states in mind.
+
+| State    | Style                                                     |
+| -------- | --------------------------------------------------------- |
+| Default  | The base style                                            |
+| Hover    | `--color-bg-mute` — a gentle color shift                  |
+| Focus    | `box-shadow: var(--shadow-ring-info)` on `:focus-visible` |
+| Active   | `--color-bg-emphasize`                                    |
+| Disabled | `opacity: 0.5; cursor: not-allowed`                       |
+| Loading  | A spinner or a skeleton                                   |
+| Selected | `--color-primary-bg-subtle`                               |
+| Error    | `--color-border-error` + `--color-fg-error`               |
+
+## Transitions
+
+Restrained, natural motion.
+
+| Purpose                        | Recommended setting                                      |
+| ------------------------------ | -------------------------------------------------------- |
+| Hover color change             | the colors over `--duration-fast` with `--easing-out`    |
+| Opacity change                 | `opacity` over `--duration-moderate` with `--easing-out` |
+| When size changes are involved | the changing properties over `--duration-fast`           |
+| A page or a panel replaced     | `<ViewTransition>` — the browser's cross-fade            |
+
+`--duration-fast` is 150ms, `--duration-moderate` 200ms and `--duration-slow`
+300ms. `--easing-out` and `--easing-in-out` are Tailwind's curves
+(`cubic-bezier(0, 0, 0.2, 1)` and `cubic-bezier(0.4, 0, 0.2, 1)`), not the CSS
+keywords of the same name. With `tailwind.css`: `transition-colors
+duration-150 ease-out`.
+
+### Timing principles
+
+- **100ms**: immediate feedback (a button press)
+- **150–200ms**: the standard transition (hover, focus)
+- **300ms**: open/close animation (the limit for Accordion, Drawer)
+- **Never exceed 300ms** — it starts to feel heavy
+
+### Choosing an animation
+
+```css
+/* Good: transition only the colors that change */
+.item {
+  transition-property: color, background-color;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--easing-out);
+}
+
+@media (hover: hover) {
+  .item:hover {
+    background-color: var(--color-bg-mute);
+  }
+}
+
+/* OK: list every property when several change */
+.card {
+  transition-property: background-color, scale;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--easing-out);
+}
+
+/* Bad: bounce or spring easing */
 ```
 
-## フォーカス管理
+## Focus management
 
-- `focus-visible` を使う（`focus` ではなく）— マウスクリック時にリングが出ない
-- フォーカスリングは `ring-border-info` で統一
-- `outline-hidden` でデフォルトのアウトラインを消してから ring を適用
+- Use `:focus-visible`, not `:focus` — no ring appears on a mouse click
+- Keep the focus ring consistent with `--shadow-ring-info`
+- Clear the default outline before applying the ring, and give it back under forced colors, where the ring (a shadow) disappears
+- Keep focus on a button that is waiting on its own action: show the wait with `aria-busy` and `aria-disabled` and ignore presses, rather than setting `disabled`. Chromium moves focus to `body` when the focused element becomes disabled, so the keyboard user who pressed it loses their place. `Button` and `IconButton` do this for `onAction`
+- For the same reason, a text field whose form's action is pending turns `readOnly`, not `disabled`, and ignores the keys that would change its value, so the user who pressed Enter in it keeps their place. `TextField`, `Textarea`, `PasswordInput`, `NumberField`, `DateField`, `DatePicker`, `ColorPicker`, `Combobox`, and `Autocomplete` do this. `readOnly` does not apply to a checkbox, radio, range, or select, yet Enter in one still submits the form through its submit button, so `Checkbox`, `Radio`, `Switch`, `Slider`, `RangeSlider`, and `Select` take `aria-disabled` instead and ignore what would change their value. A checkbox or radio cancels the click in the capture phase and stops it there: cancelled any later, React's change tracking has already recorded the toggle the browser then undoes, calls `onChange` for it, and misses the next real one. A range ignores the arrow, Home, End, and Page keys and the pointer; a select ignores those keys, Space, F4, typed characters, and the pointer
 
-```tsx
-className =
-  'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-border-info';
+```css
+.control:focus-visible {
+  outline-style: none;
+  box-shadow: var(--shadow-ring-info);
+
+  @media (forced-colors: active) {
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+  }
+}
 ```
 
-## フォームデザイン
+## Form design
 
-- ラベルは入力の上に配置（左配置は日本語で読みにくい）
-- エラーメッセージは入力の直下に `text-fg-error text-sm`
-- 必須マークは `*` でラベルの後ろに
-- バリデーションは送信時に行う（リアルタイムは控えめに）
-- `FormControl` コンポーネントでラベル・エラー表示を統一
+- Put the label above the input (a left-aligned label reads badly in Japanese)
+- Put the error message directly under the input, in `--color-fg-error` at `--font-size-sm`
+- Mark required fields with `*` after the label
+- Validate on submit; keep real-time validation to a minimum
+- Use the `FormControl` component so labels and errors stay consistent
 
 ```tsx
 import { FormControl, TextField } from '@k8ordo/ui';
 
 <FormControl
-  label="メールアドレス"
-  errorText="入力してください"
+  label="Email address"
+  errorText="This field is required"
   required
   renderInput={(props) => (
     <TextField {...props} placeholder="example@mail.com" />
@@ -79,17 +108,18 @@ import { FormControl, TextField } from '@k8ordo/ui';
 />;
 ```
 
-## アクセシビリティ
+## Accessibility
 
-- `aria-label` / `aria-describedby` を適切に設定
-- キーボードナビゲーションを確保（Tab, Enter, Escape, 矢印キー）
-- `prefers-reduced-motion` を考慮 — motion ライブラリが自動対応
-- カラーだけに頼らない状態表現（アイコンやテキストを併用）
+- Set `aria-label` / `aria-describedby` where they belong
+- Guarantee keyboard navigation (Tab, Enter, Escape, arrow keys)
+- Respect `prefers-reduced-motion`. Under it the stylesheet turns off the open animation of Popover and what is built on it (DropdownMenu, ListBox, Tooltip), the Toast, Modal, and Drawer animations, the Tabs indicator slide, and every view transition; `Card`'s hover scale runs only under `prefers-reduced-motion: no-preference`. Skeleton's pulse, Spinner's spin, and the Accordion chevron, Switch thumb, and Progress bar transitions keep running. Put your own motion under `@media (prefers-reduced-motion: no-preference)`
+- Never signal state with color alone; pair it with an icon or text
+- The components follow `prefers-contrast: more` and stay legible under `forced-colors: active` (see [High contrast and forced colors](./color.md#high-contrast-and-forced-colors)); do the same in your own UI
 
-## やってはいけないこと
+## What not to do
 
-- bounce / spring 系のイージング
-- 300ms を超えるアニメーション
-- ホバーに強い原色（`bg-primary-bg`）を使う
-- `cursor-pointer` をボタン以外に付ける（リンクにも不要）
-- ダブルクリック防止なしの送信ボタン
+- Bounce or spring easing
+- Animation longer than 300ms
+- A strong primary color (`--color-primary-bg`) on hover
+- `cursor: pointer` on anything that is not a button (links do not need it either)
+- A submit button with no double-click guard