@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/FeatureList.json

@@ -0,0 +1,43 @@
+{
+  "docPath": "data-display/feature-list.tsx",
+  "example": "import { FeatureList } from \"@godxjp/ui/data-display\";\n\n<FeatureList\n  items={[\n    { state: \"included\", label: \"SSO\", description: \"SAML と OIDC\" },\n    { state: \"limited\", label: \"API 呼び出し\", description: \"月 10,000 回まで\" },\n    { state: \"excluded\", label: \"監査ログのエクスポート\" },\n  ]}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "FeatureList",
+  "props": [
+    {
+      "description": "The lines, in reading order. `state` drives the glyph, its mark colour and a localized sr-only word, so colour is never the only carrier (WCAG 1.4.1). `description` is a muted second line that WRAPS.",
+      "name": "items",
+      "required": true,
+      "type": "{ state: \"included\" | \"excluded\" | \"limited\"; label: ReactNode; description?: ReactNode }[]"
+    },
+    {
+      "description": "Root class. The rhythm and the glyph metric live in the --feature-list-* tokens, not here.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ListRow — a single-line entity row (session, token, passkey) with a trailing action; it truncates and it rules a line between rows.",
+    "Timeline — the same glyph rail, but ordered in TIME, with a connector and done/current/pending.",
+    "Descriptions — a term/value grid. A feature line has no value column; the state IS the value, and it is drawn.",
+    "Legend — the key that says what a COLOUR means across other marks; a FeatureList makes statements of its own."
+  ],
+  "rules": [],
+  "storyPath": "data-display/FeatureList.stories.tsx",
+  "tagline": "A list of STATEMENTS, each with a leading state glyph (included ✓ / limited − / excluded ✗), an optional wrapping description, and the glyph aligned to the first text line.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { FeatureList } from \"@godxjp/ui/data-display\";`",
+    "DO put a quantity INSIDE the label — there is no prop for it, because `<Text tone=\"muted\" tabular>` in the label is already legal and already audit-clean.",
+    "DO leave `excluded` lines un-emphasised. The component mutes the label and draws a plain ✗; a red cross per omission reads as a list of errors instead of a list of facts.",
+    "DON'T hand-roll it as a `<ul className=\"flex flex-col gap-2\">` with an `mt-0.5` icon nudge — that is three ui-audit errors (no-utility-layout, no-utility-spacing ×2), and the 2px is below --space-1 so no token step spells it.",
+    "DON'T reach for ListRow: it is a single-line ENTITY row with a divider between every row and a trailing action slot, and it truncates where a statement has to wrap.",
+    "DON'T reach for Timeline: it is an ORDERED event rail with a connector line and done/current/pending statuses — that is time, not inclusion."
+  ],
+  "useCases": [
+    "A pricing-plan card listing what the plan includes, what it limits and what it leaves out.",
+    "A comparison surface where each tier repeats the same rows with different states.",
+    "A submission review: which requirements the upload met, which it met partially, which it missed.",
+    "A capability or compatibility list — supported / partially supported / unsupported."
+  ]
+}

package/agent/components/Field.json

