@godxjp/ui 31.4.0 → 31.6.0

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 31.4.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.6.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -47,19 +47,19 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
-1. `components-index.json` — 47 KB, all 176 components as name + group +
+1. `components-index.json` — 47 KB, all 177 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
    first; it exists because that is the mistake.
-2. `components/<Name>.json` — one file per component (1 KB–35 KB, median 6 KB), carrying its props,
+2. `components/<Name>.json` — one file per component (1 KB–36 KB, median 6 KB), carrying its props,
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 50 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2080 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2099 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1765 `component` entries are per-part knobs; reach for one only when a role is
+   1784 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -145,7 +145,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
 | `semantic` | 104 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1765 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 1784 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/BranchScopePicker.json

@@ -59,6 +59,11 @@
       "name": "searchable",
       "type": "boolean"
     },
+    {
+      "description": "antd `notFoundContent` — shown when the branch SEARCH matches nothing (default: localized `dataEntry.branchScope.noMatches`). An empty `branches` list is `empty`'s job, not this.",
+      "name": "notFoundContent",
+      "type": "ReactNode"
+    },
     {
       "description": "Override the localized radio labels (e.g. domain wording like 全店舗).",
       "name": "allLabel / selectedLabel",

package/agent/components/Cascader.json

@@ -152,7 +152,7 @@
       "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.",
+      "description": "antd `loadData` — lazy children. Called when a branch that has no children and isLeaf !== true is expanded, and never again once its promise resolves; push the fetched children into options. A rejected promise is forgotten, so the next activation of the branch asks again (gh#1041).",
       "name": "loadData",
       "type": "(selectedOptions: TreeOptionProp[]) => void | Promise<void>"
     },

package/agent/components/CodeBlock.json

@@ -1,5 +1,5 @@
 {
-  "example": "import { CodeBlock } from \"@godxjp/ui/data-display\";\n\n<CodeBlock maxHeight=\"sm\" language=\"json\" aria-label=\"Response body\">{body}</CodeBlock>\n<CodeBlock size=\"xs\" maxHeight=\"md\" aria-label=\"Console\">{consoleText}</CodeBlock>",
+  "example": "import { CodeBlock } from \"@godxjp/ui/data-display\";\n\n<CodeBlock maxHeight=\"sm\" language=\"json\" aria-label=\"Response body\">{body}</CodeBlock>\n<CodeBlock size=\"xs\" maxHeight=\"md\" aria-label=\"Console\">{consoleText}</CodeBlock>\n<CodeBlock copyable language=\"bash\">pnpm add @godxjp/ui</CodeBlock>",
   "group": "data-display",
   "importPath": "@godxjp/ui/data-display",
   "name": "CodeBlock",
@@ -31,6 +31,11 @@
       "name": "language",
       "type": "string"
     },
+    {
+      "description": "antd Typography's `copyable`, same name and semantics (gh#1032): a copy button in the block's inline-end corner. `true` copies the block's text content (highlighter spans included); `text` overrides it. The block reserves the button's column, the confirmed state is announced politely, and `onCopy` fires only after the clipboard write succeeds.",
+      "name": "copyable",
+      "type": "boolean | { text?: string | (() => string | Promise<string>); onCopy?: (event) => void; tooltips?: ReactNode | [ReactNode, ReactNode] | false; icon?: ReactNode | [ReactNode, ReactNode]; format?: \"text/plain\" | \"text/html\"; tabIndex?: number }"
+    },
     {
       "description": "Extra classes on the `pre`.",
       "name": "className",
@@ -52,6 +57,7 @@
     "DO cap the height of anything that can be large (a 64 KB response body, a console dump) with `maxHeight`; the page keeps its rhythm and the block scrolls.",
     "DON'T hand-roll `<pre className=\"max-h-64 overflow-auto rounded bg-muted p-2 whitespace-pre-wrap\">`: every one of those values is a copy of a token this component reads.",
     "DON'T reach for `Text as=\"code\"` for a block: that is inline monospace with no wrapping axis. Use `Text as=\"code\"` for an identifier inside a sentence, CodeBlock for a block.",
+    "DO use `copyable` for a command or snippet the reader will paste (gh#1032). DON'T hand-roll a copy Button next to or over a CodeBlock: `copyable` owns the clipboard call, the confirmed state, the placement and the polite announcement.",
     "DON'T use CodeBlock for a single value in a Descriptions row: `Descriptions.Item mono` owns that (it breaks the value, not the row).",
     "SYNTAX COLOUR (gh#784): CodeBlock does not highlight, but it DOES own the palette. Tag each span from your highlighter with `data-code-token` — the twelve names are Shiki createCssVariablesTheme's verbatim (comment, keyword, string, string-expression, function, constant, parameter, punctuation, link, inserted, deleted, changed, plus the block foreground) — and the package colours them. DON'T put `style={{ color }}` or a palette `className` on the spans: both are visual overrides, and the colour is not the consumer's to choose. Retheme with the `--code-block-token-*-color` knobs, which are role-mirrors, so light and dark follow the theme with no second palette."
   ],

package/agent/components/DataTable.json

