@godxjp/ui 33.1.1 → 33.3.0

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 163 components, 2228 tokens, 44 cardinal rules — is published in two forms from one
+The catalog — 166 components, 2230 tokens, 44 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -53,12 +53,12 @@ static files straight from this public repo — no hosting, no deploy step:
 | [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt) | 3 KB | the [llms.txt](https://llmstxt.org/) entry point |
 | [`agent/DESIGN.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md) | 17 KB | the visual spec: tokens, colour scarcity, admin screen anatomy, do/don't |
 | [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json) | 3 KB | manifest: version, counts, every file's URL |
-| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 49 KB | all 163 as name + group + tagline — **fetch this first** |
+| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 50 KB | all 166 as name + group + tagline — **fetch this first** |
 | [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1 KB–37 KB | one file per component, each with its `importPath` — **this is the route to take** |
-| [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.2 MB | all 163 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
-| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 857 KB | all 2228 design tokens, their values and why they exist |
+| [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.3 MB | all 166 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 857 KB | all 2230 design tokens, their values and why they exist |
 | [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json) | 7 KB | the controlled prop vocabulary |
-| [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 22 KB | the 44 cardinal rules |
+| [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 23 KB | the 44 cardinal rules |
 <!-- prettier-ignore-end -->
 <!-- agent-catalog-files:end -->
 

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 33.1.1.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 33.3.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -48,11 +48,11 @@ inspect every screenshot at every width region by region (no top-N cap), and han
 → These files are for you. Read `DESIGN.md` (in this folder) first: tokens, scarcity rules and
 screen anatomy, the visual target the rules below do not give you. Then fetch in this order:
 
-0. `patterns-index.json` — 25 whole-task patterns as name + tagline + tags. **If your
+0. `patterns-index.json` — 28 whole-task patterns as name + tagline + tags. **If your
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
-1. `components-index.json` — 49 KB, all 163 components as name + group +
+1. `components-index.json` — 50 KB, all 166 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
@@ -61,15 +61,15 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 44 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2228 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2230 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 216 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1899 `component` entries are per-part knobs; reach for one only when a role is
+   1901 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 35 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
 
-**Do not fetch `components.json`.** It is 1.2 MB, and most URL fetchers truncate a
+**Do not fetch `components.json`.** It is 1.3 MB, and most URL fetchers truncate a
 response that size and return the head without telling you. You get the first few entries, believe
 you read the catalog, and answer the rest from memory — which is the failure this file exists to
 prevent. The per-component files say the same thing without the cliff.
@@ -150,7 +150,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 216 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** The default `--primary` is a neutral placeholder: set it (`:root { --primary: <H> <S>% <L>%; }`, HSL components, no `hsl()` wrapper) or import a theme preset such as `@godxjp/ui/themes/godx.css` |
 | `semantic` | 113 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1899 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 1901 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/Command.json

@@ -126,6 +126,12 @@
       "description": "Renders automatically only when there are no matching results. Place inside CommandList.",
       "name": "CommandEmpty",
       "type": "React.ReactNode (children)"
+    },
+    {
+      "defaultValue": "true",
+      "description": "CommandSeparator is cmdk's Command.Separator (data-slot=\"command-separator\", ref forwarded, className merged): a hairline between two groups of one list. Default true — the OPPOSITE of cmdk, which drops the separator once the search is non-empty; a `+ Create \"<q>\"` group only exists while the user types, so the rule above it must stay. Pass false for cmdk's palette behaviour. Hidden automatically beside a group cmdk has hidden (no matching rows) and under `split` (which already rules group boundaries). aria-hidden: decorative, since a separator is not an allowed listbox child. Tokens: --command-item-divider-width / --command-item-divider-color (→ --stroke-hairline / --border), margin-block --command-group-padding.",
+      "name": "CommandSeparator.alwaysRender",
+      "type": "boolean"
     }
   ],
   "related": [
@@ -146,7 +152,8 @@
     "CommandGroup",
     "CommandInput",
     "CommandItem",
-    "CommandList"
+    "CommandList",
+    "CommandSeparator"
   ],
   "tagline": "Accessible, keyboard-navigable command palette / combobox list built on cmdk — always pair CommandInput inside its own wrapper div, never render items outside CommandList.",
   "usage": [
@@ -155,6 +162,7 @@
     "DO always provide a stable explicit value prop on CommandItem when the item's text content can change between renders — relying on inferred textContent with dynamic labels causes selection bugs.",
     "DO include CommandEmpty inside CommandList to show a no-results message. It renders automatically only when the filtered count is zero; do not conditionally render it yourself.",
     "DO use split for checkbox/option lists (a filter facet, a picker: Popover + PopoverContent flush + Command split) — rows get a divider between them and 0 list padding, so they read as one box. Keep the default (unsplit) for a command palette. Never re-create the look with page CSS (border on items, padding 0 on the group): retune --command-item-divider-color / --command-item-divider-width instead.",
+    "DO divide a result group from an action group with CommandSeparator — matches, then `<CommandSeparator />`, then `<CommandGroup forceMount><CommandItem forceMount value={`__create__${q}`}>+ Create \"{q}\"</CommandItem></CommandGroup>` rendered only while the query has no exact match. Give the create item an explicit value (never inferred from its changing text) and forceMount both it and its group so the filter cannot hide it. Never keep a local copy of the Command family for the divider — a compound must come from one cmdk instance.",
     "DON'T use CommandInput as a standalone search input — it is only meaningful inside a Command root (the root manages shared filter state). For a standalone search field use SearchInput instead.",
     "DON'T hand-roll keyboard navigation on a list of items; Command handles arrow keys, Enter, Escape, Home/End, and vim bindings. Adding your own keyDown handlers on top creates conflicts — use onSelect on CommandItem for selection logic."
   ],

