@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/Command.json

@@ -0,0 +1,168 @@
+{
+  "example": "{`import {\n  Command,\n  CommandEmpty,\n  CommandGroup,\n  CommandInput,\n  CommandItem,\n  CommandList,\n} from \"@godxjp/ui/data-entry\";\n\nfunction AccountQuickPick({ onSelect }: { onSelect: (id: string) => void }) {\n  return (\n    <Command label=\"Quick pick account\" loop>\n      <CommandInput placeholder=\"Search accounts…\" />\n      <CommandList>\n        <CommandEmpty>No accounts found.</CommandEmpty>\n        <CommandGroup heading=\"Revenue\">\n          <CommandItem value=\"4001\" onSelect={onSelect}>\n            Sales Revenue\n          </CommandItem>\n          <CommandItem value=\"4002\" onSelect={onSelect}>\n            Service Revenue\n          </CommandItem>\n        </CommandGroup>\n        <CommandGroup heading=\"Expenses\">\n          <CommandItem value=\"6001\" onSelect={onSelect}>\n            Rent Expense\n          </CommandItem>\n          <CommandItem value=\"6002\" disabled onSelect={onSelect}>\n            Deprecated Account\n          </CommandItem>\n        </CommandGroup>\n      </CommandList>\n    </Command>\n  );\n}`}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Command",
+  "props": [
+    {
+      "description": "Accessible label for the command menu. Not shown visually — used by screen readers.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Set to false to disable automatic filtering and sorting. When false, you must conditionally render matching items yourself based on the search query.",
+      "name": "shouldFilter",
+      "type": "boolean"
+    },
+    {
+      "description": "Custom filter function. Returns a score between 0 (hidden) and 1 (best match). Defaults to command-score library scoring.",
+      "name": "filter",
+      "type": "(value: string, search: string, keywords?: string[]) => number"
+    },
+    {
+      "description": "Default selected item value on initial render (uncontrolled).",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Controlled state of the currently selected item value.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Called when the selected item changes.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, keyboard arrow-key navigation wraps from last item back to first and vice versa.",
+      "name": "loop",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, pointer events cannot select items — keyboard only.",
+      "name": "disablePointerSelection",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Set to false to disable ctrl+n/j/p/k vim-style navigation shortcuts.",
+      "name": "vimBindings",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd List `split`. Draws the list as ONE ruled box: group/list padding 0, rows full-bleed to the panel edge with a square highlight, a hairline border-block-end between rows and none after the last visible row, row content aligned with CommandInput's leading glyph. Sets `data-split` on the root; the parts need no prop. Tokens: --command-list-split-padding, --command-list-split-inset, --command-item-divider-width, --command-item-divider-color. Select mode=multiple / mode=tags renders its popup split by default.",
+      "name": "split",
+      "type": "boolean"
+    },
+    {
+      "description": "Additional CSS classes merged onto the root div via cn().",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Controlled search string for the input.",
+      "name": "CommandInput.value",
+      "type": "string"
+    },
+    {
+      "description": "Called when the search input text changes.",
+      "name": "CommandInput.onValueChange",
+      "type": "(search: string) => void"
+    },
+    {
+      "description": "Accessible label for the list of suggestions. Not shown visually.",
+      "name": "CommandList.label",
+      "type": "string"
+    },
+    {
+      "description": "Unique value for this item. If omitted, inferred from children textContent — must be stable; provide explicitly when text changes between renders.",
+      "name": "CommandItem.value",
+      "type": "string"
+    },
+    {
+      "description": "Called when this item is selected via click or keyboard.",
+      "name": "CommandItem.onSelect",
+      "type": "(value: string) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Prevents this item from being selected.",
+      "name": "CommandItem.disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Additional keywords matched during filtering that are not part of the visible label.",
+      "name": "CommandItem.keywords",
+      "type": "string[]"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, renders this item regardless of filtering results.",
+      "name": "CommandItem.forceMount",
+      "type": "boolean"
+    },
+    {
+      "description": "Visible heading rendered above items in this group.",
+      "name": "CommandGroup.heading",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Required unique identifier for the group when no heading is provided.",
+      "name": "CommandGroup.value",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, renders this group regardless of filtering.",
+      "name": "CommandGroup.forceMount",
+      "type": "boolean"
+    },
+    {
+      "description": "Renders automatically only when there are no matching results. Place inside CommandList.",
+      "name": "CommandEmpty",
+      "type": "React.ReactNode (children)"
+    }
+  ],
+  "related": [
+    "SearchSelect — higher-level compound component that composes Command + Popover + server search; use SearchSelect for a fully managed async combobox instead of building your own with Command.",
+    "Select — simple dropdown for static option lists without type-to-filter; use Select when there are fewer than ~10 options and no search is needed.",
+    "SearchInput — standalone text input with a search icon; use SearchInput for filtering visible page content (tables, lists) not for selecting from a command menu.",
+    "CommandInput (sub-part) — the styled search input that only works inside a Command root; never use it alone as a general search field."
+  ],
+  "rules": [
+    2,
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-entry/Command.stories.tsx",
+  "subParts": [
+    "CommandEmpty",
+    "CommandGroup",
+    "CommandInput",
+    "CommandItem",
+    "CommandList"
+  ],
+  "tagline": "Accessible, keyboard-navigable command palette / combobox list built on cmdk — always pair CommandInput inside its own wrapper div, never render items outside CommandList.",
+  "usage": [
+    "DO compose the full tree: Command > CommandInput + CommandList > (CommandEmpty | CommandGroup > CommandItem | CommandItem). Every interactive element must live inside CommandList; items outside it are invisible to the keyboard engine.",
+    "DO set shouldFilter={false} and manage filtering yourself when the options list comes from a server/async source (e.g. SearchSelect pattern). With shouldFilter=true the default client-side scoring runs over all rendered items automatically.",
+    "DO always provide a stable explicit value prop on CommandItem when the item's text content can change between renders — relying on inferred textContent with dynamic labels causes selection bugs.",
+    "DO include CommandEmpty inside CommandList to show a no-results message. It renders automatically only when the filtered count is zero; do not conditionally render it yourself.",
+    "DO use split for checkbox/option lists (a filter facet, a picker: Popover + PopoverContent flush + Command split) — rows get a divider between them and 0 list padding, so they read as one box. Keep the default (unsplit) for a command palette. Never re-create the look with page CSS (border on items, padding 0 on the group): retune --command-item-divider-color / --command-item-divider-width instead.",
+    "DON'T use CommandInput as a standalone search input — it is only meaningful inside a Command root (the root manages shared filter state). For a standalone search field use SearchInput instead.",
+    "DON'T hand-roll keyboard navigation on a list of items; Command handles arrow keys, Enter, Escape, Home/End, and vim bindings. Adding your own keyDown handlers on top creates conflicts — use onSelect on CommandItem for selection logic."
+  ],
+  "useCases": [
+    "Command palette / global action launcher (Cmd+K menu): wraps Command + CommandInput + grouped CommandItems for quick navigation across pages or actions.",
+    "Popover-based combobox with server-side search: Command with shouldFilter={false} inside a Popover, managing the query state externally and filtering options before rendering — this is exactly how SearchSelect is built internally.",
+    "Tree/cascader search panel: inject Command + CommandInput as a search header above a custom scroll area (no CommandList needed for the tree body) to get a styled, accessible search input — as used by CascaderSelect and TreeSelect.",
+    "Multi-group option picker: use CommandGroup with heading to visually separate option categories (e.g. 'Accounts', 'Contacts', 'Documents') inside one dropdown with a single search box.",
+    "Keyboard-first admin shortcut bar: embed Command with loop={true} and vimBindings={true} in a persistent sidebar for power-user keyboard navigation without page reloads."
+  ]
+}

package/agent/components/CommandPalette.json

@@ -0,0 +1,84 @@
+{
+  "example": "import { CommandPalette } from \"@godxjp/ui/data-entry\";\n\n<CommandPalette\n  groups={[{ id: \"pages\", label: \"Pages\", items: [{ id: \"home\", label: \"Home\" }] }]}\n  labels={{ open: \"Open commands\", title: \"Commands\", description: \"Choose a command\", placeholder: \"Search\", empty: \"No results\" }}\n  onSelect={(item) => navigate(item.id)}\n/>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "CommandPalette",
+  "props": [
+    {
+      "description": "Grouped command items.",
+      "name": "groups",
+      "required": true,
+      "type": "CommandPaletteGroup[]"
+    },
+    {
+      "description": "Localized dialog and search copy.",
+      "name": "labels",
+      "required": true,
+      "type": "CommandPaletteLabels"
+    },
+    {
+      "description": "Consumer-owned selection handler.",
+      "name": "onSelect",
+      "required": true,
+      "type": "(item: CommandPaletteItem) => void"
+    },
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Initial uncontrolled open state.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state callback.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Controlled search-box query. Pairs with `onSearchChange`.",
+      "name": "search",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"\"",
+      "description": "Initial uncontrolled query, and the value the palette resets to when it closes.",
+      "name": "defaultSearch",
+      "type": "string"
+    },
+    {
+      "description": "Fires on every keystroke with the current query — the seam for search-as-you-type. Also fires with `defaultSearch` when the palette closes.",
+      "name": "onSearchChange",
+      "type": "(query: string) => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Whether the palette filters `groups` itself. Set false for server-side search, which also hands the empty node to the palette (derived from `groups`).",
+      "name": "shouldFilter",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Shows the supplied loading content.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Consumer-supplied error content.",
+      "name": "error",
+      "type": "ReactNode"
+    }
+  ],
+  "rules": [],
+  "storyPath": "data-entry/CommandPalette.stories.tsx",
+  "tagline": "Searchable command dialog with controlled or uncontrolled open state and consumer-owned selection.",
+  "usage": [
+    "Provide localized labels and real command groups; the component does not fetch commands.",
+    "Use either `open` plus `onOpenChange` or `defaultOpen`; do not mirror both state models.",
+    "Search-as-you-type against an API: read the query from `onSearchChange`, pass the results back as `groups`, and set `shouldFilter={false}` so the rows are not scored a second time against the same string.",
+    "The empty-state contract: with `shouldFilter` (default) cmdk decides — items exist, the query matches none. With `shouldFilter={false}` the PALETTE decides from props — `labels.empty` renders when `groups` carries no items, and never while `loading` or `error` is set. Hold `loading` for the whole in-flight window: a request that has not answered yet is not an empty result, and asserting over cmdk's own empty node races an async group that populates a frame late."
+  ]
+}