@@ -159,9 +159,9 @@
       "type": "() => void"
     },
     {
-      "description": "Full row-selection configuration (antd rowSelection). Supersedes — and can be mixed with — selectable/selected/onSelectChange, which drive the same state. type:'radio' makes the column single-choice (no header checkbox at all). getCheckboxProps is the declared home for 'this row cannot be selected' (disabled) and for a per-row accessible name. preserveSelectedRowKeys keeps a key selected after its row leaves `data` (server paging / a filter), which is the only way a select-across-pages bulk action can be correct. selections adds bulk entries under the header checkbox (true = the built-in all · invert · none).",
+      "description": "Full row-selection configuration (antd rowSelection). Supersedes — and can be mixed with — selectable/selected/onSelectChange, which drive the same state. type:'radio' makes the column single-choice (no header checkbox at all). getCheckboxProps is the declared home for 'this row cannot be selected' (disabled) and for a per-row accessible name. preserveSelectedRowKeys keeps a key selected after its row leaves `data` (server paging / a filter), which is the only way a select-across-pages bulk action can be correct. selections adds bulk entries under the header checkbox (true = the built-in all · invert · none; a list mixes antd's DataTable.SELECTION_ALL / SELECTION_INVERT / SELECTION_NONE with custom entries in the order given). selectAllLabel names the header checkbox — say what it really selects (on a server-paged table: the page) instead of replacing it through columnTitle. matching (no antd equivalent; Gmail/Jira/GitHub) is the server-paged 'select all N matching' banner: once the whole page is ticked and total exceeds the page, a polite status above the header offers 'Select all N matching rows'; choosing it reports onSelectedChange(true) — send your FILTER, not the ids, for the bulk write — and while selected every row of any page shows ticked. Unticking a row or 'Clear selection' reports false. With matching set, the header checkbox defaults to 'Select all rows on this page'.",
       "name": "rowSelection",
-      "type": "{ type?: 'checkbox'|'radio'; selectedRowKeys?: string[]; defaultSelectedRowKeys?: string[]; onChange?: (keys, rows) => void; getCheckboxProps?: (row) => { disabled?, 'aria-label'? }; preserveSelectedRowKeys?: boolean; selections?: true | { key, text, onSelect }[]; hideSelectAll?: boolean; columnTitle?: ReactNode }"
+      "type": "{ type?: 'checkbox'|'radio'; selectedRowKeys?: string[]; defaultSelectedRowKeys?: string[]; onChange?: (keys, rows) => void; getCheckboxProps?: (row) => { disabled?, 'aria-label'? }; preserveSelectedRowKeys?: boolean; selections?: true | ({ key, text, onSelect } | DataTable.SELECTION_ALL | DataTable.SELECTION_INVERT | DataTable.SELECTION_NONE)[]; hideSelectAll?: boolean; columnTitle?: ReactNode; selectAllLabel?: string; matching?: { total: number; selected: boolean; onSelectedChange: (selected: boolean) => void } }"
     },
     {
       "description": "Expandable detail rows (antd expandable). Supplying expandedRowRender adds a leading expand column before the selection column and renders the panel in a real <tr> spanning every column, so the table's grid semantics survive. rowExpandable gates the affordance per row; expandedRowKeys + onExpandedRowsChange make it controlled.",

package/agent/components/InfiniteQueryState.json

@@ -27,6 +27,11 @@
       "name": "children",
       "required": true,
       "type": "(flat, helpers) => ReactNode"
+    },
+    {
+      "description": "Idle text of the built-in load-more button (default: localized `query.loadMore`, 「さらに読み込む」) — e.g. 「さらに表示」「さらに古い版を表示」. The button, its pending label and disabled-while-fetching stay the component's. Ignored when `loadMore` replaces the footer.",
+      "name": "loadMoreLabel",
+      "type": "ReactNode"
     }
   ],
   "related": [
@@ -43,7 +48,7 @@
     "DO: Always pass `skeleton` (e.g. `<SkeletonTable />` or `<SkeletonStat />`). It shows on initial `isPending`, on refetch-after-error, and whenever `data` is absent. Never show a blank area while loading.",
     "DO: Pass `empty` (an `<EmptyState>` node) to handle the zero-results case — without it the children render-prop is called with an empty array and you get a silent blank screen. Provide a custom `isEmpty` only when `TFlat` is not an array.",
     "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; a 401 is handled by the app-root `AuthExpiryProvider` (auto, once, skeleton + live region) or, without one, by the `onAuthError` sign-in button; raw backend/token text is never rendered.",
-    "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Override only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
+    "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Rename it with `loadMoreLabel` (keeps the pending state); replace it only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
     "DON'T: Use `InfiniteQueryState` for a `useQuery` result — it expects `UseInfiniteQueryResult` shape (`pages`, `hasNextPage`, `fetchNextPage`, `isFetchingNextPage`). For regular `useQuery` use `DataState` instead.",
     "DON'T: Confuse the two generics: `TPage` is the raw page shape from the API, `TFlat` is what `flatten` returns (usually `TItem[]`). The `children` render-prop receives `TFlat`, not `TPage`. Pass `isEmpty` if `TFlat` is not a plain array so empty detection works correctly."
   ],

package/agent/components/OrgChart.json