package/agent/components/ResponsiveGrid.json

@@ -21,9 +21,9 @@
       "type": "\"rows\" | \"columns\""
     },
     {
-      "description": "antd `Row align`, spelled with Flex's FlexAlignProp values (antd `top` → \"start\"). \"stretch\" makes every cell as tall as the tallest one. Omitted, flow=\"columns\" keeps \"start\" and flow=\"rows\" keeps the grid's natural stretch.",
+      "description": "antd `Row align`, spelled with Flex's FlexAlignProp values (antd `top` → \"start\", `middle` → \"center\"). \"center\" puts cells of different heights on one centre line (a condition row's number and ＋/− buttons beside taller controls). \"stretch\" makes every cell as tall as the tallest one. Omitted, flow=\"columns\" keeps \"start\" and flow=\"rows\" keeps the grid's natural stretch.",
       "name": "align",
-      "type": "\"start\" | \"stretch\""
+      "type": "\"start\" | \"center\" | \"stretch\""
     },
     {
       "defaultValue": "4",

package/agent/components/SearchForm.json

@@ -0,0 +1,115 @@
+{
+  "absorbed": [
+    "QueryFilter",
+    "SearchPanel"
+  ],
+  "docPath": "navigation/search-form",
+  "example": "import { SearchForm } from \"@godxjp/ui/navigation\";\nimport { FormField, Input, Select, DatePicker } from \"@godxjp/ui/data-entry\";\n\n<SearchForm\n  controlWidth=\"100%\"\n  onSubmit={(e) => { e.preventDefault(); setApplied(draft); }}\n  onReset={() => { setDraft(EMPTY); setApplied(EMPTY); }}\n  summary=\"国籍: ベトナム / 状態: 実習中\"\n  resultCount={rows.length}\n>\n  <FormField label=\"氏名\" id=\"q-name\"><Input id=\"q-name\" value={draft.name} onChange={(e) => set({ name: e.target.value })} /></FormField>\n  <FormField label=\"国籍\" id=\"q-nat\"><Select id=\"q-nat\" options={nationalities} value={draft.nationality} onValueChange={(v) => set({ nationality: v })} /></FormField>\n  <FormField label=\"入国日\" id=\"q-entry\"><DatePicker id=\"q-entry\" range /></FormField>\n  <FormField label=\"職種\" id=\"q-occ\"><Select id=\"q-occ\" options={occupations} value={draft.occupation} onValueChange={(v) => set({ occupation: v })} /></FormField>\n</SearchForm>",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "SearchForm",
+  "props": [
+    {
+      "description": "One FormField per condition, in reading order. Each direct child is one grid cell; a range (「日付」 From〜To, 「金額」 「下限〜上限」) is ONE FormField holding both controls.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "{ base: 1, md: 2, lg: 3 }",
+      "description": "Grid columns per container breakpoint — one column on a phone, aligned columns above. Conditions never spread to the edges.",
+      "name": "columns",
+      "type": "ResponsiveGridColumnsProp"
+    },
+    {
+      "description": "Conditions shown while collapsed (antd `defaultFormItemsNumber`). Default: the widest `columns` step, i.e. the first row.",
+      "name": "visibleFields",
+      "type": "number"
+    },
+    {
+      "description": "Controlled: whether the conditions past `visibleFields` are shown.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Uncontrolled initial state — collapsed to the first row by default.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Fires when the 「詳細条件を開く」 / 「閉じる」 toggle is pressed.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Search (「検索」) — the native form submit. Call `preventDefault()` and copy the draft conditions into the applied query; the form never searches on each keystroke.",
+      "name": "onSubmit",
+      "type": "FormEventHandler<HTMLFormElement>"
+    },
+    {
+      "description": "Clear (「クリア」). The button renders only when this is set.",
+      "name": "onReset",
+      "type": "() => void"
+    },
+    {
+      "description": "The conditions the CURRENT results were searched with, shown after the localized 「検索条件」 label in the status line (e.g. 「国「籍」: 「ベトナム」 / 「状態」: 「実習」中」).",
+      "name": "summary",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Localized, pluralized result count in the same `role=\"status\"` line.",
+      "name": "resultCount",
+      "type": "number"
+    },
+    {
+      "description": "Puts the Search button in its loading state while the query runs.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Overrides the localized Search (「検索」) text.",
+      "name": "searchLabel",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Overrides the localized Clear (「クリア」) text.",
+      "name": "resetLabel",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Accessible name of the `search` landmark (default: localized 'Search conditions').",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "Passed to the underlying Form: `layout=\"vertical\"` (default) is label-top; `layout=\"horizontal\"` + `labelWidth` is the label-left table style of Japanese business systems. Set `controlWidth` once here so Selects fill their column.",
+      "name": "layout / labelWidth / controlWidth / labelAlign",
+      "type": "Form props"
+    }
+  ],
+  "related": [
+    "Toolbar — FilterBar, the live filter strip; use it for a few filters applied as the user changes them.",
+    "Form — the layout container SearchForm renders (`role=\"search\"`); its `layout`, `labelWidth` and `controlWidth` pass through.",
+    "FormField — one per condition; a range is one FormField holding two controls.",
+    "DataTable — the results under the form."
+  ],
+  "rules": [
+    23,
+    51
+  ],
+  "storyPath": "navigation/search-form.tsx",
+  "tagline": "Submit-driven 「検索条件フォーム」 (Ant Design ProComponents QueryFilter): a `search` landmark holding a grid of labelled conditions aligned in columns, Search 「検索」 + Clear 「クリア」, the conditions past the first row behind ONE 「詳細条件を開く」 toggle that names how many are hidden, and a 「検索条件」 summary + result count in a role=\"status\" line after the search. Use it instead of a live FilterBar when the conditions are many, the query is heavy, or users expect an explicit 「検索」 button (rule #51 decision table).",
+  "usage": [
+    "DO pick the shape from rule #51's decision table: a few filters applied instantly → FilterBar; many conditions / a heavy query / users who expect an explicit 「検索」 button → SearchForm; arbitrary field × operator conditions saved as views → pattern `condition-builder`.",
+    "DO put one FormField per condition as a direct child. Ranges (「入国日」 From〜To, 「金額」 「下限〜上限」) are ONE FormField with both controls; 「部分一致」 / 「完全一致」 is a RadioGroup inside the name field.",
+    "DO keep a draft and an applied copy of the conditions: inputs edit the draft, onSubmit copies it to the applied query, onReset clears both. Pass the applied conditions as `summary` and the hit count as `resultCount`.",
+    "DO NOT wrap it in another Form, and do not rebuild it as a Form + ResponsiveGrid + Collapsible by hand — the collapse, the hidden-count toggle, the search landmark and the status line are what this component owns. Hidden conditions stay mounted, so a typed value survives collapsing.",
+    "A SearchForm (or any `<Form role=\"search\" onSubmit>`) above a table is NOT flagged by ui-audit `form-on-list-page` or `hand-rolled-filter-bar`; a submitting create form without role=\"search\" still is."
+  ],
+  "useCases": [
+    "「検索条件フォーム」 on a Japanese business-system list (「基幹系」 / 「業務システム」): 6–12 conditions, 「検索」 and 「クリア」 buttons, 「詳細条件を開く」.",
+    "Search screens over a heavy query where searching on every keystroke would be too expensive.",
+    "Label-left (「表形式」) or label-top search panels above a DataTable, with the applied conditions summarized after the search."
+  ]
+}

package/agent/components/Toolbar.json

@@ -101,7 +101,8 @@
     "DataTable.Toolbar — the in-table strip for column/density/bulk-action controls; Toolbar (this) is the page-level filter strip that sits ABOVE the table.",
     "SearchInput — the debounced free-text control placed as the first child of Toolbar.",
     "Badge — compose Badge + a sibling icon Button to render each active-filter chip; Badge itself is a non-interactive leaf.",
-    "Sheet — holds the filters beyond the 2–4 inline ones, opened by ONE 'More filters' Button inside the bar (pattern `list-filters`, rule #51). Not a ScrollArea: a filter strip never scrolls sideways."
+    "Sheet — holds the filters beyond the 2–4 inline ones, opened by ONE 'More filters' Button inside the bar (pattern `list-filters`, rule #51). Not a ScrollArea: a filter strip never scrolls sideways.",
+    "SearchForm — the submit-driven 「検索条件フォーム」 for many conditions or an explicit 「検索」 button (rule #51 decision table); FilterBar is the live strip."
   ],
   "rules": [
     23,
@@ -116,7 +117,7 @@
     "FilterBar",
     "FilterBarGroup"
   ],
