@godxjp/ui 20.0.0 → 20.2.0

package/dist/tokens/semantic/layout.css

@@ -18,6 +18,8 @@
   --overlay-z-index: 50;
 
   --master-detail-rail-compact: 18.75rem;
+  --master-detail-rail-narrow: 12rem;
+  --master-detail-rail-wide: 24rem;
   --master-detail-rail-standard: 20rem;
   --master-detail-gap: var(--space-stack-md);
 
@@ -37,6 +39,8 @@
 
   --overlay-background: rgb(0 0 0 / 0.5);
 
+  --surface-recessed: hsl(var(--muted) / 0.4);
+
   --page-footer-pad-block-end: var(--space-stack-md);
   --page-header-divider: none;
 
@@ -80,6 +84,11 @@
   --field-label-gap: var(--space-2);
 }
 
+.dark,
+:root[data-theme="dark"] {
+  --surface-recessed: hsl(var(--background));
+}
+
 :root {
   --admin-collection-control-height: var(--control-height-default);
   --admin-collection-section-gap: var(--space-stack-md);

package/docs/CONSUMER-RULES.md

@@ -12,3 +12,16 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
 9. Logical directions (`ms-`, `me-`, `start-`, `end-`) when a utility is unavoidable; never `ml-` / `left-`.
 10. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs <dir>` before every review; then `visual-audit.mjs <url>` on the running app. Zero errors is the bar.
+
+**Opting a deliberate exception out.** Name the rule; the block form also has to say why.
+
+```tsx
+// ui-audit-disable-line no-physical-direction
+// ui-audit-disable-next-line no-physical-direction
+
+// ui-audit-disable-begin no-utility-spacing — vendor widget ships its own grid, gh#123
+const legacyClasses = ["gap-3", "p-2"];
+// ui-audit-disable-end no-utility-spacing
+```
+
+A block with no reason (or under 12 characters of it) is ignored and the finding stands; an unclosed block runs to the end of the file. The class-shaped rules (`gap-*`, `bg-red-500`, `w-[37px]`, `pr-*`, `dark:*`) only read class expressions — a `className`/`class` attribute, a class-named binding (`baseClass`, `statusStyles`, `badgeVariants`) or a `cn()`/`clsx()`/`cva()` call — so product copy or an i18n value that happens to spell a utility is never a finding.

package/docs/DESIGN-AUTHORITY.md

@@ -187,6 +187,43 @@ 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.
 
+## 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`,
@@ -293,7 +330,7 @@ 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 a single multiplier, not a scatter of overrides.** `--focus-outline` is one flag,
@@ -316,11 +353,11 @@ the **field** indicator on every control — one hairline (1px) in the focus hue
 `--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 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,

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: **131**
-- With ≥1 frame: **131** · 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 | · | · | · | · | · | · |
@@ -55,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 | · | · | · | · | · | · | · |
@@ -79,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 | ✓ | · | · | · | · | · | · | · | · | · |
@@ -112,12 +124,12 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | 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 | · | · | · | · | · | · | · |
@@ -140,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 | · | · | · | · | · | · | · | · |

package/docs/README.md

@@ -20,7 +20,7 @@
 ```bash
 cd packages/ui
 pnpm preview          # http://localhost:6008
-pnpm preview:build    # static site → preview/dist/
+pnpm preview:build    # static site → preview/dist/ — heavy; CI's job, run at most once pre-PR
 ```
 
 ### Preview doc format

package/docs/STANDARDS-vocabulary-tokens.md

@@ -1,6 +1,6 @@
 # Prop Vocabulary + Design Token Standards
 
-These rules are normative for @godxjp/ui 8.0.0. They mirror `debate/props-vocab-token-consistency/04-Decision.md`.
+These rules are normative for @godxjp/ui. They came out of the props-vocabulary / token-consistency debate, whose record lived in `debate/` until that directory was removed — this file is now the normative source, not a mirror of one.
 
 1. Prop vocabulary: every exported `*Prop` type in `src/props/components/` MUST have exactly one `COMPONENT_PROP_REGISTRY` entry.
 2. Prop vocabulary: every public property in an exported component prop type MUST map to one `VOCABULARY_REGISTRY` entry or to a `local: true` registry record with a non-empty `reason`.

package/docs/TESTING.md

@@ -5,10 +5,16 @@ Every component **must** ship with a Vitest suite before merge.
 ## Run
 
 ```bash
-cd packages/ui
-pnpm test              # single run
-pnpm test:watch        # watch mode
-pnpm test:coverage     # v8 coverage report
+# While working — ONLY the tests for what you touched. Tests sit beside the
+# component in `src/components/<group>/__tests__/`, so scope to that folder.
+pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2
+pnpm vitest watch src/components/<group>/__tests__     # watch one component
+
+# CI only — 506 files / 3700+ tests. Do NOT run these from an agent loop or with
+# other agents on the machine: measured 70 vitest workers at load 90, an overheating
+# laptop and a burnt monthly API budget.
+pnpm test              # single run — CI
+pnpm test:coverage     # v8 coverage report — CI
 ```
 
 ## File location
@@ -68,7 +74,7 @@ import "@testing-library/jest-dom/vitest";
 | `react-hooks/set-state-in-effect` | sync setState in effects         |
 | `RenderLoopGuard` in tests        | runaway re-renders during Vitest |
 
-Run `pnpm lint` before `pnpm test` — official React Compiler rules align with test guard.
+Run `pnpm lint` before your scoped test run — official React Compiler rules align with test guard.
 
 ## Forms testing
 
@@ -83,7 +89,10 @@ Never test forms with raw `useState` — mirror production `FormRoot` + `FormFie
 
 ## CI gate
 
-`pnpm test` in `packages/ui` must pass with zero failures before any UI PR merges.
+The full suite must pass with zero failures before any UI PR merges — **and that run belongs
+to CI, not to you.** Locally you run only the tests for the files you changed; CI runs
+everything on the PR. `tal --help` states the same rule for the agent loop: *FULL SUITE KHÔNG
+THUỘC VỀ VÒNG LẶP.*
 
 ## When tests fail
 

package/docs/charts/cjk-category-axis.tsx

@@ -0,0 +1,81 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { BarChart } from "@godxjp/ui/charts";
+
+/**
+ * 横棒グラフの分類軸と、カードの見出しとの重複 — gh#409 · 1 と 2。
+ *
+ * 監理団体の実習実施者（受入企業）名は「株式会社」を含む 8〜10 文字の全角で、幅は 100〜125px に
+ * なります。分類軸の幅を固定にすると、名前の**先頭**、つまり識別に必要な部分から切り落とされます。
+ * BarChart は実際に描画される字形で各目盛りを実測し、いちばん広い目盛りに合わせて軸を確保します。
+ * 上限はトークン `--chart-category-axis-max-fraction` が持ち、これを超える名前だけが**末尾**で
+ * 省略され、全文は目盛りの `<title>` と図の代替テキストに残ります。
+ *
+ * 下段のカードは `showCaption={false}`。`CardTitle` が見出しを担うので、キャプションは
+ * `sr-only` として DOM に残り、`role="img"` の名前は失われません。
+ */
+
+/** 実習実施者ごとの受入人数。企業名は 8〜10 文字の全角で、固定幅の軸では先頭が消えていました。 */
+const acceptances = [
+  { company: "株式会社山田製作所", trainees: 42 },
+  { company: "佐藤食品株式会社", trainees: 35 },
+  { company: "株式会社中村建設", trainees: 28 },
+  { company: "東海精密工業株式会社", trainees: 24 },
+  { company: "みどり農産株式会社", trainees: 18 },
+  { company: "大和金属加工株式会社", trainees: 12 },
+];
+
+export default function Demo() {
+  return (
+    <PageContainer
+      title="CJK category axis"
+      subtitle="横棒グラフの分類軸を実測で確保し、見出しの重複をなくす"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>横棒 BarChart · 分類軸は目盛りの実測で決まる</CardTitle>
+            <CardDescription>
+              いちばん広い目盛りに合わせて軸幅を確保します。キャプションは既定どおり表示。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <BarChart
+              id="cjk-axis-chart"
+              label="実習実施者別 受入人数"
+              data={acceptances}
+              categoryKey="company"
+              series={[{ dataKey: "trainees", label: "受入人数" }]}
+              showLegend={false}
+              size="md"
+              horizontal
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>実習実施者別 受入人数</CardTitle>
+            <CardDescription>
+              `showCaption={"{false}"}` — 見出しは CardTitle が担い、キャプションは sr-only
+              として残るのでアクセシブルな名前は保たれます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <BarChart
+              id="cjk-axis-chart-no-caption"
+              label="実習実施者別 受入人数"
+              data={acceptances}
+              categoryKey="company"
+              series={[{ dataKey: "trainees", label: "受入人数" }]}
+              showLegend={false}
+              showCaption={false}
+              size="md"
+              horizontal
+            />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/data-display/card/index.tsx

@@ -281,6 +281,28 @@ export default function Demo() {
             </Card>
           </ResponsiveGrid>
         </Flex>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>連続したツールバー</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Text>本文</Text>
+          </CardContent>
+          <CardBar pad={{ block: 1, inline: 3 }} surface="muted" border="block-start" gap="sm">
+            <Button variant="ghost" size="sm">
+              添付
+            </Button>
+          </CardBar>
+          <CardBar
+            pad={{ block: 2, inline: 3 }}
+            border="block-start"
+            gap="sm"
+            extra={<Button>送信</Button>}
+          >
+            <Text tone="muted">下書きを保存しました</Text>
+          </CardBar>
+        </Card>
       </Flex>
     </PageContainer>
   );