@@ -0,0 +1,59 @@
+{
+  "docPath": "data-display/org-chart.tsx",
+  "example": "import { Avatar, AvatarFallback, Badge, OrgChart } from \"@godxjp/ui/data-display\";\n\n<OrgChart\n  label=\"Company org chart\"\n  data={[\n    {\n      key: \"ceo\", name: \"Haruka Tanaka\", title: \"CEO\",\n      avatar: <Avatar size=\"sm\"><AvatarFallback>HT</AvatarFallback></Avatar>,\n      children: [\n        { key: \"cto\", name: \"Kenji Watanabe\", title: \"CTO\" },\n        { key: \"bot\", name: \"Review Agent\", title: \"Code review\", variant: \"agent\",\n          extra: <Badge tone=\"success\">Running</Badge> },\n      ],\n    },\n  ]}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "OrgChart",
+  "props": [
+    {
+      "description": "The hierarchy: { key, name, title?, avatar?, extra?, variant?: \"person\" | \"agent\", children? }. `key` is unique across the chart. `avatar` is usually an <Avatar>; `extra` a Badge or status.",
+      "name": "data",
+      "type": "OrgChartNodeProp[]"
+    },
+    {
+      "description": "Replace a box's content. The box, its border, the connectors and the keyboard stay the library's; the narrow Tree form uses it too.",
+      "name": "renderNode",
+      "type": "(node: OrgChartNodeProp) => ReactNode"
+    },
+    {
+      "description": "Accessible name of the role=\"tree\" (a plain string). Localized default \"Organization chart\".",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the root.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Root class.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Tree — the indented, collapsible outline. OrgChart renders it as its narrow form.",
+    "Avatar — the mark in each box.",
+    "Badge — a status in a box's `extra` slot."
+  ],
+  "rules": [
+    2,
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "data-display/OrgChart.stories.tsx",
+  "tagline": "An organization chart: boxes (avatar, name, title, extra) joined by CSS connector lines, top-down; `agent` nodes are dashed. Scrolls horizontally in its own named region when wider than its container, and turns into an indented Tree when the CONTAINER is under 40rem. APG tree view (tree/treeitem/group, roving tabindex, arrow keys).",
+  "usage": [
+    "DO mark AI agents with `variant: \"agent\"` — the box is dashed AND its accessible name ends in a localized \"AI agent\", so the kind is never carried by the stroke alone.",
+    "DO give it the width it has; the breakpoint is a container query, so a chart in a narrow side panel switches to the Tree form on a wide screen too.",
+    "DO retune boxes and lines through the --org-chart-* tokens (node size, gaps, line width/colour, agent border style).",
+    "DON'T wrap it in your own overflow-x scroller — it owns its scroll region, which only becomes a named tab stop when the chart actually overflows.",
+    "DON'T use it for an outline users expand and collapse — that is Tree. OrgChart always shows every node."
+  ],
+  "useCases": [
+    "A company or team org chart with people and AI agents side by side.",
+    "Reporting lines on an admin screen, falling back to an indented list in a narrow panel or on a phone."
+  ]
+}

package/agent/components/RangeTimeline.json

@@ -64,6 +64,12 @@
       "description": "Fires with the next expanded parent ids when a disclosure is toggled, for controlled and uncontrolled timelines alike.",
       "name": "onExpandedValuesChange",
       "type": "(values: string[]) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd Table `sticky` — keep the axis header (bands + ticks) on screen while the PAGE scrolls a long schedule. `offsetHeader` is px from the top of the scrolling viewport (the height of a fixed app topbar). The header moves out of the horizontal scroller and follows its scrollLeft; the section becomes `overflow: clip` and the body scroller takes the keyboard tab stop. Like antd, it needs no clipping ancestor between the timeline and the page scroller: `Card` is `overflow: hidden`, so a sticky timeline goes in the page as its own section, not inside a Card. antd's `offsetScroll` / `getContainer` (sticky horizontal scrollbar) are not ported.",
+      "name": "sticky",
+      "type": "boolean | { offsetHeader?: number }"
     }
   ],
   "rules": [],

package/agent/components/RecordPicker.json

@@ -82,6 +82,16 @@
       "name": "dialogTitle",
       "type": "string"
     },
+    {
+      "description": "antd `notFoundContent` — shown when the search finds nothing, in the dropdown shape and the dialog alike (default: localized `dataEntry.recordPicker.empty`). Say WHAT has no match, e.g. 「該当するファイルはありません」.",
+      "name": "notFoundContent",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Text of the dialog's load-more button (default: localized `dataEntry.recordPicker.more`). Only the label — the button still appears only while the server returns a `nextCursor`.",
+      "name": "loadMoreLabel",
+      "type": "ReactNode"
+    },
     {
       "description": "Control height of the trigger, on the shared control ladder.",
       "name": "size",

package/agent/components/Transfer.json

@@ -109,6 +109,11 @@
       "name": "onSelectChange",
       "type": "(sourceSelectedKeys: string[], targetSelectedKeys: string[]) => void"
     },
+    {
+      "description": "antd `locale`, ported for `notFoundContent` only: what an empty or search-emptied pane shows (default: localized `dataEntry.transfer.empty`). A `[source, target]` pair sets each pane separately, as in antd.",
+      "name": "locale",
+      "type": "{ notFoundContent?: ReactNode | [ReactNode, ReactNode] }"
+    },
     {
       "description": "Fires when items move between panels; you own `targetKeys` state.",
       "name": "onValueChange",

package/agent/components/Tree.json

@@ -86,7 +86,7 @@
       "type": "boolean"
     },
     {
-      "description": "Lazy children (antd `loadData`). Called ONCE per node the first time a branch with no `children` and `isLeaf !== true` is expanded; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`.",
+      "description": "Lazy children (antd `loadData`). Called when a branch with no `children` and `isLeaf !== true` is expanded, and never again once its promise RESOLVES; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`. A REJECTED promise is not a load (rc-tree, gh#1041): the branch folds back shut (uncontrolled expansion) and the next expand asks again, up to 10 attempts.",
       "name": "loadData",
       "type": "(node: TreeNodeProp) => void | Promise<void>"
     },
@@ -95,6 +95,22 @@
       "name": "titleRender",
       "type": "(node: TreeNodeProp) => ReactNode"
     },
