@godxjp/ui 33.1.1 → 33.2.1

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 — 165 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,10 +53,10 @@ 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) | 49 KB | all 165 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 165 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 |
 <!-- prettier-ignore-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.2.1.** 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.
@@ -52,7 +52,7 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    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` — 49 KB, all 165 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/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",

package/agent/components.json

@@ -7126,6 +7126,182 @@
       "Audit log annotation — allowing an accountant to attach a plain-text explanation to a manual journal entry or adjustment record."
     ]
   },
+  {
+    "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)"
+    ]
+  },
+  {
+    "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"
+    ]
+  },
   {
     "example": "import { Label } from \"@godxjp/ui/data-entry\";\n\n<Label htmlFor=\"stackable\">併用を許可</Label>",
     "group": "data-entry",
@@ -10669,6 +10845,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": [
@@ -10689,7 +10871,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": [
@@ -10698,6 +10881,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/index.json

@@ -1,10 +1,10 @@
 {
   "counts": {
     "anti-ai-tells": 35,
-    "components": 163,
+    "components": 165,
     "patterns": 25,
     "rules": 44,
-    "tokens": 2228,
+    "tokens": 2230,
     "vocabulary": 14
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
@@ -16,12 +16,12 @@
     },
     {
       "file": "components-index.json",
-      "note": "49 KB — name + group + tagline for all 163. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "49 KB — name + group + tagline for all 165. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
       "file": "components/<Name>.json",
-      "note": "One file per component (1 KB–37 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.2 MB blob.",
+      "note": "One file per component (1 KB–37 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.3 MB blob.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/<Name>.json"
     },
     {
@@ -54,19 +54,19 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.1.1/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.2.1/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 1899,
+      "component": 1901,
       "foundation": 216,
       "semantic": 113
     },
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "33.1.1"
+  "version": "33.2.1"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 163 components, 2228 design tokens,
-> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.1.1.
+> A Japanese-enterprise React design system: 165 components, 2230 design tokens,
+> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.2.1.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@33.1.1`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@33.2.1`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -16,10 +16,10 @@ that can only fetch URLs.
 ## Catalog
 
 - [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 25 whole-task patterns (name, tagline, tags). Start here when the task is a TASK — "build a settings page" — then fetch `patterns/<name>.json` for complete code.
-- [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 49 KB — all 163 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
+- [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 49 KB — all 165 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/&lt;Name&gt;.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–37 KB, median 6 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
-- [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.2 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 216 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1899 `component` knobs.
+- [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.3 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 216 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1901 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 44 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 35 shapes that make generated UI look generated, each with its fix.
@@ -27,7 +27,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v33.1.1/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v33.2.1/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/tokens.json

@@ -6503,6 +6503,18 @@
     "tier": "component",
     "value": "16rem"
   },
+  {
+    "description": "TranslatableInput / TranslatableTextarea (gh#1336). The rhythm between the locale tab strip and the field it switches — a service aligning its forms to a tighter grid sets it once. 4px",
+    "name": "--translatable-field-gap",
+    "tier": "component",
+    "value": "var(--space-1)"
+  },
+  {
+    "description": "The error mark beside a locale's name on its tab. The ICON scale one step below the tab's own 14px text, so it reads as a mark on the label rather than a second word. 12px",
+    "name": "--translatable-field-error-icon-size",
+    "tier": "component",
+    "value": "var(--icon-size-xs)"
+  },
   {
     "description": "Width of the label column when <Descriptions layout=\"horizontal\">. Labels align to this shared column so the values line up (the horizontal-detail look, mirroring <Form layout>). A rem value gives a fixed aligned column; set `max-content` to size each label to its text. (rule #44/#45 — a service theme tunes it here instead of forking CSS.)",
     "name": "--descriptions-label-width",