@k8ordo/ui 1.0.0

package/docs/references/generative-ui.md

@@ -0,0 +1,112 @@
+# 生成 UI（json-render / OpenUI）
+
+k8ordo UI は、LLM が k8ordo UI コンポーネントだけで UI を生成できる公式アダプタを同梱している。生成される UI はデザイントークンに固定され、ブランドから外れない。フレームワークは [json-render](https://json-render.dev) と [OpenUI](https://www.openui.com) の 2 つ。
+
+いずれも optional peer dependency なので、使うフレームワークだけインストールする。
+
+```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
+```
+
+## json-render
+
+catalog（スキーマ・プロンプト）と registry（描画）が分かれており、catalog は**サーバー安全**。
+
+### 1. サーバーでプロンプトを生成する
+
+```tsx
+import { catalog, uiRules } from '@k8ordo/ui/json-render';
+
+// customRules は LLM が破りやすい横断制約を注入する
+// （Table のセル数を columns に一致 / href の形式 / Tabs・Accordion の content はテキストのみ）。
+const systemPrompt = catalog.prompt({ customRules: [...uiRules] });
+```
+
+### 2. クライアントで描画する
+
+`JsonRenderUI` が `JSONUIProvider` + `Renderer` + registry を内部結線済みなので、spec を渡すだけでよい。フォーム値を回収するときは `onStateChange` を渡す。
+
+```tsx
+'use client';
+import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';
+
+export function GenUi({ spec }: { spec: unknown }) {
+  return <JsonRenderUI spec={spec} />;
+}
+```
+
+高度な構成（独自の `navigate` / `handlers` / `validationFunctions`）が必要なら、低レベルの `registry` を `@json-render/react` の `JSONUIProvider` / `Renderer` に直接渡す。
+
+### 3. LLM 出力を検証して描画 or 修復する
+
+`validateGeneratedSpec` は機械修正 → 構造検証 → コンポーネントごとの props 検証を行い、失敗時はそのまま LLM に投げ返せる修復プロンプトを返す。`catalog.validate()` は現行の上流バージョンで正常 spec を誤って弾くため、こちらを使う。
+
+```tsx
+import { validateGeneratedSpec } from '@k8ordo/ui/json-render';
+
+const result = validateGeneratedSpec(JSON.parse(llmOutput));
+if (result.ok) {
+  // result.fixes に自動修正の内容
+  return <JsonRenderUI spec={result.spec} />;
+}
+// 壊れていたら修復プロンプトで再生成させる
+const retried = await llm(result.repairPrompt);
+```
+
+### 4. 型付き spec（任意）
+
+`satisfies UISpec` で書くと、component 名・props の typo がコンパイルエラーになり、`as unknown as Spec` が不要になる。
+
+```tsx
+import type { UISpec } from '@k8ordo/ui/json-render';
+
+const spec = {
+  root: 'root',
+  elements: {
+    root: { type: 'Stack', props: { direction: 'column' }, children: ['ok'] },
+    ok: { type: 'Button', props: { label: 'OK' } },
+  },
+} satisfies UISpec;
+```
+
+`ComponentName` / `ComponentProps<K>` も export されており、特定コンポーネントの props 型を取り出せる。
+
+## OpenUI
+
+子要素を型付きサブコンポーネント（`z.array(Child.ref)`）で表すモデル。描画は `'use client'`。
+
+```tsx
+'use client';
+import { library } from '@k8ordo/ui/openui';
+import { Renderer } from '@openuidev/react-lang';
+
+export function GenUi({ response }: { response: string }) {
+  return <Renderer library={library} response={response} />;
+}
+```
+
+システムプロンプトはサーバー安全な専用エントリで生成できる（json-render の `catalog.prompt()` と対称）。
+
+```tsx
+import { prompt } from '@k8ordo/ui/openui/prompt';
+
+const systemPrompt = prompt(); // React 非依存。RSC / API ルートから呼べる
+```
+
+OpenUI では `Stack` / `Grid` の直下に `Stack` / `Grid` / `Card` を置けない（自己参照スキーマ非対応）。入れ子レイアウトが必要なら `Card` の中に `Stack` / `Grid` を入れる。json-render は slots ベースで自由に入れ子にできる。
+
+## エクスポート早見表
+
+| エクスポート                      | 区分           | 内容                                                               |
+| --------------------------------- | -------------- | ------------------------------------------------------------------ |
+| `@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` でのラップが前提。

package/docs/references/helpers.md

@@ -0,0 +1,120 @@
+# ヘルパー・型
+
+k8ordo UI が提供するユーティリティ関数と型定義。
+
+```tsx
+import { cn, between, commalize, uuidV4 } from '@k8ordo/ui';
+import type { Status, Direction, Option } from '@k8ordo/ui';
+```
+
+## ヘルパー関数
+
+### cn
+
+Tailwind クラスのマージ（clsx + tailwind-merge）。
+
+```tsx
+import { cn } from '@k8ordo/ui';
+
+cn('text-fg-base', isActive && 'bg-primary-bg', className);
+// 重複するクラスを自動的に解決
+cn('px-4 py-2', 'px-6'); // → 'py-2 px-6'
+```
+
+### between
+
+値を範囲内にクランプ。
+
+```tsx
+import { between } from '@k8ordo/ui';
+
+between(150, 0, 100); // → 100
+between(-5, 0, 100); // → 0
+between(50, 0, 100); // → 50
+```
+
+### commalize
+
+数値を3桁区切りでフォーマット。
+
+```tsx
+import { commalize } from '@k8ordo/ui';
+
+commalize(1000); // → '1,000'
+commalize(1234567); // → '1,234,567'
+```
+
+### toPrecision
+
+指定した小数点以下の精度に丸める。
+
+```tsx
+import { toPrecision } from '@k8ordo/ui';
+
+toPrecision(3.14159, 2); // → 3.14
+```
+
+### cast
+
+型キャストユーティリティ。
+
+```tsx
+import { cast } from '@k8ordo/ui';
+```
+
+### isInternalRoute
+
+内部ルートかどうかの判定。
+
+```tsx
+import { isInternalRoute } from '@k8ordo/ui';
+
+isInternalRoute('/about'); // → true
+isInternalRoute('https://ext.com'); // → false
+```
+
+### findAllColors
+
+デザイントークンからすべてのカラーを抽出。
+
+```tsx
+import { findAllColors } from '@k8ordo/ui';
+
+const colors = findAllColors();
+```
+
+### uuidV4
+
+UUID v4 の生成。
+
+```tsx
+import { uuidV4 } from '@k8ordo/ui';
+
+const id = uuidV4(); // → 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
+```
+
+## 型定義
+
+### Status
+
+```tsx
+type Status = 'success' | 'info' | 'warning' | 'error';
+```
+
+Alert, Badge, Toast 等のステータス表示に使用。
+
+### Direction
+
+```tsx
+type Direction = 'up' | 'down' | 'right' | 'left';
+```
+
+ChevronIcon 等の方向指定に使用。
+
+### Option
+
+```tsx
+type Option = { value: string; label: string };
+```
+
+Select, Autocomplete 等の選択肢に使用。

package/docs/references/hooks.md

@@ -0,0 +1,314 @@
+# Hooks
+
+k8ordo UI が提供するカスタムフック。
+
+```tsx
+import { useDisclosure, useDeferredDebounce } from '@k8ordo/ui';
+```
+
+## 状態管理
+
+### useDisclosure
+
+開閉状態のトグル管理。
+
+```tsx
+const { isOpen, open, close, toggle } = useDisclosure();
+```
+
+### useControllableState
+
+Controlled / Uncontrolled を透過的に扱うパターン。
+
+```tsx
+const [value, setValue] = useControllableState({
+  value: controlledValue,
+  defaultValue: 'default',
+  onChange: onControlledChange,
+});
+```
+
+### useStep
+
+ステップカウンター。進む/戻るの制御。
+
+```tsx
+const { count, next, back, isDisabledBack, isDisabledNext } = useStep({
+  initialCount: 0,
+  maxCount: 5,
+});
+```
+
+### useHash
+
+URL ハッシュの読み取り（読み取り専用）。
+
+```tsx
+const hash = useHash(); // string | null
+```
+
+## ストレージ
+
+### useLocalStorage
+
+LocalStorage と同期した状態。`remove` で削除も可能。
+
+```tsx
+const [value, setValue, remove] = useLocalStorage<string>('key', 'default');
+```
+
+### useSessionStorage
+
+SessionStorage と同期した状態。`remove` で削除も可能。
+
+```tsx
+const [value, setValue, remove] = useSessionStorage<string>('key', 'default');
+```
+
+## イベント
+
+### useClickAway
+
+要素外クリックの検知。ref と callback を引数に取る。
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+
+useClickAway(ref, (e) => {
+  console.log('外側をクリック');
+});
+```
+
+引数:
+
+- `ref`: `RefObject<T | null>`
+- `callback`: `(e: Event) => void`
+- `enabled`: boolean（デフォルト: `true`）
+
+### useHover
+
+ホバー状態の検知。`hoverProps` を要素に spread する。
+
+```tsx
+const { isHovered, hoverProps } = useHover();
+
+<div {...hoverProps}>{isHovered ? 'ホバー中' : '通常'}</div>;
+```
+
+`hoverProps` は `{ onPointerEnter, onPointerLeave }` を含む。
+
+## タイミング
+
+> `useDeferredDebounce` と `useDebouncedTransition` は役割が異なります。
+>
+> - **`useDeferredDebounce`**: **描画の遅延**（render defer）。React スケジューラが重い再レンダーを後回しにするだけで、遅延時間の保証はない。副作用（fetch / 外部 API）を間引く用途には使えない。
+> - **`useDebouncedTransition`**: **副作用の間引き**（rate limiting）。指定した `delay` を待ってからアクションを実行し、再呼び出し時には前回の `AbortSignal` を abort する。fetch など「軽々しく連射したくない処理」に使う。
+
+### useDeferredDebounce
+
+`useDeferredValue` をラップし、値と「追いついていない」ペンディング状態を返す。入力に応じてリストを絞り込むような **純 UI 用途のみ** 向け。
+
+```tsx
+const [deferredValue, isPending] = useDeferredDebounce(inputValue);
+```
+
+戻り値:
+
+- `[T, boolean]` — `[deferredValue, isPending]`
+
+### useDebouncedTransition
+
+`startTransition(async)` と `AbortController` を組み合わせ、delay 経過後にアクションを実行する。再呼び出し時は前回のアクションに渡した signal を abort し、action 内が `fetch({ signal })` 等で AbortError を投げても未処理 rejection にはならない。
+
+```tsx
+const [isPending, run] = useDebouncedTransition(300);
+
+const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+  const q = e.target.value;
+  setQuery(q);
+  run(async (signal) => {
+    const res = await fetch(`/api/search?q=${q}`, { signal });
+    setResults(await res.json());
+  });
+};
+```
+
+戻り値:
+
+- `[boolean, (action: (signal: AbortSignal) => void | Promise<void>) => void]`
+
+### useInterval
+
+定期実行。
+
+```tsx
+useInterval(() => {
+  fetchData();
+}, 5000);
+```
+
+### useTimeout
+
+遅延実行。
+
+```tsx
+useTimeout(() => {
+  hideMessage();
+}, 3000);
+```
+
+## DOM・ブラウザ
+
+### useWindowSize
+
+ウィンドウサイズの取得。
+
+```tsx
+const { width, height } = useWindowSize();
+```
+
+### useWindowResize
+
+ウィンドウリサイズのリスナー。コールバックに `{ width, height }` が渡される。
+
+```tsx
+useWindowResize(
+  (size) => {
+    recalculate(size.width, size.height);
+  },
+  { enabled: true },
+);
+```
+
+引数:
+
+- `callback`: `(size: { width: number; height: number }) => void`
+- `options`: `{ enabled?: boolean }`
+
+### useResize
+
+要素のリサイズ監視（ResizeObserver）。ref を引数に取る。
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+
+useResize(
+  ref,
+  (entry) => {
+    console.log(entry.contentRect);
+  },
+  { enabled: true },
+);
+```
+
+引数:
+
+- `ref`: `RefObject<T | null>`
+- `callback`: `(entry: ResizeObserverEntry) => void`
+- `options`: `{ enabled?: boolean }`
+
+### useIntersectionObserver
+
+交差オブザーバー。ref を引数に取る。
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+
+useIntersectionObserver(
+  ref,
+  (entry) => {
+    console.log(entry.isIntersecting);
+  },
+  { threshold: 0.5 },
+);
+```
+
+引数:
+
+- `ref`: `RefObject<T | null>`
+- `callback`: `(entry: IntersectionObserverEntry) => void`
+- `options`: IntersectionObserver のオプション
+
+### useInView
+
+要素の表示状態。ref を引数に取り、boolean を返す。
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const isInView = useInView(ref, { threshold: 0.1 });
+```
+
+引数:
+
+- `ref`: `RefObject<T | null>`
+- `options`: IntersectionObserver のオプション
+
+### useScrollDirection
+
+スクロール方向の検知。X 軸と Y 軸の両方を返す。
+
+```tsx
+const { x, y } = useScrollDirection();
+// x: 'left' | 'right'
+// y: 'up' | 'down'
+```
+
+### useScrollLock
+
+body のスクロールロック。lock / unlock 関数を返す。
+
+```tsx
+const { lock, unlock } = useScrollLock();
+
+// モーダルを開くとき
+lock();
+
+// モーダルを閉じるとき
+unlock();
+```
+
+### useWritingMode
+
+要素の `writing-mode` を検知し、`'horizontal'` または `'vertical'` を返す。`vertical-*` / `sideways-*` はすべて `'vertical'` として正規化される。ResizeObserver で監視し、SSR では `'horizontal'` を返す。
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const writingMode = useWritingMode(ref); // 'horizontal' | 'vertical'
+```
+
+引数:
+
+- `ref`: `RefObject<Element | null>`
+
+戻り値:
+
+- `'horizontal' | 'vertical'`
+
+### useBreakpoint
+
+Tailwind ブレークポイントの判定。
+
+```tsx
+const isMd = useBreakpoint('md'); // 768px 以上かどうか
+```
+
+## ユーティリティ
+
+### useClient
+
+クライアントサイドかどうか。
+
+```tsx
+const isClient = useClient();
+```
+
+### useClipboard
+
+クリップボードの読み書き。
+
+```tsx
+const { writeClipboard, readClipboard } = useClipboard();
+
+await writeClipboard('コピーするテキスト');
+const text = await readClipboard();
+```

package/docs/references/interaction-design.md

@@ -0,0 +1,95 @@
+# インタラクションデザイン
+
+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';
+```
+
+## フォーカス管理
+
+- `focus-visible` を使う（`focus` ではなく）— マウスクリック時にリングが出ない
+- フォーカスリングは `ring-border-info` で統一
+- `outline-hidden` でデフォルトのアウトラインを消してから ring を適用
+
+```tsx
+className =
+  'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-border-info';
+```
+
+## フォームデザイン
+
+- ラベルは入力の上に配置（左配置は日本語で読みにくい）
+- エラーメッセージは入力の直下に `text-fg-error text-sm`
+- 必須マークは `*` でラベルの後ろに
+- バリデーションは送信時に行う（リアルタイムは控えめに）
+- `FormControl` コンポーネントでラベル・エラー表示を統一
+
+```tsx
+import { FormControl, TextField } from '@k8ordo/ui';
+
+<FormControl
+  label="メールアドレス"
+  errorText="入力してください"
+  required
+  renderInput={(props) => (
+    <TextField {...props} placeholder="example@mail.com" />
+  )}
+/>;
+```
+
+## アクセシビリティ
+
+- `aria-label` / `aria-describedby` を適切に設定
+- キーボードナビゲーションを確保（Tab, Enter, Escape, 矢印キー）
+- `prefers-reduced-motion` を考慮 — motion ライブラリが自動対応
+- カラーだけに頼らない状態表現（アイコンやテキストを併用）
+
+## やってはいけないこと
+
+- bounce / spring 系のイージング
+- 300ms を超えるアニメーション
+- ホバーに強い原色（`bg-primary-bg`）を使う
+- `cursor-pointer` をボタン以外に付ける（リンクにも不要）
+- ダブルクリック防止なしの送信ボタン