@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/PieChart.json

@@ -0,0 +1,99 @@
+{
+  "example": "import { PieChart } from \"@godxjp/ui/charts\";\n\n<PieChart\n  label={t(\"dashboard.expenseSplit\")}\n  data={data}\n  dataKey=\"amount\"\n  nameKey=\"category\"\n  numberFormat={{ style: \"currency\", currency: \"JPY\" }}\n  donut\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/charts",
+  "name": "PieChart",
+  "props": [
+    {
+      "description": "Row data: one slice per row.",
+      "name": "data",
+      "required": true,
+      "type": "ChartDatum[]"
+    },
+    {
+      "description": "Key into each datum holding the slice's numeric value.",
+      "name": "dataKey",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Key into each datum holding the slice's category label.",
+      "name": "nameKey",
+      "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": "Per-slice colours by index (defaults to the --chart-1..6 palette).",
+      "name": "colors",
+      "type": "string[]"
+    },
+    {
+      "description": "Extra context appended to the screen-reader description.",
+      "name": "description",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Canvas height preset. Ignored when `height` is set.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Explicit canvas height in px (overrides `size`).",
+      "name": "height",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show the slice legend.",
+      "name": "showLegend",
+      "type": "boolean"
+    },
+    {
+      "description": "Locale-aware formatting for tooltip values.",
+      "name": "numberFormat",
+      "type": "Intl.NumberFormatOptions"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Render a donut (hollow centre) instead of a full pie.",
+      "name": "donut",
+      "type": "boolean"
+    },
+    {
+      "description": "Message shown when `data` is empty.",
+      "name": "emptyMessage",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "BarChart — when there are many categories or precise comparison matters.",
+    "Progress — single ratio against a target rather than a multi-slice split."
+  ],
+  "rules": [],
+  "storyPath": "charts/PieChart.stories.tsx",
+  "tagline": "Part-to-whole composition across a small set of slices — `donut` option, localized tooltips, and a screen-reader breakdown of every slice. Data-visualization graph / diagram.",
+  "usage": [
+    "DO import from the charts entry: `import { PieChart } from \"@godxjp/ui/charts\";` (recharts optional peer required).",
+    "DO import only the chart a screen uses — `import { PieChart } from \"@godxjp/ui/charts/pie-chart\";` — when the `./charts` barrel should not link the whole chart family. Without the `recharts` peer the build then fails ONCE, naming the package and the fix.",
+    "DO keep slices few (≈2–6) — pies are unreadable past a handful; use BarChart for many categories.",
+    "DO pass `numberFormat` (e.g. percent or currency) so tooltip values localize.",
+    "DON'T use a pie for trends over time (LineChart/AreaChart) or precise comparison (BarChart)."
+  ],
+  "useCases": [
+    "Budget / expense split across a few categories.",
+    "Market or status share (e.g. paid vs overdue vs draft)."
+  ]
+}

package/agent/components/Popover.json

@@ -0,0 +1,110 @@
+{
+  "example": "import {\n  Popover,\n  PopoverTrigger,\n  PopoverContent,\n  PopoverHeader,\n  PopoverTitle,\n  PopoverDescription,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\n\n// Uncontrolled — basic usage\nexport function InvoiceFilterPopover() {\n  return (\n    <Popover>\n      <PopoverTrigger asChild>\n        <Button variant=\"outline\">Advanced filters</Button>\n      </PopoverTrigger>\n      <PopoverContent align=\"start\" width=\"trigger\">\n        <PopoverHeader>\n          <PopoverTitle>Filter invoices</PopoverTitle>\n          <PopoverDescription>Narrow results by date range and status.</PopoverDescription>\n        </PopoverHeader>\n        {/* place form controls here */}\n      </PopoverContent>\n    </Popover>\n  );\n}\n\n// Controlled — programmatic open/close\nimport * as React from \"react\";\n\nexport function ControlledPopover() {\n  const [open, setOpen] = React.useState(false);\n  return (\n    <Popover open={open} onOpenChange={setOpen}>\n      <PopoverTrigger asChild>\n        <Button variant=\"ghost\" size=\"icon\" aria-label=\"Show details\">\n          ?\n        </Button>\n      </PopoverTrigger>\n      <PopoverContent side=\"right\" sideOffset={8}>\n        <PopoverHeader>\n          <PopoverTitle>About this field</PopoverTitle>\n          <PopoverDescription>\n            The MF ID is the unique identifier assigned by Money Forward.\n          </PopoverDescription>\n        </PopoverHeader>\n      </PopoverContent>\n    </Popover>\n  );\n}",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Popover",
+  "props": [
+    {
+      "description": "Controls open state in controlled mode. Pair with onOpenChange.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Initial open state for uncontrolled usage.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Callback fired when the popover open state changes. Required when using controlled mode (open prop).",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, interaction outside the popover is blocked and focus is trapped inside (Radix Root prop).",
+      "name": "modal",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"center\"",
+      "description": "PopoverContent prop. Horizontal alignment of the popover relative to the trigger.",
+      "name": "align",
+      "type": "'start' | 'center' | 'end'"
+    },
+    {
+      "defaultValue": "4",
+      "description": "PopoverContent prop. Distance in pixels between the popover panel and its anchor.",
+      "name": "sideOffset",
+      "type": "number"
+    },
+    {
+      "defaultValue": "\"bottom\"",
+      "description": "PopoverContent prop. Which side of the trigger the panel prefers to open on (auto-flips on overflow).",
+      "name": "side",
+      "type": "'top' | 'right' | 'bottom' | 'left'"
+    },
+    {
+      "defaultValue": "false",
+      "description": "PopoverTrigger prop. Merges trigger props onto the immediate child element (e.g. a Button) instead of rendering an extra DOM node. Strongly recommended to avoid a wrapping <button>.",
+      "name": "asChild",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "PopoverContent prop. The panel's CONTENT owns its inset: the popover zeroes its own --popover-space-inset so a Command list, a menu or a table runs edge to edge and draws its separators across the full width. Reach for it whenever the child already paints its own rows; leave it off for prose panels, which want the panel padding.",
+      "name": "flush",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"panel\"",
+      "description": "PopoverContent prop. How the panel is MEASURED across the inline axis. \"panel\" (default) is the popover's own --popover-width (18rem) — right for prose and for a list the panel sizes itself. \"auto\" lets the CONTENT decide, the only correct answer for something with a width of its own (a two-month Calendar is far wider than 18rem and was being clipped by it). \"trigger\" matches the anchor. It is the counterpart of `flush`: both set a token the panel already reads, so a service theme keeps owning them, where a `w-*` utility on className is a per-call-site constant nothing can retune.",
+      "name": "width",
+      "type": "\"panel\" | \"auto\" | \"trigger\""
+    },
+    {
+      "description": "PopoverContent prop. Extra Tailwind classes merged onto the panel (default: w-72 p-4 rounded-md border shadow-md z-50).",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Tooltip — use Tooltip for brief, non-interactive label-like hints (hover-only, no inputs). Use Popover when the floating content is interactive (buttons, inputs, forms).",
+    "Dialog/Sheet — use Dialog or Sheet for full modal actions that require user confirmation or significant input. Use Popover for lightweight, anchor-relative panels that dismiss on outside click.",
+    "DropdownMenu — use DropdownMenu for a flat list of clickable actions or links. Use Popover when the floating panel needs arbitrary layout (forms, grids, rich content) rather than a menu list."
+  ],
+  "rules": [
+    3,
+    23,
+    31,
+    35
+  ],
+  "storyPath": "data-display/Popover.stories.tsx",
+  "subParts": [
+    "PopoverAnchor",
+    "PopoverContent",
+    "PopoverDescription",
+    "PopoverHeader",
+    "PopoverTitle",
+    "PopoverTrigger"
+  ],
+  "tagline": "Radix-backed floating panel anchored to a trigger — always compose with PopoverTrigger + PopoverContent; never use a raw div overlay.",
+  "usage": [
+    "DO compose: <Popover> → <PopoverTrigger asChild> → <Button/> and <PopoverContent>. All four parts are required for any popover to function; omitting PopoverTrigger or PopoverContent produces nothing.",
+    "DO set `<PopoverContent width=\"auto\">` when the child brings its own measure — a Calendar, a chart, a fixed-width preview. The panel's own 18rem clips them, and a `w-*` utility on className is a per-call-site constant no service theme can retune, which is exactly what `flush` exists to avoid on the padding axis. `width=\"trigger\"` matches the anchor, the shape every select-like control wants.",
+    "DO set `<PopoverContent flush>` when the panel holds a Command list, a menu or a table — the child owns its own inset, so its rows and separators reach the panel edges. Never zero the padding with a utility on className: that is a per-call-site constant no service theme can retune, while `flush` keeps the inset on --popover-space-inset.",
+    "DO use asChild on PopoverTrigger when the trigger is already a Button or link — this avoids a nested <button><button> violation and extra DOM nesting.",
+    "DO use controlled mode (open + onOpenChange) when external code must open/close the popover programmatically (e.g., form validation reveal, keyboard shortcut). For toggle-only interactions, uncontrolled (defaultOpen) is simpler.",
+    "DO structure panel content with PopoverHeader > PopoverTitle + PopoverDescription for labelled panels. This is purely presentational but establishes the correct font-weight and muted-foreground on the description.",
+    "DON'T hand-roll a floating div or use a CSS show/hide toggle — Popover provides portal rendering, focus trap, Escape-to-close, and ARIA automatically.",
+    "DON'T place a Popover inside a Dialog without setting modal={false} on the Popover — nested modals conflict with Radix's focus management and produce stuck focus."
+  ],
+  "useCases": [
+    "Advanced filter panel: a Filters Button triggers a Popover containing filter inputs (date range, status selects); panel measured with `<PopoverContent width='auto'>` so the filters set the width, or `width='trigger'` to match the button.",
+    "Row action menu overflow: when a DataTable row has too many actions for inline display, a Popover holds the secondary actions (Edit, Archive, Delete) without navigating away.",
+    "Contextual help / tooltip-rich: a small '?' icon button opens a Popover with PopoverTitle + PopoverDescription explaining a form field — richer than a Tooltip but less intrusive than a Dialog.",
+    "Inline record preview: clicking a reference number in an invoice list opens a Popover showing a summary card of the linked document before the user decides to navigate.",
+    "Column visibility picker: a 'Columns' button above a DataTable opens a Popover containing checkboxes to show/hide columns, with controlled state managed in parent.",
+    "Quick-edit cell: for an admin table, clicking a status badge opens a Popover with a RadioGroup to change status in-place without a full Dialog."
+  ]
+}

package/agent/components/PrefetchLink.json

@@ -0,0 +1,65 @@
+{
+  "example": "import { PrefetchLink } from \"@godxjp/ui/query\";\nimport { fetchInvoice } from \"@/api/invoices\";\n\n// Inside a table row or list item:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  staleTime={60_000}\n  className=\"font-medium hover:underline\"\n>\n  {invoice.number}\n</PrefetchLink>\n\n// Disable prefetch for rows where data is not yet stable:\n<PrefetchLink\n  to={`/invoices/${invoice.id}`}\n  queryKey={[\"invoice\", invoice.id]}\n  queryFn={() => fetchInvoice(invoice.id)}\n  prefetchOn=\"none\"\n>\n  {invoice.number}\n</PrefetchLink>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/query",
+  "name": "PrefetchLink",
+  "props": [
+    {
+      "description": "TanStack Query cache key for the data to prefetch. Must match the key used by the destination page's useQuery call.",
+      "name": "queryKey",
+      "required": true,
+      "type": "QueryKey"
+    },
+    {
+      "description": "Fetch function passed to queryClient.prefetchQuery. Same function (or equivalent) as the one used in the destination page's useQuery.",
+      "name": "queryFn",
+      "required": true,
+      "type": "() => Promise<unknown>"
+    },
+    {
+      "defaultValue": "\"both\"",
+      "description": "Which interaction triggers prefetching. 'both' fires on either mouseenter or focus. 'none' disables prefetching entirely (useful for conditional opt-out without unmounting the component).",
+      "name": "prefetchOn",
+      "type": "\"hover\" | \"focus\" | \"both\" | \"none\""
+    },
+    {
+      "defaultValue": "30000",
+      "description": "Milliseconds before the prefetched cache entry is considered stale. Matches queryClient.prefetchQuery staleTime. Defaults to 30 s — set higher for rarely-changing data (e.g. reference tables), lower for live feeds.",
+      "name": "staleTime",
+      "type": "number"
+    },
+    {
+      "description": "All standard React Router v6 Link props are spread through: to, replace, state, relative, reloadDocument, preventScrollReset, viewTransition, className, children, etc. onMouseEnter and onFocus are merged (your handler still fires).",
+      "name": "...linkProps",
+      "type": "LinkProps (react-router-dom)"
+    }
+  ],
+  "related": [
+    "Link (react-router-dom) — use bare Link when no prefetching is needed or when the destination has no TanStack Query data (e.g. a static page or a form page that fetches nothing on load).",
+    "DataState — the companion lifecycle widget for the destination page; ensures PrefetchLink's prefetch is consumed correctly via useQuery.",
+    "InfiniteQueryState — use instead of PrefetchLink when the list itself is infinitely paginated and items are loaded lazily rather than navigated to.",
+    "ButtonRefetch — for triggering a manual cache refresh on an already-loaded page, not for navigation prefetching."
+  ],
+  "rules": [
+    2,
+    3,
+    31
+  ],
+  "storyPath": "data-display/PrefetchLink.stories.tsx",
+  "tagline": "React Router Link that fires prefetchQuery on hover/focus so detail pages feel instant — requires a TanStack Query QueryClient in context.",
+  "usage": [
+    "DO: provide a queryKey that exactly matches the destination page's useQuery key — a mismatch means the prefetch populates a different cache slot and the page still loads cold.",
+    "DO: keep queryFn lightweight and side-effect-free; it runs speculatively on hover. Avoid mutations or write operations inside queryFn.",
+    "DO: tune staleTime to your data's freshness requirement. The default 30 s is fine for most detail views; set it lower (e.g. 5000) for real-time data or higher (e.g. 300_000) for static reference data.",
+    "DON'T: use PrefetchLink when the destination page's data is user-specific per request (e.g. contains a nonce or CSRF token embedded in the payload) — the prefetched response may be stale or unusable.",
+    "DON'T: hand-roll a Link + useQueryClient prefetch pattern when PrefetchLink already ships it. Using raw Link loses the hover/focus prefetch behaviour and duplicates logic.",
+    "REQUIRES: a TanStack Query QueryClient provider (QueryClientProvider) above this component in the tree. It calls useQueryClient internally — rendering without a provider throws."
+  ],
+  "useCases": [
+    "List-to-detail navigation in an accounting app: hovering an invoice row in a DataTable triggers prefetch of that invoice's detail data so the detail page renders immediately on click.",
+    "Sidebar navigation links where the destination is a dashboard or summary page — prefetch on focus covers keyboard-only users tabbing through the nav.",
+    "Paginated table rows where each row links to a resource detail page (partner, journal entry, account). prefetchOn='hover' avoids wasted prefetches from keyboard navigation.",
+    "Admin list pages with 'Edit' action links: the edit form data is prefetched on hover so the form appears populated without a loading spinner.",
+    "Breadcrumb links on deep-nested pages where clicking 'back' should feel instant — prefetch the parent page's query on mount/focus of the breadcrumb link."
+  ]
+}

package/agent/components/Progress.json

@@ -0,0 +1,79 @@
+{
+  "example": "import { Progress } from \"@godxjp/ui/data-display\";\n\n<Progress value={pct} label={pct + \"% 使用中\"} tone={pct >= 80 ? \"warning\" : \"success\"} />\n<Progress value={252} over label=\"252% 積載\" />\n<Progress\n  segments={[\n    { value: 2, tone: \"destructive\", label: \"期限超過\" },\n    { value: 3, tone: \"warning\", label: \"期限間近\" },\n    { value: 12, tone: \"success\", label: \"対応済\" },\n  ]}\n  aria-labelledby={companyNameId}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Progress",
+  "props": [
+    {
+      "description": "METER mode: progress percentage 0–100 (clamped unless `over`). Required unless you pass `segments` — the two modes are a discriminated union, so `value` and `segments` can never appear together.",
+      "name": "value",
+      "required": true,
+      "type": "number"
+    },
+    {
+      "description": "BREAKDOWN mode: one total split into slices. Pass ABSOLUTE amounts in one unit (counts, bytes, yen) — the bar computes each share, so three numbers never have to be rounded into 100. Renders role=\"img\" named from every slice (a partition is not three progressbars), on a taller track (--progress-breakdown-block-size 1.375rem, --progress-breakdown-radius var(--radius)) because three abutting fills on the meter's 0.5rem pill read as a coloured hairline. `label` on each slice is REQUIRED — colour alone never carries meaning (WCAG 1.4.1). Mutually exclusive with value/tone/over.",
+      "name": "segments",
+      "type": "{ value: number; tone: \"success\" | \"warning\" | \"destructive\"; label: string }[]"
+    },
+    {
+      "description": "Text label beside/below the bar; it also becomes the accessible name. Pass `aria-labelledby` instead when the name is ALREADY on screen (a row's company name, a card heading) — the bar then borrows it rather than repeating it.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"success\"",
+      "description": "Bar colour tone. Over-capacity defaults to destructive.",
+      "name": "tone",
+      "type": "\"success\" | \"warning\" | \"destructive\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Allow value > 100 to render an over-capacity fill: bar caps at 100% width but gets a diagonal hatch + destructive tone (e.g. 252%). aria-valuetext reports the real ratio. Off by default (clamps to 100). On shape='ring' there is no hatch — diagonal stripes are a rectangle drawing — so the destructive tone and aria-valuetext carry it.",
+      "name": "over",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"bar\"",
+      "description": "METER geometry — the SAME measurement drawn as a full-width bar or as an arc. Same value, tone, size and ARIA either way; `label` moves INSIDE the ring, which is the point of it: a phone app bar showing '18 of 42 done' beside a title has one square of space, and a bar plus its caption needs two stacked rows. Reach for it when the SPACE is square, not when the number is important. It is meter-only: a ring around a `segments` breakdown is a pie chart, which is `PieChart donut` in the charts entry point — a part-to-whole across CATEGORIES with a legend, announced as an image rather than as a progressbar. The arc reads the MARK token tier, exactly as the bar does, so a warning ring and a warning bar on one screen are one colour.",
+      "name": "shape",
+      "type": "\"bar\" | \"ring\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Bar THICKNESS, on both modes. `md` is what each mode was designed at and stays the default. `sm` is for a bar that annotates a row rather than being the subject of the screen — an in-table capacity column, where a 1.375rem breakdown outweighs the row and sets the height of the whole table. Thickness only: the ARIA, the spoken breakdown and the corner are untouched. Never hand-write CSS to thin a bar — ui-audit blocks that in a consumer, and the two steps come from --progress-meter-block-size(-sm) / --progress-breakdown-block-size(-sm) so a theme retunes the scale instead of one call site.",
+      "name": "size",
+      "type": "\"sm\" | \"md\""
+    }
+  ],
+  "related": [
+    "Slider — use Slider when the user must drag or set a bounded numeric value (volume, priority, price range); use Progress when the value is read-only and must not be interacted with.",
+    "Steps — use Steps for a discrete, named sequence of phases (onboarding wizard, checkout flow) where each step has a label and a clear current/done/pending state; use Progress for a continuous 0–100 fill.",
+    "Badge / Badge — use Badge or Badge to communicate a categorical status label (e.g. \"Paid\", \"Overdue\") without a fill metaphor; use Progress when the numeric proportion itself is the information.",
+    "StatCard — use StatCard to headline a single KPI metric with a title; compose Progress inside or alongside StatCard when a visual fill adds meaning to the number.",
+    "Legend — the key for a breakdown: which tone means what, spelled out in words once for the whole card instead of on every bar.",
+    "BarChart / PieChart / LineChart (@godxjp/ui/charts) — a Progress breakdown handles ONE total split into a few named states, inline and without a charting runtime; move up to a chart when you have several series, many categories, or a value changing over time."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Progress.stories.tsx",
+  "tagline": "Progress in two modes: a METER (`value` 0–100, optional tone, over-capacity striped state, drawn as a bar or — with `shape='ring'` — as an arc with the readout inside it) and a BREAKDOWN (`segments` — one total split into tone-coloured slices on a taller track).",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`, not from a generic UI path: `import { Progress } from \"@godxjp/ui/data-display\";`",
+    "DO pass `value` as a 0–100 number — the component clamps it internally via `Math.max(0, Math.min(100, value))`, so out-of-range values are safe but misleading; compute the real percentage before passing it.",
+    "DO drive `tone` dynamically from business logic — e.g. `variant={pct >= 80 ? \"warning\" : \"success\"}` — to communicate threshold status semantically rather than with raw colour classes.",
+    "DON'T use a `disabled` Slider as a read-only progress bar — Slider is semantically an interactive control even when disabled, which pollutes the a11y tree and exposes the wrong ARIA role (`slider` vs `progressbar`). Progress renders the correct read-only indicator.",
+    "DON'T pass children or sub-components — Progress is a single self-contained element (track + bar + label). The `label` prop is the only text injection point; don't wrap it in a custom parent div to add a label alongside it.",
+    "DON'T hand-roll a stacked bar out of three divs to show a part-to-whole split — pass `segments`. Hand-rolled slices need a hex fill, an arbitrary height and an arbitrary radius, which ui-audit blocks three ways (no-arbitrary-hex, no-arbitrary-size, no-arbitrary-radius), and they leave the picture with no accessible name at all.",
+    "DON'T convert segment amounts to percentages yourself — pass the raw counts. The component divides by the total, so the slices always sum to the whole; pre-rounded percentages do not.",
+    "DO pair a breakdown with `Legend` so each tone is spelled out in words once, instead of repeating the labels on every bar.",
+    "DON'T use Progress for editable numeric input or range selection — it has no callbacks, no interactivity, and no form `name` prop. Use Slider (bounded range input) or Input (free-form number) for data-entry scenarios."
+  ],
+  "useCases": [
+    "Budget utilisation in an accounting dashboard — show how much of a monthly budget has been consumed, switching to `tone=\"warning\"` when the figure crosses 80%.",
+    "Invoice payment progress — display the proportion of an invoice total that has been settled (e.g. partial payments), with a label like `\"¥45,000 / ¥60,000 支払済\"` computed before passing `value`.",
+    "Storage or quota indicator in an admin panel — visualise disk usage, API quota, or seat licence consumption against a fixed limit.",
+    "Sync / import job completion feedback — surface the completion percentage of a long-running background job (polling the server) without giving the user an interactive control.",
+    "StatCard companion — pair with a `StatCard` metric to add a visual fill below the KPI number, reinforcing how close a target is to being met.",
+    "Multi-step onboarding or setup checklist — render one Progress per section (e.g. 3/5 steps complete = 60%) to give users a quick scan of overall progress across areas.",
+    "Over-capacity meter — an air-cargo weight/volume load or an over-booked resource pushed past its limit (e.g. 252%): pass `over` with the real ratio to get a red diagonal-hatched bar that reads unmistakably as over-limit, not merely full."
+  ]
+}

package/agent/components/Prose.json

@@ -0,0 +1,57 @@
+{
+  "example": "import { Prose } from \"@godxjp/ui/data-display\";\nimport Markdown from \"react-markdown\";\nimport remarkGfm from \"remark-gfm\";\n\n<Prose size=\"sm\">\n  <Markdown remarkPlugins={[remarkGfm]}>{issue.description}</Markdown>\n</Prose>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Prose",
+  "props": [
+    {
+      "defaultValue": "\"md\"",
+      "description": "Body size. `md` is the page body size (a wiki page); `sm` is the compact step (an issue description, a comment).",
+      "name": "size",
+      "type": "\"sm\" | \"md\""
+    },
+    {
+      "defaultValue": "\"fit\"",
+      "description": "`fit` scales images to the column; `original` shows them at their authored size and the container scrolls horizontally.",
+      "name": "imageSize",
+      "type": "\"fit\" | \"original\""
+    },
+    {
+      "description": "The rendered content.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra classes on the container.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "CodeBlock - a standalone block of preformatted text; Prose delegates its `pre` to the same tokens.",
+    "Text / Heading - UI copy, not a document.",
+    "LegalDocumentShell - a whole legal document with its own table of contents and section anchors; use Prose for the body of arbitrary rendered content.",
+    "ScrollArea - if a very long document needs its own scroll viewport, wrap Prose in ScrollArea."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Prose.stories.tsx",
+  "tagline": "Typography for rendered content (Markdown, CMS bodies, issue descriptions): styles the semantic HTML inside it from the tokens, with no opinion about where the HTML comes from.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { Prose } from \"@godxjp/ui/data-display\";`",
+    "DO wrap the OUTPUT of your Markdown pipeline (react-markdown + remark-gfm + rehype-sanitize), a sanitised CMS string via `dangerouslySetInnerHTML`, or plain JSX. Prose styles descendants: h1..h4, p, ul/ol/li, blockquote, code, pre, table/th/td, a, img, hr.",
+    "DO keep soft line breaks the pipeline's job (remark-breaks or the renderer's `breaks` option). Prose does not turn single newlines into `<br>`; it is typography, not parsing.",
+    "DON'T restate the heading scale, table cell measures or list rhythm with `[&_h1]:text-lg [&_td]:border …` utilities: they copy token values and never follow a retune. Prose reads --heading-h1..h4, --table-cell-padding-* and --prose-* directly.",
+    "DO tune the link through --prose-link-color and --prose-link-decoration-line (gh#717). The ink defaults to hsl(var(--primary)) resolved at the anchor, so a scoped [data-tenant] re-tint reaches it; the resting underline defaults to `underline` and is a SEPARATE knob from --text-link-decoration-line, because Prose is running text and there the underline is a WCAG 1.4.1 requirement, not a taste.",
+    "DO style a state your own renderer knows about by marking the anchor and selecting it: `a[data-unresolved]` (a wiki link whose target does not exist yet), then re-declare --prose-link-color inside that selector. Prose writes data-* on its ROOT ONLY — never on a descendant — so every data-* on an `a` inside it is yours and stays selectable. That is a promise held by a test (prose-link-717.test.tsx), not a coincidence; there is no prop for it, the same way `TableRow data-expanded-row` is an attribute rather than an API.",
+    "DON'T sanitise inside Prose: it renders whatever HTML it is given. Sanitise before (rehype-sanitize, or the server).",
+    "DON'T use Prose for UI text (labels, descriptions, empty states): those are Text / Heading. Prose is for a document."
+  ],
+  "useCases": [
+    "A wiki page rendered from Markdown, at the page body size.",
+    "A wiki page whose renderer marks links it knows something extra about: `<a data-unresolved=\"true\">` for a target nobody has written yet, re-declaring --prose-link-color as --text-error inside `a[data-unresolved]` so it reads differently from a link that resolves.",
+    "An issue description or a comment in a tracker, `size=\"sm\"`.",
+    "A bug-report intake inbox that renders the report body (description, steps, environment table) sent by a browser extension.",
+    "A CMS article body delivered as sanitised HTML.",
+    "An email preview rendered from stored HTML."
+  ]
+}

package/agent/components/QrCode.json

@@ -0,0 +1,62 @@
+{
+  "example": "import { CredentialReveal, QrCode } from \"@godxjp/ui/data-display\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n<Flex direction=\"col\" gap=\"md\">\n  <QrCode\n    value={security.qr_code_url}\n    label=\"二要素認証の登録用QRコード\"\n    size=\"lg\"\n  />\n  <CredentialReveal\n    secret={security.secret}\n    label=\"手動設定キー\"\n    warning={null}\n    defaultRevealed\n  />\n</Flex>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "QrCode",
+  "props": [
+    {
+      "description": "Value encoded in-process. It is never used as accessible text or a URL.",
+      "name": "value",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Localized, purpose-specific accessible name for the QR image.",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Natural display-size tier; remains bounded by the available inline space.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Root SVG class override.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Root SVG element id.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "CredentialReveal — pair it with QrCode for the manual setup-key fallback without exposing the full encoded URI.",
+    "Card — supplies the one outer enrollment surface; QrCode intentionally adds no nested border or card chrome.",
+    "Text — provides concise localized scan/manual guidance around the non-text QR image."
+  ],
+  "rules": [
+    6,
+    7,
+    23,
+    24
+  ],
+  "storyPath": "data-display/QrCode.stories.tsx",
+  "tagline": "Local-only SVG QR renderer for enrollment links, device pairing and other values that must never be sent to a third-party image service.",
+  "usage": [
+    "DO use QrCode when the encoded payload must remain inside the browser, especially an otpauth enrollment URI containing a TOTP secret.",
+    "DO provide a localized label that describes the job, such as 'Two-factor authentication setup code'; the encoded value is intentionally excluded from the accessibility tree.",
+    "DO compose an adjacent CredentialReveal with the manual key when users need a non-camera fallback. Keep both inside one parent Card rather than adding a bordered QR card.",
+    "DON'T create an image URL with the payload, call a remote QR service, add a logo/image overlay, or expose raw colour/size props. The local encoder, four-module quiet zone and scanner-safe colours are security and reliability invariants.",
+    "DON'T encode the manual secret alone for TOTP. Encode the canonical otpauth URI returned by the backend so issuer, account, algorithm, digits and period stay intact."
+  ],
+  "useCases": [
+    "TOTP authenticator enrollment",
+    "Device pairing or application handoff",
+    "Locally rendered invitation or deep link",
+    "Payment or ticket payload that must not reach a third-party renderer"
+  ]
+}

package/agent/components/Radio.json

@@ -0,0 +1,98 @@
+{
+  "example": "{`import { Radio } from \"@godxjp/ui/data-entry\";\n\n// --- Options-array API (recommended for most cases) ---\nconst PAYMENT_METHODS = [\n  { label: \"Credit Card\", value: \"card\", description: \"Charged immediately on save.\" },\n  { label: \"Bank Transfer\", value: \"bank\" },\n  { label: \"Invoice\", value: \"invoice\", disabled: true },\n];\n\nfunction PaymentMethodPicker() {\n  const [method, setMethod] = React.useState(\"card\");\n\n  return (\n    <Radio.Group\n      name=\"payment_method\"\n      value={method}\n      onValueChange={setMethod}\n      options={PAYMENT_METHODS}\n      orientation=\"vertical\"\n    />\n  );\n}\n\n// --- Manual composition (when you need custom layout) ---\nfunction CustomRadioGroup() {\n  return (\n    <Radio.Group name=\"account_type\" defaultValue=\"asset\">\n      <Radio.Item id=\"opt-asset\" value=\"asset\" />\n      {/* wrap each item in Field for label + description */}\n    </Radio.Group>\n  );\n}`}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Radio",
+  "props": [
+    {
+      "defaultValue": "\"default\"",
+      "description": "antd `optionType` — how each choice is DRAWN. `default` is a radio dot beside its label; `button` welds them into one segmented bar. It is paint, never semantics: the roles stay radiogroup/radio, so arrow-key traversal and native submission keep working. That is also why this is not a ToggleGroup: a ToggleGroup's single mode is a row of aria-pressed buttons that permits 'none chosen' unless it is given `disallowEmptySelection` (gh#744), and Radio is a form control with a `name` that submits.",
+      "name": "optionType",
+      "type": "\"default\" | \"button\""
+    },
+    {
+      "defaultValue": "\"outline\"",
+      "description": "antd `buttonStyle` — fill of the selected choice while `optionType` is `button`. Ignored otherwise.",
+      "name": "buttonStyle",
+      "type": "\"outline\" | \"solid\""
+    },
+    {
+      "description": "Controlled selected value. Must be paired with onValueChange to update state.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial value. Use when you do not need to track selection in state.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Callback fired when the user selects a different option. Required when value is controlled.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Declarative option list: { label: ReactNode; value: string; disabled?: boolean; description?: ReactNode }[]. When provided, Radio.Group renders each option as a labelled Field automatically. Omit to compose children manually.",
+      "name": "options",
+      "type": "ChoiceOptionProp[]"
+    },
+    {
+      "defaultValue": "\"vertical\"",
+      "description": "Layout direction for the option list. Vertical stacks options; horizontal lays them side by side.",
+      "name": "orientation",
+      "type": "\"vertical\" | \"horizontal\""
+    },
+    {
+      "description": "Disables the entire group when true. Individual options can also be disabled via options[].disabled.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "HTML form field name. Required for native form submission — each option is a real `<input type=\"radio\">` under this name, so the browser serialises the selected value with no extra wiring.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Additional CSS class applied to the group root.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Manual composition fallback — used only when options is not provided. Render Radio.Item (+ Field wrapper) children directly inside Radio.Group.",
+      "name": "children",
+      "type": "React.ReactNode"
+    }
+  ],
+  "related": [
+    "Checkbox.Group — use when users may select multiple options simultaneously; Radio.Group enforces single-selection only.",
+    "Switch / Field — use for a single boolean on/off toggle (e.g. enable notifications); Radio.Group is for choosing one among three or more named options.",
+    "Select — use when there are many options (5+) and vertical screen space is limited; Radio.Group is preferable for 2-4 short options where all choices should be visible at a glance."
+  ],
+  "rules": [
+    3,
+    6,
+    13,
+    23
+  ],
+  "storyPath": "data-entry/Radio.stories.tsx",
+  "subParts": [
+    "RadioItem"
+  ],
+  "tagline": "Radio group on react-aria-components, with an options-array shorthand — always use Radio.Group, never a bare radio input. `role=\"radio\"` is the real `<input>`; the painted dot is the `<label>` around it and carries `data-state`.",
+  "usage": [
+    "DO use Radio.Group (not the bare Radio export) as the root — it wires up the group context, keyboard navigation, and the shared input name. A lone Radio.Item outside a Radio.Group has no context and will not function.",
+    "DO prefer the options array API for static/data-driven option lists: pass options={[{ label, value, description?, disabled? }]} and Radio.Group renders each as a correctly-labelled Field automatically — no manual id/label wiring needed.",
+    "DO pass name to Radio.Group when the selection must be submitted via a native HTML form — the options ARE `<input type=\"radio\" name={name}>`, so FormData/fetch pick the value up without extra wiring.",
+    "DO use controlled mode (value + onValueChange) when the selection drives other UI (conditional fields, preview panels). Use defaultValue for fire-and-forget uncontrolled forms.",
+    "DON'T hand-roll a label-plus-radio row with raw <input type='radio'> — use Radio.Group with options or compose Radio.Item inside Field for custom markup. Every option must be wrapped in Field (or equivalent) for the label htmlFor/id linkage.",
+    "DON'T disable individual options inside the options array and ALSO set disabled on the group — group-level disabled wins and overrides all per-item disabled states."
+  ],
+  "useCases": [
+    "Payment method selection (Credit Card / Bank Transfer / Invoice) on a checkout or invoice-creation form — mutually exclusive, 2-4 options, use options array + name for form submission.",
+    "Account type picker (Asset / Liability / Equity / Revenue / Expense) on a chart-of-accounts create/edit page — use options with descriptions to explain each type.",
+    "Report frequency chooser (Daily / Weekly / Monthly / Quarterly) in a scheduled-report settings panel — horizontal orientation when options are short labels.",
+    "Tax regime selector on an entity or vendor profile form where exactly one option must always be active — controlled mode so adjacent fields can react to the selection.",
+    "Approval workflow step type (Automatic / Manual / Conditional) in a workflow builder — use descriptions inside options to explain each mode without extra tooltip markup.",
+    "Filter scope toggle (All entities / Current entity only) in an admin dashboard filter bar — horizontal orientation, no name needed (state managed in React, not submitted)."
+  ]
+}