+    {
+      "description": "Highlight the nodes this returns true for (antd `filterTreeNode`, gh#1043) — the match of a search box above the tree. Matching rows are MARKED, not hidden: `data-filter-node=\"true\"`, the label in `--tree-node-filter-foreground` (default `hsl(var(--primary))`) at the medium weight, plus sr-only \"matches the filter\" text. Outline, keyboard and ARIA are unchanged. To also open the branches that hold a match, drive `expandedValues`.",
+      "name": "filterTreeNode",
+      "type": "(node: TreeNodeProp) => boolean"
+    },
+    {
+      "description": "Viewport height in px (antd `height`, gh#1042). The tree scrolls inside it and, unless `virtual={false}`, renders only the rows in view plus a small overscan — the windowed rows stay a flat run of treeitems whose `aria-level`/`aria-setsize`/`aria-posinset` still describe the whole outline. Rows must share one height (the `size` tier).",
+      "name": "height",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Set `false` to keep the `height` viewport but render every row (antd `virtual`).",
+      "name": "virtual",
+      "type": "boolean"
+    },
     {
       "defaultValue": "false",
       "description": "Draw the connector rails between a parent and its children (antd `showLine`). Off by default — a rail is chrome, and chrome defaults quiet.",
@@ -152,7 +168,7 @@
     "TreeSelect — the same hierarchy INSIDE a Popover, as a form field. Use TreeSelect when the answer is a value in a form; use Tree when the hierarchy itself is the page.",
     "Cascader — a path picker across columns. Use it when the user walks one path to a leaf; use Tree when several branches are open at once.",
     "Accordion — single-level disclosure with rich panel content. It is not a hierarchy and has no tree keyboard model.",
-    "ScrollArea — wrap Tree in one to cap a long outline; Tree does not virtualise in v1."
+    "ScrollArea — not needed around Tree: pass `height`, and the tree is its own (windowed) scroll viewport."
   ],
   "rules": [
     2,
@@ -172,8 +188,9 @@
     "DON'T nest a Button, Checkbox, Link or any focusable control inside a node label. A tree item owns exactly ONE tab stop; the disclosure triangle and the tick box are decorative glyphs for that reason. Put row actions in a sibling column outside the tree, or open a detail pane on selection.",
     "DON'T hand-roll an indented `<ul>` (or a NavList / ListRow stack with a per-depth margin) for a hierarchy. A flat indented list only LOOKS like a tree: no expand/collapse, no `role=\"tree\"`, no keyboard model, no selection contract. `TreeList` was exactly that list and was REMOVED in 21.0.0 — Tree is what replaced it, and it is the one to reach for whenever nodes expand, collapse or are keyboard-navigated.",
     "DO pass `divided` when the tree IS the navigation of a page — a wiki/document outline or a section index sitting in a `Card` (`Card` > `CardContent flush` > `Tree divided`). Without a rule the rows run together and the outline reads as one block; with it, it reads as the ruled list ListRow and Table already give a flat list. Retint it per theme with `--tree-divider-color`, never with a per-page utility class.",
-    "DO cap a long tree with `ScrollArea` — virtualisation is not in v1, so a 5,000-node tree renders 5,000 rows.",
-    "DO push fetched children into `treeData` from `loadData`; the tree calls it once per node and shows a Skeleton row until the data lands."
+    "DO pass `height` for a long tree (antd `height` + `virtual`): the tree scrolls inside that height and keeps only the rows in view in the DOM, so a 421-child level renders a few dozen rows. Do not wrap it in `ScrollArea` as well — the tree is its own viewport.",
+    "DO push fetched children into `treeData` from `loadData`; the tree calls it once per node that loads and shows a Skeleton row until the data lands. Reject the promise on failure — the branch folds shut and the next expand retries.",
+    "DON'T wait for a paged \"load more\" node — antd's Tree has none, and `height` covers a long list. If the API itself is paged, append a leaf node such as `{ value: `${parent}::more`, label: t(\"…load more\"), isLeaf: true }` to the loaded children and fetch the next page from `onValueChange` when it is selected: it is a real treeitem, so it is keyboard-reachable and announced."
   ],
   "useCases": [
     "A permission tree: modules → resources → actions with tri-state checkboxes, where ticking a module ticks everything under it and a partly-granted module shows the dash.",

package/agent/components/TreeSelect.json

@@ -179,7 +179,7 @@
       "type": "boolean"
     },
     {
-      "description": "antd `loadData` — lazy children. Called ONCE per node that has no children and isLeaf !== true, the first time it is expanded; push the fetched children into treeData. Such a node still reads as expandable (aria-expanded + a working expander).",
+      "description": "antd `loadData` — lazy children. Called when a node that has no children and isLeaf !== true is expanded, and never again once its promise resolves; push the fetched children into treeData. A rejected promise folds the branch shut and the next expand asks again, up to 10 attempts (rc-tree, gh#1041). Such a node still reads as expandable (aria-expanded + a working expander).",
       "name": "loadData",
       "type": "(node: TreeOptionProp) => void | Promise<void>"
     },

package/agent/components-index.json

@@ -886,6 +886,11 @@
     "name": "ThoughtChain",
     "tagline": "The assistant's reasoning, step by step (Ant Design X ThoughtChain): an ORDERED list of steps, each with an ordinal or a glyph, a status, and a body it can collapse — where Ant X's own step is a <div onClick> with no role and no aria-expanded."
   },
