@godxjp/ui 19.6.0 → 20.1.0

package/docs/DESIGN-AUTHORITY.md

@@ -17,9 +17,9 @@ It changes no code by itself. It is the tie-breaker a reviewer points at.
 | Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                              | already followed — 33 references in `src/`                                                                                        |
 | Behaviour primitives                                               | **Radix**                                     | already the implementation — 193 references                                                                                       |
 | Component composition shape                                        | **shadcn**                                    | already the structural convention — 23 references                                                                                 |
-| Component taxonomy / grouping                                      | **Ant Design** groups                         | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general`                            |
+| Component taxonomy / grouping                                      | **Ant Design** groups                         | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed |
 | Colour foundation                                                  | **SmartHR**                                   | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER               |
-| **Derived colour — every step computed from a seed**                | **Ant Design (the algorithm itself)**         | **NEW — this decision.** antd is no longer a shape reference here: `scripts/gen-antd-tokens.mjs` runs `theme.getDesignToken()` at build time and emits the derived map |
+| **Derived colour — the interaction states hanging off each seed**    | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold — see below |
 | **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                   | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves |
 | **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency) | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                       |
 | **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                | **NEW — this decision**                                                                                                           |
@@ -187,70 +187,131 @@ Recorded rather than silently fixed, because each is a real decision:
    strokes blur far more visibly than Latin letterforms. Another reason to prefer Carbon's integer
    steps if the scale is ever revisited.
 
-## Derived colour is GENERATED, not authored
-
-**The problem this fixes.** The library hand-authored roughly a thousand tokens and reasoned about
-each one. A hover step was chosen by eye, an active step was chosen by eye, a focus-halo alpha was
-chosen by eye and then justified in a paragraph. Every one of those is a decision with no outside
-authority behind it, and every one has to be re-argued the next time somebody looks at it.
-
-**Ant Design already solves this exactly once**: a SEED colour goes in, an ALGORITHM runs, and the
-whole derived map falls out. This document already named antd as the authority for component
-taxonomy and focus shape; that is now extended to make antd the **generator** of derived colour.
-
-`scripts/gen-antd-tokens.mjs` reads the seeds out of `src/tokens/foundation.css`, runs antd 6.6.2's
-own `theme.getDesignToken()` (`defaultAlgorithm` for light, `darkAlgorithm` for dark) and writes
-`src/tokens/antd.generated.css`. `pnpm check:antd-tokens` fails CI if that file drifts from the
-algorithm. **antd is a devDependency and a build-time tool only** — `pnpm check:no-antd-runtime`
-asserts it never reaches `dependencies`, `src/`, or `dist/`.
-
-**What is authored:** five brand colours per theme (SmartHR MAIN plus four 和色, and the lifted dark
-ramp). **What is computed:** `--primary-hover`, `--primary-active`, `--primary-border`,
-`--destructive-hover`, `--destructive-active`, `--control-outline*` and `--ring`.
-
-**What is deliberately NOT taken from antd, and why — each a measurement, not a preference:**
+## The PROP SURFACE of a component is antd's too, not just its group name
+
+antd was already the authority for which components exist and which group they live in. That
+answered "is there a Table" and never answered "what does a Table take". So every prop was decided
+here, one at a time, and the answer drifted per component: `DataTable` grew `pin: "end"` where antd
+has `fixed`, `sortable: true` where antd has `sorter`, and no answer at all for filters, expandable
+rows or a totals row — which is how a consumer ends up hand-rolling a `<tfoot>` and a sticky column
+in page CSS.
+
+**The rule: where antd names a capability, this library takes antd's name and antd's semantics.**
+The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`,
+`antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never
+from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour
+of `start` inside rc-table itself).
+
+> Đọc sau 20.0.0: bản major ấy đã **gỡ `antd` khỏi devDependencies** cùng máy sinh màu của nó, và
+> `check:no-antd-runtime` canh cho nó không quay lại. Câu trên mô tả cách bề mặt prop này ĐƯỢC ĐỌC
+> lúc antd còn cài, không phải một lời mời cài lại. Lần sau muốn đối chiếu, đọc type ở một checkout
+> riêng rồi ghi số hiệu bản vào đây — đừng thêm dependency.
+
+**Three things override antd's spelling, each for a stated reason:**
+
+- **Logical over physical.** antd's `fixed: 'left' | 'right'` cannot mirror for an RTL locale, so
+  only `start` / `end` are published. Same rule that makes `check:rtl` a gate.
+- **This library's controlled vocabulary wins on values.** antd's `SortOrder` is
+  `'ascend' | 'descend'`; here it stays `SortDirectionProp` (`asc` / `desc`), because that type
+  already exists and a second spelling of the same axis is exactly what `check:prop-vocabulary`
+  exists to prevent.
+- **A capability this library already has keeps its own name.** antd's `size`
+  (`small | middle | large`) IS `density` (`compact | default | comfortable`); antd's `locale` IS
+  the `t()` layer. Adding the antd spelling as an alias would be duplication, not parity.
+
+**A knob that only a fork could reach is not parity either.** antd's `components`,
+`filterDropdown`, `classNames`/`styles` semantic maps and `prefixCls` all exist to let a consumer
+replace the rendered markup. This library answers that layer with tokens (cardinal rule #45), so
+those are deliberately NOT adopted — adopting them would re-open the hole the token tiers close.
+
+## Derived colour is AUTHORED, and MEASUREMENT is what makes it authoritative
+
+**Twenty values, in `src/tokens/derived.css`:** `--primary-hover`, `--primary-active`,
+`--primary-border`, `--destructive-hover`, `--destructive-active`, `--control-outline` and its
+alpha, `--control-outline-error` and its alpha, and `--ring` — each in both themes. They are the
+interaction states that hang off the five authored seeds per theme (SmartHR MAIN plus four 和色,
+and the lifted dark ramp), which stay in `src/tokens/foundation.css`.
+
+**These twenty were once generated.** A colour algorithm ran at build time, took the seeds and
+emitted the derived map; the authority behind each value was "the algorithm said so". That
+generator has been removed and its dependency with it. The values did not change — but the reason
+to trust them had to.
+
+**The authority is now the measurement, not the derivation.** Four suites read `derived.css`
+directly and hold every value in it to a threshold this repo has already committed to:
+
+| suite                                                   | what it holds                                                                                                                                                        |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tokens/__tests__/focus-ring-contrast.test.ts`       | the focus mark in both switch positions — ≥3:1 (WCAG 2.2 SC 1.4.11) on every surface a control sits on, and the halo proven to be decoration rather than the indicator |
+| `src/tokens/__tests__/interactive-fill-contrast.test.ts` | an interactive fill must clear **4.5:1** against the label sitting on it                                                                                              |
+| `src/tokens/__tests__/destructive-contrast.test.ts`      | `--destructive-hover` / `--destructive-active` against the same bar                                                                                                  |
+| `src/lib/__tests__/theme-tokens-css.test.ts`             | the tier is actually loaded, and complete in both themes                                                                                                             |
+
+The first three also pin each value as a literal, so an edit to `derived.css` alone turns CI red
+rather than quietly retinting the library. **That is a stronger claim than the generator made, not
+a weaker one.** An algorithm guarantees a value is _consistent_; this repo had to override it four
+times (below) precisely because consistent is not the same as _accessible_. A threshold guarantees
+the property actually being sold.
+
+**To change a derived value:** change it, run `pnpm test`, and if a threshold breaks the value is
+wrong. Do not relax the threshold.
+
+**The four overrides that existed even while a generator did** — the clearest evidence the
+algorithm was never the real authority. Stepping an interactive fill towards the label sitting on
+it lands under 4.5:1, so those four states take the same ramp at the same step size in the
+opposite direction:
+
+| token                    | conventional step | shipped           |
+| ------------------------ | ----------------- | ----------------- |
+| light `--primary-hover`  | #208bc9 · 3.69:1  | #005596 · 7.53:1  |
+| light `--primary-active` | #005596 · 7.53:1  | #003c70 · 10.97:1 |
+| dark `--primary-hover`   | #61b6e8 · 7.92:1  | #61b6e8 · 7.92:1  |
+| dark `--primary-active`  | #2f76a6 · 3.60:1  | #8bd0f3 · 10.50:1 |
+
+**What was deliberately never derived, and why — each a measurement, not a preference:**
 
 - **The neutral spine.** Colour foundation stays SmartHR's (see the table above); the neutrals are