package/agent/components/CompactBarTrend.json

@@ -0,0 +1,101 @@
+{
+  "example": "import { CompactBarTrend } from \"@godxjp/ui/charts/compact-bar-trend\";\n\n<CompactBarTrend\n  label={t(\"dashboard.newOrganizations7d\")}\n  description={t(\"dashboard.newOrganizationsHint\")}\n  data={trend}\n  categoryKey=\"date\"\n  valueKey=\"count\"\n  emphasizedIndex={-1}\n  size=\"xs\"\n  footer={<Text size=\"xs\" tone=\"muted\">{t(\"dashboard.lastUpdated\", { at })}</Text>}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/charts/compact-bar-trend",
+  "name": "CompactBarTrend",
+  "props": [
+    {
+      "description": "Row data — one bar per row. Any point count (7 is not hard-coded).",
+      "name": "data",
+      "required": true,
+      "type": "ChartDatum[]"
+    },
+    {
+      "description": "Key into each datum holding the category (tick) label.",
+      "name": "categoryKey",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Key into each datum holding the plotted numeric value.",
+      "name": "valueKey",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Accessible name + visible caption.",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Paint `label` as a visible caption. Set false when a CardTitle or section heading already says it — the caption stays in the DOM as sr-only, so role=img keeps its accessible name.",
+      "name": "showCaption",
+      "type": "boolean"
+    },
+    {
+      "description": "Extra context appended to the screen-reader description.",
+      "name": "description",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"xs\"",
+      "description": "Plot-height tier (--chart-trend-plot-height-*). xs is the dashboard summary-card density.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Index of the emphasized 'current' bar. Negative counts from the end (-1 = latest); out of range = no emphasis. Also annotated in the text alternative, so it is never colour-only.",
+      "name": "emphasizedIndex",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Render the category tick labels under the plot.",
+      "name": "showCategoryLabels",
+      "type": "boolean"
+    },
+    {
+      "description": "Locale-aware formatting for the values in the text alternative.",
+      "name": "numberFormat",
+      "type": "Intl.NumberFormatOptions"
+    },
+    {
+      "description": "Activity footer slot below the plot, rendered OUTSIDE the role=img graphic so links/buttons in it stay reachable.",
+      "name": "footer",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Message shown when `data` is empty.",
+      "name": "emptyMessage",
+      "type": "string"
+    },
+    {
+      "description": "Forwarded to the <figure> element.",
+      "name": "ref",
+      "type": "React.Ref<HTMLElement>"
+    }
+  ],
+  "related": [
+    "BarChart — full cartesian bar chart with axes/grid/tooltip/legend (requires the recharts optional peer).",
+    "StatCard — the KPI headline this trend usually sits under.",
+    "Progress — one ratio against a target, not a series over time."
+  ],
+  "rules": [],
+  "storyPath": "charts/CompactBarTrend.stories.tsx",
+  "tagline": "DEPENDENCY-FREE compact vertical bar trend for dashboard summary cards — N category/value pairs, muted marks plus ONE emphasized 'current' bar, all geometry from --chart-trend-* tokens. Needs NO recharts. Sparkline / micro-chart / activity pulse / KPI trend strip.",
+  "usage": [
+    "DO import from the isolated entry: `import { CompactBarTrend } from \"@godxjp/ui/charts/compact-bar-trend\";` — unlike the charts barrel, this path never links modules that require the optional `recharts` peer.",
+    "DO reach for it INSIDE a dashboard summary card (a 7-day signup/organization/activity strip under a StatCard headline) — that is the density `size=\"xs\"` is tuned for.",
+    "DO mark the current period with `emphasizedIndex={-1}` (or an explicit index); the highlight is duplicated in the screen-reader text alternative, so it never depends on colour alone.",
+    "DO retheme through the `--chart-trend-*` tokens (bar gap/radius/width, plot heights, muted + emphasis fills, opt-in baseline). NEVER add page-local CSS, an inline height calculation, or a hardcoded colour.",
+    "DON'T use it when you need axes, a grid, tooltips, multiple series, or a continuous trend — that is BarChart / LineChart / AreaChart (recharts peer). DON'T fake bars with styled divs in the app.",
+    "DON'T put interactive content in the plot: anything clickable goes in `footer`, which renders outside the `role=\"img\"` graphic."
+  ],
+  "useCases": [
+    "Seven-day new-organizations / new-users trend inside an admin dashboard summary card (SCR-201).",
+    "Weekly activity pulse beside a KPI headline, where the SHAPE matters more than exact figures.",
+    "A dependency-constrained app (no recharts) that still needs a token-driven chart."
+  ]
+}

