@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/Banner.json

@@ -0,0 +1,48 @@
+{
+  "example": "import { Banner } from \"@godxjp/ui/feedback\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<Banner tone=\"warning\">\n  <Banner.Content>\n    <Banner.Title>お支払いが確認できていません</Banner.Title>\n    <Banner.Description>サービスの停止を避けるため、お支払い方法を更新してください。</Banner.Description>\n  </Banner.Content>\n  <Banner.Actions>\n    <Button size=\"sm\" variant=\"outline\">お支払い方法を更新</Button>\n  </Banner.Actions>\n</Banner>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Banner",
+  "props": [
+    {
+      "defaultValue": "\"default\"",
+      "description": "Semantic tone driving the surface colour, the default leading icon AND live-region politeness (\"destructive\"/\"warning\" announce assertively via role=\"alert\"; every other tone politely via role=\"status\").",
+      "name": "tone",
+      "type": "\"default\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\""
+    },
+    {
+      "description": "Renders the built-in localized dismiss button (top/inline-end). It sits LAST in DOM and focus order: content → actions → dismiss.",
+      "name": "onDismiss",
+      "type": "() => void | Promise<void>"
+    },
+    {
+      "description": "Override or hide (false) the tone's default leading icon.",
+      "name": "icon",
+      "type": "LucideIcon | false"
+    }
+  ],
+  "related": [
+    "Alert — the SAME primitive in its inline-card presentation; use inside a page section or Card for persistent local feedback. Banner is the full-bleed strip presentation for shell/page-level attention.",
+    "Toaster — transient auto-dismissing feedback (toast()). Banner is persistent until acted on or dismissed.",
+    "ErrorSurface — a whole-page semantic exception state (403/404/5xx) that REPLACES the page. Banner annotates a page that still works.",
+    "PageContainer — Banner sits ABOVE or as the first child of PageContainer, never inside the header slots; the page header's own status/meta belongs in PageContainer's `status` prop."
+  ],
+  "rules": [],
+  "storyPath": "feedback/Banner.stories.tsx",
+  "tagline": "Full-bleed page/shell attention strip (past-due subscription, support session, maintenance). Parts: Banner.Title/Description/Content/Actions.",
+  "usage": [
+    "CANONICAL BANNER CONTRACT: `Banner` is `Alert` with the structural axis fixed to `variant=\"banner\"` — same tone system, same slots, same dismiss/a11y behaviour, but STRIP geometry owned by the `--banner-*` tokens (square corners, hairline block-end rule, page-gutter inline inset). Never fake a banner by putting `className` overrides on an `Alert`, and never hand-roll a coloured div strip.",
+    "DO: Place a Banner FULL-BLEED at the top of the surface it warns about — directly under the Topbar inside AppShell's children for shell-wide attention (past-due subscription, active support session), or as the first child of a page for page-scoped notices. Its inline inset defaults to the page gutter (--space-page-active-x) so the text column aligns with page content.",
+    "DO: Compose text as `Banner.Title` + `Banner.Description` (group multi-part copy in `Banner.Content` when you add `Banner.Actions`). At >=640px actions sit in a trailing column; below the step they drop onto their own full-width WRAPPING line, so a 390px viewport wraps instead of clipping.",
+    "DO: Pass `onDismiss` for dismissible notices — the component renders its own accessible, localized dismiss button. DON'T hand-roll an × Button in `Banner.Actions`.",
+    "DON'T: Use Banner for transient feedback ('saved successfully') — that is `toast()` + `<Toaster>`. Banner is persistent and page/shell-scoped, and there should be at most ONE per surface; stack further messages inside the page as inline `Alert`s.",
+    "DON'T: Encode DXS business rules here (when past_due shows, who sees a support-session strip) — the app decides WHEN to render; Banner owns only presentation and behaviour."
+  ],
+  "useCases": [
+    "Past-due subscription strip across the console shell — `tone=\"warning\"` with a `Banner.Actions` \"お支払い方法を更新\" Button, rendered above the page slot until billing recovers.",
+    "Active support-session indicator — `tone=\"info\"` with the operator name in `Banner.Description` and a \"セッションを終了\" action; not dismissible while the session runs.",
+    "Scheduled maintenance notice — `tone=\"neutral\"` with `onDismiss` so the user can clear it for the session.",
+    "Read-only / archived-organization mode — `tone=\"muted\"` explaining why every mutation control on the page is disabled.",
+    "Degraded-service warning after a partial outage — `tone=\"destructive\"` with a status-page link in `Banner.Actions`."
+  ]
+}

