@k8ordo/ui 1.0.0 → 2.0.0

package/docs/references/generative-ui.md

@@ -1,35 +1,42 @@
-# 生成 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 エントリを使う場合は追加で:
+# Add this too if you use OpenUI's server-safe prompt entry:
 pnpm add @openuidev/lang-core
 ```
 
 ## 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';
@@ -40,27 +47,33 @@ export function GenUi({ spec }: { spec: unknown }) {
 }
 ```
 
-高度な構成（独自の `navigate` / `handlers` / `validationFunctions`）が必要なら、低レベルの `registry` を `@json-render/react` の `JSONUIProvider` / `Renderer` に直接渡す。
+For an advanced setup (your own `navigate`, `handlers`, or
+`validationFunctions`), pass the low-level `registry` straight to
+`@json-render/react`'s `JSONUIProvider` / `Renderer`.
 
-### 3. LLM 出力を検証して描画 or 修復する
+### 3. Validate LLM output, then render or repair it
 
-`validateGeneratedSpec` は機械修正 → 構造検証 → コンポーネントごとの props 検証を行い、失敗時はそのまま LLM に投げ返せる修復プロンプトを返す。`catalog.validate()` は現行の上流バージョンで正常 spec を誤って弾くため、こちらを使う。
+`validateGeneratedSpec` applies mechanical fixes, validates the structure, then
+validates props per component. On failure it returns a repair prompt you can
+send straight back to the LLM. Use it instead of `catalog.validate()`, which
+rejects valid specs in the current upstream version.
 
 ```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 +87,13 @@ const spec = {
 } satisfies UISpec;
 ```
 
-`ComponentName` / `ComponentProps<K>` も export されており、特定コンポーネントの props 型を取り出せる。
+`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 +105,29 @@ 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 ベースで自由に入れ子にできる。
+In OpenUI a `Stack` or `Grid` cannot sit directly inside another `Stack` or
+`Grid` (self-referential schemas are unsupported). When you need nested layout,
+put the `Stack` / `Grid` inside a `Card`. json-render is slot-based and nests
+freely.
 
-## エクスポート早見表
+## Exports at a glance
 
-| エクスポート                      | 区分           | 内容                                                               |
+| Export                            | Kind           | Contents                                                           |
 | --------------------------------- | -------------- | ------------------------------------------------------------------ |
-| `@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()`（プロンプト生成）                                       |
-
-> いずれも `@k8ordo/ui/styles.css`（Tailwind CSS 4 のプロジェクトは代わりに `@k8ordo/ui/tailwind.css`）の読み込みと `UIProvider` でのラップが前提。
+| `@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()` (prompt generation)                                     |
+
+> All of them assume you have loaded `@k8ordo/ui/styles.css` (or
+> `@k8ordo/ui/tailwind.css` in a Tailwind CSS 4 project) and wrapped the tree in
+> `UIProvider`.

package/docs/references/helpers.md

@@ -1,120 +1,223 @@
-# ヘルパー・型
+# Helpers and types
 
-k8ordo UI が提供するユーティリティ関数と型定義。
+Utility functions and type definitions that `@k8ordo/ui` provides.
 
 ```tsx
-import { cn, between, commalize, uuidV4 } from '@k8ordo/ui';
-import type { Status, Direction, Option } from '@k8ordo/ui';
+import {
+  chain,
+  cn,
+  createSafeContext,
+  mergeProps,
+  mergeRefs,
+} from '@k8ordo/ui';
+import type {
+  Status,
+  Direction,
+  Placement,
+  ModalSide,
+  DrawerSide,
+  Option,
+} from '@k8ordo/ui';
 ```
 
-## ヘルパー関数
+The list below is the complete public helper API: `pnpm check:props` fails
+when the headings under "Helper functions" and the exports of
+`src/helpers/index.ts` disagree.
+
+## Helper functions
+
+### chain
+
+Combines several callbacks into one that calls each in order with the same
+arguments. `undefined` entries are skipped, so an optional user handler can be
+passed straight in. The combined function returns nothing.
+
+```tsx
+import { chain } from '@k8ordo/ui';
+
+const onClick = chain(props.onClick, () => {
+  setOpen(false);
+});
+
+<button onClick={onClick} />;
+```
+
+Signature:
+
+```ts
+const chain: <T extends (...args: never[]) => unknown>(
+  ...callbacks: Array<T | undefined>
+) => (...args: Parameters<T>) => void;
+```
 
 ### cn
 
-Tailwind クラスのマージ（clsx + tailwind-merge）。
+Merges Tailwind classes (clsx + tailwind-merge). Accepts strings, arrays,
+objects, and falsy values, and resolves conflicting utilities with the last
+one winning.
 
 ```tsx
 import { cn } from '@k8ordo/ui';
 
 cn('text-fg-base', isActive && 'bg-primary-bg', className);
-// 重複するクラスを自動的に解決
+cn('flex', undefined, { hidden: false, grow: true }); // → 'flex grow'
 cn('px-4 py-2', 'px-6'); // → 'py-2 px-6'
 ```
 
-### between
+Signature:
+
+```ts
+const cn: (...inputs: ClassValue[]) => string;
+```
+
+### createSafeContext
 
-値を範囲内にクランプ。
+Creates a context whose hook throws with the given message when there is no
+provider above it, instead of handing back `null`. Returns the context (to
+render as a provider) and the hook as a tuple.
 
 ```tsx