@@ -0,0 +1,64 @@
+{
+  "example": "{`import { Field, Switch } from \"@godxjp/ui/data-entry\";\n\nexport function NotifyRow() {\n  return (\n    <Field id=\"notify\" label=\"メール通知\" description=\"重要な更新をメールで受け取る\">\n      <Switch id=\"notify\" defaultChecked />\n    </Field>\n  );\n}`}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Field",
+  "props": [
+    {
+      "description": "id wired to the control via htmlFor; pass the same id to the child control.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "The field label, rendered as a <Label>.",
+      "name": "label",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Content rendered BESIDE the label and OUTSIDE the <label> element — a help button, a Tooltip trigger, a status chip, a short text action. Same semantics as FormField.labelAddon. It must not go through `label`: Field's label is a real <label htmlFor> pointing at the checkbox/radio/switch, so a browser forwards a click anywhere inside it to that control and an interactive addon placed there TOGGLES the control when pressed (gh#812). A non-interactive mark (Badge as=\"span\") is still fine inside `label`.",
+      "name": "labelAddon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Muted hint rendered under the label, announced with the control via aria-describedby. Composes with `error` — both lines stack, they do not replace each other.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Validation message under the description (role=alert). The message IS the invalid state: the control is cloned with aria-invalid, and the message id reaches it through aria-errormessage AND aria-describedby (react-aria's hidden input drops the former). This is how a validated boolean stays in Field — FormField must not wrap a bare Switch.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "The control (Checkbox/Radio/Switch) placed beside the label.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra CSS classes on the wrapper.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "FormField — block label/helper/required layout for text inputs; use it instead when the control stacks under its label. Field now carries `labelAddon` and `error` with FormField's semantics, so the two read as one idea (gh#812); what Field still does NOT have is `required`, `helper`, `name`/error-bag binding, layout/width knobs and `staticText`.",
+    "Switch / Checkbox / Radio — the controls Field typically wraps."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "data-entry/Field.stories.tsx",
+  "tagline": "Label + optional description laid out beside a single checkbox/radio/switch control — the inline alternative to FormField's full block layout.",
+  "usage": [
+    "DO: Use Field to label a single boolean/choice control (Switch, Checkbox, Radio) in a compact two-column row — control beside label + description.",
+    "DO: Match the child control's id to Field's id so the label is correctly associated.",
+    "DO: Pass a pressable help affordance (Tooltip trigger, icon Button) through `labelAddon`, never through `label` — inside the <label> a press toggles the control (gh#812).",
+    "DO: Use `error` for a validated boolean instead of hand-wiring aria-invalid / aria-describedby or smuggling the message through `description`. Field wires aria-invalid, aria-errormessage and aria-describedby onto the control itself.",
+    "DON'T: Use Field for text inputs needing the full block label/required/helper layout — use FormField instead. There is no ChoiceField anymore; Field is the canonical name."
+  ],
+  "useCases": [
+    "A settings list of toggle rows (notifications, auto-save) where each Switch has a label + description.",
+    "A consent checkbox with an explanatory description beside it.",
+    "A radio option row in a preferences form."
+  ]
+}

package/agent/components/FilterBar.json

@@ -0,0 +1,99 @@
+{
+  "example": "import { FilterBar } from \"@godxjp/ui/navigation\";\n\n<FilterBar\n  search={{ value: query, onValueChange: setQuery, placeholder: \"Search records\" }}\n  filters={[\n    {\n      value: \"status\",\n      label: \"Status\",\n      options: STATUS_OPTIONS,\n      selected: status,\n      onSelectedChange: setStatus,\n    },\n  ]}\n  chips={appliedChips}\n  onChipRemove={removeFilter}\n  onClear={clearFilters}\n  hasActiveFilters={hasFilters}\n  resultCount={rows.length}\n  actions={<Button onClick={openCreate}>Add member</Button>}\n/>",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "FilterBar",
+  "props": [
+    {
+      "description": "Filter controls and groups (composition form). In the typed-model form children remain valid as CUSTOM filters, rendered after the typed `filters`.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Consumer-owned clear/reset action — also the chips' clear-all.",
+      "name": "onClear",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Shows clear only when filters are active.",
+      "name": "hasActiveFilters",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Uses the token-owned sticky presentation.",
+      "name": "sticky",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "'wrap'",
+      "description": "Responsive overflow strategy. 'wrap': stacked column below 640px, wrapping rows above. 'scroll': one bounded inline-scrolling row above 640px (still stacked below) with the clear-all action pinned at the inline end. The geometry is entirely token/CSS owned — never re-implement it in the page.",
+      "name": "overflow",
+      "type": "'wrap' | 'scroll'"
+    },
+    {
+      "description": "Typed model: search slot, first in the strip, token-owned width (--filter-bar-search-width). Presence of ANY model prop (search/filters/chips/onChipRemove/actions/resultCount/loading/disabled/error) activates the model layout; without them the composition form renders unchanged.",
+      "name": "search",
+      "type": "FilterBarSearchProp"
+    },
+    {
+      "description": "Typed model: labelled Select filters ({ value, label, options, selected/defaultSelected/onSelectedChange, placeholder, disabled }) — label becomes the control's real <label>. Width knob: --filter-bar-filter-width.",
+      "name": "filters",
+      "type": "FilterBarFilterProp[]"
+    },
+    {
+      "description": "Typed model: applied-filter chips ({ value, label, disabled }) in a labelled row. Add = include in the array; remove = onChipRemove(value); clear-all = onClear.",
+      "name": "chips",
+      "type": "FilterBarChipProp[]"
+    },
+    {
+      "description": "Per-chip remove handler; required for the × remove buttons to render.",
+      "name": "onChipRemove",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Typed model: trailing action slot at the inline end, after reset in DOM/keyboard order.",
+      "name": "actions",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Typed model: localized CLDR-pluralized count in a polite role='status' line; 0 is the rendered empty state.",
+      "name": "resultCount",
+      "type": "number"
+    },
+    {
+      "description": "Typed model: aria-busy strip + data-loading root while results (re)load.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Typed model: disables all model-rendered controls.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Typed model: role='alert' error line replacing the result count.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional structural class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "rules": [],
+  "storyPath": "navigation/FilterBar.stories.tsx",
+  "subParts": [
+    "FilterBarGroup"
+  ],
+  "tagline": "Domain-neutral list-page filter toolbar with optional clear action and labelled groups.",
+  "usage": [
+    "Prefer the typed model for a canonical list page: pass `search` + `filters` + `chips` + `resultCount` and the bar owns the layout, widths, chip lifecycle, keyboard order (search → filters → children → reset → actions → chip removes) and responsive stacking through --filter-bar-* tokens. Everything stays consumer data — the bar renders state, never owns it.",
+    "Compose real controls as children when the model doesn't fit; filter state and URL synchronization remain consumer-owned. Children also render INSIDE the model layout (after the typed filters) for one-off custom controls like a date-range picker.",
+    "Give each FilterBarGroup a `controlId` matching its single control's `id` so the visible caption is that control's real <label>; otherwise the control is nameless to a screen reader. Typed `filters` wire this automatically.",
+    "Reach for `overflow='scroll'` on filter-heavy list pages so a long JA/EN/VI label set never grows the strip into multiple rows and pushes the table below the fold.",
+    "A mobile sheet presentation is a COMPOSITION, not a prop: put the same typed FilterBar inside a Sheet triggered from a compact toolbar when a screen wants drawer-style filters. The bar's own responsive behavior is stack (below 640px) + wrap/scroll (above), token-owned."
+  ]
+}

package/agent/components/Flex.json

@@ -0,0 +1,153 @@
+{
+  "example": "import { Flex } from \"@godxjp/ui/layout\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<Flex direction=\"row\" gap=\"sm\" align=\"center\" justify=\"between\" wrap>\n  <SearchSummary />\n  <Flex direction=\"row\" gap=\"xs\" align=\"center\" wrap>\n    <Button variant=\"outline\">リセット</Button>\n    <Button>適用</Button>\n  </Flex>\n</Flex>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Flex",
+  "props": [
+    {
+      "description": "Floating child actions shown on parent hover/focus-within; always visible on touch.",
+      "name": "reveal",
+      "type": "\"hover\""
+    },
+    {
+      "description": "Negative inline inset on the token scale.",
+      "name": "bleed",
+      "type": "GapProp"
+    },
+    {
+      "description": "Lightweight surface, without Card structure.",
+      "name": "surface",
+      "type": "\"muted\" | \"popover\" | \"warning\""
+    },
+    {
+      "description": "false prevents shrinking.",
+      "name": "shrink",
+      "type": "boolean"
+    },
+    {
+      "description": "Grow into remaining flex space.",
+      "name": "grow",
+      "type": "boolean"
+    },
+    {
+      "description": "Semantic element. A list keeps its marker and indentation unless marker=\"none\" says otherwise.",
+      "name": "as",
+      "type": "\"div\" | \"span\" | \"ul\" | \"ol\" | \"li\""
+    },
+    {
+      "defaultValue": "as=\"ul\" → \"disc\", as=\"ol\" → \"decimal\"",
+      "description": "Marker for a LIST element; ignored by every other tag. marker=\"none\" emits NO data-list, so the list keeps its <ul>/<ol>, its <li> semantics and its gap token, and loses the bullet AND the --space-5 indent — that is the container a short entity list needs: <Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\"> with <ListRow as=\"li\"> rows. Before it, the bullet was unconditional and .ui-flex[data-list] > li { display: list-item } outranked [data-slot=\"list-row\"] { display: flex }, so rows fell out of flex layout (94.58px tall instead of 69.98px) and the only move left was a raw <ul>, which carries no gap token (gh#714). disc/decimal stay available so an <ol> can be bulleted, or a <ul> numbered, without a list-style-type in a className.",
+      "name": "marker",
+      "type": "\"disc\" | \"decimal\" | \"none\""
+    },
+    {
+      "description": "Responsive axis; omitted steps inherit.",
+      "name": "direction",
+      "type": "\"row\" | \"col\" | {base?: \"row\" | \"col\"; sm?: \"row\" | \"col\"; md?: \"row\" | \"col\"; lg?: \"row\" | \"col\"; xl?: \"row\" | \"col\"}"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Token gap between children, shared with other layout primitives. \"none\" is a DELIBERATE zero for two lines that read as one block — a name over its role, a weekday over its date, a tab bar with no seam — not a way to opt out of the token scale.",
+      "name": "gap",
+      "type": "\"none\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\""
+    },
+    {
+      "description": "ESCAPE HATCH: a gap in pixels, off every step of the scale. Real designs land on 2px, 5px, 6px, 10px, 14px — rounding to the nearest named step drifts the layout, and writing the literal in a className is blocked by ui-audit. Spend the ten named steps FIRST: `gap={3}` is 12px and follows the user's --scaling, gapRaw does not. It wins over `gap` (which then emits no class, so the two cannot fight over specificity) and leaves data-gap-raw on the DOM, so every escape stays countable.",
+      "name": "gapRaw",
+      "type": "number"
+    },
+    {
+      "description": "Inner padding on the token scale — one step for all four sides, or an object keyed by LOGICAL side. Exists because a missing padding prop produced 42 of 51 ui-audit errors in one real consumer (gh#408): `<Flex className=\"p-3\">` was the only move left.",
+      "name": "pad",
+      "type": "number | { inline?, block?, inlineStart?, inlineEnd?, blockStart?, blockEnd? }"
+    },
+    {
+      "description": "Raw-pixel padding for values off the scale, same contract and same price as gapRaw: it leaves data-pad-raw on the DOM so each escape is countable. Overrides `pad` PER SIDE, not as a whole.",
+      "name": "padRaw",
+      "type": "number | { inline?, block?, inlineStart?, inlineEnd?, blockStart?, blockEnd? }"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Take the space the siblings leave — the ELASTIC column of a `fixed | elastic | fixed` row (name · meter · figures). Also sets min-inline-size: 0, which is what lets a truncating child ellipse instead of pushing the row wider. Without this axis the only move was className=\"flex-1 min-w-0\", which ui-audit blocks (gh#405 §2).",
+      "name": "fill",
+      "type": "boolean"
+    },
+    {
+      "description": "A FIXED column: number = px, string = any CSS length. Comes with flex: none — a width a sibling can still squeeze is a suggestion, and stacked rows would start at different x offsets. Leaves data-width-raw on the DOM so the measurement stays countable, like gapRaw/padRaw.",
+      "name": "width",
+      "type": "number | string"
+    },
+    {
+      "description": "CENTRE this box and CAP it at a page measure (--page-measure-narrow 42rem / -medium 48rem / -wide 72rem): margin-inline:auto + inline-size:100% + max-inline-size. THE public answer to \"full-bleed outside, measured column inside\" — a marketing <section> paints edge to edge and its inner Flex measure=\"wide\" holds the content on the page measure. Deliberately NOT on PageContainer: that owns page padding and a header/toolbar/footer scaffold, so a full-bleed page cannot consume it, and the refusal left the centred column owned by nobody — three showcases each hand-wrote the same four declarations (gh#839). It adds NO gutter: the page inset is pad={{ inline: 6 }}, and one band with two padding owners drifts. A MAX, so nothing binds below the cap at 390px. An explicit `width` wins. Do not give a READING column \"wide\" — prose stays narrow/medium, which bracket Bringhurst's 45-75 characters. Omitted emits no attribute at all.",
+      "name": "measure",
+      "type": "\"narrow\" | \"medium\" | \"wide\""
+    },
+    {
+      "description": "Cross-axis alignment, emitted as a data attribute for the layout CSS.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\" | \"stretch\" | \"baseline\""
+    },
+    {
+      "description": "Main-axis distribution, emitted as a data attribute for the layout CSS.",
+      "name": "justify",
+      "type": "\"start\" | \"center\" | \"end\" | \"between\" | \"around\" | \"evenly\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Allows children to wrap onto additional flex lines.",
+      "name": "wrap",
+      "type": "boolean"
+    },
+    {
+      "description": "Drop this region below a canonical breakpoint step (sm 40rem, md 48rem, lg 64rem, xl 80rem). THE public way to make a region responsive without a page-local media query — a public header hides its anchor navigation with hideBelow=\"md\". Omitted by default, so no attribute is emitted and no rule matches. display:none also removes it from the a11y tree, so keep its destinations reachable elsewhere (a footer nav) at that width.",
+      "name": "hideBelow",
+      "type": "\"sm\" | \"md\" | \"lg\" | \"xl\""
+    },
+    {
+      "description": "Inverse of hideBelow — drop the region FROM that step upwards, i.e. keep it only on the narrow side (a compact-only affordance).",
+      "name": "hideFrom",
+      "type": "\"sm\" | \"md\" | \"lg\" | \"xl\""
+    },
+    {
+      "description": "ESCAPE HATCH: the same drop, at a width in PIXELS off every step of the scale — the gapRaw/padRaw contract on the breakpoint axis (gh#528). An off-scale breakpoint is a LOCAL EXCEPTION, not a new tier: sm/md/lg/xl are shared with collapseBelow and --master-detail-collapse-below, so two regions asked to fold at the same step really do fold together, while a raw width folds one region only. Spend the four steps first; reach here when the canonical design specifies a width the scale has not got (a nav that becomes a hamburger at 900px). It leaves data-hide-below-raw on the DOM so every escape stays countable, and prints one deduped media rule per distinct width (a media query cannot read a var()). It wins over hideBelow, which then emits nothing.",
+      "name": "hideBelowRaw",
+      "type": "number"
+    },
+    {
+      "description": "Inverse of hideBelowRaw, same contract and same price (data-hide-from-raw). THE SEAM: hideBelowRaw hides while width < N and hideFromRaw hides while width >= N — the same comparisons as the token steps, so the pair is exact complements and at exactly N the hideBelowRaw region is the visible one. Never hand-roll this with an inclusive max-width: `<= N` paired with `>= N` hides BOTH at exactly N, the 1px hole a consumer measured on a hand-rolled max-[900px]: pair.",
+      "name": "hideFromRaw",
+      "type": "number"
+    }
+  ],
+  "related": [
+    "Flex `direction='col'` — the standard pattern for ordinary vertical block spacing; use explicit `align`, `justify`, or `wrap` props when you need more control.",
+    "Flex `direction='row'` — the standard pattern for simple horizontal groups; add `wrap` and `align='center'` for the typical row with wrapped centered items.",
+    "ResponsiveGrid — use for equal-width, multi-column tile layouts. Flex arranges children on one flex axis and does not provide column-count behavior.",
+    "PageContainer — page scaffold and padding context. Flex is an inner layout primitive used inside page sections, cards, dialogs, and toolbars. PageContainer `measure` bounds an APP page (header and body together, narrow | medium); Flex `measure` bounds ONE centred column inside a full-bleed band, and is the only one that reaches the marketing `wide` step."
+  ],
+  "rules": [
+    2,
+    40
+  ],
+  "storyPath": "layout/Flex.stories.tsx",
+  "tagline": "Token-spaced flex primitive with explicit direction, alignment, justification, and wrapping controls.",
+  "usage": [
+    "DO import from `@godxjp/ui/layout` and reach for Flex when the axis, alignment, justification, or wrap behavior is part of the component contract: `import { Flex } from \"@godxjp/ui/layout\"`.",
+    "DO keep spacing on the `gap` prop instead of raw `gap-*`, `space-*`, or padding utilities. Flex uses the same token scale as other layout primitives, so spacing remains tied to the design system.",
+    "DO use `direction=\"row\"` with `wrap` for responsive control rows, chip clusters, and action groups that need more control than simple row composition.",
+    "DO use `direction=\"col\"` for vertical groupings that need explicit `align` or `justify` behavior. For pure vertical stacking without alignment control, `direction=\"col\"` is sufficient.",
+    "DON'T override the axis with `className` after choosing a direction prop. Keep the layout intent in props so catalog guidance and data attributes stay accurate.",
+    "FULL-BLEED BAND: a marketing/landing section is a `<section>` carrying the edge-to-edge paint (background, border, halo) around ONE `<Flex direction=\"col\" measure=\"wide\" pad={{ inline: 6, block: 20 }}>`. The measure centres and caps the column, `pad` owns the gutter and the band rhythm (`block: 20` = 80px, `block: 24` = 96px — the two band steps). Never a page-local `max-width: 1200px` + `margin-inline: auto` class, and never an inline style saying the same thing: that four-declaration idiom is what this prop replaced (gh#839).",
+    "Flex is a plain div with React.HTMLAttributes<HTMLDivElement>; pass `id`, `role`, `aria-*`, `data-*`, and structural className values as needed, but do not use it as a semantic form or button wrapper. When the parent only accepts phrasing content — a TabsTrigger, PopoverTrigger or Button, all of which render a <button> — pass `as=\"span\"` rather than reaching for a raw `<span className=\"flex …\">`.",
+    "SEMANTIC LIST: a list of rows is `<Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\">` with `<ListRow as=\"li\">` children — never a raw `<ul>` (no gap token), never `<div role=\"list\">` + `<div role=\"listitem\">` (ARIA re-describing markup HTML already has), and never a wrapper around each row: the divider is `:not(:last-child)` among SIBLINGS, so a row alone in its own wrapper loses it silently. `ui-audit` flags all three as `no-hand-rolled-list`.",
+    "NAMED FLEX = GROUP: a role-less div may not carry a naming attribute (axe aria-allowed-attr), so a Flex given `aria-label`/`aria-labelledby` — e.g. by FormField wrapping a composite range/年月 field — automatically renders `role='group'`, folds `aria-errormessage` into `aria-describedby`, and drops the widget-only `aria-required`/`aria-invalid`. Passing an explicit `role` opts out of all of this and the caller owns the attribute set."
+  ],
+  "useCases": [
+    "Toolbar internals where controls should sit in a row, wrap on narrow widths, and stay vertically centered.",
+    "Card headers that need title content on the left and actions on the right via `justify='between'` without hand-rolling flex utility classes.",
+    "Empty-state or loading blocks that center content on both axes using `align='center'` and `justify='center'`.",
+    "Form sub-sections where a vertical group needs stretched children or centered helper content beyond what a plain column Flex provides.",
+    "Badge, chip, or tag clusters where wrapping is required but the caller also needs explicit gap control.",
+    "Low-level layout composition inside custom components where raw flex classes would duplicate the primitive."
+  ]
+}

package/agent/components/FloatButton.json

@@ -0,0 +1,91 @@
+{
+  "docPath": "general/float-button.tsx",
+  "example": "import { FloatButton } from \"@godxjp/ui/general\";\nimport { MessageCircle, Share2 } from \"lucide-react\";\n\n<FloatButton.Group trigger=\"click\" type=\"primary\" icon={<MessageCircle />} aria-label=\"Trợ lý\">\n  <FloatButton tooltip=\"Hỏi trợ lý\" badge={{ count: 3 }} />\n  <FloatButton tooltip=\"Chia sẻ\" icon={<Share2 />} />\n  <FloatButton.BackTop />\n</FloatButton.Group>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "FloatButton",
+  "props": [
+    {
+      "description": "The glyph. Falls back to a document mark when the button carries neither an icon nor `content`, which is antd's own default.",
+      "name": "icon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "A short caption UNDER the glyph. Legal only with shape=\"square\" — a circle has no room, and asking for one logs antd's dev warning.",
+      "name": "content",
+      "type": "ReactNode"
+    },
+    {
+      "description": "antd 6's deprecated spelling of `content`, kept so an antd call site compiles unchanged. `content` wins when both are given. Prefer `content` in new code.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "antd's word for the FILL, not the native button type — `default` is the surface-with-hairline mark, `primary` the brand fill. The native attribute is `htmlType`.",
+      "name": "type",
+      "type": "\"default\" | \"primary\""
+    },
+    {
+      "defaultValue": "\"circle\"",
+      "description": "Round mark or rounded square. A FloatButton inside a Group inherits the group's shape, so a stack can never mix the two.",
+      "name": "shape",
+      "type": "\"circle\" | \"square\""
+    },
+    {
+      "description": "Hover/focus label. When it is a STRING and no aria-label is given it also becomes the button's accessible name — an icon-only control needs a name, and a tooltip alone never reaches a touch user (WCAG 4.1.2).",
+      "name": "tooltip",
+      "type": "ReactNode | { title, side, align, sideOffset }"
+    },
+    {
+      "description": "Renders an <a> instead of a <button>, exactly as antd does.",
+      "name": "href",
+      "type": "string"
+    },
+    {
+      "description": "Anchor target; only meaningful beside `href`.",
+      "name": "target",
+      "type": "string"
+    },
+    {
+      "description": "The corner count/dot mark. `overflowCount` defaults to 99 and `showZero` to false, both antd's. antd's `offset` and `size` are deliberately not ported — `offset` is a raw px tuple no token step spells.",
+      "name": "badge",
+      "type": "{ count?: number; dot?: boolean; overflowCount?: number; showZero?: boolean; color?: string }"
+    },
+    {
+      "description": "Non-interactive. A Group's trigger inherits it. Remember the house rule: the REASON a control is disabled is visible text, never the tooltip.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"button\"",
+      "description": "The native button type, since `type` is taken by the fill. antd 5.21+.",
+      "name": "htmlType",
+      "type": "\"button\" | \"submit\" | \"reset\""
+    }
+  ],
+  "related": [
+    "Button — the same control IN the layout flow. A float button is a Button that gave up its place in the page and took a corner instead.",
+    "Popover — anchors a panel to a trigger; it does not place the trigger.",
+    "Banner — a full-bleed strip, not a corner mark.",
+    "Toolbar / PageContainer extra — where an action belongs when it IS part of this page's content."
+  ],
+  "rules": [],
+  "storyPath": "general/FloatButton.stories.tsx",
+  "tagline": "Ant Design's corner action, ported whole — a control pinned to the viewport above the page, with FloatButton.Group (a stack, or a menu behind one trigger) and FloatButton.BackTop. The corner insets are tokens, so a service moves the mark without a media query.",
+  "usage": [
+    "DO import from `@godxjp/ui/general`: `import { FloatButton } from \"@godxjp/ui/general\";`",
+    "DO give every float button a name — `tooltip` as a plain string is enough, since it becomes the aria-label too.",
+    "DO move the mark with the `--float-button-offset-block-end` / `--float-button-offset-inline-end` tokens when a sticky action bar or a mobile tab bar is already in that corner.",
+    "DO pass `target={() => element}` to FloatButton.BackTop inside a shell that owns its own scroll region, so it watches that region rather than the document.",
+    "DON'T hand-roll it as a Button with `position: fixed` at the call site — that is page-local CSS the audit blocks, and it is the exact gap gh#558 was filed for.",
+    "DON'T reach for Popover: it anchors a PANEL to a trigger, so it answers where the panel goes, not where the trigger goes.",
+    "DON'T put a caption on a circle. `content` needs shape=\"square\"."
+  ],
+  "useCases": [
+    "An assistant or composer that must stay reachable while the reader works — a chat you may want open is not a one-shot trigger in a bar.",
+    "A stack of secondary actions collapsed behind one corner trigger (share / export / print).",
+    "Back to top on a long document or a long list.",
+    "A corner action carrying an unread count, via `badge`."
+  ]
+}

package/agent/components/Form.json

@@ -0,0 +1,87 @@
+{
+  "example": "import { Form, FormField, Input } from \"@godxjp/ui/data-entry\";\n\n<Form layout=\"horizontal\" labelWidth={120} columns={2} onSubmit={onSubmit}>\n  <FormField id=\"first\" label=\"姓\"><Input id=\"first\" /></FormField>\n  <FormField id=\"last\" label=\"名\"><Input id=\"last\" /></FormField>\n  <FormField id=\"address\" label=\"住所\" colSpan={2}><Input id=\"address\" /></FormField>\n</Form>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Form",
+  "props": [
+    {
+      "defaultValue": "\"vertical\"",
+      "description": "Label position relative to control; applied to all FormFields.",
+      "name": "layout",
+      "type": "\"vertical\" | \"horizontal\" | \"inline\""
+    },
+    {
+      "description": "Label column width in horizontal layout (number→px). e.g. 120 or '8rem'.",
+      "name": "labelWidth",
+      "type": "number | string"
+    },
+    {
+      "description": "Cap the control width (number→px). Omit to fill the column.",
+      "name": "controlWidth",
+      "type": "number | string"
+    },
+    {
+      "defaultValue": "\"end\"",
+      "description": "Horizontal alignment of the label within its column.",
+      "name": "labelAlign",
+      "type": "\"start\" | \"end\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Breakpoint below which horizontal collapses to vertical (mobile-first). false = always horizontal.",
+      "name": "collapseBelow",
+      "type": "\"sm\" | \"md\" | \"lg\" | \"xl\" | false"
+    },
+    {
+      "description": "Lay fields out in a responsive grid (reuses ResponsiveGrid; 1 col on small).",
+      "name": "columns",
+      "type": "number | { sm?: number; md?: number; lg?: number }"
+    },
+    {
+      "description": "Server validation error bag (e.g. Inertia's form.errors). Each FormField name='…' inside resolves its own message from the bag and CLAIMS its key; <FormErrors /> renders the unclaimed remainder (errors on hidden/derived fields). Works in both <form> and asChild modes.",
+      "name": "errors",
+      "type": "Partial<Record<string, string | string[]>>"
+    },
+    {
+      "description": "Apply a density to controls inside the form.",
+      "name": "density",
+      "type": "\"compact\" | \"default\" | \"comfortable\""
+    },
+    {
+      "description": "Disable controls inside FormField, including nested native controls.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Show required marks, hide them, or mark optional fields.",
+      "name": "requiredMark",
+      "type": "boolean | \"optional\""
+    }
+  ],
+  "related": [
+    "FormField — the per-field wrapper (label + control + helper/error) that reads Form's layout context; use one per control inside a Form.",
+    "FormErrors — renders the error-bag entries no mounted FormField claims (validation errors on hidden/derived fields); place inside a `Form errors={…}`.",
+    "ResponsiveGrid — Form `columns` reuses it; use ResponsiveGrid directly for non-form card grids."
+  ],
+  "rules": [
+    23,
+    24
+  ],
+  "storyPath": "data-entry/Form.stories.tsx",
+  "tagline": "Ant-style layout container — renders <form> and pushes layout (vertical/horizontal), labelWidth/controlWidth, label alignment, responsive collapse, and multi-column grid down to every FormField (overridable per field).",
+  "usage": [
+    "DO set `layout`, `labelWidth`, `controlWidth` ONCE on `<Form>` — every `<FormField>` inside inherits them. Override a single field by passing the same prop on that `<FormField>` (Form → FormField priority).",
+    "DO rely on mobile-first collapse: `layout='horizontal'` automatically stacks to vertical below `collapseBelow` (default `md`). Pass `collapseBelow={false}` only when a field MUST stay label-beside-control even on phones.",
+    "DO use `columns` for multi-field forms (e.g. `columns={2}`) — it reuses ResponsiveGrid (1 column on small screens, more on md/lg). Span a wide field across columns with `<FormField colSpan={2}>`.",
+    "ROW RHYTHM IS THE SAME ON EVERY PATH: a grid of FormFields hands its row spacing to the grid's own `row-gap` (--form-grid-row-gap, defaulting to --form-field-row-gap) instead of the per-field margin a stacked Form uses. So `columns={1}` — and any `columns={n}` form once a narrow container collapses it to one column — is pixel-identical to a Form with no `columns`, and a hand-written `<ResponsiveGrid columns={2}>` of FormFields inside a `CardContent` (what a form with several titled Card sections has to write) matches `columns={2}` exactly. Retune --form-field-row-gap to move every path together; --form-grid-row-gap / --form-grid-column-gap to retune the grid rows / gutter alone. Never add margin to a FormField to space a grid row: a per-item margin inside a grid misaligns row 1 and double-counts the track gap.",
+    "DON'T hand-roll a `<form>` + Flex stack for spacing — `<Form>` provides the vertical rhythm and the layout context FormField reads. Wire react-hook-form by spreading `onSubmit={handleSubmit(...)}` onto `<Form>`.",
+    "SERVER ERROR BAG: pass `errors={form.errors}` (Inertia) ONCE on `<Form>`, give each field a `name`, and put `<FormErrors />` at the top of the form. A named field resolves its message from the bag automatically (no per-field `error={errors.x}`), and FormErrors catches validation errors on hidden/derived keys (`action_mode`, `page`, a source-record id) that no visible field could display — without it those submits fail SILENTLY.",
+    "SIBLING FORMS: an edit screen split into several Card+Form sections shares ONE bag by wrapping the region in `<FormErrorsProvider errors={form.errors}>` instead of passing `errors` to each Form — the section Forms (without their own `errors`) join the shared registry, and one `<FormErrors />` anywhere in the region renders the unclaimed remainder."
+  ],
+  "useCases": [
+    "A settings page form where every label sits in a fixed 120px column to the left of its control (horizontal), collapsing to stacked labels on mobile.",
+    "A two-column entity-edit form (`columns={2}`) where the address field spans both columns (`colSpan={2}`).",
+    "A compact filter form (`layout='horizontal' density='compact'`) above a DataTable.",
+    "An Inertia edit screen passing `errors={form.errors}` so every `FormField name='…'` self-binds its server validation message and `<FormErrors />` surfaces the hidden-field remainder."
+  ]
+}

package/agent/components/FormErrors.json

@@ -0,0 +1,51 @@
+{
+  "example": "import { Form, FormErrors, FormField, Input } from \"@godxjp/ui/data-entry\";\nimport { useForm } from \"@inertiajs/react\";\n\nconst form = useForm({ customer_nm: \"\", action_mode: \"regist\" });\n\n<Form asChild layout=\"horizontal\" labelWidth={140} errors={form.errors}>\n  <form onSubmit={submit}>\n    <FormErrors />\n    <FormField name=\"customer_nm\" label=\"顧客名\" required>\n      <Input value={form.data.customer_nm} onChange={(e) => form.setData(\"customer_nm\", e.target.value)} />\n    </FormField>\n  </form>\n</Form>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "FormErrors",
+  "props": [
+    {
+      "description": "Explicit error bag — overrides the surrounding Form's `errors`. Use when the component sits outside a Form (e.g. inside FormRoot); field claiming still applies when a Form provides the registry.",
+      "name": "errors",
+      "type": "Partial<Record<string, string | string[]>>"
+    },
+    {
+      "description": "Heading above the messages. Defaults to the localized 'please review your input' title (dataEntry.formErrors.title).",
+      "name": "title",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Root class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Form — provides the error bag (`errors`) and the claim registry FormErrors reads; FormErrors must sit inside it (or receive `errors` explicitly).",
+    "FormErrorsProvider — the shared registry for a REGION of sibling Forms (multi-Card edit screens): wrap the region with it, leave `errors` off the section Forms, and one FormErrors covers the whole screen.",
+    "FormField — `name` claims a bag key and self-binds its message; the claimed key never re-appears in FormErrors.",
+    "Alert — the underlying destructive banner; use Alert directly for non-validation notices."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "data-entry/FormErrors.stories.tsx",
+  "subParts": [
+    "FormErrorsProvider"
+  ],
+  "tagline": "The 'no field to stand on' error summary — renders the entries of the surrounding Form's server error bag that no mounted FormField name='…' claims: validation errors on hidden/derived fields (action_mode, page, a source-record id) that would otherwise fail silently. Composed on Alert tone='destructive' (role='alert'); renders nothing while every entry is claimed or the bag is empty.",
+  "usage": [
+    "DO pass the WHOLE bag to `<Form errors={form.errors}>` and place `<FormErrors />` at the top of the form — never hand-filter the bag per page. Fields with `name` claim their keys automatically; FormErrors shows only the remainder, so the consumer never maintains an except-list.",
+    "DO give every visible field its `name` when adopting `Form errors` on a screen. A field that keeps a manual `error={errors.x}` WITHOUT `name` does not claim its key, and FormErrors will show that message twice.",
+    "DON'T hand-roll a destructive Alert bound to `errors.hidden_key` per page — that is exactly the per-page listing this component exists to remove, and it goes stale the moment the server adds a new derived-field rule.",
+    "DON'T use FormErrors as a generic mutation-failure banner — that is `Alert.QueryError` / toast territory. FormErrors is scoped to the VALIDATION bag of the surrounding form.",
+    "INSIDE FormRoot: `<FormRoot form={form} onSubmit={(v) => m.mutateAsync(v)} errors={serverErrors(m.error)}><FormErrors /><AlertMutationFeedback mutation={m} />…</FormRoot>` — FormRoot mounts the claim registry, so `<FormErrors />` needs no `errors` of its own and shows only unclaimed keys. A 422 renders exactly once: claimed keys under their fields, unclaimed keys here, no AlertMutationFeedback alert (gh#690) and no FormRoot submitFailed banner (gh#698).",
+    "ARRAY ENTRIES: a `string[]` bag value lists every message in the banner; a claimed field shows only the FIRST message of its array (Laravel `$errors->first()` semantics).",
+    "SIBLING FORMS: when the screen is split into several Card+Form sections, wrap the REGION in `<FormErrorsProvider errors={form.errors}>` and give NO `errors` to the section Forms — they join the shared registry and one `<FormErrors />` covers the whole screen. A nested Form WITH its own `errors` deliberately starts a separate (shadowed) registry."
+  ],
+  "useCases": [
+    "An Inertia edit screen whose Laravel FormRequest validates hidden/derived inputs (`action_mode`, `page`, `source_slip_cd`) — the user pressed save and previously saw NOTHING because those keys have no visible field.",
+    "A ported legacy screen where the server rejects a stale edit-lock or a missing source record under a key that only exists server-side.",
+    "A create form where a Laravel `RuleObject` attaches a cross-field error to a synthetic key (e.g. `combination`) rather than to one input."
+  ]
+}