-  not derived from the brand seed. `colorBorder` is also the only role antd offers for a control
-  boundary and it measures **1.43:1** on the page, where `--input` is held to 3:1 by SC 1.4.11 and
-  by `input-boundary-contrast.test.ts`.
-- **The text ramp.** antd's is alpha-based (`rgba(0,0,0,0.88)`), which cannot enter this library's
-  opaque `H S% L%` triple without choosing a surface to composite against — lossy by construction.
-- **The dark `--primary` itself.** `darkAlgorithm` MOVES the seed (antd's own `#1677ff` becomes
-  `#1668dc`). Feeding this library's light seed in gives `#0363a4` at **2.81:1** on the dark spine,
-  which `primary-text-contrast.test.ts` rejects outright; antd's transform of the committed dark
-  seed gives `#3794d3` at 5.36:1 where the seed itself measures 7.07:1. The dark theme therefore
-  keeps its seed and everything derived from it is antd's. This is the one structural divergence,
-  recorded in `DIVERGENCES` in the generator.
-
-**Geometry antd owns was already correct.** `lineWidth` 1, `controlOutlineWidth` 2,
-`lineWidthFocus` 3, `borderRadius` 6, `controlHeight` 32 and `fontSize` 14 all match the named
-scales this library already ships (`--stroke-*`, `--radius`, `--band-height-md`,
-`--font-size-base`). The generator asserts that agreement rather than emitting a second copy, so
-the two cannot drift apart silently.
-
-## Focus appearance — Ant Design owns the shape, and the indicator SHIPS OFF
-
-### The two forms, read from antd's source
+  not derived from the brand seed. The one derived role on offer for a control boundary measures
+  **1.43:1** on the page, where `--input` is held to 3:1 by SC 1.4.11 and by
+  `input-boundary-contrast.test.ts`.
+- **The text ramp.** The derived one is alpha-based (`rgba(0,0,0,0.88)`), which cannot enter this
+  library's opaque `H S% L%` triple without choosing a surface to composite against — lossy by
+  construction.
+- **The dark `--primary` itself.** A mechanical dark derivation MOVES the seed. Deriving from this
+  library's light seed gives `#0363a4` at **2.81:1** on the dark spine, which
+  `primary-text-contrast.test.ts` rejects outright; deriving from the committed dark seed gives
+  `#3794d3` at 5.36:1, where the seed itself measures 7.07:1. The dark theme therefore keeps its
+  own seed — recorded, with the measurement, in `focus-ring-contrast.test.ts`.
+
+**The focus geometry was already on the named scale.** Border 1, halo width 2, heavy outline 3,
+radius 6, control height 32 and font size 14 all match scales this library already ships
+(`--stroke-*`, `--radius`, `--band-height-md`, `--font-size-base`), so the focus tokens bind to
+those steps instead of restating a second copy of the number.
+
+**antd itself is gone from this repository**, and `pnpm check:no-antd-runtime` is what keeps it
+gone: it fails if antd or any `@ant-design/*` package appears in any manifest field, is imported
+anywhere in `src/`, or leaves a trace in `dist/`. Deleting that gate re-opens the door it closes.
+
+## Focus appearance — a two-form convention, and the indicator SHIPS OFF
+
+### The two forms
 
 **SmartHR** (`smarthr-ui@99.6.0`) draws focus as an opaque ring held off the control by a white