-import { between } from '@k8ordo/ui';
+import { createSafeContext } from '@k8ordo/ui';
 
-between(150, 0, 100); // → 100
-between(-5, 0, 100); // → 0
-between(50, 0, 100); // → 50
-```
+const [TabsContext, useTabsContext] = createSafeContext<{
+  selectedId: string;
+}>('Tabs.Tab must be used within <Tabs.Root>');
 
-### commalize
+const Root = ({ children }) => (
+  <TabsContext value={{ selectedId }}>{children}</TabsContext>
+);
 
-数値を3桁区切りでフォーマット。
+const Tab = () => {
+  const { selectedId } = useTabsContext(); // throws outside <Root>
+};
+```
 
-```tsx
-import { commalize } from '@k8ordo/ui';
+Signature:
 
-commalize(1000); // → '1,000'
-commalize(1234567); // → '1,234,567'
+```ts
+const createSafeContext: <T>(
+  errorMessage: string,
+) => readonly [Context<T | null>, () => T];
 ```
 
-### toPrecision
+### mergeProps
 
-指定した小数点以下の精度に丸める。
+Merges two props objects the way a `render*` prop expects: `className` goes
+through `cn`, `style` is shallow-merged, event handlers (`onClick`,
+`onKeyDown`, …) are chained with `chain` so both run, and any other key is
+overwritten by `override` unless its value is `undefined`.
 
 ```tsx
-import { toPrecision } from '@k8ordo/ui';
+import { mergeProps } from '@k8ordo/ui';
+
+const merged = mergeProps(
+  { className: 'p-2 text-fg-base', onClick: track },
+  { className: 'text-fg-mute', onClick: open, id: 'menu' },
+);
+// merged.className → 'p-2 text-fg-mute'
+// merged.onClick() → track(), then open()
+```
+
+Signature:
 
-toPrecision(3.14159, 2); // → 3.14
+```ts
+const mergeProps: <
+  A extends Record<string, unknown>,
+  B extends Record<string, unknown>,
+>(
+  base: A,
+  override: B,
+) => Omit<A, keyof B> & B;
 ```
 
-### cast
+### mergeRefs
 
-型キャストユーティリティ。
+Combines several refs into one callback ref, so a component can keep an
+internal ref while forwarding the caller's. Object refs are assigned, function
+refs are called, and `null` / `undefined` are skipped. The returned callback
+returns a cleanup (React 19 ref cleanup) that resets object refs to `null` and
+runs each function ref's own cleanup — or calls it with `null` when it did not
+return one.
 
 ```tsx
-import { cast } from '@k8ordo/ui';
+import { mergeRefs } from '@k8ordo/ui';
+
+const Field = ({ ref, ...rest }: { ref?: Ref<HTMLInputElement> }) => {
+  const internalRef = useRef<HTMLInputElement>(null);
+  return <input ref={mergeRefs(internalRef, ref)} {...rest} />;
+};
 ```
 
-### isInternalRoute
+Signature:
 
-内部ルートかどうかの判定。
+```ts
+const mergeRefs: <T>(
+  ...refs: ReadonlyArray<Ref<T> | undefined>
+) => RefCallback<T>;
+```
 
-```tsx
-import { isInternalRoute } from '@k8ordo/ui';
+## Type definitions
 
-isInternalRoute('/about'); // → true
-isInternalRoute('https://ext.com'); // → false
+### Status
+
+```tsx
+type Status = 'success' | 'info' | 'warning' | 'error';
 ```
 
-### findAllColors
+Used for the status of Alert, Badge, Toast, and similar components.
 
-デザイントークンからすべてのカラーを抽出。
+### Direction
 
 ```tsx
-import { findAllColors } from '@k8ordo/ui';
-
-const colors = findAllColors();
+type Direction = 'up' | 'down' | 'right' | 'left';
 ```
 
-### uuidV4
+Used to point ChevronIcon and similar icons.
 
-UUID v4 の生成。
+### Placement
 
 ```tsx
-import { uuidV4 } from '@k8ordo/ui';
-
-const id = uuidV4(); // → 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
+type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
 ```
 
-## 型定義
+Placement relative to an anchor element, for Popover, Tooltip, DropdownMenu,
+and ListBox (the `placement` prop).
 
-### Status
+### ModalSide
 
 ```tsx
-type Status = 'success' | 'info' | 'warning' | 'error';
+type ModalSide = 'center' | 'bottom' | 'left' | 'right';
 ```
 
-Alert, Badge, Toast 等のステータス表示に使用。
+Which viewport edge a Modal sticks to (the `side` prop). It is a different
+idea from `Placement`, which is relative to an anchor, so the prop name differs
+too.
 
-### Direction
+### DrawerSide
 
 ```tsx
-type Direction = 'up' | 'down' | 'right' | 'left';
+type DrawerSide = Extract<ModalSide, 'left' | 'right'>;
 ```
 
-ChevronIcon 等の方向指定に使用。
+The subset of `ModalSide` a Drawer accepts: a drawer always slides in from an
+edge, so `center` is excluded.
 
 ### Option
 
 ```tsx
-type Option = { value: string; label: string };
+type Option = Readonly<{ value: string; label: string }>;
 ```
 
-Select, Autocomplete 等の選択肢に使用。
+Used for the choices in Radio, Select, Autocomplete, and similar components.