-  "tagline": "List-page filter strip — SearchInput + labelled ToolbarGroup filter slots (or the typed `search`/`filters`/`chips` model) + a clear-all affordance, optionally sticky. It WRAPS and never scrolls sideways; many filters → 2–4 inline + ONE 'More filters' Sheet (rule #51, pattern `list-filters`). `FilterBar`/`FilterBarGroup` are the same components under their alias names.",
+  "tagline": "List-page filter strip — SearchInput + labelled ToolbarGroup filter slots (or the typed `search`/`filters`/`chips` model) + a clear-all affordance, optionally sticky. It WRAPS and never scrolls sideways; many filters → 2–4 inline + ONE 'More filters' Sheet (rule #51, pattern `list-filters`). `FilterBar`/`FilterBarGroup` are the same components under their alias names. Eleven layouts (inline, Filter menu + chips, More-filters Sheet, saved views, two rows, actions + sticky, faceted sidebar, compact in a card, date range, phone, docked panel) → pattern `filter-bar-layouts`.",
   "usage": [
     "DO prefer the typed model on a canonical list page — `search`/`filters`/`chips`/`onChipRemove`/`actions`/`resultCount` (+ `loading`/`disabled`/`error`) make the bar own layout, widths, chip lifecycle and keyboard order through --filter-bar-* tokens while ALL state stays consumer data. Children composition remains fully supported and unchanged when no model prop is passed.",
     "DO place Toolbar ABOVE the table Card, never inside a `CardContent flush`. Put SearchInput as a direct child (it self-labels) and wrap every other control in a ToolbarGroup with a `label`.",
@@ -124,6 +125,7 @@
     "DO set `sticky` for long list pages so the filters stay reachable while scrolling; if a topbar sits above the list, raise `--filter-bar-sticky-offset` so the strip parks below it.",
     "DO pass `controlId` on a ToolbarGroup that wraps ONE control and give that control the same `id` — the visible caption then becomes the control's real `<label htmlFor>` (WCAG 2.5.3 label-in-name). Without it the caption only names the group wrapper and the control itself is NAMELESS (axe: select-name / button-name), so you must fall back to an `aria-label` that repeats the caption.",
     "DO let the strip WRAP — cardinal rule #51 (`get_rule 51`). It stacks below 640px and wraps onto extra rows above; it never scrolls sideways, and neither may anything you wrap it in (`ScrollArea orientation=\"horizontal\"`, an `overflow-x-auto` box): the `overflow` prop and its `scroll` strategy were removed in 33.0.0 because a sideways strip hid filters off-screen and clipped the first label. When the filters are many, keep the 2–4 most-used ones inline and put the rest behind ONE 'More filters' Button (`count` = hidden filters applied) that opens a Sheet holding them as FilterBarGroup + control; every applied filter, inline or hidden, is a chip in `chips` (the chips row wraps too). Copy-paste composition: pattern `list-filters` (`get_pattern list-filters`); there is no dedicated component. Never re-implement the geometry in the page: no page-local flex/grid/width/overflow rules on a filter strip.",
+    "DO keep filters PACKED at the start of the bar with its one gap. Never lay them out yourself in a Flex/div/Card/ResponsiveGrid of FormFields above the table, and never spread them with `justify=\"between\"|\"around\"|\"evenly\"` — the only far-end element of a filter bar is its `actions` slot (with the clear button). ui-audit `hand-rolled-filter-bar` flags both. For a layout other than one strip (saved views, a Filter menu with chips, a faceted sidebar, a docked side panel, a compact bar inside a table card, a date range with quick ranges, a phone Sheet), copy pattern `filter-bar-layouts` (docs page navigation/filter-bar-layouts).",
     "DON'T build active-filter chips by nesting a Button inside a Badge (invalid markup + broken focus). Render each chip as a Badge label with a SIBLING icon Button (`aria-label` = 'clear <filter>'); a ghost `size='sm'` Button clears all.",
     "DON'T hand-roll a debounced search box or a raw `<select>` — compose SearchInput and Select. Toolbar is layout + clear-all only; the controls own their own state and a11y.",
     "Prefer the typed model for a canonical list page: pass `search` + `filters` + `chips` + `resultCount` and the bar owns the layout, widths, chip lifecycle, keyboard order (search → filters → children → reset → actions → chip removes) and responsive stacking through --filter-bar-* tokens. Everything stays consumer data — the bar renders state, never owns it.",
@@ -134,6 +136,7 @@
   "useCases": [
     "Master list screens (members, organizations, subscriptions, invoices) that need free-text search plus a few dropdown filters above a DataTable.",
     "Sticky filter strip over a tall list where the filters must remain visible as the user scrolls the results.",
-    "Filtered views that surface applied conditions as removable chips (clear-one via each chip's × Button, clear-all via `onClear`)."
+    "Filtered views that surface applied conditions as removable chips (clear-one via each chip's × Button, clear-all via `onClear`).",
+    "Filter layout choices — saved views filter tabs above the bar, a search-first bar with one Filter menu, a faceted filter sidebar with per-facet counts, a docked filter panel beside the table, a compact table toolbar, a date range filter with quick ranges, a phone filter Sheet: pattern `filter-bar-layouts`."
   ]
 }

