@godxjp/ui 20.2.0 → 21.0.0

package/docs/data-entry/chat-suggestion.tsx

@@ -0,0 +1,301 @@
+import { useState } from "react";
+
+import {
+  Avatar,
+  AvatarFallback,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@godxjp/ui/data-display";
+import {
+  ChatComposer,
+  ChatSuggestion,
+  type ChatSuggestionItemProp,
+} from "@godxjp/ui/data-entry";
+import { Text } from "@godxjp/ui/general";
+import {
+  AppShell,
+  Flex,
+  PageContainer,
+  Sidebar,
+  type SidebarSectionProp,
+  Topbar,
+} from "@godxjp/ui/layout";
+import { AtSign, Bot, Hash, MessageSquare, Settings, Slash, Users } from "lucide-react";
+
+/**
+ * ChatSuggestion — the trigger-character list that completes a draft in place.
+ *
+ * It owns the part `Command` does not: watching a TEXTAREA for a trigger character at the caret,
+ * tracking the query as the caret moves, and closing on Escape, on blur and on a word break —
+ * while the list itself stays the real `Command` inside a real `Popover`, so the listbox ARIA is
+ * cmdk's and not hand-rolled.
+ *
+ * Every card here is one axis at rest, so the whole API is visible without clicking:
+ * `triggerCharacter`, one level of `children`, a disabled row, an empty result, and the
+ * open/defaultOpen/onOpenChange triad. `ChatComposer`'s own page shows it wired into a live
+ * transcript; this page is about the completion behaviour alone.
+ *
+ * Composed only from real @godxjp/ui components.
+ */
+const sections: SidebarSectionProp[] = [
+  {
+    label: "アシスタント",
+    items: [
+      { id: "chat", label: "チャット", icon: MessageSquare },
+      { id: "agents", label: "エージェント", icon: Bot },
+      { id: "members", label: "メンバー", icon: Users },
+    ],
+  },
+  { label: "管理", items: [{ id: "settings", label: "設定", icon: Settings }] },
+];
+
+/** Slash commands — the `template` row carries one level of `children`. */
+const COMMANDS: ChatSuggestionItemProp[] = [
+  { value: "summarize", label: "要約する", description: "このスレッドを3行で要約します" },
+  { value: "translate", label: "翻訳する", description: "英語 ⇄ 日本語" },
+  { value: "explain", label: "詳しく説明する" },
+  {
+    value: "archive",
+    label: "アーカイブする",
+    description: "権限がないため選択できません",
+    disabled: true,
+  },
+  {
+    value: "template",
+    label: "テンプレート",
+    description: "定型文を挿入します",
+    children: [
+      { value: "minutes", label: "議事録" },
+      { value: "weekly", label: "週報" },
+    ],
+  },
+];
+
+const MEMBERS: ChatSuggestionItemProp[] = [
+  { value: "sato", label: "佐藤 花子", description: "経理" },
+  { value: "tanaka", label: "田中 太郎", description: "開発" },
+  { value: "nguyen", label: "Nguyễn Minh", description: "Design" },
+];
+
+const CHANNELS: ChatSuggestionItemProp[] = [
+  { value: "general", label: "general", description: "全社アナウンス" },
+  { value: "accounting", label: "accounting", description: "経理チーム" },
+];
+
+export default function Demo() {
+  const [slashDraft, setSlashDraft] = useState("");
+  const [mentionDraft, setMentionDraft] = useState("");
+  const [channelDraft, setChannelDraft] = useState("");
+  const [emptyDraft, setEmptyDraft] = useState("");
+  const [controlledDraft, setControlledDraft] = useState("");
+  const [controlledOpen, setControlledOpen] = useState(false);
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          activeId="chat"
+          sections={sections}
+          onSelect={() => {}}
+          product={{ name: "CoreDesk", role: "アシスタント", color: "hsl(var(--primary))" }}
+        />
+      }
+      topbar={
+        <Topbar
+          start={
+            <Avatar className="rounded-md">
+              <AvatarFallback className="bg-primary text-primary-foreground font-bold">
+                C
+              </AvatarFallback>
+            </Avatar>
+          }
+        />
+      }
+    >
+      <PageContainer
+        title="入力補完"
+        subtitle="ChatSuggestion · トリガー文字 / 階層 / 無効行 / 該当なし / 制御された開閉"
+        breadcrumb={[{ label: "アシスタント", to: "#" }, { label: "入力補完" }]}
+      >
+        <Flex direction="col" gap="lg">
+          {/* ── 1. The default trigger, and one level of children ────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>
+                <Slash aria-hidden="true" />
+                スラッシュコマンド
+              </CardTitle>
+              <CardDescription>
+                「/」を入力すると開きます。「テンプレート」は子を持つので、Enter
+                はまだ確定せず一段深く入ります。Escape
+                は閉じるだけで、入力済みの文字はそのまま残ります。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <ChatSuggestion
+                items={COMMANDS}
+                onValueChange={(value) => setSlashDraft(`/${value} `)}
+              >
+                {({ onTrigger, onKeyDown }) => (
+                  <ChatComposer
+                    id="slash-composer"
+                    aria-label="スラッシュコマンドを試す"
+                    value={slashDraft}
+                    onValueChange={(next) => {
+                      setSlashDraft(next);
+                      onTrigger(next);
+                    }}
+                    onKeyDown={onKeyDown}
+                    onSubmit={() => setSlashDraft("")}
+                    placeholder="「/」でコマンド一覧"
+                  />
+                )}
+              </ChatSuggestion>
+            </CardContent>
+          </Card>
+
+          {/* ── 2. triggerCharacter="@" ──────────────────────────────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>
+                <AtSign aria-hidden="true" />
+                triggerCharacter=&quot;@&quot;
+              </CardTitle>
+              <CardDescription>
+                トリガー文字は差し替えられます。1つの入力欄に対して1つの
+                ChatSuggestion — 2種類を同時に見張るのではなく、用途ごとに別の欄にします。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <ChatSuggestion
+                items={MEMBERS}
+                triggerCharacter="@"
+                onValueChange={(value) => setMentionDraft(`@${value} `)}
+              >
+                {({ onTrigger, onKeyDown }) => (
+                  <ChatComposer
+                    id="mention-composer"
+                    aria-label="メンバーをメンション"
+                    value={mentionDraft}
+                    onValueChange={(next) => {
+                      setMentionDraft(next);
+                      onTrigger(next);
+                    }}
+                    onKeyDown={onKeyDown}
+                    onSubmit={() => setMentionDraft("")}
+                    placeholder="「@」でメンバー一覧"
+                  />
+                )}
+              </ChatSuggestion>
+            </CardContent>
+          </Card>
+
+          {/* ── 3. triggerCharacter="#" ──────────────────────────────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>
+                <Hash aria-hidden="true" />
+                triggerCharacter=&quot;#&quot;
+              </CardTitle>
+              <CardDescription>チャンネル参照。項目が少なくても扱いは同じです。</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <ChatSuggestion
+                items={CHANNELS}
+                triggerCharacter="#"
+                onValueChange={(value) => setChannelDraft(`#${value} `)}
+              >
+                {({ onTrigger, onKeyDown }) => (
+                  <ChatComposer
+                    id="channel-composer"
+                    aria-label="チャンネルを参照"
+                    value={channelDraft}
+                    onValueChange={(next) => {
+                      setChannelDraft(next);
+                      onTrigger(next);
+                    }}
+                    onKeyDown={onKeyDown}
+                    onSubmit={() => setChannelDraft("")}
+                    placeholder="「#」でチャンネル一覧"
+                    size="sm"
+                  />
+                )}
+              </ChatSuggestion>
+            </CardContent>
+          </Card>
+
+          {/* ── 4. No items — the empty state is the component's, not the caller's ───────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>該当なし</CardTitle>
+              <CardDescription>
+                候補が0件でもパネルは開き、件数は読み上げ用の status
+                で通知されます。空の list を黙って閉じると、利用者には「効かない」ように見えます。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <ChatSuggestion items={[]} onValueChange={() => {}}>
+                {({ onTrigger, onKeyDown }) => (
+                  <ChatComposer
+                    id="empty-composer"
+                    aria-label="候補が0件の例"
+                    value={emptyDraft}
+                    onValueChange={(next) => {
+                      setEmptyDraft(next);
+                      onTrigger(next);
+                    }}
+                    onKeyDown={onKeyDown}
+                    onSubmit={() => setEmptyDraft("")}
+                    placeholder="「/」を押しても候補はありません"
+                  />
+                )}
+              </ChatSuggestion>
+            </CardContent>
+          </Card>
+
+          {/* ── 5. open / onOpenChange — the controlled triad ────────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>open · onOpenChange</CardTitle>
+              <CardDescription>
+                開閉も制御できます。下の行は現在の状態をそのまま映したもので、
+                トリガー文字・Escape・語の区切りのいずれでも同じ値が動きます。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Flex direction="col" gap="sm">
+                <ChatSuggestion
+                  items={COMMANDS}
+                  open={controlledOpen}
+                  onOpenChange={setControlledOpen}
+                  onValueChange={(value) => setControlledDraft(`/${value} `)}
+                >
+                  {({ onTrigger, onKeyDown }) => (
+                    <ChatComposer
+                      id="controlled-composer"
+                      aria-label="開閉を制御した例"
+                      value={controlledDraft}
+                      onValueChange={(next) => {
+                        setControlledDraft(next);
+                        onTrigger(next);
+                      }}
+                      onKeyDown={onKeyDown}
+                      onSubmit={() => setControlledDraft("")}
+                      placeholder="「/」で開き、Escape で閉じます"
+                    />
+                  )}
+                </ChatSuggestion>
+                <Text size="xs" tone="muted">
+                  open = {controlledOpen ? "true" : "false"}
+                </Text>
+              </Flex>
+            </CardContent>
+          </Card>
+        </Flex>
+      </PageContainer>
+    </AppShell>
+  );
+}

package/docs/roadmap/ai-chat-components.md

@@ -0,0 +1,207 @@
+# AI / chatbot components — normalized spec
+
+> **Reference:** Ant Design X (<https://x.ant.design/components/overview>) for *capabilities*.
+> **Naming:** when a component's identity is unclear, look it up at
+> <https://namethatui.com/?platform=web> before inventing a name.
+> **Contract:** `.claude/skills/godxjp-ui-component/SKILL.md` is the hard gate — MCP-first, real
+> primitives only, `t()` + `Intl`, WAI-ARIA APG + WCAG 2.2 AA + vitest-axe, logical CSS, controlled
+> vocabulary, semantic tokens, MCP catalog entry, real-screen docs page.
+
+The library has **zero** chat/AI components today (verified against `mcp/src/data/components.ts` —
+127 entries, none of them conversational). This document decides which of Ant Design X's surface
+becomes a framework component and which is a composition, so no agent has to re-litigate it.
+
+## 1. Scope decision — GATE 0 applied to every Ant Design X component
+
+`docs/COMPOSITION-VS-COMPONENT.md` C1–C7. **Any FAIL ⇒ composition, never `src/components/`.**
+
+| Ant Design X | godx name | Group | C1 | C2 | C3 | C4 | C5 | C6 | C7 | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `Bubble` | **`ChatBubble`** | `data-display` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Bubble.List` | **`ChatBubbleList`** | `data-display` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Sender` | **`ChatComposer`** | `data-entry` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Suggestion` | **`ChatSuggestion`** | `data-entry` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Framework component** |
+| `Conversations` | **`ConversationList`** | `navigation` | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | **Verify C3 first** — see §6 |
+| `ThoughtChain` / `Think` | **`ThoughtChain`** | `data-display` | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ✅ | ⚠️ | **Verify C2/C3 first** — see §6 |
+| `Prompts` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `ResponsiveGrid` + `Card` + `Button` |
+| `Welcome` | — | — | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — static block, `EmptyState`-shaped |
+| `Actions` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `Button` + `DropdownMenu` |
+| `Attachments` / `FileCard` | — | — | ✅ | ✅ | ❌ | — | — | — | — | **Extend `Upload`** — duplicating it is an instant reject |
+| `CodeHighlighter` | — | — | — | — | ❌ | — | — | — | — | **Use `CodeBlock`** |
+| `Sources` | — | — | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | **Composition** — `ListRow` + `Badge` |
+| `XProvider` | — | — | — | — | ❌ | — | — | — | — | **Use `AppProvider`** |
+| `Mermaid` | — | — | ❌ | — | — | — | — | — | ❌ | **Out of scope** |
+| `Folder/File Tree` | — | — | — | — | ❌ | — | — | — | — | **Covered by `Tree`** — see `docs/roadmap/tree-components.md` |
+
+**v1 build set: `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`** (4 components,
+all 7/7 PASS). `ConversationList` and `ThoughtChain` are conditional — §6.
+Everything else ships as a `docs/` showcase composition, not library code.
+
+---
+
+## 2. `ChatBubble` — one message in a conversation
+
+**Group:** `data-display` · **File:** `src/components/data-display/chat-bubble.tsx`
+
+| Ant Design X | **godx `ChatBubble`** |
+| --- | --- |
+| `content` | `children` (a `ReactNode`; do not take an HTML string) |
+| `placement: 'start' \| 'end'` | `placement: 'start' \| 'end'` (logical — flips under RTL) |
+| `variant: 'filled' \| 'borderless' \| 'outlined' \| 'shadow'` | `variant: 'filled' \| 'borderless' \| 'outlined'` (drop `shadow`; the design system is 1px-border, no drop shadows) |
+| `avatar` | `avatar` (a real `Avatar` node, never a styled div) |
+| `header` / `footer` | `header` / `footer` |
+| `loading` | `loading` (renders `Skeleton`, `aria-busy="true"`) |
+| `typing` | `typing: boolean \| { step?: number; interval?: number }` |
+| `messageRender` | *dropped* — the caller passes rendered `children` |
+| `shape` | *dropped* — corner radius is a token |
+| — | `size: 'xs' \| 'sm' \| 'lg'` (`md` default) |
+| — | `tone` for status-tinted bubbles (error/warning), never colour-only |
+
+**Semantics.** The bubble is an `<article>` inside the list's feed. Give it an accessible name from
+its `header` (the author). The typing animation MUST respect `prefers-reduced-motion: reduce` —
+render the full text immediately, no animation. Streaming text goes in an `aria-live="polite"`
+region owned by `ChatBubbleList`, **not** per-bubble (a live region per bubble floods a screen
+reader). Decorative avatars `aria-hidden`.
+
+**Tokens** (`src/tokens/components/chat-bubble.css`): `--chat-bubble-background`,
+`--chat-bubble-foreground`, `--chat-bubble-border-color`, `--chat-bubble-radius`,
+`--chat-bubble-gap`, `--chat-bubble-max-inline-size`, `--chat-bubble-avatar-size`.
+Role-mirror knobs default to `initial` (`docs/TOKENS.md`).
+
+**i18n:** `chat.bubble.typing`, `chat.bubble.loading`, `chat.bubble.you`, `chat.bubble.assistant`.
+Timestamps via `Intl.DateTimeFormat`; "2 minutes ago" via `Intl.RelativeTimeFormat`; counted nouns
+via `Intl.PluralRules` — never a template string.
+
+---
+
+## 3. `ChatBubbleList` — the message feed
+
+**Group:** `data-display` · **File:** same module as `ChatBubble`
+
+| Ant Design X `Bubble.List` | **godx `ChatBubbleList`** |
+| --- | --- |
+| `items` | `items: ChatMessageProp[]` |
+| `roles` | `roles: Record<string, Partial<ChatBubbleProp>>` — per-role defaults (`user`, `assistant`, `system`) |
+| `autoScroll` | `autoScroll` (default `true`) |
+
+**The behavior that earns C2/C3** — none of it is composable from `ScrollArea` + `map`:
+
+1. **Stick-to-bottom.** Auto-scroll while the user is at the bottom; the moment they scroll up,
+   **stop** and surface a "jump to latest" affordance. Silently yanking a reader back to the bottom
+   mid-read is the classic chat-UI defect.
+2. **Streaming without layout thrash** — appended text must not re-scroll the whole feed.
+3. **One `aria-live="polite"` region** for the whole feed, announcing only the newest message.
+4. `role="log"` on the scroll container, `aria-label` via `t()`.
+5. Keyboard: the feed is focusable and scrollable with `PageUp`/`PageDown`/`Home`/`End`; bubbles
+   are not a roving-tabindex widget (interactive controls inside them keep normal tab order).
+
+---
+
+## 4. `ChatComposer` — the message input (Ant's `Sender`)
+
+**Group:** `data-entry` · **File:** `src/components/data-entry/chat-composer.tsx`
+
+Named for what the industry calls it (Slack/Discord "composer"); `Sender` describes the person,
+not the control.
+
+| Ant Design X `Sender` | **godx `ChatComposer`** |
+| --- | --- |
+| `value` / `onChange` | `value` / `defaultValue` / `onValueChange` (**controlled triad — mandatory**) |
+| `onSubmit` | `onSubmit(value: string)` |
+| `loading` + `onCancel` | `loading` + `onCancel` |
+| `submitType: 'enter' \| 'shiftEnter'` | `submitType: 'enter' \| 'shiftEnter'` |
+| `placeholder` | `placeholder` (through `t()` at the call site) |
+| `disabled` / `readOnly` | `disabled` / `readOnly` |
+| `header` (`Sender.Header`) | `header` slot |
+| `prefix` / `footer` / `actions` | `prefix` / `footer` / `actions` slots |
+| `allowSpeech` | **out of scope v1** — Web Speech API is not cross-browser; file a follow-up |
+| `autoSize` | always auto-sizing; not a prop |
+| — | `size: 'xs' \| 'sm' \| 'lg'` · `maxLength` · `status` |
+
+**Rules.**
+- Built on the real `Textarea` primitive and real `Button`s — **no raw `<textarea>`/`<button>`**.
+- Auto-grow between a min and max height expressed in `--control-height` tiers, then scroll
+  inside. **No literal `height` and no `calc(var(--control-height) ± …)`** (`check:control-sizing`).
+- `submitType="enter"`: `Enter` submits, `Shift+Enter` newline. `submitType="shiftEnter"`: the
+  inverse. IME composition must never submit — guard on `compositionstart`/`compositionend`
+  (this is the bug that breaks Japanese and Vietnamese input; it is not optional).
+- Empty or whitespace-only input does not submit; the submit button is `disabled` with an
+  accessible name, not merely greyed out.
+- While `loading`, the submit button becomes a cancel button — **one trailing action at a time**,
+  the same discipline as the picker trailing-action rule.
+- The textarea is the semantic focus target; forward the `FormField` label/helper/error contract
+  onto it via `pickFieldA11y` / `useFieldIdentity` — do not reinvent it (`src/lib/field-a11y.ts`).
+
+---
+
+## 5. `ChatSuggestion` — trigger-character autocomplete over the composer
+
+**Group:** `data-entry` · **File:** `src/components/data-entry/chat-suggestion.tsx`
+
+| Ant Design X `Suggestion` | **godx `ChatSuggestion`** |
+| --- | --- |
+| `items` | `items: SuggestionItemProp[]` (supports one level of `children`) |
+| `onSelect` | `onValueChange(value: string)` |
+| `block` | *dropped* — width follows the anchor |
+| render-prop `children({ onTrigger, onKeyDown })` | same shape — it wraps `ChatComposer` |
+| — | `triggerCharacter` (default `'/'`) · `open` / `defaultOpen` / `onOpenChange` |
+
+**Rules.** Compose the existing `Command` (cmdk) inside a `Popover` anchored to the composer — do
+**not** hand-roll a listbox; `Command` already ships correct ARIA. What this component owns is the
+part `Command` does not: detecting the trigger character in a textarea, tracking the query as the
+caret moves, and closing on `Escape`/blur/word-break. `Escape` returns focus to the textarea and
+leaves the typed text intact.
+
+---
+
+## 6. Conditional components — prove C3 before writing code
+
+Do **not** start these until the ledger is recorded in the PR description.
+
+**`ConversationList`** (Ant's `Conversations`). `NavList` already renders selectable rows with
+`aria-current="page"`, an icon column and a badge; `ListRow` covers short entity lists. Before
+building, answer in writing: what does a conversation list own that `NavList` does not?
+The honest candidates are date **grouping** (Today / Yesterday / Last 7 days — via
+`Intl.RelativeTimeFormat` + `Intl.DateTimeFormat`, never hand-rolled buckets), a **per-item
+overflow menu**, and **inline rename**. If those land as `NavList` props instead, that is the
+better outcome — extend `NavList` and close this out.
+
+**`ThoughtChain`** (Ant's `ThoughtChain` / `Think`). `Timeline` already has a 3-state per-item
+`status` (`done`/`current`/`pending`), an icon rail and ordinal/status variants; `Collapsible`
+owns disclosure. `ThoughtChain` = `Timeline` + per-item collapsible body + a streaming/pending
+state. Strongly prefer adding a `collapsible` affordance to `Timeline` over a new component.
+Whichever way it goes, the reasoning body must be collapsible, and the running step must be
+announced once via `aria-live="polite"` — not on every token.
+
+---
+
+## 7. Per-component definition of done
+
+Every component in the build set ships **all** of:
+
+1. `src/components/<group>/<name>.tsx` — real primitives only, logical CSS, `t()` for every string
+   and `aria-label`, `ref` forwarded, `...props` spread, `className` + `id` accepted.
+2. `XProp` + `XProp as XProps` in `src/props/components/<group>.prop.ts`, **registered in
+   `src/props/registry.ts`**.
+3. `src/tokens/components/<name>.css` + an `@import` in `src/tokens/base.css`; names pass
+   `check:token-tiers`; control boxes come from the `--control-height` tier.
+4. Keys in `src/i18n/messages/en.json`, `vi.json`, `ja.json` — all three, no exceptions.
+5. Tests in `src/components/<group>/__tests__/`: a behavior test using `@testing-library/user-event`
+   **and** a `<name>.a11y.test.tsx` with `expectNoA11yViolations` at **0 violations**.
+6. An `mcp/src/data/components.ts` entry (props / usage / useCases / related / example / rules) —
+   `check:mcp-sync` and `check:mcp-orphans` must pass.
+7. A real-screen docs page under `docs/<group>/` (AppShell + PageContainer + real primitives), not
+   a bare `Card` snippet.
+8. Export from the group's `index.ts`.
+
+Gates, then **only** the touched group's tests:
+
+```
+pnpm typecheck && pnpm lint && pnpm run audit \
+  && pnpm check:prop-vocabulary && pnpm check:mcp-sync && pnpm check:mcp-orphans \
+  && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:example-imports
+pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2
+```
+
+`pnpm test` and a bare `pnpm vitest run` are **forbidden** — 506 files / 3700+ tests, and several
+agents on one machine takes the load past 90. The full suite is CI's job on the PR.

package/docs/roadmap/antd-parity.md

@@ -0,0 +1,154 @@
+# Ant Design parity — the audit programme
+
+> The complaint is systemic: *"hầu hết các component thiếu tính năng so với Ant Design."*
+> This document is the **method**, so that 127 catalog entries can be audited by different agents
+> and still produce comparable, reviewable results. Per-component specs live in sibling files.
+
+## 0. Ground rules (a parity gap is not a licence to copy Ant Design)
+
+1. **Capabilities are the target; prop names are not.** Map every antd prop onto
+   `docs/PROPS-VOCABULARY.md` — controlled triad `value`/`defaultValue`/`onValueChange`,
+   overlays `open`/`defaultOpen`/`onOpenChange`, `size ∈ xs|sm|md|lg` (never `"default"`),
+   `tone` for status, positive booleans. Where the library already has a spelling
+   (`getRowId`, `gap`, `columns: {base,sm,md,lg}`, `count`/`overflowCount`/`showZero`), **reuse it**.
+   A third dialect of the same idea is the defect this repo keeps paying to fix.
+2. **GATE 0 still applies.** A missing antd component is not automatically a framework component.
+   Run the C1–C7 test in `docs/COMPOSITION-VS-COMPONENT.md` and publish the ledger. Ant ships
+   things that are compositions here (`Badge.Ribbon`, `Welcome`, `Prompts`).
+3. **Do not duplicate what exists.** Ant's `CheckableTag` is this library's `Toggle`. Ant's
+   searchable select is `Select showSearch`. Check the MCP catalog before proposing anything.
+4. **Do not port antd's mistakes.** Skip `styles={{…}}` inline-style twins (this system themes with
+   tokens), pixel `offset` pairs, and physical `left/right` spellings.
+5. **A gap is only real once measured.** Cite the file and line, or the absence of a grep hit.
+   "Looks less capable than antd" is not a finding.
+
+## 1. Spacing, geometry and token names — the rules already exist, so use them
+
+This library is instrumented with ~60 checkers. Anything you write — **a spec document included** —
+is machine-checkable, so check it before you hand it to anyone.
+
+**Spacing is not free-form.** `docs/SPACING.md` is binding:
+
+- Macro layout uses a **φ modular scale (≈1.618)**, *not* the 8pt grid. `xs`/`sm` = 4px grid,
+  `md` = φ⁰, `lg` = φ¹, `xl` = φ². Applying Material's 8pt grid here is wrong, not "standard".
+- Tailwind `p-*` / `m-*` / `gap-*` are rejected by `no-utility-spacing`; hand-rolled `flex`/`grid`
+  by `no-utility-layout`. Rows are `<Flex>`, stacks `<Flex direction="col" gap>`, grids
+  `<ResponsiveGrid>`, page sections spaced by `<PageContainer>` itself.
+- **Card padding has a single owner**: `src/styles/card-layout.css`. Anything else that must sit on
+  the same rhythm uses `ui-card-inset-x` / `ui-card-inset-y` / `ui-card-inset` — and those three do
+  **not** share one value. Never invent a per-component inline-padding token where the Card already
+  owns the inset.
+
+**Component token names must match this exact shape** — `check:token-tiers` enforces it:
+
+```
+--{component}-{part}-{property}
+```
+
+where `{property}` is one of: `space color background foreground border radius height width padding
+gap size font line letter shadow glow tint gradient alpha align inset offset translate max overflow
+display`.
+
+`surface`, `bg`, `fg`, `spacing` are **not** accepted words. Control boxes come from the
+`--control-height` tier — never a literal height, never `calc(var(--control-height) ± …)`
+(`check:control-sizing`), never a Tailwind scale literal (`check:no-hardcoded-geometry` —
+even `min-w-0` fails).
+
+**Before handing over any doc or spec, run at minimum:**
+
+```
+pnpm check:doc-prop-existence   # a prop named in an example must exist on that component —
+                                # including a prop you only meant as an Ant Design illustration
+pnpm check:token-tiers && pnpm check:no-hardcoded-geometry && pnpm run audit
+```
+
+This section exists because it was violated: a comparison table in
+`badge-tag-chip-count.md` wrote an antd `Badge` + `count` example to illustrate *Ant's* API and
+`check:doc-prop-existence` correctly read it as a claim about *ours*; and three specs named tokens
+`--…-surface` / `--…-bg`, which the shape above forbids. Both were caught by gates that already
+existed and simply had not been run.
+
+## 2. The ledger format — every audit produces exactly this table
+
+One row per antd capability. No prose findings.
+
+| Ant Design prop / behaviour | Status | Evidence | Verdict |
+| --- | --- | --- | --- |
+| `<prop>` — one-line meaning | `PRESENT` / `RENAMED` / `COVERED-ELSEWHERE` / `MISSING` / `WONT-PORT` | `src/…:line`, or the grep that found nothing | for `MISSING`: the godx prop name to add, or "composition" |
+
+- `RENAMED` — present under the house spelling. Record both names; no work.
+- `COVERED-ELSEWHERE` — another primitive owns it. Name it. No work, but add a `related` cross-link
+  in the catalog **on both sides** (a one-sided claim is the mistake commit `8365bf05` fixed).
+- `WONT-PORT` — a deliberate refusal. State the reason in the catalog entry so nobody re-adds it.
+
+Close every audit with a **priority call**: `P0` (breaks a real screen), `P1` (a workaround exists
+but it is hand-rolled and a11y-risky), `P2` (nice to have).
+
+## 3. Findings so far
+
+### 3.1 Already specced — see the sibling documents
+
+| Area | Verdict | Spec |
+| --- | --- | --- |
+| `Tree` / `TreeList` / `TreeSelect` | `TreeSelect` fine; `TreeList` is not a tree; **`Tree` missing entirely** | `tree-components.md` |
+| Badge / Tag / Chip / Pill / Count | Count marker missing entirely; removable chip trapped inside `TagInput`; selectable chip already is `Toggle` | `badge-tag-chip-count.md` |
+| `List` (Ant `Listy`) / `Masonry` | Both missing entirely — no virtualization and no column packing anywhere in `src/` | `list-masonry.md` |
+| AI / chat surface | Nothing exists; 4 components + 6 compositions decided | `ai-chat-components.md` |
+
+### 3.2 `Tabs`, `Steps`, `Segmented` — audited 2026-09-10
+
+These three are **already deliberately Ant-aligned** — the prop types cite antd by name. The
+remaining gaps are narrow, and none of them is P0.
+
+**`Tabs`** (`src/props/components/navigation.prop.ts:301`, `src/components/navigation/tabs.tsx`).
+Present: `items` (incl. `closable`/`closeIcon`/`icon`), `value`/`defaultValue`/`onValueChange`,
+`variant` (`line`/`card`/`editable-card`), `tabPlacement`, `centered`, `extra`
+(= antd `tabBarExtraContent`), `destroyOnHidden`, `onEdit`, `addIcon`, `hideAdd`. Overflow already
+scrolls and keeps the active tab visible (`src/components/navigation/tabs-scroll.ts`).
+
+| Gap | Priority | Verdict |
+| --- | --- | --- |
+| `moreIcon` + an overflow **"more" dropdown** when the strip cannot scroll (narrow viewports) | **P1** | Add. Scrolling alone hides tabs from a touch user with no affordance. |
+| `indicator: { size, align }` | P2 | Add as tokens (`--tabs-indicator-*`), not props — it is a design knob (cardinal rule #44). |
+| `tabBarGutter` | P2 | Token, not a prop. |
+| `animated` | P2 | `WONT-PORT` as a prop — motion is a system decision and must follow `prefers-reduced-motion`. |
+| `renderTabBar` | P2 | `WONT-PORT` — an escape hatch that lets a consumer bypass the a11y contract. |
+| `size` lacks `xs` | P2 | Add `xs` for the full `xs\|sm\|md\|lg` tier. |
+
+**`Steps`** (`src/props/components/navigation.prop.ts:201-240`).
+Present: `items` (`title`/`subtitle`/`description`/`icon`/`status`/`disabled`),
+`value`/`defaultValue`/`onValueChange`, `orientation`, `status`, `type`
+(`default`/`dot`/`inline`/`navigation` — `dot` **is** antd's deprecated `progressDot`), `percent`,
+`titlePlacement`, `separator`.
+
+| Gap | Priority | Verdict |
+| --- | --- | --- |
+| `initial` — start the visible numbering at N | P2 | Add. Trivial, and real for resumed wizards. |
+| `responsive` — auto-switch to vertical on a narrow container | **P1** | Add. Today a horizontal 5-step bar on a phone is the caller's problem. |
+| `size` is `md\|sm` only | P2 | Extend to `xs\|sm\|md\|lg`. |
+
+**`Segmented`** (`src/components/ui/segmented.tsx`). Built on Radix `RadioGroup` — the correct APG
+choice, and the comment explaining why it is not a `ToggleGroup` should be preserved verbatim.
+Present: `options` (`value`/`label`/`icon`/`disabled`), `value`/`defaultValue`/`onValueChange`,
+`block`, `vertical`, `size`, `disabled`, `name`.
+
+| Gap | Priority | Verdict |
+| --- | --- | --- |
+| `shape: 'default' \| 'round'` | P2 | Add as `shape` — the existing `ShapeProp` vocabulary already has `pill`; reuse it rather than antd's `round`. |
+| Option as a bare `string \| number` | P2 | Add. Ant accepts it; it removes ceremony for the common case. |
+| Per-option `title` (a tooltip / hover hint) | P2 | `COVERED-ELSEWHERE` — wrap the option in `Tooltip`. Do not add a second tooltip API. |
+| `size` lacks `xs` | P2 | Add. |
+
+**None of these three is the source of the "doesn't look like Ant Design" impression** — that is
+`TreeList`, the missing count badge, and the missing `List`/`Masonry`/`Tree`.
+
+## 4. How to run an audit (per component group)
+
+1. Read the group's catalog entries in `mcp/src/data/components.ts` and the prop types in
+   `src/props/components/<group>.prop.ts`.
+2. Fetch the matching Ant Design docs page for each. Where a component's *identity* is unclear,
+   settle it at <https://namethatui.com/?platform=web> before writing anything.
+3. Produce the §2 ledger per component. Cite file:line.
+4. Publish a GATE-0 C1–C7 ledger for anything proposed as a **new** component.
+5. Do **not** write source in an audit pass. An audit is read-only; fixes are a separate wave with
+   their own spec, so the diff stays reviewable and two agents never edit one file at once.