package/agent/components/BarChart.json

@@ -0,0 +1,108 @@
+{
+  "example": "import { BarChart } from \"@godxjp/ui/charts\";\n\n<BarChart\n  label={t(\"report.salesByRegion\")}\n  data={data}\n  categoryKey=\"region\"\n  series={[{ dataKey: \"sales\", label: t(\"metric.sales\") }]}\n  numberFormat={{ notation: \"compact\" }}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/charts",
+  "name": "BarChart",
+  "props": [
+    {
+      "description": "Row data: one category per row with a numeric value per series.",
+      "name": "data",
+      "required": true,
+      "type": "ChartDatum[]"
+    },
+    {
+      "description": "Plotted series: { dataKey, label?, color? }.",
+      "name": "series",
+      "required": true,
+      "type": "ChartSeriesProp[]"
+    },
+    {
+      "description": "Key into each datum holding the category label.",
+      "name": "categoryKey",
+      "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": "\"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 series legend.",
+      "name": "showLegend",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show the cartesian background grid.",
+      "name": "showGrid",
+      "type": "boolean"
+    },
+    {
+      "description": "Locale-aware formatting for ticks + tooltip values.",
+      "name": "numberFormat",
+      "type": "Intl.NumberFormatOptions"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Stack series into one bar instead of grouping side by side.",
+      "name": "stacked",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Lay bars out horizontally (category on the y-axis).",
+      "name": "horizontal",
+      "type": "boolean"
+    },
+    {
+      "description": "Message shown when `data` is empty.",
+      "name": "emptyMessage",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "LineChart — continuous trend rather than discrete comparison.",
+    "PieChart — single part-to-whole composition.",
+    "DataTable — exact tabular figures."
+  ],
+  "rules": [],
+  "storyPath": "charts/BarChart.stories.tsx",
+  "tagline": "Compare a value across categories — grouped or `stacked`, vertical or `horizontal`, with localized ticks/tooltips and a built-in text alternative. Data-visualization graph / plot / diagram.",
+  "usage": [
+    "DO import from the charts entry: `import { BarChart } from \"@godxjp/ui/charts\";` (recharts optional peer required).",
+    "DO import only the chart a screen uses — `import { BarChart } from \"@godxjp/ui/charts/bar-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 use `horizontal` when category labels are long (they read better on the y-axis).",
+    "DO use `stacked` for part-to-whole-per-category; keep grouped (default) for direct side-by-side comparison.",
+    "DON'T use BarChart for a single part-to-whole total — that is PieChart. DON'T fake bars with styled divs."
+  ],
+  "useCases": [
+    "Sales by region / category comparison.",
+    "Stacked composition per period (e.g. expense breakdown by month).",
+    "Ranking with long labels (horizontal)."
+  ]
+}

package/agent/components/BranchScopePicker.json

@@ -0,0 +1,89 @@
+{
+  "docPath": "data-entry/branch-scope-picker.tsx",
+  "example": "import { BranchScopePicker, FormField } from \"@godxjp/ui/data-entry\";\n\n<FormField label=\"適用範囲\" required error={errors.scope}>\n  <BranchScopePicker\n    branches={branches}\n    value={scope}\n    onValueChange={setScope}\n    error={scope.mode === \"selected\" && !scope.branchIds?.length ? \"1件以上選択してください\" : undefined}\n  />\n</FormField>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "BranchScopePicker",
+  "props": [
+    {
+      "description": "Giá trị có kiểm soát: phạm vi đang chọn.",
+      "name": "value",
+      "type": "BranchScopeValueProp"
+    },
+    {
+      "description": "Giá trị khởi tạo khi không kiểm soát.",
+      "name": "defaultValue",
+      "type": "BranchScopeValueProp"
+    },
+    {
+      "description": "Phát khi phạm vi đổi.",
+      "name": "onValueChange",
+      "type": "(value: BranchScopeValueProp) => void"
+    },
+    {
+      "description": "The selectable branches — consumer domain data.",
+      "name": "branches",
+      "required": true,
+      "type": "{ id: string; name: string; description?: string; disabled?: boolean }[]"
+    },
+    {
+      "description": "The controlled triad; default { mode: \"all\" }. Mode flips PRESERVE branchIds so switching back to all never destroys a curated subset.",
+      "name": "value / defaultValue / onValueChange",
+      "type": "{ mode: \"all\" | \"selected\"; branchIds?: string[] }"
+    },
+    {
+      "description": "Field VALIDATION message — rendered under the control and wired via aria-invalid/aria-errormessage on the radiogroup. Collection read failures are `listError`, not this.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "`true` renders the built-in localized message.",
+      "name": "listError / denied / loading / empty",
+      "type": "boolean | ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Locked view: the current scope as a static summary (mode + branch badges).",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Controls visible but inert.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Built-in branch search above the checkbox list.",
+      "name": "searchable",
+      "type": "boolean"
+    },
+    {
+      "description": "Override the localized radio labels (e.g. domain wording like 全店舗).",
+      "name": "allLabel / selectedLabel",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "CheckboxGroup / RadioGroup — the primitives underneath; use them directly for non-scope choices.",
+    "Transfer — large two-list assignment; BranchScopePicker is the compact all-vs-subset scope idiom.",
+    "TreeSelect — hierarchical selection when branches nest."
+  ],
+  "rules": [
+    24
+  ],
+  "storyPath": "data-entry/BranchScopePicker.stories.tsx",
+  "tagline": "Canonical scope control: all branches vs an explicit subset.",
+  "usage": [
+    "DO treat scope as ONE form field: the single { mode, branchIds } value goes through FormField like any other control.",
+    "DO import it from @godxjp/ui/data-entry — never compose an ad-hoc radio+checkbox scope block per screen.",
+    "DO use `error` ONLY for validation (e.g. mode=selected with zero branches checked); a failed branch fetch is `listError`, a 403 is `denied`.",
+    "DO NOT preselect branches for the user — default is { mode: \"all\" }; an explicit subset is a user decision."
+  ],
+  "useCases": [
+    "Role/permission assignment scoped to branches (service role forms).",
+    "Report or notification audience: whole org vs selected branches.",
+    "Read-only scope display on a detail screen (readOnly)."
+  ]
+}

package/agent/components/Breadcrumb.json

@@ -0,0 +1,54 @@
+{
+  "example": "import { Breadcrumb } from \"@godxjp/ui/layout\";\n\n<Breadcrumb items={[\n  { label: \"ホーム\", to: \"/\" },\n  { label: \"会員管理\", to: \"/members\" },\n  { label: \"田中 太郎\" },\n]} />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Breadcrumb",
+  "props": [
+    {
+      "description": "Array of { label, to?, menu? } — omit `to` on the last (current) segment. `menu` (Ant Design `BreadcrumbItemType.menu`) hangs a sibling picker off that segment: `{ items: { value, label, to?, disabled? }[], onSelect? }`. The segment then renders as a menu button, not a link — an entry with `to` becomes a real anchor inside the menu while keeping `role=\"menuitem\"`.",
+      "name": "items",
+      "required": true,
+      "type": "BreadcrumbItemProp[]"
+    },
+    {
+      "description": "Ant Design `separator`. Defaults to the chevron glyph; a string (`\"/\"`) or any node replaces it and `\"\"` removes it. Always `aria-hidden` — the trail's structure is the `<ol>`/`<li>`, so a screen reader never reads the glyph.",
+      "name": "separator",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Ant Design `itemRender`. Replaces ONE segment's body while Breadcrumb keeps owning the `<nav>` landmark, the `<ol>`/`<li>`, the separators and `aria-current`. Use it to hand the trail a router `<Link>` (Inertia, react-router) instead of a bare `<a>`.",
+      "name": "itemRender",
+      "type": "(item: BreadcrumbItemProp, info: { index: number; isLast: boolean; items: BreadcrumbItemProp[] }) => React.ReactNode"
+    },
+    {
+      "description": "Override the nav landmark's accessible name (defaults to a localized \"Breadcrumb\"). Required when more than one Breadcrumb renders on the same page/view — two nav landmarks sharing one name/role fail landmark-unique.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "PageContainer — accepts `breadcrumb` as `BreadcrumbItemProp[]` (raw array, not a ReactNode); use this when each page owns its own breadcrumb and you want it co-located with the page title, actions, and body.",
+    "AppShell — accepts `breadcrumb` as `ReactNode`; pass `<Breadcrumb items={…} />` here when the breadcrumb is a persistent shell-level strip that sits above all page content rather than being owned by individual pages.",
+    "Steps — use instead of Breadcrumb when showing progress through an ordered multi-step flow (wizard, checkout, onboarding); Steps conveys sequence and completion state, not spatial location.",
+    "PrefetchLink — if ancestor breadcrumb segments should prefetch their destination query on hover/focus, consider pairing the `to` values with `PrefetchLink` in a custom breadcrumb or pre-warming the cache on mount; Breadcrumb's internal links are plain react-router-dom `<Link>` with no prefetch behaviour."
+  ],
+  "rules": [],
+  "storyPath": "layout/Breadcrumb.stories.tsx",
+  "tagline": "Standalone breadcrumb nav rendering an ordered trail of page segments.",
+  "usage": [
+    "DO import from `@godxjp/ui/layout` (not from a navigation or general sub-path) and pass a single `items` prop — an ordered array of `{ label, to? }` objects. No children, no sub-components, no render-prop API.",
+    "DO omit `to` on the last (current-page) segment — the component automatically renders it as a `<span aria-current=\"page\">` instead of a router `<Link>`. Passing `to` on the last item does NOT make it a link; drop it intentionally.",
+    "DO pass the Breadcrumb node as a ReactNode to the `breadcrumb` prop of `AppShell` (or `AppShell`) for shell-level breadcrumbs, or to `PageContainer`'s `breadcrumb` prop (which accepts `BreadcrumbItemProp[]` directly — not a ReactNode). When passing to `PageContainer`, pass the raw array; when passing to `AppShell`, wrap it: `breadcrumb={<Breadcrumb items={…} />}`.",
+    "DON'T hand-roll a breadcrumb strip (divs with chevrons, anchors, separators) — Breadcrumb ships the `<nav aria-label=\"Breadcrumb\">` + `<ol>` + `aria-hidden` chevrons. Any custom trail is a violation of the no-hand-roll rule and will fail `npm run ui:audit`.",
+    "DON'T use Breadcrumb for tab-style or step-style navigation (multi-step forms, wizard progress). Those flows belong to `Steps`. Breadcrumb is strictly a spatial location trail, not a process indicator.",
+    "The component is fully uncontrolled and stateless — it renders whatever `items` you pass. Dynamic breadcrumbs (route-derived, breadcrumb context, etc.) must be assembled in the parent and passed down as a plain array; there is no internal routing awareness."
+  ],
+  "useCases": [
+    "Per-page location trail on any admin page deeper than two levels — e.g. Home → Accounting → Invoices → Invoice #1042 — passed to `PageContainer`'s `breadcrumb` prop so it appears above the page `<h1>`.",
+    "Persistent shell-level breadcrumb in a `AppShell` or `AppShell` layout that updates as the user navigates between Inertia/React Router pages; constructed from route params and passed as a ReactNode to `AppShell`'s `breadcrumb` prop.",
+    "Master-detail drill-down in an accounting app: the detail page (journal entry, partner, bank account) shows a breadcrumb back to the list and to the domain root, giving the user a one-click escape without using the browser back button.",
+    "Embedded sub-panel breadcrumb inside a `SplitPane` or `Sheet` where a secondary content area has its own navigable hierarchy and needs a compact location indicator.",
+    "Audit log or document history page where the entity being reviewed (invoice, payment) is the current segment and the parent module (Accounting, Receivables) is a clickable ancestor.",
+    "Prefetch pairing: wrap ancestor segments' `to` values with `PrefetchLink` semantics by putting them in `items` — each non-last item with `to` is already rendered as a router `<Link>`, so hovering naturally prefetches if `PrefetchLink` is used elsewhere on the same route."
+  ]
+}

package/agent/components/Button.json

@@ -0,0 +1,133 @@
+{
+  "example": "import { Button } from \"@godxjp/ui/general\";\nimport { Trash2 } from \"lucide-react\";\n\n<>\n  <Button>保存</Button>\n  <Button variant=\"outline\" size=\"sm\">編集</Button>\n  <Button variant=\"ghost\" size=\"icon-sm\"><Trash2 className=\"size-4\" /></Button>\n</>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Button",
+  "props": [
+    {
+      "defaultValue": "\"default\"",
+      "description": "Visual style. `dashed` = outline with a dashed border (Ant-style add-row / placeholder action).",
+      "name": "variant",
+      "type": "\"default\" | \"destructive\" | \"outline\" | \"dashed\" | \"secondary\" | \"ghost\" | \"link\" | \"bare\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Size preset (height, padding, icon dims).",
+      "name": "size",
+      "type": "\"default\" | \"xs\" | \"sm\" | \"lg\" | \"icon\" | \"icon-xs\" | \"icon-sm\" | \"icon-lg\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Corner radius from the tokens — `default` (control radius), `pill` (fully rounded, --radius-pill), `sharp` (square, --radius-sharp). Use the prop instead of a `rounded-*` className.",
+      "name": "shape",
+      "type": "\"default\" | \"pill\" | \"sharp\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Span the full container width (`width:100%`) instead of sizing to content.",
+      "name": "fullWidth",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Take the space the siblings leave, and let a long label ELLIPSE instead of widening the row — the same axis Flex calls `fill`, for the same reason. Button ships flex-shrink: 0, which is right almost everywhere and wrong in a constrained bar: an account menu holding an avatar plus a person's name keeps its full width while the cluster clips it, so a keyboard user tabs to a control they cannot see (SC 2.4.7). Sets flex: 1 1 auto and min-inline-size: 0; pair it with a <Text truncate> label. This is what replaces className=\"min-w-0 flex-1\", which ui-audit blocks — and which this package's own Topbar guidance used to recommend.",
+      "name": "fill",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Allow multi-line text labels to grow the button height. Uses the active size tier as its minimum height; use with fullWidth in narrow collections.",
+      "name": "wrap",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"center\"",
+      "description": "Logical content alignment. Use start for full-width collection actions; respects RTL.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Render as Radix Slot — merge props onto the child (<a>/<Link>).",
+      "name": "asChild",
+      "type": "boolean"
+    },
+    {
+      "description": "Disable the button.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "In-flight state — shows a leading `Loader2` spinner (replaces a leading icon if present), sets `aria-busy=\"true\"`, and blocks activation (non-interactive, pointer-events disabled) while keeping the label visible so the width doesn't jump. Prefer this over a hand-rolled `<Loader2 className=\"animate-spin\">` inside the button. Ignored when `asChild` (Slot requires a single child).",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Optional label to swap in while `loading` (pass the `t()`-translated string, e.g. `loadingText={t('saving')}`). When omitted the original children stay beside the spinner.",
+      "name": "loadingText",
+      "type": "string"
+    },
+    {
+      "description": "Click handler. Does not fire while `loading` or `disabled`.",
+      "name": "onClick",
+      "type": "React.MouseEventHandler<HTMLButtonElement>"
+    },
+    {
+      "description": "Trailing borderless counter pill after the label (filter tabs / segmented toggles, e.g. \"Chờ bay 18\"). Localized via `Intl.NumberFormat`; styled per variant — never nest a `Badge` in a Button for this. Ignored when `asChild`.",
+      "name": "count",
+      "type": "number"
+    },
+    {
+      "defaultValue": "99",
+      "description": "Cap for `count` (Ant Badge parity) — when `count` exceeds it the pill renders `{overflowCount}+` (e.g. `99+`).",
+      "name": "overflowCount",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Whether the pill renders when `count` is 0 (Ant Badge parity). Pass `false` to hide the pill at zero.",
+      "name": "showZero",
+      "type": "boolean"
+    },
+    {
+      "description": "Localized description of what `count` MEANS, folded into the accessible name — the SAME prop and the same contract Toggle has carried since gh#312, added here in gh#734 because a counted Button measured `\"Git3\"` in the accessibility tree, not \"Git, 3 pages\". The pill is aria-hidden and the spoken clause is an sr-only sibling, so a text button announces as `\"<label>, <count> <countLabel>\"`; with an explicit `aria-label` (an icon-only counted button) the clause is folded into that instead. Pass a t()-resolved string — the library does not own this wording. Even without it the name is now `\"Git, 3\"` rather than `\"Git3\"`; `countLabel` is what turns the digits into a unit.",
+      "name": "countLabel",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "TopbarItem — the same trigger INSIDE a Topbar slot. A Button there is a --control-height pill floating in a taller bar, with its own hover fill and a ring around the pill instead of the cell; TopbarItem is the bar cell itself. Anywhere that is not a bar, Button is right.",
+    "DropdownMenu — when a button needs to reveal a list of actions (e.g. 'Actions ▾' in a DataTable row), wrap the Button as a `DropdownMenuTrigger` inside a `DropdownMenu` compound; don't open a Sheet/Dialog just to show a list of options.",
+    "ButtonRefetch — a pre-wired Button variant from `@godxjp/ui/query` that binds directly to a TanStack Query result (shows spinner, auto-disables while fetching, retries on click). Use it instead of a raw Button whenever the action is a query refetch — do not pass `onClick`/`disabled` to it manually.",
+    "AlertMutationFeedback — for surfacing mutation errors and a retry action; it renders its own retry Button internally. Do not add a separate Button alongside AlertMutationFeedback for the same mutation.",
+    "PrefetchLink — use when the goal is purely navigation with hover-prefetch (Inertia v3 prefetch); it renders as an `<a>` not a button. Only reach for `Button asChild + Link` when the navigation control must look like a button (primary CTA style)."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "general/Button.stories.tsx",
+  "subParts": [
+    "ButtonRefetch"
+  ],
+  "tagline": "Core button with variant + size presets, built on cva and Radix Slot (asChild).",
+  "usage": [
+    "DO pick the right variant for intent: `default` (primary CTA, one per section), `destructive` (irreversible actions like delete/revoke), `outline` (secondary actions alongside a primary), `secondary` (less prominent actions), `ghost` (toolbar icon-only actions), `link` (inline text-style navigation without an underline by default).",
+    "DO use icon-only sizes (`icon`, `icon-xs`, `icon-sm`, `icon-lg`) exclusively for buttons that contain only an SVG — these sizes set equal width/height. For text+icon buttons use `default|sm|lg|xs` sizes; icons inside are auto-sized to 1rem via `[&_svg:not([class*='size-'])]:size-4`.",
+    "DO use `asChild` to render the button as a React Router/Inertia `<Link>` or native `<a>` while keeping all button styling and a11y: `<Button asChild variant=\"outline\"><Link href={route('invoices.show', id)}>詳細</Link></Button>`. Never wrap a `<button>` around an `<a>` — that is invalid HTML.",
+    "DON'T use raw `<button>` elements anywhere in the UI — always use this `Button`. The only exception is an `aria-hidden` native control used as an e2e/a11y hook paired with a visible godx-ui control.",
+    "DO set `type=\"submit\"` explicitly on form submit buttons (the default HTML button type inside `<form>` is already `submit`, but being explicit prevents accidental double-submissions when a `type=\"button\"` sibling exists). For cancel/reset actions set `type=\"button\"` to avoid accidental form submission.",
+    "DON'T apply raw padding, height, or `rounded-*` overrides to `Button` via `className` — the size variants encode the full box model. If a custom size is truly needed, use `buttonVariants` from `@godxjp/ui/general` to compose a new cva class rather than fighting the existing ones.",
+    "DO use the `loading` prop for async/pending actions instead of hand-rolling `<Loader2 className=\"animate-spin\">` inside the button — `loading` renders the spinner, sets `aria-busy`, and blocks activation for you; pair with `loadingText={t('saving')}` to swap the label. For a TanStack Query refetch use `ButtonRefetch` (it owns its own loading lifecycle) rather than wiring `loading` manually.",
+    "DO pass `countLabel` with every `count` — without it the number is read as a bare digit run glued to the label. `<Button count={3} countLabel={t('common.pages')}>Git</Button>` announces \"Git, 3 pages\".",
+    "DON'T reach for `<Button count aria-pressed>` to build a FILTER CHIP — Button paints no pressed state, so the chip looks identical selected and unselected. That is `<Toggle variant=\"soft\" shape=\"pill\" count countLabel>` (gh#734)."
+  ],
+  "useCases": [
+    "Primary form submission in a Dialog or Sheet (e.g. `<Button type=\"submit\" disabled={form.processing}>保存</Button>`) — the `disabled` prop greys it out and blocks pointer events, preventing double-submit during async operations.",
+    "Destructive confirmation inside a Dialog — pair `tone=\"destructive\"` Button as the confirm action and `variant=\"outline\"` as Cancel; never use `variant=\"default\"` for a delete action.",
+    "Icon-only toolbar actions in a DataTable column (edit, delete, copy) using `size=\"icon-sm\"` + `variant=\"ghost\"` + a Lucide icon child — gives equal-width square targets that don't distort the row.",
+    "Navigation links styled as buttons (e.g. 'New Invoice', 'Back to list') using `asChild` + Inertia `<Link>` — preserves SPA navigation while using the button's visual treatment.",
+    "Async mutation trigger in an accounting workflow (e.g. 'Sync from MF', 'Export CSV') — disable on processing state; pair with `AlertMutationFeedback` for error/retry UI rather than inline `try/catch` alerts.",
+    "Refetch / retry trigger when NOT using TanStack Query — for manual cache refresh inside a TanStack Query context use `ButtonRefetch` instead, which owns its own `disabled`/`onClick` lifecycle."
+  ]
+}