package/agent/components/TranslatableInput.json

@@ -0,0 +1,92 @@
+{
+  "example": "import { FormField, TranslatableInput, TranslatableTextarea, type TranslatableValue } from \"@godxjp/ui/data-entry\";\n\nconst [productName, setProductName] = React.useState<TranslatableValue>({ ja: \"醤油ラーメン\" });\nconst [description, setDescription] = React.useState<TranslatableValue>({});\n\n<FormField label=\"商品名\" required>\n  <TranslatableInput\n    locales={[\"ja\", \"en\", \"vi\"]}\n    fallbackLocale=\"ja\"\n    value={productName}\n    onValueChange={setProductName}\n    errors={{ en: \"英語名を入力してください\" }}\n  />\n</FormField>\n\n<FormField label=\"説明\">\n  <TranslatableTextarea locales={[\"ja\", \"en\", \"vi\"]} value={description} onValueChange={setDescription} rows={3} />\n</FormField>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "TranslatableInput",
+  "props": [
+    {
+      "description": "Controlled per-locale values — `Partial<Record<string, string>>` keyed by BCP-47 tag. A missing key or `\"\"` is an empty locale.",
+      "name": "value",
+      "type": "TranslatableValue"
+    },
+    {
+      "description": "Uncontrolled initial per-locale values.",
+      "name": "defaultValue",
+      "type": "TranslatableValue"
+    },
+    {
+      "description": "The WHOLE map after an edit: only the active locale's key changes, every other locale is carried over untouched. The ✕ of `allowClear` empties the active locale only.",
+      "name": "onValueChange",
+      "type": "(value: TranslatableValue) => void"
+    },
+    {
+      "description": "The BCP-47 tags the field edits, in tab order. Default: every locale registered with the app (`getRegisteredLocales()` — built-in `vi`/`en`/`ja` plus `registerLocale`). Tabs are named by `Intl.DisplayNames` in the reader's UI language; the tags stay the keys.",
+      "name": "locales",
+      "type": "readonly string[]"
+    },
+    {
+      "description": "The locale tab selected first. Default: the AppProvider's active locale when it is in `locales`, else the fallback locale.",
+      "name": "defaultLocale",
+      "type": "string"
+    },
+    {
+      "description": "The locale whose text an EMPTY locale shows as its placeholder. Default: the AppProvider's `fallbackLocale`, or the first of `locales` when that is not one of them.",
+      "name": "fallbackLocale",
+      "type": "string"
+    },
+    {
+      "description": "Per-locale validation messages. Each locale that has one gets an error mark on its tab — a glyph plus screen-reader text («Vietnamese, has an error»), never colour alone. The ACTIVE locale's message sets `aria-invalid` and is shown in the enclosing FormField's own error line (wired by `aria-errormessage`); without a FormField it is shown under the field.",
+      "name": "errors",
+      "type": "Partial<Record<string, ReactNode>>"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "The field's control tier, as on Input. The tab strip uses the Tabs `sm` tier (`md` for an `lg` field).",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Shown while the active locale is empty and there is no fallback text to show (the fallback locale itself, or an empty fallback).",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "description": "Disables the control; the locale tabs stay operable so every locale can still be read.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Lands on the control, so a FormField label click focuses it.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Root (strip + field) class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "TranslatableTextarea — the same contract over a Textarea.",
+    "Input — the control it composes; every Input prop applies.",
+    "FormField — the label / helper / error wiring it reports into.",
+    "Tabs — the switcher it composes (strip-only, `controls` → the field's panel).",
+    "AppSettingPicker kind=\"locale\" — chooses the UI language, not per-locale content."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/translatable-input.tsx",
+  "tagline": "ONE text field holding a value per locale (`{ ja, en, vi }`), switched by locale tabs above it (gh#1336). For user content stored per locale — a product name, a category label, a menu description (Astrotomic / Spatie `*_translations`). Locales, first tab and fallback come from AppProvider; an empty locale shows the fallback locale's text as its placeholder; a locale with an error is marked on its tab. Every other `Input` prop applies to the one control.",
+  "usage": [
+    "DO wrap it in FormField: the label names the control together with the active locale («商品名 English») and names the tab strip («商品名 Language»), `required`/`helper` reach the control, and the active locale's error renders in FormField's error line.",
+    "DO pass the per-locale error map from your validator as `errors` (e.g. Laravel `name.ja` → `errors.ja`). Don't pass the same message to FormField `error` as well: FormField's own `error` wins over the reported one, and it would mark the field invalid on every locale.",
+    "DO set `fallbackLocale` to the content's SOURCE language (often `ja`) when it differs from the AppProvider's UI fallback — the placeholder of an untranslated locale then shows the source text to translate from.",
+    "DON'T build a local wrapper of Tabs + Input for this: the tab↔panel ARIA, the lang attribute, the error marks and the FormField wiring are what this component exists for.",
+    "DON'T use it for a choice of language that IS the form's value (a user's preferred language): that is `AppSettingPicker kind=\"locale\"` or a Select.",
+    "The locale switcher is the WAI-ARIA APG tabs pattern (tablist → one tabpanel holding the field), not a Segmented radio group: the locale is not form state — every locale is submitted together — the tab only chooses which locale the one field shows."
+  ],
+  "useCases": [
+    "Product / menu item name in ja, en and vi on an admin edit form",
+    "Category or section label stored per locale (Astrotomic `*_translations`)",
+    "Translated description or recipe text (TranslatableTextarea)"
+  ]
+}

package/agent/components/TranslatableTextarea.json

@@ -0,0 +1,84 @@
+{
+  "example": "import { FormField, TranslatableTextarea } from \"@godxjp/ui/data-entry\";\n\n<FormField label=\"説明\">\n  <TranslatableTextarea locales={[\"ja\", \"en\", \"vi\"]} value={description} onValueChange={setDescription} autoGrow minRows={3} />\n</FormField>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "TranslatableTextarea",
+  "props": [
+    {
+      "description": "Controlled per-locale values, keyed by BCP-47 tag.",
+      "name": "value",
+      "type": "TranslatableValue"
+    },
+    {
+      "description": "Uncontrolled initial per-locale values.",
+      "name": "defaultValue",
+      "type": "TranslatableValue"
+    },
+    {
+      "description": "The whole map after an edit; only the active locale's key changes.",
+      "name": "onValueChange",
+      "type": "(value: TranslatableValue) => void"
+    },
+    {
+      "description": "The BCP-47 tags the field edits, in tab order. Default: the app's registered locales.",
+      "name": "locales",
+      "type": "readonly string[]"
+    },
+    {
+      "description": "The locale tab selected first. Default: the AppProvider's active locale.",
+      "name": "defaultLocale",
+      "type": "string"
+    },
+    {
+      "description": "The locale whose text an empty locale shows as its placeholder. Default: the AppProvider's `fallbackLocale`.",
+      "name": "fallbackLocale",
+      "type": "string"
+    },
+    {
+      "description": "Per-locale messages: tab marks for each, `aria-invalid` + FormField's error line for the active one.",
+      "name": "errors",
+      "type": "Partial<Record<string, ReactNode>>"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "The field's control tier, as on Textarea.",
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Shown while the active locale is empty and there is no fallback text.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "description": "Disables the control; the locale tabs stay operable.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Lands on the control.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Root class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "TranslatableInput — the single-line form and the full contract.",
+    "Textarea — the control it composes."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/translatable-input.tsx",
+  "tagline": "TranslatableInput over a Textarea (gh#1336): one multi-line field holding a value per locale, switched by locale tabs. Same locale, fallback-placeholder, error-mark and FormField contract; every Textarea prop (rows, autoGrow, count…) applies to the one control.",
+  "usage": [
+    "DO use it for per-locale multi-line content (a description, a recipe); for a single line use TranslatableInput.",
+    "DO wrap it in FormField, exactly as TranslatableInput."
+  ],
+  "useCases": [
+    "Menu item description in ja, en and vi",
+    "Recipe or notice body stored per locale"
+  ]
+}

package/agent/components-index.json

@@ -408,6 +408,16 @@
     "name": "Textarea",
     "tagline": "Styled wrapper around native <textarea>. Pair with FormField for labelled fields. For a Markdown body (wiki page, issue description, mail) use the sibling package `@godxjp/editor` `MarkdownEditor` — this Textarea plus a formatting toolbar, preview through `@godxjp/markdown`, and paste/drop upload through a host `upload` function (gh#1109)."
   },
+  {
+    "group": "data-entry",
+    "name": "TranslatableInput",
+    "tagline": "ONE text field holding a value per locale (`{ ja, en, vi }`), switched by locale tabs above it (gh#1336). For user content stored per locale — a product name, a category label, a menu description (Astrotomic / Spatie `*_translations`). Locales, first tab and fallback come from AppProvider; an empty locale shows the fallback locale's text as its placeholder; a locale with an error is marked on its tab. Every other `Input` prop applies to the one control."
+  },
+  {
+    "group": "data-entry",
+    "name": "TranslatableTextarea",
+    "tagline": "TranslatableInput over a Textarea (gh#1336): one multi-line field holding a value per locale, switched by locale tabs. Same locale, fallback-placeholder, error-mark and FormField contract; every Textarea prop (rows, autoGrow, count…) applies to the one control."
+  },
   {
     "group": "data-entry",
     "name": "Label",
@@ -483,7 +493,16 @@
   {
     "group": "navigation",
     "name": "Toolbar",
-    "tagline": "List-page filter strip — SearchInput + labelled ToolbarGroup filter slots (or the typed `search`/`filters`/`chips` model) + a clear-all affordance, optionally sticky. It WRAPS and never scrolls sideways; many filters → 2–4 inline + ONE 'More filters' Sheet (rule #51, pattern `list-filters`). `FilterBar`/`FilterBarGroup` are the same components under their alias names."
+    "tagline": "List-page filter strip — SearchInput + labelled ToolbarGroup filter slots (or the typed `search`/`filters`/`chips` model) + a clear-all affordance, optionally sticky. It WRAPS and never scrolls sideways; many filters → 2–4 inline + ONE 'More filters' Sheet (rule #51, pattern `list-filters`). `FilterBar`/`FilterBarGroup` are the same components under their alias names. Eleven layouts (inline, Filter menu + chips, More-filters Sheet, saved views, two rows, actions + sticky, faceted sidebar, compact in a card, date range, phone, docked panel) → pattern `filter-bar-layouts`."
+  },
+  {
+    "absorbed": [
+      "QueryFilter",
+      "SearchPanel"
+    ],
+    "group": "navigation",
+    "name": "SearchForm",
+    "tagline": "Submit-driven 「検索条件フォーム」 (Ant Design ProComponents QueryFilter): a `search` landmark holding a grid of labelled conditions aligned in columns, Search 「検索」 + Clear 「クリア」, the conditions past the first row behind ONE 「詳細条件を開く」 toggle that names how many are hidden, and a 「検索条件」 summary + result count in a role=\"status\" line after the search. Use it instead of a live FilterBar when the conditions are many, the query is heavy, or users expect an explicit 「検索」 button (rule #51 decision table)."
   },
   {
     "group": "providers",