+  {
+    "group": "data-display",
+    "name": "OrgChart",
+    "tagline": "An organization chart: boxes (avatar, name, title, extra) joined by CSS connector lines, top-down; `agent` nodes are dashed. Scrolls horizontally in its own named region when wider than its container, and turns into an indented Tree when the CONTAINER is under 40rem. APG tree view (tree/treeitem/group, roving tabindex, arrow keys)."
+  },
   {
     "group": "data-entry",
     "name": "Attachments",

package/agent/components.json

@@ -590,6 +590,12 @@
         "description": "Fires with the next expanded parent ids when a disclosure is toggled, for controlled and uncontrolled timelines alike.",
         "name": "onExpandedValuesChange",
         "type": "(values: string[]) => void"
+      },
+      {
+        "defaultValue": "false",
+        "description": "antd Table `sticky` — keep the axis header (bands + ticks) on screen while the PAGE scrolls a long schedule. `offsetHeader` is px from the top of the scrolling viewport (the height of a fixed app topbar). The header moves out of the horizontal scroller and follows its scrollLeft; the section becomes `overflow: clip` and the body scroller takes the keyboard tab stop. Like antd, it needs no clipping ancestor between the timeline and the page scroller: `Card` is `overflow: hidden`, so a sticky timeline goes in the page as its own section, not inside a Card. antd's `offsetScroll` / `getContainer` (sticky horizontal scrollbar) are not ported.",
+        "name": "sticky",
+        "type": "boolean | { offsetHeader?: number }"
       }
     ],
     "rules": [],
@@ -3525,9 +3531,9 @@
         "type": "() => void"
       },
       {
-        "description": "Full row-selection configuration (antd rowSelection). Supersedes — and can be mixed with — selectable/selected/onSelectChange, which drive the same state. type:'radio' makes the column single-choice (no header checkbox at all). getCheckboxProps is the declared home for 'this row cannot be selected' (disabled) and for a per-row accessible name. preserveSelectedRowKeys keeps a key selected after its row leaves `data` (server paging / a filter), which is the only way a select-across-pages bulk action can be correct. selections adds bulk entries under the header checkbox (true = the built-in all · invert · none).",
+        "description": "Full row-selection configuration (antd rowSelection). Supersedes — and can be mixed with — selectable/selected/onSelectChange, which drive the same state. type:'radio' makes the column single-choice (no header checkbox at all). getCheckboxProps is the declared home for 'this row cannot be selected' (disabled) and for a per-row accessible name. preserveSelectedRowKeys keeps a key selected after its row leaves `data` (server paging / a filter), which is the only way a select-across-pages bulk action can be correct. selections adds bulk entries under the header checkbox (true = the built-in all · invert · none; a list mixes antd's DataTable.SELECTION_ALL / SELECTION_INVERT / SELECTION_NONE with custom entries in the order given). selectAllLabel names the header checkbox — say what it really selects (on a server-paged table: the page) instead of replacing it through columnTitle. matching (no antd equivalent; Gmail/Jira/GitHub) is the server-paged 'select all N matching' banner: once the whole page is ticked and total exceeds the page, a polite status above the header offers 'Select all N matching rows'; choosing it reports onSelectedChange(true) — send your FILTER, not the ids, for the bulk write — and while selected every row of any page shows ticked. Unticking a row or 'Clear selection' reports false. With matching set, the header checkbox defaults to 'Select all rows on this page'.",
         "name": "rowSelection",
-        "type": "{ type?: 'checkbox'|'radio'; selectedRowKeys?: string[]; defaultSelectedRowKeys?: string[]; onChange?: (keys, rows) => void; getCheckboxProps?: (row) => { disabled?, 'aria-label'? }; preserveSelectedRowKeys?: boolean; selections?: true | { key, text, onSelect }[]; hideSelectAll?: boolean; columnTitle?: ReactNode }"
+        "type": "{ type?: 'checkbox'|'radio'; selectedRowKeys?: string[]; defaultSelectedRowKeys?: string[]; onChange?: (keys, rows) => void; getCheckboxProps?: (row) => { disabled?, 'aria-label'? }; preserveSelectedRowKeys?: boolean; selections?: true | ({ key, text, onSelect } | DataTable.SELECTION_ALL | DataTable.SELECTION_INVERT | DataTable.SELECTION_NONE)[]; hideSelectAll?: boolean; columnTitle?: ReactNode; selectAllLabel?: string; matching?: { total: number; selected: boolean; onSelectedChange: (selected: boolean) => void } }"
       },
       {
         "description": "Expandable detail rows (antd expandable). Supplying expandedRowRender adds a leading expand column before the selection column and renders the panel in a real <tr> spanning every column, so the table's grid semantics survive. rowExpandable gates the affordance per row; expandedRowKeys + onExpandedRowsChange make it controlled.",
@@ -4808,7 +4814,7 @@
     ]
   },
   {
-    "example": "import { CodeBlock } from \"@godxjp/ui/data-display\";\n\n<CodeBlock maxHeight=\"sm\" language=\"json\" aria-label=\"Response body\">{body}</CodeBlock>\n<CodeBlock size=\"xs\" maxHeight=\"md\" aria-label=\"Console\">{consoleText}</CodeBlock>",
+    "example": "import { CodeBlock } from \"@godxjp/ui/data-display\";\n\n<CodeBlock maxHeight=\"sm\" language=\"json\" aria-label=\"Response body\">{body}</CodeBlock>\n<CodeBlock size=\"xs\" maxHeight=\"md\" aria-label=\"Console\">{consoleText}</CodeBlock>\n<CodeBlock copyable language=\"bash\">pnpm add @godxjp/ui</CodeBlock>",
     "group": "data-display",
     "importPath": "@godxjp/ui/data-display",
     "name": "CodeBlock",
@@ -4840,6 +4846,11 @@
         "name": "language",
         "type": "string"
       },
