@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/FormField.json

@@ -0,0 +1,137 @@
+{
+  "example": "import { FormField, Input } from \"@godxjp/ui/data-entry\";\n\n<FormField id=\"coupon-name\" label=\"クーポン名\" required error={errors.name} helper=\"最大50文字\">\n  <Input id=\"coupon-name\" placeholder=\"春の花粉症対策15%OFF\" value={name} onValueChange={(e) => setName(e.target.value)} />\n</FormField>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "FormField",
+  "props": [
+    {
+      "description": "Tên trường của form — dùng khi `id` không đủ để nối control với error/aria.",
+      "name": "field",
+      "type": "string"
+    },
+    {
+      "description": "Nội dung phụ cạnh nhãn: gợi ý, badge bắt buộc, nút trợ giúp, action chữ ngắn. Nằm TRONG hàng nhãn nên không phá nhịp trường. Ở layout horizontal/inline hàng nhãn xuống dòng: addon không vừa cạnh nhãn thì rơi xuống dòng riêng dưới nhãn, trong cột nhãn, không tràn sang cột control.",
+      "name": "labelAddon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Forwarded to Label htmlFor + builds helper/error ids.",
+      "name": "id",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Error-bag key of this field. When the surrounding Form carries `errors`, the field resolves its message from `errors[name]` automatically (an explicit `error` prop wins) and CLAIMS the key so <FormErrors /> does not repeat it. NOT injected into the child — pass `name` on the control itself for native form submission.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Field label above the control.",
+      "name": "label",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Red asterisk + aria-required on the child.",
+      "name": "required",
+      "type": "boolean"
+    },
+    {
+      "description": "Muted hint shown when there is no error.",
+      "name": "helper",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"after\"",
+      "description": "Which side of the control the helper sits on. `before` puts it between the label and the input, for a hint the reader needs before answering (a bilingual form's second line, a unit or format note). Paint only — the helper keeps its id and stays on aria-describedby. Prefer it over stuffing a second line into `labelAddon` (a label-row slot for a chip, help button or short action) or into a ReactNode `label` (which loses the string-label aria fallbacks).",
+      "name": "helperPlacement",
+      "type": "\"before\" | \"after\""
+    },
+    {
+      "description": "Destructive error message (role=alert); overrides helper.",
+      "name": "error",
+      "type": "string"
+    },
+    {
+      "description": "Override the parent Form's layout for this field only.",
+      "name": "layout",
+      "type": "\"vertical\" | \"horizontal\" | \"inline\""
+    },
+    {
+      "description": "Override the Form's label width for this field.",
+      "name": "labelWidth",
+      "type": "number | string"
+    },
+    {
+      "description": "Override the Form's control width for this field.",
+      "name": "controlWidth",
+      "type": "number | string"
+    },
+    {
+      "description": "Span N columns when inside a `columns` Form grid.",
+      "name": "colSpan",
+      "type": "number"
+    },
+    {
+      "description": "The single interactive control to render. Mutually exclusive with `staticText` — pass exactly one of the two.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Read-only VALUE instead of an interactive control — renders as plain text styled to match `Descriptions.Item`'s value typography byte-for-byte (`text-sm break-all`), skipping all of FormField's id/aria-* control wiring (there is nothing to label). Mutually exclusive with `children`. Use this to put a read-only field (name, email — anything immutable) on the SAME `<Form>` as editable fields, so it inherits the exact same layout/labelAlign/row-gap automatically instead of reaching for a separate `Descriptions` block that needs its own props reconciled to match.",
+      "name": "staticText",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Validation state; an actual error takes priority. Warnings do not mark values invalid.",
+      "name": "validateStatus",
+      "type": "\"success\" | \"warning\" | \"error\" | \"validating\""
+    },
+    {
+      "description": "Show a localized accessible validation status beside its feedback icon.",
+      "name": "hasFeedback",
+      "type": "boolean"
+    },
+    {
+      "description": "Custom feedback content; the localized status remains available.",
+      "name": "feedback",
+      "type": "React.ReactNode"
+    }
+  ],
+  "related": [
+    "Label — the bare Radix label component. Use directly only when you are building a fully custom layout that cannot accept FormField's stack wrapper, and you will manage aria-describedby/aria-invalid yourself. FormField is always preferred for standard form controls.",
+    "Field — the inline row for a boolean control: label and control side by side, with `labelAddon`, `description` and `error` (gh#812 added the last two slots; `error` wires aria-invalid / aria-errormessage / aria-describedby onto the control, so a validated boolean no longer has to be hand-wired). It still renders NO hidden `<input name>` — `Switch name=\"…\"` submits itself — and it has no `required`, `helper`, error-bag `name` binding or layout/width knobs. Still: never wrap a bare `Switch` in FormField.",
+    "Field — pairs a single checkbox or radio with a label and optional description in a horizontal layout (control beside text). Use Field instead of FormField when the control and its label sit side-by-side rather than stacked.",
+    "CheckboxGroup / RadioGroup — for groups of options where FormField is not needed per-item; the group component handles its own legend/label and option layout."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "data-entry/FormField.stories.tsx",
+  "tagline": "Wraps a control with label, helper, and error; injects the accessible name (aria-labelledby), description (aria-describedby) and validation (aria-errormessage/aria-invalid/aria-required) contract onto the child, which forwards it to its real semantic focus target. Reads the parent Form's layout (vertical/horizontal) — overridable per field.",
+  "usage": [
+    "DO pass the same string to both `id` on `<FormField>` and `id` on the child control — the component wires `<Label htmlFor={id}>`, and builds `{id}-helper` / `{id}-error` ids for `aria-describedby`. If the ids diverge the label click and screen-reader announcements break.",
+    "DO pass a SINGLE React element as `children`. FormField calls `React.cloneElement` on it to inject `aria-describedby`, `aria-required`, and `aria-invalid` — if you pass a fragment or multiple nodes, cloneElement silently skips the injection and a11y attributes are lost.",
+    "COMPOSITE CHILD: when the single child is a layout wrapper — a `Flex` holding a range from/to pair or a 年/月 input+select combo — the label still reaches every control inside. FormField publishes its label through FieldNameContext and each control's semantic focus target (Input's `<input>`, Select/SearchSelect's `role=combobox` trigger, and everything composed on them) adopts it as a LAST-RESORT accessible name; a control's own `aria-label`/`aria-labelledby` always wins, so set a per-control `aria-label` (e.g. 開始日/終了日) when the two halves should announce distinct names. The wrapper itself renders as a named `role='group'` (see Flex).",
+    "DO reach for `staticText` (not `children` with a bare string/span) for a read-only field mixed into an otherwise-editable Form — e.g. an immutable name/email row above an editable role Select on the same Members-edit card. It renders with the exact typography `Descriptions.Item`'s value uses, and — because it IS a FormField reading the same Form context — it lines up with every other field's label column, `labelAlign`, and row-to-row gap automatically. A bare string as `children` instead triggers the dev-mode 'expected a single React element child' warning and has no typography contract at all.",
+    "WIDTH: a FormField FILLS its container in vertical/horizontal layout — like the conventional Form.Item (vertical → width:100%). It works full-width inside `<Form>`, a `ResponsiveGrid` cell, a bare `<Flex direction='col'>`, or a plain block; you do NOT need to wrap it in a grid to get full width. `layout='inline'` is the only content-width exception (compact, side-by-side). To narrow just the control (keeping the label row full-width), set `controlWidth` — never constrain the FormField itself.",
+    "DO use the `error` prop (not a hand-rolled `<p>`) for validation messages — it renders with `role='alert'` and `text-destructive` styling and overrides `helper` automatically. Never render an error paragraph alongside FormField.",
+    "DO use `labelAddon` (a ReactNode rendered after the label text, in the label row) for supplementary controls such as a tooltip trigger, a 'copy' icon button or a short text action ('Assign to myself'); in a horizontal/inline layout the label row wraps, so an addon that does not fit beside the label drops under it inside the label column rather than overlapping the control — never insert such controls as siblings outside FormField, which breaks layout.",
+    "DON'T wrap `Switch` in FormField — use `Field` instead. Field owns the inline row: `label`, `labelAddon`, `description`, and `error` (which wires aria-invalid / aria-errormessage / aria-describedby onto the control, gh#812). It renders no hidden input of its own — `Switch name=\"…\"` is what submits natively — and it has no `required`, `helper` or layout knobs.",
+    "DON'T use FormField for checkbox-beside-label or radio-beside-label patterns — use `Field` (single checkbox/radio with description) or `CheckboxGroup` / `RadioGroup` (multiple options), which have their own integrated labelling.",
+    "CONTRACT (which element owns each ARIA relationship): every data-entry control accepts and FORWARDS the injected props to its real semantic focus target, not a wrapper div — Input/Textarea/NumberInput → the `<input>/<textarea>`; Select/SearchSelect/Cascader/TreeSelect → the `role=combobox` trigger (with aria-expanded + aria-haspopup + aria-controls per the WAI-ARIA APG combobox pattern); DatePicker/TimePicker → the typeable `role=combobox` input (aria-haspopup=dialog); ColorPicker → the `<input type=color>` swatch; SearchInput → the `role=searchbox` input. GROUP controls own the relationship on their container: RadioGroup → `role=radiogroup` (full validation incl. aria-invalid/-errormessage/-required); CheckboxGroup, `DatePicker range` (two inputs), and Transfer → `role=group` — per ARIA 1.2 a group is not a widget, so the error id is folded into aria-describedby instead of aria-invalid/-errormessage. Upload forwards the label/description onto its native `<input type=file>`; its visible dropzone/button keeps its own action label. This forwarding is implemented once in `src/lib/field-a11y.ts` (`pickFieldA11y` / `pickGroupFieldA11y` / `resolveFieldA11y`) — do not reinvent it per control.",
+    "FIELD IDENTITY / AUTOMATION: FormField also injects a `data-field` — the field's stable MACHINE key, resolved as `field` → `name` → `id` — onto the same semantic focus target the ARIA relationships land on, and onto every option of a RadioGroup/CheckboxGroup. Use it (not a generated id, and never the visible Japanese label) as the selector in e2e tests and screen automation. It reaches NESTED controls too: when the direct child is a layout wrapper (a Flex holding a from/to pair, a 年/月 combo, a value beside a 「不明」 checkbox) cloneElement stops on that wrapper, so FormField also publishes the field through context and each control inside resolves its own key from its OWN `id` — which is what keeps `search_billing_date_from` and `..._to` distinct instead of collapsing onto one shared key. A nested control with NO id of its own deliberately gets nothing: a fabricated key is worse than a missing one, because automation binds to it and breaks silently. Two companion pieces: a `Select`'s trigger also carries `data-value` = the selected CODE (the trigger shows the option LABEL, and Radix keeps the value in an aria-hidden 1x1px native `<select>`), and each RadioGroup/CheckboxGroup option gets a deterministic `{groupId}-{optionValue}` id instead of a per-mount `React.useId()` token. Nothing here is opt-in and no DOM structure changed. A `data-field` written on the control itself always wins.",
+    "NATIVE `name` IS OPT-IN: FormField emits the same key as a real `name` attribute ONLY when the app set `<AppProvider emitFieldNames>`. It is off by default because `name` decides what a native `<form>` submit sends — turning it on globally in a shared package would make every consumer start posting new keys to its backend on an upgrade. Turn it on in apps that need native form posts or a screen-automation contract; a `name` written on the control itself always wins.",
+    "NATIVE FORM PARTICIPATION: pass `name` to a control for HTML form submission — Input/Textarea/NumberInput/Select submit natively; SearchSelect submits via a hidden input; DatePicker/TimePicker emit ISO strings (`yyyy-MM-dd` / 24h `HH:mm`); the range pickers emit `${name}_from` / `${name}_to`. `required`/`readOnly`/`disabled` map to the underlying control. Cascader/TreeSelect/Transfer submit named values via hidden inputs; Upload appends staged local files to FormData when named. Disabled controls are excluded.",
+    "ERROR TIMING & RECOVERY: pass `error` only after a field is dirty or the form is submitted (don't show errors on pristine mount). The error node renders with `role='alert'` so it is announced live the moment it appears; clearing `error` (e.g. after the user corrects the value or a server round-trip succeeds) removes aria-invalid and restores the helper. On submit, focus the first invalid control and/or render an error summary that links to each field by `id`."
+  ],
+  "useCases": [
+    "Labelling a text `Input` or `Textarea` in an invoice-entry form, showing a red asterisk for required fields and surfacing server validation errors returned from a Laravel FormRequest.",
+    "Wrapping a `Select` or `DatePicker` inside a multi-field filter panel where each control needs a visible label, helper hint (e.g. 'YYYY/MM/DD'), and inline error state.",
+    "Adding a `labelAddon` tooltip button next to a 'Tax rate' label in an accounting form to explain when different rates apply, without breaking the label–control association.",
+    "Enclosing a `DatePicker range` or `TimePicker` in an admin settings page where the field needs a label, a muted hint ('Inclusive of start and end date'), and conditional error display.",
+    "Wrapping a `SearchSelect` or `Select` (with `showSearch`) control for vendor/account lookup in a journal-entry form where the `id` must be kept consistent for programmatic focus management.",
+    "Providing structured error feedback for a `Cascader` or `TreeSelect` in a multi-level category assignment screen, replacing ad-hoc error rendering with the standardised `role='alert'` pattern."
+  ]
+}

package/agent/components/FormFieldArray.json

@@ -0,0 +1,39 @@
+{
+  "docPath": "docs/FORMS.md",
+  "example": "import { FormFieldArray, FormFieldControl } from \"@godxjp/ui/form\";\nimport { Input } from \"@godxjp/ui/data-entry\";\n<FormFieldArray name=\"contacts\">{({fields}) => fields.map(row => <FormFieldControl key={row.key} name={`${row.name}.email`} label=\"Email\">{field => <Input {...field} value={String(field.value ?? \"\")} />}</FormFieldControl>)}</FormFieldArray>;",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/form",
+  "name": "FormFieldArray",
+  "props": [
+    {
+      "description": "Array field path in the surrounding RHF FormRoot.",
+      "name": "name",
+      "type": "FieldArrayPath<T>"
+    },
+    {
+      "description": "Receives fields with stable key/name/index, append/prepend/insert/remove/move/swap/replace, array error and disabled state.",
+      "name": "children",
+      "type": "(collection) => React.ReactNode"
+    }
+  ],
+  "related": [
+    "Form",
+    "FormField",
+    "FormRoot",
+    "FormFieldControl"
+  ],
+  "rules": [
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Form.stories.tsx",
+  "tagline": "Dynamic typed field collections with stable keys, nested validation and append/remove/reorder operations.",
+  "usage": [
+    "Use inside the documented form composition; do not nest native form elements.",
+    "Use godx-ui controls and preserve field names, errors and disabled state."
+  ],
+  "useCases": [
+    "Validated settings forms",
+    "Nested repeating data entry"
+  ]
+}

package/agent/components/FormFieldControl.json

@@ -0,0 +1,129 @@
+{
+  "docPath": "docs/data-entry/form-root.tsx",
+  "example": "import { FormFieldControl } from \"@godxjp/ui/form\";\nimport { Input } from \"@godxjp/ui/data-entry\";\n<FormFieldControl name=\"email\" label=\"Email\" required>{field => <Input {...field} value={String(field.value ?? \"\")} />}</FormFieldControl>;",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/form",
+  "name": "FormFieldControl",
+  "props": [
+    {
+      "description": "Typed field path, including nested list rows.",
+      "name": "name",
+      "type": "FieldPath<T>"
+    },
+    {
+      "description": "Visible field label. Optional (antd): omitted, the field renders NO label row and reserves no space for one — the boolean-field shape, where the control carries its own inline label.",
+      "name": "label",
+      "type": "React.ReactNode"
+    },
+    {
+      "defaultValue": "\"value\"",
+      "description": "antd `valuePropName`. `\"checked\"` hands the render prop `checked` / `onCheckedChange` instead of `value` / `onChange` (the render-prop type narrows) and stores a boolean, so `<Checkbox {...field}>label</Checkbox>` / `<Switch {...field} />` need no wiring.",
+      "name": "valuePropName",
+      "type": "\"value\" | \"checked\""
+    },
+    {
+      "description": "Dependent fields that trigger revalidation.",
+      "name": "dependencies",
+      "type": "FieldPath<T>[]"
+    },
+    {
+      "description": "Extract the control value.",
+      "name": "getValueFromEvent",
+      "type": "(...args: unknown[]) => unknown"
+    },
+    {
+      "description": "Normalize before storage.",
+      "name": "normalize",
+      "type": "(value: unknown, previous: unknown) => unknown"
+    },
+    {
+      "description": "Keep value after unmount, default true.",
+      "name": "preserve",
+      "type": "boolean"
+    },
+    {
+      "description": "Override validation error text.",
+      "name": "help",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Field-level disabled state.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Validation feedback state.",
+      "name": "validateStatus",
+      "type": "\"success\" | \"warning\" | \"error\" | \"validating\""
+    },
+    {
+      "description": "Show accessible validation feedback.",
+      "name": "hasFeedback",
+      "type": "boolean"
+    },
+    {
+      "description": "Custom feedback icon/content.",
+      "name": "feedback",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Render a godx-ui control bound to the field.",
+      "name": "children",
+      "type": "(field) => React.ReactNode"
+    },
+    {
+      "description": "Optional DOM identity; defaults to a unique id even across sibling forms.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Per-field layout override.",
+      "name": "layout",
+      "type": "FormLayoutProp"
+    },
+    {
+      "description": "Per-field label width.",
+      "name": "labelWidth",
+      "type": "WidthProp"
+    },
+    {
+      "description": "Per-field control width.",
+      "name": "controlWidth",
+      "type": "WidthProp"
+    },
+    {
+      "description": "Label help or action. In a horizontal/inline layout it wraps under the label inside the label column when it does not fit beside it.",
+      "name": "labelAddon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Grid column span.",
+      "name": "colSpan",
+      "type": "number"
+    }
+  ],
+  "related": [
+    "Form",
+    "FormField",
+    "FormRoot",
+    "FormFieldControl"
+  ],
+  "rules": [
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Form.stories.tsx",
+  "tagline": "Bind a typed field to RHF or a server adapter, with shared FormField presentation and validation.",
+  "usage": [
+    "Use inside the documented form composition; do not nest native form elements.",
+    "Use godx-ui controls and preserve field names, errors and disabled state.",
+    "RENDER-PROP BAG: `{ id, name, value, onChange, onValueChange, onBlur, ref, disabled? }`. `ref` is `RefCallback<HTMLElement>` (gh#698), so `{...field}` spreads onto Input, Textarea, Select, NumberInput and DatePicker with NO cast — never cast or drop the ref (react-hook-form focuses the first invalid field through it). `value` is `unknown`: narrow it per control (`String(field.value ?? \"\")`, `typeof field.value === \"number\" ? field.value : null`).",
+    "SERVER VALIDATION: a `FormField name` under `FormRoot errors={…}` claims its bag key, so the 422 message renders once under the field — see FormRoot's canonical server-validation composition (FormRoot + FormErrors + AlertMutationFeedback renders a 422 exactly once).",
+    "CANONICAL BOOLEAN FIELD (gh#709, antd `Form.Item valuePropName=\"checked\"`): `<FormFieldControl name=\"is_shared\" valuePropName=\"checked\">{(field) => <Checkbox {...field}>プロジェクトに共有する</Checkbox>}</FormFieldControl>` — box and label on ONE line, the label text toggles the box and names it, no label row above it, and a validation / 422 error still lands on the checkbox (`aria-invalid` + `aria-describedby`). The bag is `{ id, name, checked, onCheckedChange, onBlur, ref, disabled? }`; the stored value is always a boolean.",
+    "DON'T put a boolean field's label ABOVE its checkbox — `<FormFieldControl name=\"is_shared\" label=\"プロジェクトに共有する\">{(field) => <Checkbox checked={field.value} onCheckedChange={(c) => field.onChange(c === true)} />}</FormFieldControl>` renders the label on one row and the box far below it. Use `valuePropName=\"checked\"` with the label as the Checkbox's children."
+  ],
+  "useCases": [
+    "Validated settings forms",
+    "Nested repeating data entry"
+  ]
+}

package/agent/components/FormRoot.json

@@ -0,0 +1,122 @@
+{
+  "docPath": "docs/data-entry/form-root.tsx",
+  "example": "import { FormRoot, FormFieldControl, useZodForm } from \"@godxjp/ui/form\";\nimport { Input } from \"@godxjp/ui/data-entry\";\nimport { z } from \"zod\";\nconst schema = z.object({ email: z.string().email() });\n// Inside your component:\nconst form = useZodForm(schema, { defaultValues: { email: \"\" } });\n<FormRoot form={form} onSubmit={save} layout=\"horizontal\"><FormFieldControl name=\"email\" label=\"Email\">{field => <Input {...field} value={String(field.value ?? \"\")} />}</FormFieldControl></FormRoot>;",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/form",
+  "name": "FormRoot",
+  "props": [
+    {
+      "description": "RHF form returned by useZodForm; use either form or adapter.",
+      "name": "form",
+      "type": "UseFormReturn<T>"
+    },
+    {
+      "description": "External store with getValue/setValue/getError/getValues/isSubmitting and optional reset.",
+      "name": "adapter",
+      "type": "FormStateAdapter"
+    },
+    {
+      "description": "Validated submit callback.",
+      "name": "onSubmit",
+      "type": "(values: T) => void | Promise<void>"
+    },
+    {
+      "description": "Validation failure callback.",
+      "name": "onSubmitFailed",
+      "type": "(errors: FieldErrors<T>) => void"
+    },
+    {
+      "description": "Handle rejected submission.",
+      "name": "onSubmitError",
+      "type": "(error: unknown) => void"
+    },
+    {
+      "description": "Banner shown when onSubmit rejects. Default: localized dataEntry.form.submitFailed text; a node replaces it; false never shows it. Skipped by default for a validation rejection (400/422) once the `errors` bag holds a message.",
+      "name": "submitFailedMessage",
+      "type": "ReactNode | false"
+    },
+    {
+      "description": "Called after values reset.",
+      "name": "onReset",
+      "type": "() => void"
+    },
+    {
+      "description": "Scroll the first invalid field into view.",
+      "name": "scrollToFirstError",
+      "type": "boolean"
+    },
+    {
+      "description": "Disable field mutations.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Shared Form layout.",
+      "name": "layout",
+      "type": "FormLayoutProp"
+    },
+    {
+      "description": "Shared label width.",
+      "name": "labelWidth",
+      "type": "WidthProp"
+    },
+    {
+      "description": "Shared control width.",
+      "name": "controlWidth",
+      "type": "WidthProp"
+    },
+    {
+      "description": "Shared label alignment.",
+      "name": "labelAlign",
+      "type": "\"start\" | \"end\""
+    },
+    {
+      "description": "Responsive stacking breakpoint.",
+      "name": "collapseBelow",
+      "type": "BreakpointProp | false"
+    },
+    {
+      "description": "Control density.",
+      "name": "density",
+      "type": "DensityProp"
+    },
+    {
+      "description": "Server error bag.",
+      "name": "errors",
+      "type": "ErrorBagProp"
+    },
+    {
+      "description": "Required/optional marking policy.",
+      "name": "requiredMark",
+      "type": "boolean | \"optional\""
+    },
+    {
+      "description": "Responsive field grid rendered inside the form element.",
+      "name": "columns",
+      "type": "ResponsiveGridColumnsProp"
+    }
+  ],
+  "related": [
+    "Form",
+    "FormField",
+    "FormRoot",
+    "FormFieldControl"
+  ],
+  "rules": [
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Form.stories.tsx",
+  "tagline": "Client or server-adapted forms with shared layout, validation, submission, reset and error recovery.",
+  "usage": [
+    "Use inside the documented form composition; do not nest native form elements.",
+    "Use godx-ui controls and preserve field names, errors and disabled state.",
+    "SUBMIT-FAILED BANNER: when `onSubmit` rejects, FormRoot shows a destructive banner (`submitFailedMessage`, default the localized `dataEntry.form.submitFailed`). It is SKIPPED for a validation rejection (`classifyQueryError(error).category === \"validation\"`: 400/422) once the `errors` bag holds at least one message — the fields / `<FormErrors />` show it, as antd shows field errors instead of a form banner — and stays skipped for that failure if the app later clears the bag. A validation rejection with an empty or message-less bag, and every 5xx / network / unknown rejection, still shows it, so a failure is never silently swallowed. Errors mapped with react-hook-form `setError` instead of `errors` are not detected: pass `submitFailedMessage={false}` there. `submitFailedMessage={false}` never shows the banner; a node replaces its text.",
+    "CANONICAL SERVER-VALIDATION FORM (gh#698) — a 422 renders EXACTLY ONCE: `const m = useMutation({ mutationFn: save }); <FormRoot form={form} onSubmit={(v) => m.mutateAsync(v)} errors={serverErrors(m.error)}><FormErrors /><AlertMutationFeedback mutation={m} /><FormFieldControl name=\"code\" label=\"Code\">{(field) => <Input {...field} value={String(field.value ?? \"\")} />}</FormFieldControl></FormRoot>` (`serverErrors` = your API client's mapper from its error to the Laravel-style `{ key: string[] }` bag). Each message appears once: under its field (claimed key) or in `<FormErrors />` (unclaimed key); `AlertMutationFeedback` skips the validation error (gh#690) and FormRoot shows no `submitFailed` banner. A 5xx / network rejection still shows both the FormRoot banner and the AlertMutationFeedback alert — pass `submitFailedMessage={false}` to keep only the latter.",
+    "DON'T hand-guard the banner or wrap `mutateAsync` in try/catch just to hide a 422 — pass the bag to `errors` and the form renders it once."
+  ],
+  "useCases": [
+    "Validated settings forms",
+    "Nested repeating data entry"
+  ]
+}

package/agent/components/Heading.json

@@ -0,0 +1,61 @@
+{
+  "example": "import { Heading } from \"@godxjp/ui/general\";\n\n<Heading level={2}>請求書一覧</Heading>\n<Heading level={3} tone=\"muted\">補足セクション</Heading>\n<Heading level={1} size=\"5xl\" align=\"center\">Ship it everywhere</Heading>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Heading",
+  "props": [
+    {
+      "defaultValue": "medium",
+      "description": "Độ đậm theo canon 3 bậc (400 · 500 · 700). Đặt `bold` cho tiêu đề cần nhấn.",
+      "name": "weight",
+      "type": "\"regular\" | \"medium\" | \"bold\""
+    },
+    {
+      "defaultValue": "2",
+      "description": "Heading level — renders the matching <h*> and, unless `size` overrides it, sizes from --heading-h{1..4}.",
+      "name": "level",
+      "type": "1 | 2 | 3 | 4"
+    },
+    {
+      "description": "Visual size, overriding the step `level` would have taken — the SAME ladder `Text size` reads. `level` still owns the document outline, so a marketing hero is `<Heading level={1} size=\"5xl\">`: a real <h1> at 54px, with no admin screen's <h1> moving. Omit it and `level` decides, exactly as before. Use this INSTEAD of a bespoke `.display` class with a raw font-size.",
+      "name": "size",
+      "type": "\"2xs\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | \"3xl\" | \"4xl\" | \"5xl\""
+    },
+    {
+      "description": "Override the rendered element (e.g. a visual h2 that is a real <h1>).",
+      "name": "as",
+      "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"div\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Semantic foreground colour.",
+      "name": "tone",
+      "type": "\"default\" | \"muted\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"inherit\""
+    },
+    {
+      "description": "Logical text alignment.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "description": "Single-line ellipsis.",
+      "name": "truncate",
+      "type": "boolean"
+    }
+  ],
+  "rules": [
+    6,
+    23
+  ],
+  "storyPath": "general/typography.tsx",
+  "tagline": "Section heading sized from the --heading-h* tokens. `level` sets the size AND the semantic <h1..h4>; `size` overrides the size alone, and its top three steps are the display ramp a marketing hero needs.",
+  "usage": [
+    "DO use `<Heading level>` for section titles instead of a raw `<h2 className=\"text-lg font-semibold\">`. The level drives both the token size and the semantic element.",
+    "Inside a Card use `<CardTitle>`; use `<Heading>` for free-standing page/section headings not covered by a component slot."
+  ],
+  "useCases": [
+    "A section heading on a dashboard: `<Heading level={3}>今月のKPI</Heading>`.",
+    "A visually-smaller heading that must stay an <h1> for a11y: `<Heading level={1} as=\"h1\">…</Heading>`.",
+    "A marketing hero headline: `<Heading level={1} size=\"5xl\">` — a real <h1> on the display ramp, instead of a page-local `.display` class."
+  ]
+}

package/agent/components/HoverCard.json

@@ -0,0 +1,55 @@
+{
+  "example": "import { HoverCard, HoverCardTrigger, HoverCardContent } from \"@godxjp/ui/data-display\";\n\n<HoverCard>\n  <HoverCardTrigger>@yamada</HoverCardTrigger>\n  <HoverCardContent>山田太郎 — 経理部</HoverCardContent>\n</HoverCard>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "HoverCard",
+  "props": [
+    {
+      "defaultValue": "700",
+      "description": "ms before opening on hover.",
+      "name": "openDelay",
+      "type": "number"
+    },
+    {
+      "defaultValue": "300",
+      "description": "ms before closing.",
+      "name": "closeDelay",
+      "type": "number"
+    },
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state callback.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    }
+  ],
+  "related": [
+    "Tooltip (short text label, not rich content)",
+    "Popover (click-triggered, interactive content)"
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "data-display/HoverCard.stories.tsx",
+  "subParts": [
+    "HoverCardContent",
+    "HoverCardTrigger"
+  ],
+  "tagline": "Radix hover card — a rich popover shown on hover/focus of a trigger (for sighted-pointer affordances; not a replacement for Tooltip's short text).",
+  "usage": [
+    "DO compose HoverCard > HoverCardTrigger > HoverCardContent.",
+    "DO use for RICH preview content (a card, avatar + bio); for short plain-text hints use Tooltip.",
+    "DON'T rely on it for essential info — hover isn't available on touch; provide the same content on click/tap elsewhere."
+  ],
+  "useCases": [
+    "User/profile preview on @mention hover",
+    "Entity preview (customer/account) on a table cell",
+    "Glossary term definitions",
+    "Commit/PR preview links"
+  ]
+}

package/agent/components/Icon.json

@@ -0,0 +1,60 @@
+{
+  "example": "import { Lock, ShieldCheck } from \"lucide-react\";\nimport { Icon, Text } from \"@godxjp/ui/general\";\n\n// decorative — aria-hidden, on the same step as the text beside it\n<Text size=\"sm\">\n  <Icon as={Lock} size=\"sm\" tone=\"muted\" /> {t(\"invoice.encrypted\")}\n</Text>\n\n// the glyph IS the value — give it a name\n<Icon as={ShieldCheck} size=\"md\" tone=\"success\" label={t(\"session.secure\")} />",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Icon",
+  "props": [
+    {
+      "description": "The glyph COMPONENT — `as={Lock}`, not `<Lock />`. Every lucide-react icon qualifies. Icon renders ONTO it (the sized element is the <svg> itself), so no wrapper box enters the row and Button's own `svg` rule still sees a direct svg child.",
+      "name": "as",
+      "required": true,
+      "type": "ComponentType<SVGProps<SVGSVGElement> & RefAttributes<SVGSVGElement>>"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Step of the nine-step icon scale (10/12/14/16/20/24/36/40/48px at a 16px root — docs/TOKENS.md). NOT the four-step control SizeProp: a glyph beside 2xs caption text and a 48px empty-state mark are the same primitive. An explicit step OUT-RANKS the context rules, so `size=\"lg\"` inside a Button renders at 20px, not the button's 16px.",
+      "name": "size",
+      "type": "\"2xs\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | \"3xl\" | \"4xl\""
+    },
+    {
+      "description": "Semantic colour intent, the SAME vocabulary Text uses (a status glyph reads the AA-safe --text-warning, never the --warning fill role). Omitted by default, and that default is load-bearing: a glyph inherits currentColor, so an Icon inside a Button, a Badge or a toned Text paints in that surface's own ink without being told.",
+      "name": "tone",
+      "type": "\"default\" | \"muted\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"inherit\""
+    },
+    {
+      "description": "Accessible NAME, for a glyph that is the only thing saying what it says (a lock in a status cell with no text beside it). Supplying it renders role=\"img\" + aria-label; leaving it off (the default) renders aria-hidden, which is correct for a glyph beside a visible label. Consumer-owned copy — route it through your t().",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "Merged onto the glyph. NOT the place to size it — the sizing rule is (0,3,1) and deliberately out-ranks a utility, so pass `size` instead.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Button / DropdownMenuItem / TopbarItem / ListRow — the four contexts that size a glyph for you. Inside them a bare glyph is already correct; reach for Icon there only when you want a DIFFERENT step.",
+    "Text — shares the `tone` vocabulary, and is the usual thing an Icon sits beside. Match the icon step to the text step (`size=\"sm\"` beside `Text size=\"sm\"`).",
+    "Logo — a brand mark, not a glyph: it has its own sizes and its own tone axis.",
+    "Avatar — a person or an entity, not an icon; it brings its own box and must not be squeezed into an icon measure."
+  ],
+  "rules": [],
+  "storyPath": "general/Icon.stories.tsx",
+  "tagline": "A glyph on the --icon-size-* scale, and the ONLY supported way to render a standalone one. A lucide component ships width=\"24\" height=\"24\"; only four rules in this library override that (.ui-button svg, the menu row, the topbar cell, the ListRow leading slot), so everywhere else a glyph draws at 24px beside 14px text.",
+  "usage": [
+    "DO use <Icon> for ANY glyph that is not already inside Button / DropdownMenuItem / TopbarItem / a ListRow leading slot — in a Text, a table cell, an <a>, a Flex. Those four are the only contexts in the library that size a glyph for you; everywhere else a bare lucide icon renders at 24px.",
+    "DO NOT reach for `className=\"size-4\"` or `w-[16px]` — docs/CONSUMER-RULES.md §3/§8 forbid them, and they re-derive a metric the theme owns. DO NOT pass lucide's own `size={16}` either: that is a literal where the design system has a scale.",
+    "DO leave `label` off for a decorative glyph beside a visible label — Icon is aria-hidden by default, which is what WCAG 2.2 SC 1.1.1 asks for. Announcing the same thing twice is the usual defect.",
+    "DO pass a localized `label` when the glyph carries meaning nothing else on screen says (a lock alone in a status column). It becomes role=\"img\" + that name.",
+    "DO leave `tone` unset inside a Button, a Badge or a coloured surface, so the glyph inherits that surface's ink. Set it only when the glyph carries its own status meaning.",
+    "DO retune the SCALE from the theme (`--icon-size-sm`, `--icon-size-lg`, …) rather than per call site; a single instance that genuinely sits off the scale sets `--icon-glyph-size` inline (tier 2, docs/TOKENS.md).",
+    "DO NOT wrap the glyph in a <span> to size it — a wrapper adds a box to every flex row that holds an icon, and it puts an element between Button and the svg its own rule targets."
+  ],
+  "useCases": [
+    "A status glyph inline with 14px body text: `<Text size=\"sm\"><Icon as={Lock} size=\"sm\" tone=\"muted\" /> 暗号化済み</Text>`.",
+    "A lock/unlock column in a table, where the glyph IS the value: `<Icon as={Lock} size=\"sm\" label={t('row.locked')} />`.",
+    "A glyph that must be bigger than the control around it: `<Button><Icon as={Download} size=\"lg\" />…</Button>`.",
+    "An icon inside a breakpoint wrapper (`<Flex hideBelow=\"sm\"><Icon as={Building2} size=\"lg\" /></Flex>`), where a direct-child rule can no longer reach it.",
+    "An external-link marker at the end of a link: `<Icon as={ArrowUpRight} size=\"sm\" />`."
+  ]
+}