-spacer. **Ant Design** (`antd@6.6.2`) has two forms instead:
-
-- **Field** — `borderColor: colorPrimary` at the unchanged `lineWidth`, plus
-  `boxShadow: 0 0 0 ${controlOutlineWidth}px ${controlOutline}`
-  (`es/input/style/token.js:48-50`). `es/select/style/select-input.js:32` emits the same
-  declarations, which is why an antd Select focuses exactly like an antd Input.
-- **Non-field** — `genFocusOutline` (`es/style/index.js:60-64`):
-  `outline: ${lineWidthFocus}px solid ${colorPrimaryBorder}; outline-offset: 1`.
-
-**v5 → v6 changed none of this.** Both majors were unpacked and their own `formatToken` run side by
-side; every value is identical to the digit in `antd@5.29.3`.
-
-**Ant Design wins the shape.** The library shipped an opaque brand ring drawn immediately outside an
-untouched grey border — two outlines of different colours claiming the same edge — and a Select that
-could not be told to agree with an Input. antd's rule resolves both. SmartHR still owns the hue: the
-focus colour is `--ring`, which the generated tier declares as `var(--primary)` because antd has no
-separate focus-colour token at all.
+spacer. This library takes a different, two-form convention instead — widely used in enterprise
+component libraries, and surveyed across several before it was adopted here:
+
+- **Field** — the boundary RECOLOURS to the primary at its unchanged hairline width, plus
+  `box-shadow: 0 0 0 var(--control-outline-width) var(--control-outline)`. A Select emits the same
+  declarations as an Input, which is why the two focus identically.
+- **Non-field** — an outline outside the box model:
+  `outline: var(--focus-outline-weight) solid var(--primary-border); outline-offset: 1px`.
+
+**Why this shape wins.** The library previously shipped an opaque brand ring drawn immediately
+outside an untouched grey border — two outlines of different colours claiming the same edge — and a
+Select that could not be told to agree with an Input. Recolouring the existing boundary rather than
+adding a second one resolves both. SmartHR still owns the hue: the focus colour is `--ring`, which
+the derived tier declares as `var(--primary)`, because a focused field takes the primary rather than
+a focus colour of its own.
 
 ### The indicator ships OFF. That forfeits WCAG 2.4.7 and a JIS X 8341-3 AA claim.
 