+      {
+        "description": "antd Typography's `copyable`, same name and semantics (gh#1032): a copy button in the block's inline-end corner. `true` copies the block's text content (highlighter spans included); `text` overrides it. The block reserves the button's column, the confirmed state is announced politely, and `onCopy` fires only after the clipboard write succeeds.",
+        "name": "copyable",
+        "type": "boolean | { text?: string | (() => string | Promise<string>); onCopy?: (event) => void; tooltips?: ReactNode | [ReactNode, ReactNode] | false; icon?: ReactNode | [ReactNode, ReactNode]; format?: \"text/plain\" | \"text/html\"; tabIndex?: number }"
+      },
       {
         "description": "Extra classes on the `pre`.",
         "name": "className",
@@ -4861,6 +4872,7 @@
       "DO cap the height of anything that can be large (a 64 KB response body, a console dump) with `maxHeight`; the page keeps its rhythm and the block scrolls.",
       "DON'T hand-roll `<pre className=\"max-h-64 overflow-auto rounded bg-muted p-2 whitespace-pre-wrap\">`: every one of those values is a copy of a token this component reads.",
       "DON'T reach for `Text as=\"code\"` for a block: that is inline monospace with no wrapping axis. Use `Text as=\"code\"` for an identifier inside a sentence, CodeBlock for a block.",
+      "DO use `copyable` for a command or snippet the reader will paste (gh#1032). DON'T hand-roll a copy Button next to or over a CodeBlock: `copyable` owns the clipboard call, the confirmed state, the placement and the polite announcement.",
       "DON'T use CodeBlock for a single value in a Descriptions row: `Descriptions.Item mono` owns that (it breaks the value, not the row).",
       "SYNTAX COLOUR (gh#784): CodeBlock does not highlight, but it DOES own the palette. Tag each span from your highlighter with `data-code-token` — the twelve names are Shiki createCssVariablesTheme's verbatim (comment, keyword, string, string-expression, function, constant, parameter, punctuation, link, inserted, deleted, changed, plus the block foreground) — and the package colours them. DON'T put `style={{ color }}` or a palette `className` on the spans: both are visual overrides, and the colour is not the consumer's to choose. Retheme with the `--code-block-token-*-color` knobs, which are role-mirrors, so light and dark follow the theme with no second palette."
     ],
@@ -5340,6 +5352,11 @@
         "name": "children",
         "required": true,
         "type": "(flat, helpers) => ReactNode"
+      },
+      {
+        "description": "Idle text of the built-in load-more button (default: localized `query.loadMore`, 「さらに読み込む」) — e.g. 「さらに表示」「さらに古い版を表示」. The button, its pending label and disabled-while-fetching stay the component's. Ignored when `loadMore` replaces the footer.",
+        "name": "loadMoreLabel",
+        "type": "ReactNode"
       }
     ],
     "related": [
@@ -5356,7 +5373,7 @@
       "DO: Always pass `skeleton` (e.g. `<SkeletonTable />` or `<SkeletonStat />`). It shows on initial `isPending`, on refetch-after-error, and whenever `data` is absent. Never show a blank area while loading.",
       "DO: Pass `empty` (an `<EmptyState>` node) to handle the zero-results case — without it the children render-prop is called with an empty array and you get a silent blank screen. Provide a custom `isEmpty` only when `TFlat` is not an array.",
       "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; a 401 is handled by the app-root `AuthExpiryProvider` (auto, once, skeleton + live region) or, without one, by the `onAuthError` sign-in button; raw backend/token text is never rendered.",
-      "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Override only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
+      "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Rename it with `loadMoreLabel` (keeps the pending state); replace it only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
       "DON'T: Use `InfiniteQueryState` for a `useQuery` result — it expects `UseInfiniteQueryResult` shape (`pages`, `hasNextPage`, `fetchNextPage`, `isFetchingNextPage`). For regular `useQuery` use `DataState` instead.",
       "DON'T: Confuse the two generics: `TPage` is the raw page shape from the API, `TFlat` is what `flatten` returns (usually `TItem[]`). The `children` render-prop receives `TFlat`, not `TPage`. Pass `isEmpty` if `TFlat` is not a plain array so empty detection works correctly."
     ],
@@ -6111,6 +6128,16 @@
         "name": "dialogTitle",
         "type": "string"
       },
+      {
+        "description": "antd `notFoundContent` — shown when the search finds nothing, in the dropdown shape and the dialog alike (default: localized `dataEntry.recordPicker.empty`). Say WHAT has no match, e.g. 「該当するファイルはありません」.",
+        "name": "notFoundContent",
+        "type": "ReactNode"
+      },
+      {
+        "description": "Text of the dialog's load-more button (default: localized `dataEntry.recordPicker.more`). Only the label — the button still appears only while the server returns a `nextCursor`.",
+        "name": "loadMoreLabel",
+        "type": "ReactNode"
+      },
       {
         "description": "Control height of the trigger, on the shared control ladder.",
         "name": "size",
@@ -9072,7 +9099,7 @@
         "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.",
+        "description": "antd `loadData` — lazy children. Called when a branch that has no children and isLeaf !== true is expanded, and never again once its promise resolves; push the fetched children into options. A rejected promise is forgotten, so the next activation of the branch asks again (gh#1041).",
         "name": "loadData",
         "type": "(selectedOptions: TreeOptionProp[]) => void | Promise<void>"
       },