package/agent/components/Conversations.json

@@ -0,0 +1,82 @@
+{
+  "docPath": "navigation/conversations.tsx",
+  "example": "import { Conversations } from \"@godxjp/ui/navigation\";\n\nconst [active, setActive] = useState(\"c1\");\n\n<Conversations\n  activeKey={active}\n  onActiveChange={setActive}\n  groupable={{ collapsible: true }}\n  creation={{ onClick: () => startNewChat() }}\n  items={[\n    { key: \"c1\", label: \"請求書の下書き\", group: \"today\" },\n    { key: \"c2\", label: \"経費精算の規則\", group: \"today\" },\n    { key: \"c3\", label: \"出張手当の確認\", group: \"earlier\" },\n  ]}\n  menu={{\n    items: [\n      { key: \"rename\", label: \"名前を変更\" },\n      { key: \"delete\", label: \"削除\", danger: true },\n    ],\n    onClick: ({ key, conversation }) => run(key, conversation.key),\n  }}\n/>",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "Conversations",
+  "props": [
+    {
+      "description": "The rows. A conversation is { key, label?, group?, icon?, disabled? }; a rule between runs is { type: \"divider\", key?, dashed? }. Ant Design X `items`.",
+      "name": "items",
+      "type": "(ConversationsItemProp | ConversationsDividerProp)[]"
+    },
+    {
+      "description": "Controlled selection — the key of the conversation on screen. Ant Design X `activeKey`.",
+      "name": "activeKey",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial selection. Ant Design X `defaultActiveKey`.",
+      "name": "defaultActiveKey",
+      "type": "string"
+    },
+    {
+      "description": "Fires with the picked key and the entry behind it. Ant Design X `onActiveChange`.",
+      "name": "onActiveChange",
+      "type": "(key: string, item?: ConversationsItemProp | ConversationsDividerProp) => void"
+    },
+    {
+      "description": "The per-row overflow menu: { items: [{ key, label, icon?, danger?, disabled? }], onClick?, triggerLabel? }. Pass a function to vary it per row, or return undefined for a row that has no menu. Ant Design X `menu` (antd MenuProps there).",
+      "name": "menu",
+      "type": "ConversationsMenuProp | ((conversation: ConversationsItemProp) => ConversationsMenuProp | undefined)"
+    },
+    {
+      "description": "Bucket rows by their `group` field. The object form takes label (node or (group) => node), collapsible (boolean or (group) => boolean), defaultExpandedKeys, expandedKeys and onExpand. Ant Design X `groupable`.",
+      "name": "groupable",
+      "type": "boolean | ConversationsGroupableProp"
+    },
+    {
+      "description": "The \"new conversation\" button pinned above the rail: { label?, icon?, disabled?, onClick? }. Ant Design X `creation`.",
+      "name": "creation",
+      "type": "ConversationsCreationProp"
+    },
+    {
+      "description": "Accessible name of the rail (a plain string — it lands on aria-label). Localized default otherwise.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the rail root.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ChatBubbleList — the feed beside this rail; Conversations picks WHICH feed is shown.",
+    "ListRow — a single-line entity row with a trailing action, for short lists inside a Card. It has no selection, no roving focus and no grouping.",
+    "Sidebar / NavList — route navigation. Use those when a row changes the URL; use Conversations when a row changes which conversation the surface is on.",
+    "DropdownMenu — what the per-row `menu` renders; compose it directly when the menu is not attached to a conversation row."
+  ],
+  "rules": [
+    2,
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "navigation/Conversations.stories.tsx",
+  "tagline": "The session rail of a chat surface (Ant Design X Conversations): past conversations, the current one marked with aria-current, a per-row overflow menu, and recency buckets — the whole rail one roving-tabindex tab stop, not one tab stop per conversation.",
+  "usage": [
+    "DO give every conversation a stable `key` — it is what activeKey, onActiveChange and the menu callback all address. A key that changes on re-render moves the selection.",
+    "DO reach for `menu` for rename/delete instead of adding a second Button to each row. The trigger is keyboard-reachable with the forward arrow (→ in LTR, ← in RTL), so a row's second action costs no extra tab stop.",
+    "DO pass `menu.triggerLabel` when the rows are user content: the default names the row, and twelve identical \"More actions\" buttons are indistinguishable in a screen reader's element list.",
+    "DON'T hand-roll the rail out of full-width Buttons plus aria-current. That is one tab stop PER conversation; this is one for the whole rail, with ↑/↓/Home/End inside it.",
+    "DON'T expect `styles`/`classNames` from Ant Design X — they are deliberately not ported. Retune the rail through the --conversations-* tokens (rules #44/#45).",
+    "DO use `groupable={{ collapsible: true }}` for \"Today / Previous 7 days\": the bucket headings join the same roving order, so collapsing a bucket is reachable without leaving the rail."
+  ],
+  "useCases": [
+    "The assistant rail of a chat product — past sessions, the current one marked, rename and delete per row.",
+    "Recency buckets over a long history (Today / Yesterday / Previous 7 days) with the older buckets collapsed.",
+    "A rail beside ChatBubbleList and ChatComposer: the three are one surface, and Conversations is the half that used to be missing."
+  ]
+}

package/agent/components/CredentialReveal.json

@@ -0,0 +1,93 @@
+{
+  "example": "import { CredentialReveal } from \"@godxjp/ui/data-display\";\nimport { Dialog, DialogContent, DialogHeader, DialogTitle } from \"@godxjp/ui/feedback\";\n\n<Dialog open={open} onOpenChange={setOpen}>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>APIキーを発行しました</DialogTitle>\n    </DialogHeader>\n    <CredentialReveal\n      label=\"APIキー\"\n      secret=\"gxp_live_8Fh2kQ9wR7nZ1xV4bT6mL0cD\"\n      downloadable\n      onAcknowledge={() => setOpen(false)}\n    />\n  </DialogContent>\n</Dialog>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "CredentialReveal",
+  "props": [
+    {
+      "description": "The one-time secret value.",
+      "name": "secret",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Accessible name / caption for the secret (e.g. 'API key').",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "Caution banner copy; defaults to a localized 'shown only once' warning. Pass null to suppress the banner.",
+      "name": "warning",
+      "type": "React.ReactNode | null"
+    },
+    {
+      "description": "Controlled reveal state (with defaultRevealed / onRevealedChange).",
+      "name": "revealed",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Uncontrolled initial reveal state.",
+      "name": "defaultRevealed",
+      "type": "boolean"
+    },
+    {
+      "description": "Reveal toggle handler.",
+      "name": "onRevealedChange",
+      "type": "(revealed: boolean) => void"
+    },
+    {
+      "description": "Called after the secret is written to the clipboard.",
+      "name": "onCopy",
+      "type": "(secret: string) => void"
+    },
+    {
+      "description": "Renders a confirm button; wire it to the Dialog's onOpenChange(false).",
+      "name": "onAcknowledge",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Offer a download-as-file button.",
+      "name": "downloadable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Action button size tier.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"warning\"",
+      "description": "Caution banner severity.",
+      "name": "tone",
+      "type": "\"warning\" | \"destructive\" | \"info\""
+    }
+  ],
+  "related": [
+    "PasswordInput — editable password/secret ENTRY with a show/hide toggle (data-entry); CredentialReveal is read-only DISPLAY of an issued secret.",
+    "Dialog — the modal CredentialReveal is designed to live inside.",
+    "Alert — the caution banner CredentialReveal composes internally."
+  ],
+  "rules": [
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-display/CredentialReveal.stories.tsx",
+  "tagline": "One-time secret surface — masked-by-default value with a show/hide toggle, a copy button that confirms the copy, optional download, and an optional acknowledge action to pair with Dialog. The GitHub/Stripe token-reveal pattern as a real primitive so consumers stop hand-rolling it.",
+  "usage": [
+    "DO use for a secret shown exactly once after creation (device credential, API key, service-account secret) — it masks by default and confirms the copy.",
+    "DO pair it inside a Dialog and reset via controlled `revealed`/`onRevealedChange` (or let it re-blur automatically when the `secret` prop changes) so a reopened dialog starts masked.",
+    "DO pass `onAcknowledge` to gate the dialog close behind an explicit 'I've saved it' confirmation.",
+    "DON'T use it for an editable password field — that's PasswordInput. CredentialReveal is read-only display of an issued secret.",
+    "DON'T hand-roll the copy button + copied-state + aria-live announcement; it's built in."
+  ],
+  "useCases": [
+    "Device credential issued after enrollment",
+    "API key / personal access token shown once on creation",
+    "Service-account secret / client secret reveal",
+    "Recovery code or one-time bootstrap password"
+  ]
+}

package/agent/components/DataState.json

@@ -0,0 +1,79 @@
+{
+  "example": "import { DataState } from \"@godxjp/ui/query\";\n\n<DataState query={membersQuery} skeleton={<SkeletonTable />} isEmpty={(d) => d.items.length === 0} empty={<EmptyState title=\"会員なし\" />}>\n  {(d) => <MemberTable items={d.items} />}\n</DataState>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/query",
+  "name": "DataState",
+  "props": [
+    {
+      "description": "The useQuery result.",
+      "name": "query",
+      "required": true,
+      "type": "UseQueryResult<T>"
+    },
+    {
+      "description": "Shown while loading.",
+      "name": "skeleton",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Shown when the query is disabled/unstarted (pending + fetchStatus idle).",
+      "name": "prerequisite",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Force Retry even for non-transient causes. Retry is offered automatically for transient/network/5xx errors regardless of this flag.",
+      "name": "showRetry",
+      "type": "boolean"
+    },
+    {
+      "description": "Recovery for 401 / expired-token errors: renew the session or sign in again. A 401 renders this action instead of Retry.",
+      "name": "onAuthError",
+      "type": "() => void"
+    },
+    {
+      "description": "Render function with resolved data.",
+      "name": "children",
+      "required": true,
+      "type": "(data) => ReactNode"
+    },
+    {
+      "description": "Shown when isEmpty(data) is true.",
+      "name": "empty",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Custom empty check.",
+      "name": "isEmpty",
+      "type": "(data) => boolean"
+    }
+  ],
+  "related": [
+    "InfiniteQueryState — use instead of DataState when the query is `useInfiniteQuery`; it accepts a `flatten` function to reduce pages and adds a load-more footer. DataState cannot accept `UseInfiniteQueryResult`.",
+    "SkeletonTable / SkeletonStat — pass as the `skeleton` prop of DataState; they are not standalone replacements for DataState, only the loading slot inside it.",
+    "EmptyState — pass as the `empty` prop of DataState alongside a matching `isEmpty` predicate; do not hand-roll an empty-check outside DataState by inspecting `query.data` yourself.",
+    "AlertMutationFeedback — sibling widget for mutation (not query) lifecycle; use it below a form submit button to surface `useMutation` errors, not DataState which only handles `useQuery`."
+  ],
+  "rules": [],
+  "storyPath": "query/DataState.stories.tsx",
+  "tagline": "TanStack Query lifecycle widget — skeleton / error / empty / success for one useQuery block. Import from @godxjp/ui/query.",
+  "usage": [
+    "DO: pass a `UseQueryResult<T>` directly from `useQuery` — DataState reads `isPending`, `isError`, `isFetching`, `data`, and `error` off it; never destructure those fields manually and branch yourself.",
+    "DO: always provide a `skeleton` — it renders during both the initial pending phase and during a re-fetch after an error; pass `<SkeletonTable />` for tabular data or `<SkeletonStat />` for stat card lists — never `null` or a spinner div.",
+    "DO: provide `empty` + `isEmpty` together when the data can legitimately return 0 items — e.g. `isEmpty={(d) => d.items.length === 0}` paired with `empty={<EmptyState title=\"…\" />}`. Omitting `empty` means an empty array still falls through to `children`, silently rendering a blank table.",
+    "DON'T: wrap DataState in your own conditional — e.g. `{query.isSuccess && <DataState …>}`. DataState IS the conditional; the outer guard is redundant and breaks the retry/refetch skeleton.",
+    "DON'T: use DataState for `useInfiniteQuery` results. The `query` prop type is `UseQueryResult<T>`, not `UseInfiniteQueryResult`. Use `InfiniteQueryState` (from `@godxjp/ui/query`) instead, which accepts `flatten` and renders a load-more footer.",
+    "DO: classify errors by cause. Use session renewal/sign-in for 401, access guidance for 403, contextual correction for domain errors, and opt into showRetry only for transient network/5xx errors.",
+    "DO: pass prerequisite for enabled:false queries. Pending + fetchStatus idle is unstarted, not loading, and never renders a skeleton.",
+    "DO: rely on the localized, cause-specific error message — the raw backend/token/stack text is never shown. For a domain-specific message (e.g. a 422 field error) pass a custom errorRenderer.",
+    "DO: expect a background refetch over existing data to keep the content on screen with a polite sr-only busy status — it does not flash the skeleton. Only the initial fetch (isPending) shows the skeleton."
+  ],
+  "useCases": [
+    "A detail page that loads a single invoice/journal entry via `useQuery` — DataState renders the skeleton row while fetching, an error alert with retry if the API fails, and the `<InvoiceCard>` only when data is confirmed non-null.",
+    "A list page that shows a `DataTable` of members/partners — wrap the table in DataState so the skeleton matches the column count while loading and `EmptyState` appears when the filtered result set is empty.",
+    "A sidebar panel that lazily loads related transactions for the selected entity — DataState keeps the panel in skeleton state during the background fetch without any manual `isPending` branching in the parent.",
+    "A dashboard stat card that calls a summary API — DataState handles the loading/error/empty lifecycle so `<StatCard>` is only rendered with fully resolved numbers, preventing NaN or undefined rendering.",
+    "Any page using `useQuery` where the empty state and loading state are visually different — DataState enforces the correct visual for each phase without scattered `if` statements across the component tree."
+  ]
+}