@@ -269,18 +330,18 @@ owner chose to ship it off and let whoever needs it turn it on. What that costs,
 **Turning it back on is one attribute, on the root element, with no code change:**
 
 ```html
-<html data-focus-outline="on">
+<html data-focus-outline="on"></html>
 ```
 
-**The switch is antd's own mechanism, not one invented here.** antd 6.6.2 carries a `focusOutline`
-seed flag (`es/theme/themes/seed.js:67`) and consumes it in `es/theme/util/alias.js:71`:
+**The switch is a single multiplier, not a scatter of overrides.** `--focus-outline` is one flag,
+and every painted focus length multiplies by it:
 
-```js
-lineWidthFocus: mergedToken.focusOutline === false ? 0 : mergedToken.lineWidth * 3
+```css
+--focus-ring-width: calc(var(--focus-ring-weight) * var(--focus-outline));
 ```
 
-The flag zeroes the focus line width. `--focus-outline` is that flag in CSS: every painted length
-multiplies by it, so no component rebind can bring the mark back while it is `0`. The two paints
+Setting it to `0` zeroes every focus length at once, so no component rebind can bring the mark back
+while it is off — which is the property a scatter of per-component overrides could never give. The two paints
 that are not lengths — the halo and a field's recoloured boundary — are scoped to the same attribute
 in `styles/focus-ring.css`. **Every `:focus-visible` selector stays exactly where it is**; only the
 painted result disappears.
@@ -288,18 +349,18 @@ painted result disappears.
 ### The ON state is the LIGHT one
 
 The complaint was weight, not existence, so the on-position is not the old mark restored. It paints
-antd's **field** indicator on every control — one `lineWidth` (1px) in the focus hue, plus antd's
-`controlOutline` halo — rather than antd's 3px `genFocusOutline`. Measured, in Chromium, on
+the **field** indicator on every control — one hairline (1px) in the focus hue, plus the
+`--control-outline` halo — rather than the heavy 3px outline form. Measured, in Chromium, on
 `ql.test` after the transition settles:
 
-| control | switch off | switch on |
-| --- | --- | --- |
-| Input / Select trigger | border `1px rgb(144,135,127)`, resting shadow intact | border `1px rgb(0,113,189)` + `rgba(0,182,228,0.11) 0 0 0 2px` |
-| Button (primary) | outline `0px`, resting shadow intact | `outline: 1px solid rgb(0,113,189)` @ `0px` + same halo |
-| Sidebar nav row / list row | outline `0px` | `outline: 1px solid rgb(0,113,189)` @ **`-1px`** (inset into the row) |
+| control                    | switch off                                           | switch on                                                             |
+| -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| Input / Select trigger     | border `1px rgb(144,135,127)`, resting shadow intact | border `1px rgb(0,113,189)` + `rgba(0,182,228,0.11) 0 0 0 2px`        |
+| Button (primary)           | outline `0px`, resting shadow intact                 | `outline: 1px solid rgb(0,113,189)` @ `0px` + same halo               |
+| Sidebar nav row / list row | outline `0px`                                        | `outline: 1px solid rgb(0,113,189)` @ **`-1px`** (inset into the row) |
 
-The field pair is **byte-identical to antd's own `activeBorderColor` + `activeShadow`** for this
-seed. The nav row insets its mark into its own shape rather than wrapping an already-shaded surface,
+The field pair is the recoloured boundary plus the halo, exactly as the convention specifies for
+this seed. The nav row insets its mark into its own shape rather than wrapping an already-shaded surface,
 which is the specific stacking that read as heavy.
 
 **No control's box moves when it is focused**, measured with `getBoundingClientRect()` before and
@@ -308,11 +369,12 @@ Input, Save and Delete all stay at 32.00px.
 
 **Two criteria, and only one is met by thickness alone.** SC 1.4.11 (AA, non-text contrast) is about
 COLOUR — the 1px mark measures 5.05:1 light and 7.07:1 dark on every surface a control sits on, so
-the light weight costs nothing there. antd's own `colorPrimaryBorder` (#6dc0e3) measures **2.00:1
-light / 1.66:1 dark** and could not have satisfied it at any thickness, which is why the on-state
-takes the focus hue instead — the single place it departs from `genFocusOutline`. SC 2.4.13 Focus
-Appearance (AAA) additionally wants a 2px perimeter; the on-state does not target it, and
-`--focus-outline-weight: var(--stroke-lg)` restores antd's 3px if a customer needs the area clause.
+the light weight costs nothing there. `--primary-border` (#6dc0e3) measures **2.00:1 light /
+1.66:1 dark** and could not have satisfied it at any thickness, which is why the on-state takes the
+focus hue instead — the single place it departs from the outline form. SC 2.4.13 Focus Appearance
+(AAA) additionally wants a 2px perimeter; the on-state does not target it, and
+`--focus-outline-weight: var(--stroke-lg)` restores the 3px weight if a customer needs the area
+clause.
 
 Both positions of the switch are gated in `src/tokens/__tests__/focus-ring-contrast.test.ts`: with
 it off nothing paints and no rebind can route around it, with it on the geometry and the ≥3:1

package/docs/DEVELOPMENT.md

@@ -117,13 +117,14 @@ A change isn't done until its documentation reflects it:
 ```bash
 pnpm lint                 # eslint — self-contained flat config
 pnpm typecheck            # tsc --noEmit