@@ -9313,7 +9340,7 @@
         "type": "boolean"
       },
       {
-        "description": "antd `loadData` — lazy children. Called ONCE per node that has no children and isLeaf !== true, the first time it is expanded; push the fetched children into treeData. Such a node still reads as expandable (aria-expanded + a working expander).",
+        "description": "antd `loadData` — lazy children. Called when a node that has no children and isLeaf !== true is expanded, and never again once its promise resolves; push the fetched children into treeData. A rejected promise folds the branch shut and the next expand asks again, up to 10 attempts (rc-tree, gh#1041). Such a node still reads as expandable (aria-expanded + a working expander).",
         "name": "loadData",
         "type": "(node: TreeOptionProp) => void | Promise<void>"
       },
@@ -9475,6 +9502,11 @@
         "name": "onSelectChange",
         "type": "(sourceSelectedKeys: string[], targetSelectedKeys: string[]) => void"
       },
+      {
+        "description": "antd `locale`, ported for `notFoundContent` only: what an empty or search-emptied pane shows (default: localized `dataEntry.transfer.empty`). A `[source, target]` pair sets each pane separately, as in antd.",
+        "name": "locale",
+        "type": "{ notFoundContent?: ReactNode | [ReactNode, ReactNode] }"
+      },
       {
         "description": "Fires when items move between panels; you own `targetKeys` state.",
         "name": "onValueChange",
@@ -11040,7 +11072,7 @@
         "type": "boolean"
       },
       {
-        "description": "Lazy children (antd `loadData`). Called ONCE per node the first time a branch with no `children` and `isLeaf !== true` is expanded; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`.",
+        "description": "Lazy children (antd `loadData`). Called when a branch with no `children` and `isLeaf !== true` is expanded, and never again once its promise RESOLVES; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`. A REJECTED promise is not a load (rc-tree, gh#1041): the branch folds back shut (uncontrolled expansion) and the next expand asks again, up to 10 attempts.",
         "name": "loadData",
         "type": "(node: TreeNodeProp) => void | Promise<void>"
       },
@@ -11049,6 +11081,22 @@
         "name": "titleRender",
         "type": "(node: TreeNodeProp) => ReactNode"
       },
+      {
+        "description": "Highlight the nodes this returns true for (antd `filterTreeNode`, gh#1043) — the match of a search box above the tree. Matching rows are MARKED, not hidden: `data-filter-node=\"true\"`, the label in `--tree-node-filter-foreground` (default `hsl(var(--primary))`) at the medium weight, plus sr-only \"matches the filter\" text. Outline, keyboard and ARIA are unchanged. To also open the branches that hold a match, drive `expandedValues`.",
+        "name": "filterTreeNode",
+        "type": "(node: TreeNodeProp) => boolean"
+      },
+      {
+        "description": "Viewport height in px (antd `height`, gh#1042). The tree scrolls inside it and, unless `virtual={false}`, renders only the rows in view plus a small overscan — the windowed rows stay a flat run of treeitems whose `aria-level`/`aria-setsize`/`aria-posinset` still describe the whole outline. Rows must share one height (the `size` tier).",
+        "name": "height",
+        "type": "number"
+      },
+      {
+        "defaultValue": "true",
+        "description": "Set `false` to keep the `height` viewport but render every row (antd `virtual`).",
+        "name": "virtual",
+        "type": "boolean"
+      },
       {
         "defaultValue": "false",
         "description": "Draw the connector rails between a parent and its children (antd `showLine`). Off by default — a rail is chrome, and chrome defaults quiet.",
@@ -11106,7 +11154,7 @@
       "TreeSelect — the same hierarchy INSIDE a Popover, as a form field. Use TreeSelect when the answer is a value in a form; use Tree when the hierarchy itself is the page.",
       "Cascader — a path picker across columns. Use it when the user walks one path to a leaf; use Tree when several branches are open at once.",
       "Accordion — single-level disclosure with rich panel content. It is not a hierarchy and has no tree keyboard model.",
-      "ScrollArea — wrap Tree in one to cap a long outline; Tree does not virtualise in v1."
+      "ScrollArea — not needed around Tree: pass `height`, and the tree is its own (windowed) scroll viewport."
     ],
     "rules": [
       2,
@@ -11126,8 +11174,9 @@
       "DON'T nest a Button, Checkbox, Link or any focusable control inside a node label. A tree item owns exactly ONE tab stop; the disclosure triangle and the tick box are decorative glyphs for that reason. Put row actions in a sibling column outside the tree, or open a detail pane on selection.",
       "DON'T hand-roll an indented `<ul>` (or a NavList / ListRow stack with a per-depth margin) for a hierarchy. A flat indented list only LOOKS like a tree: no expand/collapse, no `role=\"tree\"`, no keyboard model, no selection contract. `TreeList` was exactly that list and was REMOVED in 21.0.0 — Tree is what replaced it, and it is the one to reach for whenever nodes expand, collapse or are keyboard-navigated.",
       "DO pass `divided` when the tree IS the navigation of a page — a wiki/document outline or a section index sitting in a `Card` (`Card` > `CardContent flush` > `Tree divided`). Without a rule the rows run together and the outline reads as one block; with it, it reads as the ruled list ListRow and Table already give a flat list. Retint it per theme with `--tree-divider-color`, never with a per-page utility class.",
-      "DO cap a long tree with `ScrollArea` — virtualisation is not in v1, so a 5,000-node tree renders 5,000 rows.",
-      "DO push fetched children into `treeData` from `loadData`; the tree calls it once per node and shows a Skeleton row until the data lands."
+      "DO pass `height` for a long tree (antd `height` + `virtual`): the tree scrolls inside that height and keeps only the rows in view in the DOM, so a 421-child level renders a few dozen rows. Do not wrap it in `ScrollArea` as well — the tree is its own viewport.",
+      "DO push fetched children into `treeData` from `loadData`; the tree calls it once per node that loads and shows a Skeleton row until the data lands. Reject the promise on failure — the branch folds shut and the next expand retries.",
+      "DON'T wait for a paged \"load more\" node — antd's Tree has none, and `height` covers a long list. If the API itself is paged, append a leaf node such as `{ value: `${parent}::more`, label: t(\"…load more\"), isLeaf: true }` to the loaded children and fetch the next page from `onValueChange` when it is selected: it is a real treeitem, so it is keyboard-reachable and announced."
     ],
     "useCases": [
       "A permission tree: modules → resources → actions with tri-state checkboxes, where ticking a module ticks everything under it and a partly-granted module shows the dash.",
@@ -14649,6 +14698,11 @@
         "name": "searchable",
         "type": "boolean"
       },
