@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/Calendar.json

@@ -0,0 +1,259 @@
+{
+  "example": "import { useState } from \"react\";\nimport { Calendar } from \"@godxjp/ui/data-entry\";\nimport { ja } from \"react-day-picker/locale\";\n\n// --- Single-date example (controlled) ---\nexport function InvoiceDateCalendar() {\n  const [date, setDate] = useState<Date | undefined>(new Date());\n\n  return (\n    <Calendar\n      mode=\"single\"\n      selected={date}\n      onSelect={setDate}\n      locale={ja}\n      disabled={{ before: new Date(2024, 0, 1) }}\n      footer={date ? `選択日: ${date.toLocaleDateString(\"ja-JP\")}` : \"日付を選択してください\"}\n      aria-label=\"発行日カレンダー\"\n    />\n  );\n}\n\n// --- Range example inside a Popover (mirrors DatePicker range internals) ---\nimport { Popover, PopoverContent, PopoverTrigger } from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport type { DateRange } from \"react-day-picker\";\n\nexport function ReportRangeFilter() {\n  const [range, setRange] = useState<DateRange | undefined>();\n\n  return (\n    <Popover>\n      <PopoverTrigger asChild>\n        <Button variant=\"outline\">期間を選択</Button>\n      </PopoverTrigger>\n      {/* flush drops the panel's padding and width=\"auto\" lets the calendar set the measure —\n          the panel's own 18rem would clip two months. Never a w-auto/p-0 utility on className:\n          those are per-call-site constants no service theme can retune. */}\n      <PopoverContent flush width=\"auto\" align=\"end\">\n        <Calendar\n          mode=\"range\"\n          selected={range}\n          onSelect={setRange}\n          locale={ja}\n          numberOfMonths={2}\n          disabled={{ after: new Date() }}\n          autoFocus\n        />\n      </PopoverContent>\n    </Popover>\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Calendar",
+  "props": [
+    {
+      "description": "OVERRIDE only — omit it and the calendar follows AppProvider, like every other component here. It did not always: `locale` used to arrive solely through the react-day-picker spread, so with nothing passed the library's own en-US default won and a Japanese page rendered Su Mo Tu We Th Fr Sa inside an otherwise Japanese card, with no error and no warning. Pass it to PIN one market (a booking screen that must stay Japanese wherever it is opened); the locale also decides which weekday the grid starts on, not only the labels.",
+      "name": "locale",
+      "type": "DayPickerLocale"
+    },
+    {
+      "description": "Decorate a day cell — 祝日, a booked day, a deadline. It WRAPS the library's own day button rather than replacing it: `originNode` already carries the selection state, `aria-selected`, the disabled handling and its place in the grid's roving tabindex. Write `<>{originNode}<Badge …/></>` — decorate, never rebuild, or every marker re-derives all of that and most get it wrong.",
+      "name": "cellRender",
+      "type": "(date: Date, info: { originNode: ReactNode }) => ReactNode"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Rule the grid: one line between every pair of days, weekday header included (the header row is also tinted --muted). ON BY DEFAULT — with no ruling the month read as a cloud of numbers and was reported as very hard to read. Pass `bordered={false}` for floating day buttons. It is NOT a box around the calendar — that is Card's job, and the Card/popover edge is the OUTER FRAME tier. The INSIDE grid is the `--calendar-grid-border-color` knob, default `hsl(var(--border))` (L* 93.80 / 1.149:1 on the popover in light, L* 20.76 / 1.270:1 in dark) — the same tier as the frame around it, as a DataTable row rule and as the RangeTimeline grid, so the ruling can never out-weigh the surface it is drawn on. It was `hsl(var(--input) / 0.5)` (L* 78.67 / 1.738:1) through 27.6.0 and gh#730 reported that still darker than the --border every card and table uses. Retint with `--calendar-grid-border-color: hsl(var(--input) / 0.5)` for the 27.6.0 weight or `hsl(var(--input))` for the heavy line. DatePicker forwards the same prop to its popup calendar.",
+      "name": "bordered",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "How the grid claims horizontal space. `auto` (default) shrink-wraps to seven fixed day columns — the shape a picker popover needs, because the panel is shrink-to-fit and takes ITS width from the calendar inside it. Use `full` for an EMBEDDED calendar (a shift board, a booking month) that is the content of a Card rather than a dropdown: it stacks the months and lets the day cells share the row. Measured at a 1200px container: auto → root 248px / cells 32px; full → root 1200px / cells 168px; the DatePicker popover stays 250px either way. Do NOT reach for `className=\"w-full\"` instead — it widens the root and leaves the grid at 224px pinned left.",
+      "name": "width",
+      "type": "\"auto\" | \"full\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Footer action that jumps to the current month and selects today (single), fills the open end of the range (range) or adds today (multiple). Disabled when today is outside startMonth / endMonth or matches `disabled`.",
+      "name": "showToday",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Footer action that calls `onClose`.",
+      "name": "showClose",
+      "type": "boolean"
+    },
+    {
+      "description": "Called by the Close footer action.",
+      "name": "onClose",
+      "type": "() => void"
+    },
+    {
+      "description": "Selection mode. 'single' picks one day, 'multiple' picks several, 'range' picks a from/to span. Omit or set undefined for a display-only calendar with no selection.",
+      "name": "mode",
+      "type": "'single' | 'multiple' | 'range' | undefined"
+    },
+    {
+      "description": "Controlled selected value. Shape depends on mode: Date for 'single', Date[] for 'multiple', { from?: Date; to?: Date } for 'range'.",
+      "name": "selected",
+      "type": "Date | Date[] | DateRange | undefined"
+    },
+    {
+      "description": "Callback fired when the user clicks a day. Receives the new selection, the clicked date, active modifiers, and the event.",
+      "name": "onSelect",
+      "type": "(date: Date | Date[] | DateRange | undefined, triggerDate: Date, modifiers: Modifiers, e: MouseEvent) => void"
+    },
+    {
+      "description": "Uncontrolled initial month shown. For controlled month navigation use month + onMonthChange.",
+      "name": "defaultMonth",
+      "type": "Date"
+    },
+    {
+      "description": "Controlled currently-displayed month. Pair with onMonthChange to drive navigation programmatically.",
+      "name": "month",
+      "type": "Date"
+    },
+    {
+      "description": "Fired when the user navigates to a different month.",
+      "name": "onMonthChange",
+      "type": "(month: Date) => void"
+    },
+    {
+      "defaultValue": "1",
+      "description": "Number of month grids to show side-by-side.",
+      "name": "numberOfMonths",
+      "type": "number"
+    },
+    {
+      "description": "Earliest month reachable via navigation. Also constrains the dropdown range when captionLayout includes 'dropdown'.",
+      "name": "startMonth",
+      "type": "Date | undefined"
+    },
+    {
+      "description": "Latest month reachable via navigation.",
+      "name": "endMonth",
+      "type": "Date | undefined"
+    },
+    {
+      "description": "Days to disable. Accepts a Date, Date[], { before: Date }, { after: Date }, { from: Date; to: Date }, { dayOfWeek: number[] }, or an array of any of these.",
+      "name": "disabled",
+      "type": "Matcher | Matcher[] | undefined"
+    },
+    {
+      "description": "Days to hide entirely from the grid.",
+      "name": "hidden",
+      "type": "Matcher | Matcher[] | undefined"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show greyed-out days from adjacent months. godx-ui defaults this to true (overrides react-day-picker's false default).",
+      "name": "showOutsideDays",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Show ISO/locale week-number column on the left.",
+      "name": "showWeekNumber",
+      "type": "boolean"
+    },
+    {
+      "description": "Always render 6 weeks per month, padding with days from the next month.",
+      "name": "fixedWeeks",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "'label'",
+      "description": "Caption area layout. 'dropdown' shows month/year select dropdowns for faster large-range navigation.",
+      "name": "captionLayout",
+      "type": "'label' | 'dropdown' | 'dropdown-months' | 'dropdown-years'"
+    },
+    {
+      "description": "Day index (0=Sun) for the first column of the week grid. Overrides locale default.",
+      "name": "weekStartsOn",
+      "type": "0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined"
+    },
+    {
+      "description": "Custom named modifiers applied to matched days. Pair with modifiersClassNames or modifiersStyles to style them.",
+      "name": "modifiers",
+      "type": "Record<string, Matcher | Matcher[] | undefined>"
+    },
+    {
+      "description": "CSS class names keyed by modifier name.",
+      "name": "modifiersClassNames",
+      "type": "ModifiersClassNames"
+    },
+    {
+      "description": "Content rendered below the grid as a live ARIA region. Use a string to communicate selection status to screen readers. Set it to replace the built-in showToday / showClose actions.",
+      "name": "footer",
+      "type": "React.ReactNode | string"
+    },
+    {
+      "description": "Focus the first selected day (or today) when the calendar mounts — recommended when opening inside a Popover.",
+      "name": "autoFocus",
+      "type": "boolean"
+    },
+    {
+      "description": "Override the 'today' date used for the today modifier and default navigation. Defaults to new Date().",
+      "name": "today",
+      "type": "Date"
+    },
+    {
+      "description": "Extra class added to the root wrapper element (adds to the built-in p-3 padding).",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Override individual part class names (months, weekday, day, selected, today, range_start, range_end, range_middle, disabled, outside, etc.). Merged with godx-ui defaults.",
+      "name": "classNames",
+      "type": "Partial<ClassNames>"
+    },
+    {
+      "description": "Swap out internal sub-components (Chevron is already replaced by lucide icons). Use for advanced custom rendering.",
+      "name": "components",
+      "type": "Partial<CustomComponents>"
+    },
+    {
+      "description": "Animate month-to-month navigation transitions (react-day-picker >=9.6).",
+      "name": "animate",
+      "type": "boolean"
+    },
+    {
+      "description": "'ltr' (default) or 'rtl' for right-to-left layouts.",
+      "name": "dir",
+      "type": "string"
+    },
+    {
+      "description": "aria-label on the container. Provide a meaningful label when the calendar is not described by a visible heading.",
+      "name": "aria-label",
+      "type": "string"
+    },
+    {
+      "description": "ARIA role for the container element. Use 'dialog' when rendering inside a modal Popover.",
+      "name": "role",
+      "type": "'application' | 'dialog' | undefined"
+    },
+    {
+      "description": "When true the user cannot deselect the currently selected day (mode must also be set).",
+      "name": "required",
+      "type": "boolean | undefined"
+    },
+    {
+      "description": "When numberOfMonths > 1, advance all visible months at once instead of one at a time.",
+      "name": "pagedNavigation",
+      "type": "boolean"
+    },
+    {
+      "description": "Render months newest-first (right-to-left reading order) when numberOfMonths > 1.",
+      "name": "reverseMonths",
+      "type": "boolean"
+    },
+    {
+      "description": "Hide the prev/next navigation buttons without disabling keyboard navigation.",
+      "name": "hideNavigation",
+      "type": "boolean"
+    },
+    {
+      "description": "Disable month navigation entirely (buttons hidden and keyboard navigation locked).",
+      "name": "disableNavigation",
+      "type": "boolean"
+    },
+    {
+      "description": "Hide the row of weekday abbreviation headers (Mon, Tue, ...).",
+      "name": "hideWeekdays",
+      "type": "boolean"
+    },
+    {
+      "description": "Use ISO week numbering (Monday first week, ignores weekStartsOn and firstWeekContainsDate).",
+      "name": "ISOWeek",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "DatePicker — the complete single-date form control (typeable ISO input + calendar icon + Popover). Use DatePicker instead of Calendar when you need a form-submittable field with an input box.",
+    "DatePicker — the complete date form control (typeable ISO input + calendar icon + Popover); add `range` for the two-input from/to pair. Use it instead of Calendar when you need form fields.",
+    "Popover / PopoverContent — the shell you must provide when you want Calendar inside a trigger. Pass `flush` and `width=\"auto\"` so the panel neither double-pads nor clips the grid."
+  ],
+  "rules": [
+    3,
+    5,
+    6,
+    23
+  ],
+  "storyPath": "data-entry/Calendar.stories.tsx",
+  "subParts": [
+    "DayButton"
+  ],
+  "tagline": "A styled react-day-picker grid for picking single dates, multiple dates, or date ranges — always embed it inside a Popover for full date-picker UX; use DatePicker (add `range` for a from/to pair) instead when you need a form-submittable input. `components={{ DayButton }}` is the documented seam for marking a day (a shift, a price, a badge): import `DayButton` and its types from `@godxjp/ui/data-entry` rather than from react-day-picker, so the type is this package's copy and not a second one (gh#797).",
+  "usage": [
+    "DO set mode explicitly ('single', 'multiple', 'range') — omitting it renders a display-only grid with no selection. The value passed to selected and the argument shape of onSelect both depend on mode.",
+    "DO embed Calendar inside a Popover + PopoverContent when building a date-picker UI — `<PopoverContent flush width=\"auto\">`. `flush` drops the panel padding (Calendar brings its own) and `width=\"auto\"` lets the calendar set the measure, which the panel's own 18rem would otherwise clip at two months. For form-submittable single-date or range inputs prefer the higher-level DatePicker (with `range` for a from/to pair) — it owns the input, icon, locale wiring, and ISO form submission natively.",
+    "DO pass a locale object imported from 'react-day-picker/locale' (e.g. import { ja } from 'react-day-picker/locale') for i18n — weekday names, month names, and first-day-of-week all come from the locale.",
+    "DO use the disabled prop with Matcher objects ({ before: minDate }, { after: maxDate }, { dayOfWeek: [0, 6] }) to restrict selectable days — never render your own disabled overlay on top.",
+    "DON'T zero the panel padding or pin its width with utilities on className. Those are per-call-site constants no service theme can retune; `flush` and `width=\"auto\"` set the same two tokens the panel already reads.",
+    "DON'T hand-roll a calendar grid — Calendar wraps react-day-picker which is keyboard-navigable, ARIA-annotated, and screen-reader friendly out of the box. Provide a footer string for screen-reader status announcements when the selection changes.",
+    "The month frame is two knobs, not a stack of them (gh#730). `--calendar-space-inset` is the ONE inset the caption row, the `‹`/`›` nav buttons and the day grid all sit at — `--calendar-nav-space-inline` is declared as that same value, because the nav is absolutely positioned and would otherwise get its own (measured 4px against the grid's 12px, so the header read wider than the body). `--calendar-grid-space-block-start` is the ONE caption→weekday-row step (space-3, 12px; it used to stack with the month column gap for 32px). Retune those tokens rather than adding padding on the call site."
+  ],
+  "useCases": [
+    "Inline date picker within a form section where the calendar grid must always be visible (e.g., a booking page or a date-of-issue field on an invoice creation form).",
+    "Date range selection inside a Popover triggered by a filter button on an accounting report page (use mode='range', pass selected={dateRange}, onSelect updates the filter state).",
+    "Multi-date selection for picking recurring reminder dates or batch-action target dates (mode='multiple').",
+    "Custom calendar with highlighted days (e.g., marking invoice due dates or shipment ETDs with a custom modifier + modifiersClassNames) overlaid on a standard single-select grid.",
+    "Month navigator with year/month dropdowns for jumping to a historical accounting period quickly (captionLayout='dropdown', startMonth set to earliest fiscal year).",
+    "Display-only calendar (no mode set) showing booked or blocked dates using the modifiers prop with read-only styling, embedded in a dashboard card."
+  ]
+}

package/agent/components/Callout.json

@@ -0,0 +1,46 @@
+{
+  "example": "import { Callout } from \"@godxjp/ui/feedback\";\n\n<Callout kind=\"warning\">\n  <Callout.Title>この操作は取り消せません</Callout.Title>\n  <Callout.Description>\n    リポジトリを削除すると、Issue と Pull Request も一緒に削除されます。\n  </Callout.Description>\n</Callout>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Callout",
+  "props": [
+    {
+      "defaultValue": "\"note\"",
+      "description": "GitHub/Obsidian admonition preset; resolves the tone AND the leading glyph. A preset, not a second colour axis — `tone` and `icon` still override per instance.",
+      "name": "kind",
+      "type": "\"note\" | \"tip\" | \"important\" | \"warning\" | \"caution\""
+    },
+    {
+      "description": "Overrides the tone the `kind` resolves to. Drives surface colour and the leading rail ONLY — unlike Alert, tone never changes live-region politeness here, because a Callout has none.",
+      "name": "tone",
+      "type": "\"default\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\""
+    },
+    {
+      "description": "Override or hide (false) the kind's default leading glyph.",
+      "name": "icon",
+      "type": "LucideIcon | false"
+    }
+  ],
+  "related": [
+    "Alert — the SAME primitive in its inline-card presentation, and a LIVE REGION. Use it for an update to the page; Callout is for part of the page.",
+    "Banner — the same primitive as the full-bleed page/shell strip, also a live region.",
+    "Prose — the typographic column a Callout normally sits inside; the callout's block margin is tuned to that rhythm."
+  ],
+  "rules": [],
+  "storyPath": "feedback/Callout.stories.tsx",
+  "tagline": "Static aside INSIDE a document body (docs admonition, CMS note, GitHub `> [!NOTE]`). role=\"note\", never a live region. Parts: Callout.Title/Description/Content/Actions.",
+  "usage": [
+    "CANONICAL CALLOUT CONTRACT: `Callout` is `Alert` with the structural axis fixed to `variant=\"callout\"` — same tone system, same slots, but ASIDE geometry owned by the `--callout-*` tokens (leading rail, prose insets, block margin) and, uniquely, NO live region. Never fake a callout with `className` on an `Alert`, and never hand-roll a coloured div with a left border.",
+    "DO: Use Callout for content that is part of the document the reader is reading — a docs admonition, a note in a CMS article, a caveat inside a policy page. It is rendered with the page, so it must not announce.",
+    "DON'T: Use `<Alert role=\"note\">` for this. That worked only because `{...props}` is spread after the computed `role`, which the package never promised; one refactor would have silently restored the live region. A consumer neutralising a component's own semantics is the tell that it is the wrong primitive (gh#765).",
+    "DON'T: Reach for Callout to report something that just HAPPENED (a save failed, a session expired). That is an update to the page, not part of it — use `Alert` (inline), `Banner` (page/shell strip) or `toast()`, all of which announce.",
+    "DON'T: Pass `onDismiss` — the type excludes it. Prose does not get dismissed; if the reader can remove it, it is an Alert.",
+    "MARKDOWN RENDERERS: map the five GitHub types straight onto `kind` — `[!NOTE]`→note, `[!TIP]`→tip, `[!IMPORTANT]`→important, `[!WARNING]`→warning, `[!CAUTION]`→caution. Obsidian's lower-case spelling is the same set. `important` takes the NEUTRAL tone (this system has no purple role); its glyph, not its colour, is what tells it from `note`."
+  ],
+  "useCases": [
+    "Docs/handbook admonition inside a prose column — `kind=\"note\"` for an aside, `kind=\"tip\"` for a shortcut worth knowing.",
+    "A caveat inside a rendered CMS article (react-markdown + rehype-sanitize), drawn from `> [!WARNING]` in the source.",
+    "A legal or policy page clause that needs emphasis without interrupting a screen-reader user reading the page top to bottom — `kind=\"important\"`.",
+    "A destructive-consequence note beside a runbook step — `kind=\"caution\"`, still silent on load."
+  ]
+}

package/agent/components/Card.json

@@ -0,0 +1,112 @@
+{
+  "example": "import { Card, CardHeader, CardTitle, CardContent } from \"@godxjp/ui/data-display\";\n\n<Card accent=\"success\">\n  <CardHeader><CardTitle>注文サマリー</CardTitle></CardHeader>\n  <CardContent>総売上: ¥1,234,567</CardContent>\n</Card>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Card",
+  "props": [
+    {
+      "description": "Semantic accent TONE. Where it is drawn is `accentPlacement`'s job — by default a leading-edge stripe on `border-inline-start` at the `--card-accent-rail-width` measure (6px).",
+      "name": "accent",
+      "type": "\"primary\" | \"success\" | \"warning\" | \"info\" | \"attention\" | \"destructive\""
+    },
+    {
+      "defaultValue": "\"edge\"",
+      "description": "Where `accent` is drawn. \"edge\" is the classic leading rail. \"perimeter\" is the FULL attention border — the whole edge in the accent tone, at the same optical weight as `variant=\"featured\"` but tone-owned, so a card can read as \"action required\" (accent=\"attention\") or \"failed\" (accent=\"destructive\") without borrowing the brand colour. Inert without `accent`. LIMIT (gh#750): the perimeter ring is painted OUTSIDE the border box, and a scroll container clips it — a horizontal ScrollArea is `overflow: auto hidden`, and `overflow-clip-margin` is honoured only by `clip`, not by `auto`. A perimeter card flush against a scroller edge loses 1px of ring on that side; inside a scroller use the default \"edge\" placement (its rail is inside the box) or a tone fill.",
+      "name": "accentPlacement",
+      "type": "\"edge\" | \"perimeter\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Surface fill AND edge. `outline` is Ant Design's `outlined` — no fill, hairline kept. `borderless` is Ant Design's `variant=\"borderless\"` (its deprecated `bordered={false}`) — no hairline, fill kept. The two are mirror images and neither substitutes for the other. `featured` is the BRAND perimeter; its colour is the `--card-featured-border-color` knob rather than a hard-coded `--primary`. For a perimeter in a semantic tone use `accent` + `accentPlacement=\"perimeter\"` instead.",
+      "name": "variant",
+      "type": "\"default\" | \"muted\" | \"outline\" | \"borderless\" | \"featured\""
+    },
+    {
+      "description": "Ant Design `hoverable` — the card lifts to `--card-hover-shadow` on hover and takes a pointer cursor. PRESENTATION ONLY: it announces nothing and binds no handler, so pair it with a real control (a Link/Button inside, or the whole card rendered as one via `asChild`). Never with a bare onClick on the Card div — a keyboard or screen-reader user cannot reach that. Composes with `accent`/`accentPlacement=\"perimeter\"`: the hover raises the shadow TOKEN, so the attention ring survives the hover.",
+      "name": "hoverable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Borrow the child's element for the card BOX instead of rendering a div — the standard Slot passthrough (Button, AspectRatio, ListRow). This is the other half of `hoverable`: `<Card asChild hoverable><a href=\"…\">` IS \"the whole card rendered as one control\" — one tab stop, announced as one link, with the focus ring on the card box (measured in Chromium: `<div>`, `<a>` and `<button>` identical on box, border, radius, fill, padding inset, shadow and cursor at 1440 and 390). For a click-only card hand it your router's Link component as the child. NESTING CAVEAT: the card is now ONE control, so it may not contain another — an <a>/<Button>/menu trigger inside a card-as-link or card-as-button is invalid HTML, and `tabList` (a strip of button triggers) is for the same reason not drawn under `asChild` and warns in development. A card that needs interactive children is not one control: drop `asChild` and put the Link/Button inside it, which is the other branch `hoverable` names. Exactly one child — two throws React.Children.only, the same error `Button asChild` throws.",
+      "name": "asChild",
+      "type": "boolean"
+    },
+    {
+      "description": "Internal padding density (base 16 / tight 12 / cozy 20). This IS Ant Design's `size` axis; there is deliberately no `size` prop (removed 2026-08-24) — see docs/DESIGN-AUTHORITY.md, a capability this library already has keeps its own name.",
+      "name": "density",
+      "type": "\"tight\" | \"cozy\""
+    },
+    {
+      "description": "Ant Design `tabList` — the tab strip that lives IN THE CARD'S HEAD: under the title, on the same surface, inside the same border, so the card and its tabs read as ONE object. The entry keeps antd's own field names (`key`/`tab`/`disabled`), NOT the Tabs component's `value`/`label`/`content` — a card tab carries only the trigger, because the panel is the card body. The Card's children become the selected tab's body; wrap them in <CardContent> (or <CardContent flush> for an edge-to-edge DataTable, which still reaches the card edge inside a tab).",
+      "name": "tabList",
+      "type": "{ key: string; tab: ReactNode; disabled?: boolean }[]"
+    },
+    {
+      "description": "Ant Design `activeTabKey` — the CONTROLLED selection. With it set the card never moves itself; pair it with `onTabChange` and swap the children yourself, exactly as in antd.",
+      "name": "activeTabKey",
+      "type": "string"
+    },
+    {
+      "description": "Ant Design `defaultActiveTabKey` — the uncontrolled initial selection. Without it the first selectable entry of `tabList` opens (antd's own fallback); a disabled tab is never the open one.",
+      "name": "defaultActiveTabKey",
+      "type": "string"
+    },
+    {
+      "description": "Ant Design `onTabChange` — fires with the newly selected `key`, however the selection moved (pointer or keyboard).",
+      "name": "onTabChange",
+      "type": "(key: string) => void"
+    },
+    {
+      "description": "Ant Design `tabBarExtraContent`, RENAMED to `extra` and made logical — the same precedent `Tabs.extra` already set in this package, and antd's `left`/`right` keys are `start`/`end` here so an RTL locale gets the slot on the correct edge. It rides the TAB BAR beside the strip, so it is inert without `tabList`; a header-level action is <CardAction> inside <CardHeader>.",
+      "name": "extra",
+      "type": "ReactNode | { start?: ReactNode; end?: ReactNode }"
+    },
+    {
+      "description": "Ant Design `tabProps` — passed straight to the Tabs that draws the strip, so `variant`, `size`, `centered`, `overflow`, `indicator` and the rest are reachable. The fields the CARD owns are omitted rather than silently overwritten: `items` comes from `tabList`, `value`/`defaultValue`/`onValueChange` from `activeTabKey`/`defaultActiveTabKey`/`onTabChange`, and `extra` is the Card's own slot. antd drops the same fields — it writes its own over `tabProps` — so this is that behaviour made visible in the type.",
+      "name": "tabProps",
+      "type": "Omit<TabsProps, 'items' | 'value' | 'defaultValue' | 'onValueChange' | 'extra' | 'children'>"
+    }
+  ],
+  "related": [
+    "StatCard — use instead of a plain Card when rendering a KPI/metric tile (label + value + optional delta/hint). StatCard is a Card internally; do not re-wrap it in another Card.",
+    "CardContent — mandatory inner wrapper for all body content inside Card. Provides the correct padding and supports flush/tight/solo variants. The only correct way to put padded content inside Card.",
+    "Descriptions — use inside <CardContent> when body content is a label-value metadata list (e.g. entity details, invoice fields); do not hand-roll a dl/dt/dd grid.",
+    "DataState / InfiniteQueryState — use instead of Card when the content is a TanStack Query-driven list that needs automatic skeleton, empty, and error states; Card does not manage loading lifecycle."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Card.stories.tsx",
+  "subParts": [
+    "CardAction",
+    "CardCover",
+    "CardDescription",
+    "CardFooter",
+    "CardHeader",
+    "CardTitle"
+  ],
+  "tagline": "Surface container with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab toolbar/filter strip (list controls, filter chips) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card.",
+  "usage": [
+    "DO always wrap body content in <CardContent> — the bare <Card> div has zero inner padding; content renders flush against card edges without it. Never add className=\"p-4\" directly on <Card> as a substitute.",
+    "DO put titles/descriptions in <CardHeader>/<CardTitle>/<CardDescription>. Use <CardHeader banded> for a visually separated muted-background header band (mirrors <CardFooter separated>). Pair with <CardAction> inside a flex-row CardHeader for header-level action buttons.",
+    "DO set <CardTitle level={n}> to keep a valid document outline (h1 → h2 → h3, no skipped levels): CardTitle renders <h3> by default, so a section card directly under a page <h1> needs level={2}. Pick the level by OUTLINE position, NEVER for visual size — the title size is fixed by tokens and does not change with level. When the card title is a styled label rather than a section heading, use <CardTitle as=\"p\"> so it is not announced as a heading.",
+    "DO use <CardContent flush> for edge-to-edge children such as DataTable, Table, or a Tabs list — this removes horizontal padding. Combine with <CardContent tight> when there is no visual gap needed after the header, and <CardContent solo> when there is no CardHeader above (top padding matches the card shell).",
+    "DO use <CardFooter separated> to render a top-bordered action band (Save/Cancel buttons, table summary row). Use <CardFooter flush> for a full-bleed footer bar.",
+    "DO use <CardFooter actions> for Ant Design's `actions` row — N EQUAL-WIDTH cells split by vertical hairlines (複製 / 共有 / 削除 under a profile or entity card). It is a different band from `separated`, which packs children at the inline end at their natural widths: that is the right shape for a Save/Cancel pair and the wrong one for a divided strip. `actions` is self-sufficient — it draws its own top rule and full-bleed edges, so it needs neither `separated` nor `flush` beside it. The dividers are logical (border-inline-start), so the strip mirrors under RTL.",
+    "DO use <CardCover> as the first child for full-bleed cover media — the header below it uses card-section top spacing, not the card shell.",
+    "DO make the WHOLE card the control with `asChild` when the whole card is the click target: `<Card asChild hoverable><a href={href}><CardHeader><CardTitle level={2}>…</CardTitle></CardHeader><CardContent>…</CardContent></a></Card>` (or your router's Link as the child when there is no href, e.g. a nav.push handler). One tab stop, announced as one link, focus ring on the card box. DON'T wrap the card in a raw <button> (that is a `no-raw-button` error) and DON'T put a bare onClick on the Card div (unreachable by keyboard and screen reader — `hoverable`'s own docblock forbids it). NESTING CAVEAT: a card-as-link/button may not CONTAIN another control — an <a>, a <Button>, a DropdownMenu trigger or a `tabList` strip inside it is invalid HTML (`tabList` is dropped with a development warning). When the card needs interactive children it is not one control: drop `asChild` and use the other branch — `hoverable` plus a real Link/Button inside <CardHeader>/<CardAction>/<CardFooter>.",
+    "ANT DESIGN PROPS THIS FAMILY ANSWERS BY COMPOSITION, not by a prop of the same name — do not ask for these to be added: `title` is <CardHeader> + <CardTitle> (and CardTitle.level emits a real heading, which antd does not); a header-level action is <CardAction> inside <CardHeader>. `cover` is <CardCover>. `actions` is <CardFooter actions>. `loading` is a Skeleton in the body — antd renders a Skeleton with paragraph rows and no title, so the equivalent is <CardContent solo><SkeletonRows rows={4} /></CardContent>. `type=\"inner\"` is variant=\"muted\" plus <CardHeader banded>. `size` is `density`. `Card.Grid` is <ResponsiveGrid>; `Card.Meta` is <ListRow leading title description trailing>.",
+    "DO use `tabList` for a tab strip that belongs to the CARD — antd's card-head tabs, ported name for name (gh#570): `tabList={[{ key, tab, disabled? }]}` plus `activeTabKey`/`defaultActiveTabKey`/`onTabChange`, with `extra` for antd's `tabBarExtraContent` and `tabProps` for everything else on the Tabs underneath. The strip renders INSIDE the card head, under the title, on the same surface and inside the same border, and the Card's children become the selected tab's body (wrap them in <CardContent>, or <CardContent flush> for an edge-to-edge DataTable). DON'T hand-roll it as a <Tabs> parked on the page above the card (the strip floats off the card and the two read as two objects) or as a <Card> repeated inside each tab (the shell is copied per view). A <Tabs> INSIDE <CardContent tight flush> is still correct for a strip that belongs to the BODY rather than to the card head.",
+    "DO reach for `accentPlacement=\"perimeter\"` when the whole card needs attention, not one edge: `<Card accent=\"attention\" accentPlacement=\"perimeter\">` is the semantic-tone equivalent of `variant=\"featured\"` (which is brand-toned by definition). Never hand-roll it with `className=\"border-2 border-[--attention]\"` or a page-local `.card--attention` rule — the placement owns the border weight, the outer ring AND the slot-padding compensation, so text stays on the same column as an unaccented sibling.",
+    "DON'T hand-roll a stat/KPI tile with <Card> + raw divs — use <StatCard> (label, value, hint, delta, layout, inverse props) which is already a Card internally with correct token-driven layout.",
+    "SPACING IS BORDER-AWARE & token-driven (theme via src/tokens/components/card.css, never hard-code padding on slots): `--card-space-inset` is the shared horizontal column every slot (header/content/footer) aligns to. A DIVIDED section — a `banded` header or a `separated` footer, i.e. one carrying a divider border — pads SYMMETRICALLY top+bottom from `--card-space-divided-y` (a band reads as its own region). A PLAIN header flows into the body instead: top `--card-space-shell-y`, no bottom, and the body supplies the gap via `--card-space-body-y`. THE TWO AXES ARE INDEPENDENT: `--card-space-inset` is inline-only, while `--card-space-shell-y` owns the BLOCK shell edges (plain-header top, `solo` body top, terminal slot bottom) and defaults to the inset — so a shell/theme can make a card SHORTER without narrowing its column by overriding `--card-space-shell-y` alone (this is how AuthShell's `--auth-shell-card-padding-block-compact` reaches CardContent). Never bridge it with a consumer selector on the card-content slot. Special case: `<CardContent flush>` zeroes BOTH of its block edges — for ANY full-bleed body, not only one containing a <Table>` gate left a flush file LIST floating 18px off its header while the flush table beside it sat at 0) — so the plain header above it supplies the gap from its own `--card-space-body-y` bottom padding instead. `tight` and `solo` still own that axis themselves. `--card-space-gap` is the in-slot stack gap (title↕description). Tune the band rhythm once at `--card-space-divided-y`; tune the accent stripe width at `--card-accent-rail-width` (default 6px)."
+  ],
+  "useCases": [
+    "Dashboard KPI summary row: wrap each metric in <StatCard> (or a plain <Card density=\"tight\"> with <CardContent>) to render a uniform grid of labeled value tiles with optional trend deltas.",
+    "Invoice or order detail panel: <Card accent=\"primary\"> with <CardHeader banded><CardTitle>, <CardContent> body rows (use <Descriptions> inside), and <CardFooter separated> holding approve/reject buttons.",
+    "Section container on a settings or form page: a single <Card> wrapping a <CardHeader><CardTitle> plus <CardContent> containing <FormField> groups, with <CardFooter separated> for Save/Cancel.",
+    "Data table with toolbar: <Card> + <CardHeader> (title + filter controls in <CardAction>) + <CardContent flush> containing <DataTable> — <CardContent flush> removes horizontal padding so the table header spans full width.",
+    "Detail screen with views: <Card tabList={[{key,tab}]} activeTabKey onTabChange extra={<Button/>}> with <CardHeader><CardTitle> above the strip and <CardContent flush><DataTable/></CardContent> as the body — one card, tabs in its head, and a table that reaches the card edge inside the tab (docs/data-display/card/examples/tab-list.tsx).",
+    "Featured announcement or alert card: <Card variant=\"featured\"> with an accent stripe (<accent=\"warning\">) to visually elevate a card above sibling cards on the page.",
+    "Media/cover card (e.g. entity profile): <CardCover> first (full-bleed image), then <CardHeader> + <CardContent> below it for structured metadata."
+  ]
+}

package/agent/components/CardBar.json

@@ -0,0 +1,49 @@
+{
+  "docPath": "docs/data-display/card/index.tsx",
+  "example": "<Card><CardBar pad={{block:2,inline:3}} border=\"block-start\">Tools</CardBar></Card>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "CardBar",
+  "props": [
+    {
+      "description": "Instance padding on the token scale.",
+      "name": "pad",
+      "type": "PadProp"
+    },
+    {
+      "description": "Measured padding escape.",
+      "name": "padRaw",
+      "type": "PadRawProp"
+    },
+    {
+      "description": "Spacing between main and extra slots.",
+      "name": "gap",
+      "type": "GapProp"
+    },
+    {
+      "description": "Optional muted ground.",
+      "name": "surface",
+      "type": "\"muted\""
+    },
+    {
+      "description": "Override positional divider edges for stacked bars.",
+      "name": "border",
+      "type": "\"none\" | \"block-start\" | \"block-end\" | \"both\""
+    }
+  ],
+  "related": [
+    "Card",
+    "Flex"
+  ],
+  "rules": [
+    9
+  ],
+  "storyPath": "data-display/Card.stories.tsx",
+  "tagline": "Inline card toolbar with scoped inset and divider edges.",
+  "usage": [
+    "Compose inside Card. Unset border follows its position; explicit border prevents double rules in stacked bars."
+  ],
+  "useCases": [
+    "Composer tool strips and view tabs."
+  ]
+}

package/agent/components/CardContent.json

@@ -0,0 +1,51 @@
+{
+  "example": "import { Card, CardContent, DataTable } from \"@godxjp/ui/data-display\";\n\n<Card>\n  <CardContent flush>\n    <DataTable data={rows} columns={columns} />\n  </CardContent>\n</Card>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "CardContent",
+  "props": [
+    {
+      "description": "Remove horizontal padding for edge-to-edge tables / tabs lists.",
+      "name": "flush",
+      "type": "boolean"
+    },
+    {
+      "description": "No top gap after header — pair with flush toolbars/tabs.",
+      "name": "tight",
+      "type": "boolean"
+    },
+    {
+      "description": "No header above: top padding matches the card shell.",
+      "name": "solo",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Card — the parent container; CardContent is always a direct child of Card. Card itself has zero internal padding; every visible body padding comes from CardContent (or CardHeader/CardFooter). Never put content directly inside Card.",
+    "StatCard — a self-contained KPI tile that IS already a Card; do not wrap it in <Card><CardContent>. Use StatCard directly inside a ResponsiveGrid.",
+    "ScrollArea — place ScrollArea inside CardContent (non-flush) when the card body needs to scroll; do not put ScrollArea outside CardContent or you lose the card's internal padding.",
+    "SkeletonStat — the loading placeholder for a StatCard tile; swap in SkeletonStat while KPI data is loading. For general Card loading shapes, use SkeletonTable or Skeleton primitives."
+  ],
+  "rules": [
+    37,
+    38
+  ],
+  "storyPath": "data-display/Card.stories.tsx",
+  "tagline": "Card body. flush = edge-to-edge (for DataTable/tabs); tight = no top gap; solo = no header above. NEVER put a Toolbar inside flush (it loses padding).",
+  "usage": [
+    "DO: Always wrap body content in <CardContent> — a bare <Card> has no internal padding, so any child placed directly inside it renders flush against the card edges.",
+    "DO: Use <CardContent flush> for DataTable, Table, or Tabs — the flush prop removes horizontal padding so the content spans edge-to-edge inside the card border. Never add manual p-0 on the Card itself instead.",
+    "DO: Use <CardContent tight> when placing a flush toolbar or a Tabs list directly below a CardHeader — tight removes the top gap so the header and the body connect without an awkward spacing gap.",
+    "DO: Use <CardContent solo> when the card has no CardHeader above it — solo gives the top padding that matches the card shell, ensuring visual balance.",
+    "DON'T: Nest a Toolbar inside <CardContent flush> — flush strips horizontal padding and Toolbar will lose its own padding. Put Toolbar outside the flush CardContent or in a separate non-flush CardContent above it.",
+    "DON'T: Wrap a StatCard inside <Card><CardContent> — StatCard already renders its own Card border; double-wrapping produces a double border. Render StatCard directly in a ResponsiveGrid."
+  ],
+  "useCases": [
+    "Wrapping a form body (Input, Select, Textarea fields) inside a Card that has a CardHeader title — ensures the form fields have correct internal padding.",
+    "Hosting a DataTable inside a Card edge-to-edge: <CardContent flush><DataTable .../></CardContent> — the table occupies the full card width with the card's border acting as the table container.",
+    "Dashboard detail panels where the card has no title — <CardContent solo> gives top padding equivalent to the card shell so the content doesn't sit too close to the top border.",
+    "Placing a Descriptions or Timeline inside a card to display invoice/accounting details — <CardContent> provides the standard 16px (or density-adjusted) padding without needing manual className.",
+    "Pairing with <CardHeader banded> and <CardFooter separated> in a multi-section layout such as a payment summary card — each section slot (header, content, footer) carries its own semantic spacing tokens.",
+    "Putting a ScrollArea inside <CardContent> (not flush) to create a scrollable card body with consistent padding, e.g. a chat or log viewer panel."
+  ]
+}

package/agent/components/Carousel.json

@@ -0,0 +1,50 @@
+{
+  "example": "import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselDots } from \"@godxjp/ui/data-display\";\n\n// CarouselDots reads the Embla api from context — no setApi wiring needed.\n<Carousel opts={{ loop: true }}>\n  <CarouselContent>\n    <CarouselItem>1</CarouselItem>\n    <CarouselItem>2</CarouselItem>\n  </CarouselContent>\n  <CarouselPrevious />\n  <CarouselNext />\n  <CarouselDots />\n</Carousel>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Carousel",
+  "props": [
+    {
+      "description": "Embla options.",
+      "name": "opts",
+      "type": "Parameters<typeof useEmblaCarousel>[0]"
+    },
+    {
+      "description": "Embla plugins.",
+      "name": "plugins",
+      "type": "Parameters<typeof useEmblaCarousel>[1]"
+    },
+    {
+      "description": "Receive the Embla api for custom logic (autoplay, external prev/next). NOT needed for dots — CarouselDots reads the api from context itself.",
+      "name": "setApi",
+      "type": "(api: CarouselApi) => void"
+    }
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "data-display/Carousel.stories.tsx",
+  "subParts": [
+    "CarouselContent",
+    "CarouselDots",
+    "CarouselItem",
+    "CarouselNext",
+    "CarouselPrevious"
+  ],
+  "tagline": "Embla-backed carousel primitives: previous/next controls, CarouselDots indicators, and a context API.",
+  "usage": [
+    "DO compose the full set: `<Carousel>` › `<CarouselContent>` › many `<CarouselItem>`, with `<CarouselPrevious>`/`<CarouselNext>` for arrows and `<CarouselDots>` for the indicator row. Don't render items outside `<CarouselContent>` — the track is the scroll container.",
+    "DO use `<CarouselDots>` for the active-slide indicator instead of wiring `setApi` by hand — it reads `selectedIndex`/`scrollSnaps` from the Carousel context, renders one `aria-current` dot per snap, and auto-hides when there is ≤1 slide.",
+    "DON'T use a Carousel where ALL items must be seen/compared at once or be keyboard-reachable in reading order (e.g. a list of selectable options, a data table, primary navigation) — hiding content behind a swipe is an anti-pattern there; use a Grid/`ResponsiveGrid`, `ScrollArea`, or `Tabs`.",
+    "DON'T autoplay without a pause-on-hover/focus control and reduced-motion respect — pass the Embla autoplay plugin via `plugins` only for non-essential decorative content, never for content the user must read.",
+    "DO set `opts={{ loop: true }}` for galleries that wrap, and rely on the built-in disabling: `CarouselPrevious`/`CarouselNext` auto-disable at the ends (via `canScrollPrev`/`canScrollNext`) — don't hide them, let them grey out.",
+    "DO give each `<CarouselItem>` real, meaningful content; the component already injects an 'N of M' slide label for screen readers, so don't add a redundant one (a consumer `aria-label` on the item overrides the default)."
+  ],
+  "useCases": [
+    "Feature / onboarding highlight cards on a dashboard or landing surface, with CarouselDots showing position.",
+    "Image or document thumbnail gallery (e.g. uploaded receipts / 物件写真) with looping and prev/next arrows.",
+    "Horizontal stepping list of compact KPI or announcement cards that overflow the viewport width.",
+    "Product/plan comparison cards on a marketing page where swiping between a few options is acceptable (not the primary action)."
+  ]
+}