-pnpm test                 # vitest per component
-pnpm preview:build        # integration test: examples + docs must build
+pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2   # ONLY what you touched
+pnpm test                 # FULL suite — CI only, never from an agent loop
+pnpm preview:build        # integration test: examples + docs must build — at most once, pre-PR
 pnpm audit                # godxjp-ui-audit — 0 errors for touched files
 pnpm check:mcp-sync       # MCP registry ↔ library export drift guard
 ```
 
-`pnpm verify` and `pnpm verify:release` run these together (verify:release also builds). It needs `pnpm exec playwright install chromium` once locally; see [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md) for how to run/scope it, read the evidence, and regenerate its baseline after an accessibility fix.
+`pnpm verify` and `pnpm verify:release` run these together (verify:release also builds) — **both include the full suite, so both belong to CI.** Locally, run them at most once immediately before opening a PR, never inside an edit loop and never while other agents are working on the same machine. It needs `pnpm exec playwright install chromium` once locally; see [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md) for how to run/scope it, read the evidence, and regenerate its baseline after an accessibility fix.
 
 All gates are **self-contained** — no internal/external tooling package required. The eslint, prettier, and vitest setup live in the package (`eslint.config.js`, `prettier.config.mjs`, `vitest.config.ts`, `src/test/`), so a fresh checkout can lint/type-check/test without anything beyond the declared devDependencies.
 

package/docs/FORMS.md

@@ -44,11 +44,127 @@ export function CreateCustomerForm({ onSubmit }: { onSubmit: (v: Values) => void
 
 ## API
 
-| Export             | Prop type                                 | Purpose                                |
-| ------------------ | ----------------------------------------- | -------------------------------------- |
-| `useZodForm`       | `ZodSchemaProp` + `UseZodFormOptionsProp` | Hook — injects zodResolver             |
-| `FormRoot`         | `FormRootProp`                            | FormProvider + `<form onSubmit>`       |
-| `FormFieldControl` | `FormFieldControlProp`                    | Controller + FormField + error display |
+| Export              | Prop type                                 | Purpose                                       |
+| ------------------- | ----------------------------------------- | --------------------------------------------- |
+| `useZodForm`        | `ZodSchemaProp` + `UseZodFormOptionsProp` | Hook — injects zodResolver                    |
+| `FormRoot`          | `FormRootProp`                            | FormProvider + `<form onSubmit>` + layout     |
+| `FormFieldControl`  | `FormFieldControlProp`                    | Controller + FormField + error display        |
+| `FormFieldArray`    | `FormFieldArrayProp`                      | Repeating rows on RHF's `useFieldArray`       |
+| `useFormWatch`      | —                                         | Subscribe to one field (antd `Form.useWatch`) |
+| `useFormInstance`   | —                                         | The RHF instance, without prop-drilling       |
+| `useFormSubmitting` | —                                         | Submit in flight (both paths)                 |
+| `useFormDisabled`   | —                                         | Form-level `disabled`, for the action row     |
+
+### `FormRoot` — form-level knobs
+
+`onSubmit` runs only after validation passes (antd `onFinish`). Everything else is optional:
+
+| Prop                                                              | antd                    | Notes                                                                                    |
+| ----------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
+| `onSubmitFailed(errors)`                                          | `onFinishFailed`        | RHF error tree; the first invalid field is focused regardless                            |
+| `onSubmitError(error)`                                            | —                       | Optional error callback; rejected submissions show localized feedback and retain values  |
+| `onReset`                                                         | —                       | A native `<Button type="reset">` restores `defaultValues`; this runs after               |
+| `scrollToFirstError`                                              | `scrollToFirstError`    | Default `true`; centres the field row, honours `prefers-reduced-motion`                  |
+| `disabled`                                                        | Form `disabled`         | Disables fields and submission; values remain in state. Buttons read `useFormDisabled()` |
+| `layout` `labelWidth` `controlWidth` `labelAlign` `collapseBelow` | `layout` `labelCol` …   | Renders the `Form` layout shell (see the spacing note below)                             |
+| `density` / `requiredMark`                                        | `size` / `requiredMark` | Forwarded to the same shell                                                              |
+| `errors`                                                          | —                       | Server error bag; fields claim their keys, `<FormErrors />` shows the rest               |
+
+> **Spacing.** A bare `FormRoot` stacks its children with `ui-stack-md`. Passing ANY layout prop
+> switches it to the `Form` shell, whose `--form-block-gap` owns the spacing instead — the two are
+> never combined, so a form does not silently gain double gaps when a `layout` is added.
+
+`columns` renders a responsive grid inside the form. Duplicate submissions are ignored until the current attempt settles. Reset returns the form to its defaults.
+
+### `FormFieldControl` — field-level knobs
+
+| Prop                                      | antd                | Notes                                                                |
+| ----------------------------------------- | ------------------- | -------------------------------------------------------------------- |
+| `disabled`                                | Item `disabled`     | Defaults to `FormRoot disabled`; `false` re-enables one field        |
+| `dependencies`                            | `dependencies`      | Re-validate this field when another changes (after the first submit) |
+| `getValueFromEvent`                       | `getValueFromEvent` | Replaces the built-in DOM-event / raw-value detection                |
+| `normalize`                               | `normalize`         | Transform before storing; return `previousValue` to REJECT a change  |
+| `help`                                    | `help`              | Shown instead of the resolved validation message                     |
+| `validateStatus` `hasFeedback` `feedback` | same                | Forwarded to `FormField` — the in-flight remote-check state          |
+| `preserve`                                | `preserve`          | `false` unregisters the value when the field unmounts                |
+
+The binding includes both native `onChange` and godx-ui `onValueChange`; spreading it onto Input, Textarea or Select updates the same store. Native fields do not emit the shared callback twice. IDs are unique across sibling forms. Per-field layout, label/control width, label addons and column spans are forwarded to FormField.
+
+**There is no `rules` prop, by design.** react-hook-form ignores per-field register rules whenever a
+`resolver` is set, and `useZodForm` always sets one — a `rules` prop would silently do nothing.
+antd's `rules` is the Zod schema here, including the cross-field case:
+
+```tsx
+const schema = z
+  .object({ password: z.string().min(8), confirm: z.string() })
+  .refine((v) => v.confirm === v.password, { path: ["confirm"], message: "Mật khẩu không khớp" });
+```
+
+Pair that refinement with `dependencies={["password"]}` on the `confirm` field so editing the
+password re-runs it.
+
+## Dynamic rows — `FormFieldArray` (antd `Form.List`)
+
+`FormFieldArray` is react-hook-form's `useFieldArray`, so rows keep their identity across
+insert/remove/move instead of being re-keyed by index. Each row hands back its dotted path prefix;
+build the child field name from it and nested validation lands on the right row.
+
+```tsx
+import { FormFieldArray, FormFieldControl, FormRoot, useZodForm } from "@godxjp/ui/form";
+
+const schema = z.object({
+  contacts: z.array(z.object({ email: z.string().email() })).min(1, "Cần ít nhất một liên hệ"),
+});
+type Values = z.infer<typeof schema>;
+
+<FormFieldArray<Values, "contacts"> name="contacts">
+  {({ fields, append, remove, move, error, disabled }) => (
+    <>
+      {error && (
+        <Alert tone="destructive">
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+      )}
+      {fields.map((row, position) => (
+        <Card key={row.key} variant="outline">
+          <CardContent>
+            <FormFieldControl<Values> name={`${row.name}.email`} label={`Liên hệ ${position + 1}`}>
+              {(field) => <Input {...field} value={String(field.value ?? "")} />}
+            </FormFieldControl>
+            <Button type="button" variant="destructive" onClick={() => remove(row.index)}>
+              Xoá
+            </Button>
+          </CardContent>
+        </Card>
+      ))}
+      <Button
+        type="button"
+        variant="outline"
+        disabled={disabled}
+        onClick={() => append({ email: "" })}
+      >
+        Thêm liên hệ
+      </Button>
+    </>
+  )}
+</FormFieldArray>;
+```
+
+- `row.key` is RHF's stable id — use it as the React key, **never** the index.
+- `row.index` is the live position; pass it to `remove`/`move`, not the render position.
+- `error` is the ARRAY-level message (a `.min(1)` on the array itself), not a row's.
+- Also available: `prepend`, `insert`, `swap`, `replace`.
+- react-hook-form path only — a server-driven `adapter` owns its own collection state.
+
+## Watching a value — `useFormWatch`
+
+```tsx
+const plan = useFormWatch<Values>("plan"); // one field
+const all = useFormWatch<Values>(); // every value
+```
+
+Returns `unknown` (the same contract as the render-prop `value`) — narrow at the call site. It
+works on BOTH paths: react-hook-form's `useWatch`, or the adapter's `getValue`/`getValues`.
 
 ## Forbidden
 
@@ -108,7 +224,9 @@ const form = useForm({ customer_nm: "", action_mode: "regist" });
 - Never hand-filter the bag per page; that except-list is exactly what this mechanism removes.
 - `FormFieldControl` forwards its `name`, so `FormRoot` + adapter fields claim their keys too;
   give `<FormErrors errors={form.errors} />` the bag explicitly when there is no surrounding
-  `Form errors`.
+  `Form errors` — or pass the bag straight to `FormRoot errors`, which provides the same registry.
+- An adapter may implement the optional `reset()`, which `FormRoot` calls for a native
+  `<Button type="reset">`, so the reset button behaves identically on both paths.
 
 ### Sibling Forms — one bag over several Card+Form sections
 
@@ -141,3 +259,30 @@ import { Form, FormErrors, FormErrorsProvider, FormField, Input } from "@godxjp/
 
 A nested Form **with** its own `errors` starts a new registry that shadows the provider — its
 claims and messages stay inside it (use this for an embedded sub-form with a separate bag).
+
+### Multipart uploads and Inertia visits
+
+For a form that submits files together, use `<Upload name="attachments[]" pastable />`.
+The uploader appends staged local files during the native `formdata` event, including
+files selected by dropping or pasting. Completed media uploads remain the responsibility
+of `collectUploadCommitActions`.
+
+For an endpoint that redirects back after each uploaded file, connect the reusable
+Inertia bridge. Errors retain the local file for retry; removing or cancelling a file
+cancels its visit. Each request runs asynchronously so selecting another file does not
+silently cancel an unrelated upload.
+
+```tsx
+import { inertiaUpload } from "@godxjp/ui/inertia";
+import { Upload } from "@godxjp/ui/data-entry";
+
+<Upload
+  value={items}
+  onValueChange={(next) => setItems(next.filter((item) => item.status !== "done"))}
+  onUpload={inertiaUpload(
+    (file, callbacks) => router.post(uploadUrl, { file }, { ...callbacks, preserveScroll: true }),
+    t("upload.failed"),
+  )}
+  pastable
+/>;
+```

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,16 +3,28 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **129**
-- With ≥1 frame: **129** · zero-frame: **0**
+- Public components: **137**
+- With ≥1 frame: **133** · zero-frame: **4**
 - Fully covered (every contract axis declared): **0**
 
+## UNTESTED — no `/frame/**` route
+
+- [ ] `inertiaUpload`
+- [ ] `CardBar`
+- [ ] `VisuallyHidden`
+- [ ] `RangeTimeline`
+
 ## Per-component contract axes
 
 Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 
 | Component | Frame | visua | state | owner | conte | respo | inter | acces | prefe | async |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| inertiaUpload | **✗** | · | · | · | · | · | · | · | · | · |
+| CardBar | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
+| TimeRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
+| VisuallyHidden | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
+| RangeTimeline | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | PageContainer | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Flex | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | ResponsiveGrid | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
@@ -41,6 +53,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | StatCard | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | ServiceLauncherCard | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Badge | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Legend | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | ListRow | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | CredentialReveal | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | QrCode | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
@@ -54,21 +67,21 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Table | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | DataState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | InfiniteQueryState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
-| Form | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Form | ✓ | ✓ | · | N/A | · | · | · | · | · | · |
 | FormField | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | FormErrors | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Input | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | NumberInput | ✓ | ✓ | · | · | · | · | · | · | · | · |
-| SearchInput | ✓ | N/A | · | · | · | · | · | · | · | · |
+| SearchInput | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Select | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Switch | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Textarea | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Label | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Checkbox | ✓ | N/A | · | · | · | · | · | · | · | · |
 | RadioGroup | ✓ | N/A | · | · | · | · | · | · | · | · |
-| MonthPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
-| MonthRangePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
-| DatePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| MonthPicker | ✓ | · | · | · | · | · | · | · | · | · |
+| MonthRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
+| DatePicker | ✓ | · | · | · | · | · | · | · | · | · |
 | Dialog | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | AlertDialog | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | AlertDialogRoot | ✓ | N/A | N/A | · | · | · | · | · | · | · |
@@ -78,16 +91,16 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | SkeletonTable | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Toaster | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Tabs | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
-| Pagination | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Pagination | ✓ | · | · | · | · | · | · | · | · | · |
 | DropdownMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | Steps | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
 | Toolbar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | AppProvider | ✓ | · | · | · | · | · | · | · | · | · |
 | formatDate | ✓ | · | · | · | · | · | · | · | · | · |
-| TimePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
-| DateRangePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
-| Cascader | ✓ | N/A | · | · | · | · | · | · | · | · |
-| TreeSelect | ✓ | N/A | · | · | · | · | · | · | · | · |
+| TimePicker | ✓ | · | · | · | · | · | · | · | · | · |
+| DateRangePicker | ✓ | · | · | · | · | · | · | · | · | · |
+| Cascader | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| TreeSelect | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | Transfer | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Upload | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | UploadCropDialog | ✓ | · | · | · | · | · | · | · | · | · |
@@ -106,23 +119,24 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Avatar | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Separator | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | Skeleton | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
-| Toggle | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Toggle | ✓ | ✓ | · | N/A | · | · | · | · | · | · |
 | ToggleGroup | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | AspectRatio | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Accordion | ✓ | N/A | · | · | · | · | · | · | · | · |
 | HoverCard | ✓ | N/A | N/A | · | · | · | · | · | · | · |
-| PasswordInput | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| PasswordInput | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | PasswordStrength | ✓ | N/A | N/A | · | · | · | · | · | · | · |
-| InputOTP | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| InputOTP | ✓ | · | · | · | · | · | · | · | · | · |
 | Rating | ✓ | N/A | · | · | · | · | · | · | · | · |
-| Segmented | ✓ | N/A | · | · | · | · | · | · | · | · |
-| TagInput | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Segmented | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| TagInput | ✓ | ✓ | · | · | · | · | · | · | · | · |
 | ContextMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | Menubar | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | NavigationMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | ResizablePanel | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | Carousel | ✓ | N/A | N/A | · | · | · | · | · | · | · |
 | AppSettingPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| AppSettingToggle | ✓ | N/A | · | · | · | · | · | · | · | · |
 | Field | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | LineChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | BarChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
@@ -138,6 +152,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | AuthAccountSummary | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | AuthStack | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | OrgSwitcher | ✓ | N/A | · | · | · | · | · | · | · | · |
+| AppLauncher | ✓ | N/A | · | · | · | · | · | · | · | · |
 | FilterBar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | PermissionMatrix | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | BranchScopePicker | ✓ | N/A | · | · | · | · | · | · | · | · |