+      {
+        "description": "antd `notFoundContent` — shown when the branch SEARCH matches nothing (default: localized `dataEntry.branchScope.noMatches`). An empty `branches` list is `empty`'s job, not this.",
+        "name": "notFoundContent",
+        "type": "ReactNode"
+      },
       {
         "description": "Override the localized radio labels (e.g. domain wording like 全店舗).",
         "name": "allLabel / selectedLabel",
@@ -15608,6 +15662,65 @@
       "ThoughtChainItem alone: the chip an assistant drops inline to name the tool it just reached for."
     ]
   },
+  {
+    "docPath": "data-display/org-chart.tsx",
+    "example": "import { Avatar, AvatarFallback, Badge, OrgChart } from \"@godxjp/ui/data-display\";\n\n<OrgChart\n  label=\"Company org chart\"\n  data={[\n    {\n      key: \"ceo\", name: \"Haruka Tanaka\", title: \"CEO\",\n      avatar: <Avatar size=\"sm\"><AvatarFallback>HT</AvatarFallback></Avatar>,\n      children: [\n        { key: \"cto\", name: \"Kenji Watanabe\", title: \"CTO\" },\n        { key: \"bot\", name: \"Review Agent\", title: \"Code review\", variant: \"agent\",\n          extra: <Badge tone=\"success\">Running</Badge> },\n      ],\n    },\n  ]}\n/>",
+    "group": "data-display",
+    "importPath": "@godxjp/ui/data-display",
+    "name": "OrgChart",
+    "props": [
+      {
+        "description": "The hierarchy: { key, name, title?, avatar?, extra?, variant?: \"person\" | \"agent\", children? }. `key` is unique across the chart. `avatar` is usually an <Avatar>; `extra` a Badge or status.",
+        "name": "data",
+        "type": "OrgChartNodeProp[]"
+      },
+      {
+        "description": "Replace a box's content. The box, its border, the connectors and the keyboard stay the library's; the narrow Tree form uses it too.",
+        "name": "renderNode",
+        "type": "(node: OrgChartNodeProp) => ReactNode"
+      },
+      {
+        "description": "Accessible name of the role=\"tree\" (a plain string). Localized default \"Organization chart\".",
+        "name": "label",
+        "type": "string"
+      },
+      {
+        "description": "DOM id of the root.",
+        "name": "id",
+        "type": "string"
+      },
+      {
+        "description": "Root class.",
+        "name": "className",
+        "type": "string"
+      }
+    ],
+    "related": [
+      "Tree — the indented, collapsible outline. OrgChart renders it as its narrow form.",
+      "Avatar — the mark in each box.",
+      "Badge — a status in a box's `extra` slot."
+    ],
+    "rules": [
+      2,
+      6,
+      23,
+      44,
+      45
+    ],
+    "storyPath": "data-display/OrgChart.stories.tsx",
+    "tagline": "An organization chart: boxes (avatar, name, title, extra) joined by CSS connector lines, top-down; `agent` nodes are dashed. Scrolls horizontally in its own named region when wider than its container, and turns into an indented Tree when the CONTAINER is under 40rem. APG tree view (tree/treeitem/group, roving tabindex, arrow keys).",
+    "usage": [
+      "DO mark AI agents with `variant: \"agent\"` — the box is dashed AND its accessible name ends in a localized \"AI agent\", so the kind is never carried by the stroke alone.",
+      "DO give it the width it has; the breakpoint is a container query, so a chart in a narrow side panel switches to the Tree form on a wide screen too.",
+      "DO retune boxes and lines through the --org-chart-* tokens (node size, gaps, line width/colour, agent border style).",
+      "DON'T wrap it in your own overflow-x scroller — it owns its scroll region, which only becomes a named tab stop when the chart actually overflows.",
+      "DON'T use it for an outline users expand and collapse — that is Tree. OrgChart always shows every node."
+    ],
+    "useCases": [
+      "A company or team org chart with people and AI agents side by side.",
+      "Reporting lines on an admin screen, falling back to an indented list in a narrow panel or on a phone."
+    ]
+  },
   {
     "docPath": "data-entry/attachments.tsx",
     "example": "import { Attachments } from \"@godxjp/ui/data-entry\";\n\n<Attachments\n  items={files}\n  onChange={({ fileList }) => setFiles(fileList)}\n  overflow=\"scrollX\"\n  maxCount={5}\n/>",