@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/Cascader.json

@@ -0,0 +1,209 @@
+{
+  "example": "{`import { Cascader } from \"@godxjp/ui/data-entry\";\n\nconst REGIONS = [\n  {\n    value: \"jp\",\n    label: \"日本\",\n    content: [\n      {\n        value: \"tokyo\",\n        label: \"東京都\",\n        content: [\n          { value: \"shinjuku\", label: \"新宿区\" },\n          { value: \"shibuya\", label: \"渋谷区\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"vn\",\n    label: \"Việt Nam\",\n    content: [\n      {\n        value: \"hcm\",\n        label: \"TP. Hồ Chí Minh\",\n        content: [\n          { value: \"q1\", label: \"Quận 1\" },\n          { value: \"q3\", label: \"Quận 3\" },\n        ],\n      },\n    ],\n  },\n];\n\n// Controlled single-path\nfunction RegionPicker() {\n  const [path, setPath] = React.useState<string[]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      value={path}\n      onValueChange={(v) => setPath(v as string[])}\n      showSearch\n      placeholder=\"Select region…\"\n    />\n  );\n}\n\n// Multi-path (multiple selection)\nfunction MultiRegionPicker() {\n  const [paths, setPaths] = React.useState<string[][]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      multiple\n      value={paths}\n      onValueChange={(v) => setPaths(v as string[][])}\n      showSearch\n    />\n  );\n}\n\n// With custom field names (data uses 'name'/'id'/'nodes')\n<Cascader\n  options={rawApiData}\n  fieldNames={{ label: \"name\", value: \"id\", content: \"nodes\" }}\n  defaultValue={[\"dept-1\", \"team-3\"]}\n/>\n\n// changeOnSelect: lets user pick a branch node (not only leaves)\n<Cascader\n  options={REGIONS}\n  changeOnSelect\n  onValueChange={(v) => console.log(\"path\", v)}\n/>\n`}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Cascader",
+  "props": [
+    {
+      "description": "Native form field name; repeated values for multiple paths.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Prevent edits while preserving the displayed value.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "The hierarchical option tree. Each node has { value: string; label: ReactNode; disabled?: boolean; isLeaf?: boolean; children?: TreeOptionProp[] }. Normalised internally via fieldNames.",
+      "name": "options",
+      "required": true,
+      "type": "TreeOptionProp[]"
+    },
+    {
+      "description": "Controlled value. Single mode: string[] path (e.g. ['vn','hcm','q1']). Multiple mode: string[][] array of paths.",
+      "name": "value",
+      "type": "string[] | string[][]"
+    },
+    {
+      "description": "Initial value for uncontrolled mode. Same shape as value.",
+      "name": "defaultValue",
+      "type": "string[] | string[][]"
+    },
+    {
+      "description": "Fires when selection changes. First arg is the selected path(s); second is the matching node objects. On clear, called with [].",
+      "name": "onValueChange",
+      "type": "(value: string[] | string[][], selectedOptions?: TreeOptionProp[] | TreeOptionProp[][]) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Enable multi-path selection. Renders checkboxes in columns and search results. Panel stays open on each pick. value/defaultValue become string[][].",
+      "name": "multiple",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, clicking any node (including branch nodes with children) commits that path immediately instead of waiting for a leaf selection.",
+      "name": "changeOnSelect",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Renders a CommandInput at the top of the popover. Filters to matching leaf paths across the whole tree when a query is typed; reverts to cascade columns when the query is cleared.",
+      "name": "showSearch",
+      "type": "boolean"
+    },
+    {
+      "description": "Trigger button placeholder text when no value is selected. Defaults to the i18n key dataEntry.cascader.placeholder.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables the trigger button and prevents the popover from opening.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"click\"",
+      "description": "How child columns are expanded. 'hover' expands on mouseenter and collapses back on mouseleave.",
+      "name": "expandTrigger",
+      "type": "\"click\" | \"hover\""
+    },
+    {
+      "description": "Remap custom data keys: { label?: string; value?: string; children?: string }. Use when your data uses e.g. 'name' and 'id' instead of 'label' and 'value'.",
+      "name": "fieldNames",
+      "type": "TreeFieldNamesProp"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Shows an X icon on the trigger when a value is selected. Clicking it calls onChange([]) and resets to placeholder. On by default, as antd Cascader; pass `false` on a required field.",
+      "name": "allowClear",
+      "type": "boolean"
+    },
+    {
+      "description": "Extra Tailwind classes applied to the trigger button.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "HTML id forwarded to the trigger button. Use to associate a <label htmlFor>.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "antd `status`. `error` recolours the control AND sets aria-invalid (a colour-only error fails WCAG 2.2 SC 1.4.1); `warning` recolours only. An aria-invalid injected by FormField always wins.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "antd `variant` — the control surface. Default `outlined`. Drawn from --control-{surface,filled,borderless}-* tokens, so a theme retunes all three at once.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "antd `loading` — the FIELD is in flight: the trailing chevron becomes a spinner and the trigger reports aria-busy. Distinct from the list-level spinner an async loadOptions shows inside the popup.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `size` — height tier on the shared --control-height ladder.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "antd `open` — controlled panel state. The consumer is the authority: nothing internal closes a pinned panel.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `defaultOpen` — uncontrolled initial panel state.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `onOpenChange` — fires for both controlled and uncontrolled panels.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "antd `maxTagCount` — how many selected values stay visible before the rest collapse into the overflow node. antd's `\"responsive\"` is not supported (see the parity PR).",
+      "name": "maxTagCount",
+      "type": "number"
+    },
+    {
+      "description": "antd `maxTagPlaceholder` — the node standing in for what maxTagCount hid. Defaults to a localized `+N`.",
+      "name": "maxTagPlaceholder",
+      "type": "React.ReactNode | ((omitted: { value: string; label: React.ReactNode }[]) => React.ReactNode)"
+    },
+    {
+      "description": "antd `notFoundContent` — the node shown when the popup has nothing to list. Outranks the string-only emptyMessage.",
+      "name": "notFoundContent",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `autoClearSearchValue` (default true) — clear the search box after a pick / on close. Set false to resume the same filtered list on the next open.",
+      "name": "autoClearSearchValue",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `showCheckedStrategy` (multiple only). SHOW_PARENT collapses a fully-checked branch into the branch itself; SHOW_CHILD (default) lists the leaves.",
+      "name": "showCheckedStrategy",
+      "type": "\"SHOW_CHILD\" | \"SHOW_PARENT\""
+    },
+    {
+      "description": "antd `loadData` — lazy children. Called ONCE per branch that has no children and isLeaf !== true, the first time it is expanded; push the fetched children into options.",
+      "name": "loadData",
+      "type": "(selectedOptions: TreeOptionProp[]) => void | Promise<void>"
+    },
+    {
+      "description": "antd `displayRender` — owns the trigger label built from the selected path.",
+      "name": "displayRender",
+      "type": "(labels: string[], selectedOptions?: TreeOptionProp[]) => React.ReactNode"
+    },
+    {
+      "description": "antd `optionRender` — owns a column row's body. The checkbox, check mark and chevron stay with the component.",
+      "name": "optionRender",
+      "type": "(option: TreeOptionProp) => React.ReactNode"
+    },
+    {
+      "description": "Controlled search query (antd `showSearch.searchValue`).",
+      "name": "search",
+      "type": "string"
+    },
+    {
+      "description": "Search query change (antd `showSearch.onSearch`).",
+      "name": "onSearchChange",
+      "type": "(query: string) => void"
+    }
+  ],
+  "related": [
+    "TreeSelect — use when the hierarchy is a collapsible tree (expand/collapse nodes) rather than side-by-side columns, and when a single flat value string (node key) is sufficient instead of a full ancestor path. TreeSelect also supports treeCheckable for multi-select.",
+    "Select — use for a flat (non-hierarchical) list of options. Cascader is only needed when items have meaningful parent–child levels.",
+    "Transfer — use when the user needs to shuttle multiple items between two panels; not for hierarchical path selection."
+  ],
+  "rules": [
+    3,
+    6,
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Cascader.stories.tsx",
+  "tagline": "Multi-level hierarchical path picker (Popover + cascading columns); value is always a string[] path, never a flat ID — passing a bare string breaks it.",
+  "usage": [
+    "DO pass a string[] path as value in single mode (e.g. ['country','region','city']). DON'T pass a flat string ID — the component treats value as an ordered path array and will render nothing if you pass a bare string.",
+    "DO use value + onChange together for controlled mode, or defaultValue alone for uncontrolled. DON'T mix both — providing value without onChange makes the field read-only (the internal state won't update).",
+    "DO set multiple={true} and pass value as string[][] (array of paths) for multi-selection. onChange receives string[][] in that mode. Mixing single-mode shape with multiple={true} silently produces no selection.",
+    "DON'T hand-roll a search input next to Cascader. Use showSearch={true} — it adds a built-in CommandInput that filters leaf paths across the full tree and reverts to cascade columns when cleared.",
+    "DO use fieldNames to remap data keys ({label:'name', value:'id', children:'nodes'}) rather than pre-transforming your API data. This keeps options in their original shape.",
+    "For form submission, Cascader has no 'name' prop. Wrap in a controlled pattern and store the path array in your form state (useForm/useState). For Inertia useForm, keep the field as an array (e.g. data.categoryPath = ['a','b','c'])."
+  ],
+  "useCases": [
+    "Geographic drilldown (Country → Prefecture → City) for address or branch-office pickers in accounting or logistics forms.",
+    "Expense category selection (e.g. Operating Expenses → Marketing → Digital Ads) where the full classification path is required for the general ledger.",
+    "Product taxonomy navigation (Department → Category → Sub-category) in inventory or invoice line-item entry.",
+    "Organisational unit picker (Company → Division → Department) in budget allocation or approval-routing configurations.",
+    "Multi-region filter in a report or dashboard filter bar, using multiple={true} to allow selecting several leaf locations at once.",
+    "Any deeply nested classification where the relationship between levels is meaningful and must be captured — not just the leaf value."
+  ]
+}

package/agent/components/CenteredShell.json

@@ -0,0 +1,66 @@
+{
+  "example": "import { CenteredShell, Topbar, Flex } from \"@godxjp/ui/layout\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\nimport { Avatar, AvatarFallback, Card, CardContent, CardHeader, CardTitle } from \"@godxjp/ui/data-display\";\nimport { Button, Text } from \"@godxjp/ui/general\";\n\nexport function MyPage() {\n  return (\n    <CenteredShell\n      width=\"md\"\n      topbar={\n        <Topbar\n          start={\n            <Avatar className=\"rounded-md\">\n              <AvatarFallback className=\"bg-primary text-primary-foreground font-bold\">G</AvatarFallback>\n            </Avatar>\n          }\n          end={\n            <>\n              <AppSettingPicker kind=\"locale\" />\n              <Button variant=\"ghost\" size=\"sm\">田中 太郎</Button>\n            </>\n          }\n        />\n      }\n      footer={<Text size=\"xs\" tone=\"muted\">© 2026 GodX</Text>}\n    >\n      <Flex direction=\"col\" gap=\"lg\">\n        <Card>\n          <CardHeader><CardTitle level={1}>マイページ</CardTitle></CardHeader>\n          <CardContent>アカウントの概要。</CardContent>\n        </Card>\n      </Flex>\n    </CenteredShell>\n  );\n}",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "CenteredShell",
+  "props": [
+    {
+      "description": "Centred column content — page sections (identity hero, org picker, service grid, team list). Top-aligned and scrolls; NOT vertically centred like AuthShell's card.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Top bar slot (banner) — a <Topbar> with brand + real actions (AppSettingPicker, user menu, sign-out). Wrapped in the SAME padded chrome as AppShell's topbar (inline padding, border, backdrop) WITHOUT a sidebar; omit → no banner. Never hand-roll a bar (the bare Topbar ships no padding — the .ui-topbar zero-inset footgun).",
+      "name": "topbar",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Footer slot (contentinfo) pinned to the bottom (legal links, locale switch, support). Omit → no footer.",
+      "name": "footer",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Max-width of the centred column: sm ~32rem, md (default) ~46rem, lg ~64rem — all wider than AuthShell's 24rem auth card. A service retunes each tier via --centered-shell-width-*.",
+      "name": "width",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Block alignment of the centred column inside the 100dvh shell. \"start\" (default) keeps the top-aligned flowing/scrolling page shape. Overflowing content still scrolls from the top, so a long localized message is never clipped.",
+      "name": "align",
+      "type": "\"start\" | \"center\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Whole-page shell contract. \"default\" emits no attribute and keeps the exact box. \"public-landing\" owns the PUBLIC landing geometry: ONE content measure shared by the header bar, the centred column and the footer (--centered-shell-landing-max-width, 67.5rem), the section rhythm between page sections, the flat elevation-free card chrome (--centered-shell-landing-card-shadow: none) and the hero h1 tier — plus the compact step at 40rem. A landing composition therefore needs no page-local CSS, no max-width wrapper and no descendant selector against shell internals.",
+      "name": "preset",
+      "type": "\"default\" | \"public-landing\""
+    }
+  ],
+  "related": [
+    "AppShell — the shell for authenticated app pages WITH a sidebar nav rail. CenteredShell is its no-sidebar sibling (same padded topbar chrome, a centred column instead of a full-bleed main).",
+    "AuthShell — the UNAUTHENTICATED root shell (login/mfa/reset): a ~24rem card centred vertically, with its own banner `actions` slot and a `measure=\"wide\"` split-login measure. CenteredShell is the AUTHENTICATED centred-page counterpart. Never nest the two.",
+    "Topbar — compose it into `topbar`; CenteredShell supplies the padded chrome the bare Topbar lacks.",
+    "PageContainer — for a titled section INSIDE the column; or compose <Card>/<ResponsiveGrid> sections directly."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "layout/CenteredShell.stories.tsx",
+  "tagline": "Authenticated, no-sidebar, centred-column page shell (hosted-ID My Page / account / standalone settings) — padded topbar with real actions + a width-tiered centred column, zero custom CSS.",
+  "usage": [
+    "DO use CenteredShell for an AUTHENTICATED page that has a topbar with actions but NO sidebar — the hosted-ID 'My Page', an account / self-service surface, a standalone settings page. It is the third shell: AppShell (needs a sidebar) · AuthShell (unauthenticated narrow card) · CenteredShell (authenticated centred column).",
+    "DO put a <Topbar start={<brand/>} end={<actions/>}/> in `topbar` — CenteredShell wraps it in the padded `.app-topbar` chrome, so you get inline padding + border + backdrop with zero custom CSS. Do NOT hand-roll a bar with raw `padding-inline` — the bare Topbar primitive ships no inset (the .ui-topbar zero-padding footgun) and content sits flush to the edge.",
+    "DO pick `width` by content: `sm` (~32rem) for a single settings form, `md` (default, ~46rem) for a My Page of stacked sections, `lg` (~64rem) for a service-launcher grid. All are wider than AuthShell's 24rem card.",
+    "DO wrap an individual section in <Reveal> for entrance motion — CenteredShell stays layout-only and delegates prefers-reduced-motion handling to Reveal (same as AuthShell).",
+    "DO NOT use AuthShell for an authenticated page (it is the UNAUTHENTICATED root and imposes auth-card geometry), and DO NOT force AppShell with an empty sidebar — use CenteredShell. Conversely, do NOT reach for CenteredShell to build a login page: AuthShell has its own `actions` slot for the locale/theme controls and a `measure=\"wide\"` for the split brand-panel login. Never nest it inside AppShell/AuthShell (or vice-versa); it is a ROOT shell.",
+    "DO use `align=\"center\"` (+ `width=\"sm\"`) for a SYSTEM-level standalone page — a 500/503 error surface, a maintenance notice. It centres the column in the 100dvh shell at 1440/1024/390 with no consumer `min-h-dvh` / flex CSS and no className; the knob is --centered-shell-column-offset-block. For an actual 403/404/500/503 page do NOT wire this by hand — use `ErrorSurface`, which renders this shell itself in `mode=\"system\"`."
+  ],
+  "useCases": [
+    "Hosted GoDX ID 'My Page': <CenteredShell topbar={<Topbar start={<Brand/>} end={<><AppSettingPicker kind=\"locale\"/><UserMenu/></>}/>} footer={<Footer/>} width=\"md\"> with an identity hero, an org picker, a service-launcher grid and a team list.",
+    "Account / self-service settings surface (no admin sidebar): stacked <Card> sections (profile, security, sessions) in a centred `md` column under a topbar with a user menu.",
+    "Standalone single settings page: `width=\"sm\"` with one <Card> of <Field>s and a save action.",
+    "System error / maintenance page (500 · 503): `<CenteredShell align=\"center\" width=\"sm\">` around the canonical error body (status code <Text mono tabular> + <EmptyState icon tone title description action> + optional request-ID / maintenance line). See the `error-pages` pattern.",
+    "Service launcher / app picker after sign-in: `width=\"lg\"` with a <ResponsiveGrid> of app cards under the brand topbar."
+  ]
+}

package/agent/components/ChatBubble.json

@@ -0,0 +1,100 @@
+{
+  "docPath": "data-display/chat-bubble.tsx",
+  "example": "import { Avatar, AvatarFallback, ChatBubble } from \"@godxjp/ui/data-display\";\nimport { formatAppTime } from \"@godxjp/ui/datetime\";\n\n<ChatBubble\n  placement=\"start\"\n  variant=\"filled\"\n  avatar={<Avatar aria-hidden=\"true\"><AvatarFallback>AI</AvatarFallback></Avatar>}\n  header={t(\"chat.bubble.assistant\")}\n  footer={formatAppTime(message.sentAt)}\n  typing={{ step: 2, interval: 24 }}\n>\n  {message.text}\n</ChatBubble>\n\n// The reply has been requested and has not arrived yet.\n<ChatBubble placement=\"start\" header={t(\"chat.bubble.assistant\")} loading />\n\n// A failed send: colour AND a localized sr-only word, never colour alone.\n<ChatBubble placement=\"end\" tone=\"destructive\" header={t(\"chat.bubble.you\")}>\n  {draft}\n</ChatBubble>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ChatBubble",
+  "props": [
+    {
+      "description": "The message. Pass a plain STRING to make `typing` animatable — a ReactNode has no character count to reveal, so it always renders whole.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"start\"",
+      "description": "Side of the conversation, on the LOGICAL inline axis: \"start\" is the other party, \"end\" is the reader's own message. It flips automatically under dir=\"rtl\" — never branch on locale.",
+      "name": "placement",
+      "type": "\"start\" | \"end\""
+    },
+    {
+      "defaultValue": "\"filled\"",
+      "description": "Structural treatment of the body. Ant Design X's `shadow` is absent on purpose: this is a 1px-border system with no drop shadows. Status colour is `tone`, never `variant`.",
+      "name": "variant",
+      "type": "\"filled\" | \"borderless\" | \"outlined\""
+    },
+    {
+      "description": "The author's mark — a real <Avatar>, never a styled div. Mark it aria-hidden when `header` already names the author.",
+      "name": "avatar",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Line above the body naming the turn. When present it becomes the bubble's ACCESSIBLE NAME (aria-labelledby), so keep it text.",
+      "name": "header",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Line below the body — a timestamp (format it with formatAppTime from @godxjp/ui/datetime), per-message actions, a token count.",
+      "name": "footer",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "The reply was requested and has not arrived: renders Skeleton bars (aria-hidden, they are decorative) plus a localized sr-only line, and sets aria-busy on the article.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Stream the text in. `true` = 1 character every 50ms; the object form retunes it. While streaming the half-typed text is aria-hidden and the article is aria-busy, so the log announces the finished message ONCE. Under prefers-reduced-motion: reduce the full text renders immediately and no timer starts.",
+      "name": "typing",
+      "type": "boolean | { step?: number; interval?: number }"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Type step and inner inset. Never \"default\".",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Status intent for a message that is not ordinary conversation (a failed send, a rate-limit warning). Washes the role colour like Alert AND renders a localized sr-only tone word — never colour alone.",
+      "name": "tone",
+      "type": "\"default\" | \"info\" | \"success\" | \"warning\" | \"destructive\""
+    },
+    {
+      "description": "DOM id forwarded to the bubble's `<article>`. Supply one when something outside the bubble has to point at it (an `aria-describedby` from a retry button, a deep link to a single message); otherwise leave it off and let React generate the ids the header/label wiring needs.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ChatBubbleList — the feed. Use it whenever there is more than one message: it owns stick-to-bottom, the jump-to-latest affordance and the single aria-live region.",
+    "ListRow — a single-line entity row for short lists (sessions, tokens). Use ListRow for records, ChatBubble for conversation turns.",
+    "Alert — a page-level status banner. A toned ChatBubble is a status INSIDE a conversation; an Alert is a status about the screen.",
+    "Prose — use it inside `children` when the assistant returns rendered Markdown; ChatBubble owns the container, Prose owns the typography of the body.",
+    "Skeleton — what `loading` renders. Do not compose it yourself around a bubble; the prop also sets aria-busy and the localized status line."
+  ],
+  "rules": [
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "data-display/ChatBubble.stories.tsx",
+  "tagline": "One message in a conversation: an author mark, a header naming the turn, the body, and a footer. Renders as an <article> inside ChatBubbleList's log; `loading` shows Skeleton and `typing` streams a string in, dropping the animation entirely under prefers-reduced-motion.",
+  "usage": [
+    "DO let ChatBubbleList own the feed. A lone ChatBubble is for a single quoted message; a conversation is `items` + `roles` on the list, which is where stick-to-bottom and the one aria-live region live.",
+    "DO pass a real <Avatar> to `avatar` and a plain string to `header`. The header is the accessible name of the bubble, so a decorative avatar next to it should be aria-hidden.",
+    "DO pass `typing` on the streaming message only, and only when its body is a string. Do not re-mount the bubble on every token — change `children` and let the component reveal it.",
+    "DO format timestamps for `footer` with formatAppTime / formatAppDate from @godxjp/ui/datetime (Intl.DateTimeFormat + the AppProvider timezone). Never hand-build a date string.",
+    "DO NOT put an aria-live region inside a bubble. The feed owns exactly one; one per bubble floods a screen reader on every token.",
+    "DO NOT reach for `variant` to signal an error — that is `tone`. `variant` is structural (filled/borderless/outlined) and has no status values.",
+    "DO NOT hand-roll the bubble as a rounded div with a background: placement, the RTL flip, the max measure and the tone wash are all tokens on this component (--chat-bubble-*)."
+  ],
+  "useCases": [
+    "An AI assistant panel — assistant turns on the start side, the operator's own prompts on the end side, with the in-flight reply streaming via `typing`.",
+    "A support-inbox thread where an agent reads the customer's history: the same feed renders both parties and marks a failed send with tone=\"destructive\".",
+    "A tool/agent transcript where a system note (tone=\"info\", variant=\"outlined\") sits between conversational turns.",
+    "A quoted single message inside a Card — a reported message in a moderation screen, rendered as one ChatBubble with a footer carrying the report time."
+  ]
+}

package/agent/components/ChatBubbleList.json

@@ -0,0 +1,64 @@
+{
+  "docPath": "data-display/chat-bubble.tsx",
+  "example": "import { ChatBubbleList, type ChatMessageProp } from \"@godxjp/ui/data-display\";\n\nconst messages: ChatMessageProp[] = [\n  { id: \"m1\", role: \"assistant\", content: \"How can I help?\" },\n  { id: \"m2\", role: \"user\", content: \"Summarise yesterday's invoices.\" },\n  { id: \"m3\", role: \"assistant\", content: reply, typing: true },\n];\n\n<ChatBubbleList\n  label={t(\"chat.list.label\")}\n  items={messages}\n  roles={{\n    assistant: { placement: \"start\", variant: \"filled\", avatar: assistantAvatar },\n    user: { placement: \"end\", variant: \"outlined\" },\n    system: { placement: \"start\", variant: \"borderless\", tone: \"info\", size: \"sm\" },\n  }}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ChatBubbleList",
+  "props": [
+    {
+      "description": "`{ id, role?, content?, ...ChatBubbleProp }` in conversation order, oldest first. `id` is the React key AND the rendered <article>'s DOM id.",
+      "name": "items",
+      "required": true,
+      "type": "ChatMessageProp[]"
+    },
+    {
+      "description": "Per-role bubble defaults, merged UNDER each message's own props: `{ assistant: { placement: \"start\" }, user: { placement: \"end\", variant: \"outlined\" } }`. Written once instead of on every message.",
+      "name": "roles",
+      "type": "Record<string, Partial<ChatBubbleProp>>"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Keep the newest message in view WHILE the reader is at the bottom. It is not \"scroll to the bottom when content arrives\": scrolling up revokes the pin until the reader asks for it back, because yanking them down mid-sentence is a change of context they did not request (WCAG 3.2.5).",
+      "name": "autoScroll",
+      "type": "boolean"
+    },
+    {
+      "description": "Accessible name of the feed; lands on aria-label. Defaults to the localized t(\"chat.list.label\").",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "DOM id forwarded to the feed's scroll container (`role=\"log\"`). Supply one when a control outside the feed must reference it — an `aria-controls` on a \"jump to latest\" button of your own, or a skip link that moves focus into the transcript.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ChatBubble — one message; this list renders them and supplies per-role defaults.",
+    "ScrollArea — the scrolling primitive underneath. Use ScrollArea anchor=\"bottom\" directly for a non-conversational live stream (an audit log); use ChatBubbleList when the rows are conversation turns.",
+    "Timeline — an ordered event rail with no scale and no live region. Use Timeline for a record's history, ChatBubbleList for a dialogue.",
+    "DataTable — for many rows that need sorting, filtering and pagination. A conversation is neither sorted nor paged."
+  ],
+  "rules": [
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "data-display/ChatBubbleList.stories.tsx",
+  "tagline": "The message feed. It owns STICK-TO-BOTTOM (auto-scroll only while the reader is already at the bottom; the moment they scroll up the pin is revoked and a focusable jump-to-latest button appears), one aria-live=\"polite\" role=\"log\" region for the whole conversation, and per-role bubble defaults.",
+  "usage": [
+    "DO drive the feed from `items` and shape it with `roles`. Mapping ChatBubbles yourself inside a ScrollArea loses stick-to-bottom, the jump affordance and the single live region — the three reasons this component exists.",
+    "DO give the list a DEFINITE height — `className=\"h-96\"`, or a flex/grid parent that hands it a track. It scrolls inside itself; measured at 1280px, a list with no height grew to its content (1,952px) inside a 256px Card, scrollHeight === clientHeight, and stick-to-bottom had nothing to anchor.",
+    "DO keep `id` stable per message. It is the React key, so a regenerated id re-mounts the bubble and restarts any typing animation.",
+    "DO leave autoScroll on for a live conversation and turn it off for an archived transcript, where landing on the newest message is not what the reader wants.",
+    "DO NOT add your own aria-live region inside the feed, and do not put one on a bubble. This list already declares role=\"log\" with aria-live=\"polite\"; a second region double-announces every message.",
+    "DO NOT scroll the viewport yourself on every append. That is the defect stick-to-bottom exists to prevent; the reader's scroll position is the only thing that grants the pin."
+  ],
+  "useCases": [
+    "The transcript pane of an AI assistant screen, above a ChatComposer, streaming the assistant's reply into the last bubble.",
+    "A support conversation in an admin detail page, where an operator scrolls up to re-read an earlier message while new ones keep arriving.",
+    "An agent/tool run log rendered as a conversation, with system notes as toned bubbles between turns.",
+    "An archived thread opened read-only from a report (autoScroll={false}), so the reader lands where the citation is rather than at the end."
+  ]
+}

package/agent/components/ChatComposer.json

@@ -0,0 +1,160 @@
+{
+  "docPath": "data-entry/chat-composer.tsx",
+  "example": "import { ChatComposer } from \"@godxjp/ui/data-entry\";\n\nconst [draft, setDraft] = useState(\"\");\nconst [streaming, setStreaming] = useState(false);\n\n<ChatComposer\n  value={draft}\n  onValueChange={setDraft}\n  onSubmit={(text) => { send(text); setDraft(\"\"); }}\n  loading={streaming}\n  onCancel={() => setStreaming(false)}\n  placeholder={t(\"chat.placeholder\")}\n  footer={t(\"dataEntry.chatComposer.hintEnter\")}\n/>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "ChatComposer",
+  "props": [
+    {
+      "description": "Controlled draft text. Pair with onValueChange or the box freezes.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial draft text.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Draft-text change handler; fires on every keystroke, including during an IME conversion.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Send the draft. Never fires for empty or whitespace-only text (unless allowEmptySubmit, which passes \"\"), nor while loading/disabled/readOnly.",
+      "name": "onSubmit",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Stop the in-flight response. Only reachable while loading.",
+      "name": "onCancel",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "A response is streaming: the trailing action BECOMES cancel. Send and cancel never render together.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"enter\"",
+      "description": "\"enter\": Enter sends, Shift+Enter breaks the line. \"shiftEnter\": the inverse, for long deliberate drafts. \"modEnter\" (library extension; antd X Sender has only the first two): ⌘+Enter on Apple platforms, Ctrl+Enter elsewhere sends, while Enter and Shift+Enter both break the line — the record-comment convention (GitHub, Jira, Linear).",
+      "name": "submitType",
+      "type": "\"enter\" | \"shiftEnter\" | \"modEnter\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Let an empty or whitespace-only draft be sent when header/footer carry payload of their own (a status change on a record). The send button stays enabled and the button and keyboard submit call onSubmit(\"\"). Still blocked while loading/disabled/readOnly.",
+      "name": "allowEmptySubmit",
+      "type": "boolean"
+    },
+    {
+      "description": "Empty-state text of the draft box — pass it through t() at the call site.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disable the composer and every action.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Show the draft without allowing an edit; still focusable.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Slot ABOVE the draft row — attachments, a reply-to banner, a model picker.",
+      "name": "header",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Slot at the inline START of the draft row — an attach Button, an Avatar.",
+      "name": "prefix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Slot BELOW the draft row — a hint line, a token counter.",
+      "name": "footer",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Extra trailing actions, rendered BEFORE the send/cancel action.",
+      "name": "actions",
+      "type": "React.ReactNode"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Height tier on the shared --control-height ladder; moves both auto-grow bounds together.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Hard ceiling on the draft length, forwarded to the textarea.",
+      "name": "maxLength",
+      "type": "number"
+    },
+    {
+      "description": "Validation state the frame paints. error also reports aria-invalid (colour alone fails WCAG 1.4.1).",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "Accessible name override for the send action (localized default otherwise).",
+      "name": "submitLabel",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name override for the cancel action (localized default otherwise).",
+      "name": "cancelLabel",
+      "type": "string"
+    },
+    {
+      "description": "Keydown on the draft box — how ChatSuggestion drives its list. A handler that calls preventDefault() owns the key, and the composer will not treat it as a send.",
+      "name": "onKeyDown",
+      "type": "React.KeyboardEventHandler<HTMLTextAreaElement>"
+    },
+    {
+      "description": "Native form name, forwarded to the textarea.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the textarea (the semantic focus target FormField labels).",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Textarea — the primitive underneath. Use it directly for an ordinary multi-line form field with no send action.",
+    "ChatSuggestion — wraps ChatComposer to add trigger-character (/) autocomplete.",
+    "ChatBubbleList — the feed the composer sends into.",
+    "SearchInput — a single-line query field; a composer is multi-line and holds a draft."
+  ],
+  "rules": [
+    2,
+    6,
+    43,
+    45
+  ],
+  "storyPath": "data-entry/ChatComposer.stories.tsx",
+  "tagline": "The message input of a conversation (Ant Design X Sender): an auto-growing Textarea plus exactly ONE trailing action — send, or cancel while a response streams. Enter / Shift+Enter / ⌘-or-Ctrl+Enter is configurable and never fires during an IME conversion.",
+  "usage": [
+    "DO pair a controlled `value` with `onValueChange` — a controlled value with no synchronised handler is the classic frozen-input bug, and it freezes the whole conversation.",
+    "DO wrap it in FormField when the composer is a labelled field; the label/helper/error contract lands on the <textarea>, which is the semantic focus target (ref goes there too).",
+    "DON'T hand-roll Enter-to-send. An IME conversion (ja/vi) fires a real Enter to ACCEPT a candidate; ChatComposer already guards compositionstart/compositionend, and skipping that guard makes Japanese and Vietnamese input impossible.",
+    "DON'T render your own stop button beside the send button — set `loading` and the trailing action becomes cancel. Exactly one trailing action exists at a time (the picker trailing-action discipline).",
+    "DO put a hint in `footer` (t('dataEntry.chatComposer.hintEnter') / 'hintShiftEnter') when you flip `submitType` — the keystroke contract is invisible otherwise. For submitType=\"modEnter\" use t('dataEntry.chatComposer.hintModEnter', { modifier: isApplePlatform() ? '⌘' : 'Ctrl' }) with isApplePlatform from @godxjp/ui/lib/utils — the same platform test the composer uses to pick metaKey vs ctrlKey.",
+    "DO set `allowEmptySubmit` (not a hidden fake draft) when the composer also submits field changes from `header`/`footer`; your onSubmit receives \"\" and decides whether anything changed.",
+    "DON'T size it with a className height: the box grows between --chat-composer-min-height and --chat-composer-max-height, both derived from the --control-height tier. Use `size`, or re-tune the two tokens in your theme."
+  ],
+  "useCases": [
+    "The message box of an AI assistant or support chat, under a ChatBubbleList feed.",
+    "A comment composer on a record detail screen (prefix = attach Button, footer = character counter).",
+    "A long-form reply box where Enter must break the line: submitType=\"shiftEnter\".",
+    "A comment bar on an issue/record where Enter breaks the line and ⌘/Ctrl+Enter posts, and a status change may be posted without text: submitType=\"modEnter\" + allowEmptySubmit.",
+    "A streaming answer the user can stop: loading + onCancel."
+  ]
+}