@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/ChatSuggestion.json

@@ -0,0 +1,86 @@
+{
+  "docPath": "data-entry/chat-composer.tsx",
+  "example": "import { ChatComposer, ChatSuggestion } from \"@godxjp/ui/data-entry\";\n\nconst [draft, setDraft] = useState(\"\");\n\n<ChatSuggestion\n  items={[\n    { value: \"summarize\", label: \"要約する\", description: \"Summarize the thread\" },\n    { value: \"translate\", label: \"翻訳する\" },\n  ]}\n  onValueChange={(value) => setDraft(\"/\" + value + \" \")}\n>\n  {({ onTrigger, onKeyDown }) => (\n    <ChatComposer\n      value={draft}\n      onValueChange={(next) => { setDraft(next); onTrigger(next); }}\n      onKeyDown={onKeyDown}\n      onSubmit={(text) => send(text)}\n    />\n  )}\n</ChatSuggestion>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "ChatSuggestion",
+  "props": [
+    {
+      "description": "The rows to offer: { value, label?, description?, icon?, disabled?, children? }. One level of children is honoured — picking a parent drills into it instead of emitting.",
+      "name": "items",
+      "required": true,
+      "type": "ChatSuggestionItemProp[]"
+    },
+    {
+      "description": "Fires with the picked row's value. The CALLER owns what that does to the draft text — the component never rewrites the textarea behind your back.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "defaultValue": "\"/\"",
+      "description": "The character that opens the list when typed at a word boundary (use \"@\" for a mention list).",
+      "name": "triggerCharacter",
+      "type": "string"
+    },
+    {
+      "description": "Controlled open state of the list.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Uncontrolled initial open state.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state change handler.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Render prop wrapping the composer. Call onTrigger from the composer's onValueChange and forward onKeyDown to its onKeyDown.",
+      "name": "children",
+      "required": true,
+      "type": "(props: { onTrigger: (value?: string | false) => void; onKeyDown: React.KeyboardEventHandler<HTMLTextAreaElement> }) => React.ReactNode"
+    },
+    {
+      "description": "Shown when the query matches nothing (localized default otherwise).",
+      "name": "emptyMessage",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name of the listbox (localized default otherwise).",
+      "name": "listLabel",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the anchor wrapping the composer.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ChatComposer — the control it wraps; use it alone when there is nothing to suggest.",
+    "Command / CommandPalette — a full-screen command surface opened by a shortcut, not by a character in a draft.",
+    "Select (showSearch) — the searchable single-select; a suggestion list edits free text, it does not hold a value."
+  ],
+  "rules": [
+    2,
+    3,
+    6
+  ],
+  "storyPath": "data-entry/ChatSuggestion.stories.tsx",
+  "tagline": "Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it.",
+  "usage": [
+    "DO wire BOTH halves of the render prop: `onTrigger` from the composer's onValueChange and `onKeyDown` from its onKeyDown. With only one wired the list either never opens or cannot be driven.",
+    "DO decide yourself what a pick does to the draft — onValueChange hands you the value; the typed /query is still in the box, so replace it or append to it as your screen needs.",
+    "DON'T hand-roll a listbox next to a textarea. This composes the real Command (cmdk) inside a Popover, which already ships the listbox/option roles, active-row bookkeeping and scroll-into-view.",
+    "DO rely on Escape: it closes the list, returns focus to the textarea and leaves the typed text intact. It also stops propagating, so a composer inside a Dialog does not close the Dialog too.",
+    "DON'T expect it to filter server-side — filtering is a plain substring match over label/value/description. For a remote list, filter `items` yourself as the query changes."
+  ],
+  "useCases": [
+    "Slash commands over an assistant composer (/summarize, /translate, /explain).",
+    "Mention picker in a comment composer (triggerCharacter=\"@\").",
+    "Prompt-template inserter grouped one level deep (a category row that drills into its templates)."
+  ]
+}

package/agent/components/Checkbox.json

@@ -0,0 +1,68 @@
+{
+  "example": "import { Checkbox } from \"@godxjp/ui/data-entry\";\n\n// children is the inline label (antd): box first, label on the same line, the text toggles the box.\n// Never a hand-rolled <div className=\"flex items-center gap-2\"> around a bare <Label>.\n<Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)}>\n  利用規約に同意する\n</Checkbox>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Checkbox",
+  "props": [
+    {
+      "description": "antd `indeterminate` — paint the PARTIAL mark (a dash) and announce `mixed`, without changing `checked`. This component also accepts the same state as `checked=\"indeterminate\"`; the flag is antd's spelling of it, and the box falls back to the underlying `checked` the moment the flag goes false.",
+      "name": "indeterminate",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled checked state.",
+      "name": "checked",
+      "type": "boolean | 'indeterminate'"
+    },
+    {
+      "description": "Uncontrolled initial state. It takes the tri-state too, and the box keeps the dash until the first click rather than falling back to unchecked.",
+      "name": "defaultChecked",
+      "type": "boolean | 'indeterminate'"
+    },
+    {
+      "description": "Fires when checked state changes.",
+      "name": "onCheckedChange",
+      "type": "(checked) => void"
+    },
+    {
+      "description": "Links to a <Label htmlFor>.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "antd `<Checkbox>label</Checkbox>` — the INLINE label: box first, label at inline-end on the same line, the same markup as a `Checkbox.Group` option. A real `<label for>`: clicking the text toggles the box and the text is its accessible name. `className` then styles the labelled row.",
+      "name": "children",
+      "type": "React.ReactNode"
+    }
+  ],
+  "related": [
+    "CheckboxGroup — use instead of bare Checkbox when you have a list of 2+ options from an array; it handles id generation, Field wrapping, value array management, and the `name` prop for form submission. Checkbox is for a single boolean; CheckboxGroup is for multi-select.",
+    "Switch / Field — use Switch when the action takes immediate effect (enable/disable a feature in settings) rather than selecting an option to be submitted later. Checkbox implies 'will be submitted as part of a form'; Switch implies 'applies now'. Field adds a hidden input for HTML form compatibility.",
+    "RadioGroup — use when only one option in a group may be selected at a time (mutually exclusive). CheckboxGroup = multiple selections allowed; RadioGroup = single selection only.",
+    "Field — the internal layout primitive (control slot + Label + description) that Checkbox.Group renders per item. Use it directly only when you need a one-off labelled checkbox or radio item outside of a group, and you want the consistent indent/description layout without the group's value-management overhead."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/Checkbox.stories.tsx",
+  "subParts": [
+    "CheckboxVisual"
+  ],
+  "tagline": "Checkbox on react-aria-components; standalone or via CheckboxGroup with an options array. `role=\"checkbox\"` is the real `<input>`; the painted box is the `<label>` around it and carries `data-state`.",
+  "usage": [
+    "DO give a single boolean its label as children (antd `<Checkbox>label</Checkbox>`, gh#709): `<Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)}>利用規約に同意する</Checkbox>` — box first, label on the same line, the text toggles the box and is its accessible name. In a form: `<FormFieldControl name=\"agree\" valuePropName=\"checked\">{(field) => <Checkbox {...field}>利用規約に同意する</Checkbox>}</FormFieldControl>`.",
+    "DON'T render a boolean field's label ABOVE its checkbox — `<FormFieldControl label=\"…\">{(field) => <Checkbox checked={field.value} … />}</FormFieldControl>` puts the label on one row and the box far below it. Put the label in the Checkbox's children and use `valuePropName=\"checked\"` on the field.",
+    "DO pair every standalone Checkbox WITHOUT children with a `<Label htmlFor={id}>` (or an `aria-label`) — the id prop on Checkbox must match the htmlFor on Label so screen readers announce the label on focus. Without this pairing the control is inaccessible.",
+    "DO use the controlled pattern (`checked` + `onCheckedChange`) for any form-bound checkbox. `onCheckedChange` receives `boolean | 'indeterminate'` — always coerce with `!!v` or an explicit guard before storing in state.",
+    "DO use `Checkbox.Group` (alias for CheckboxGroup) with the `options` prop when you have ≥2 choices from an array — it renders each item inside a `Field` (label + optional description), generates stable ids automatically, and manages the `string[]` value array. NEVER hand-roll a loop of bare `<Checkbox>` elements for a multi-select list.",
+    "DO pass `name` on `Checkbox.Group` (not on individual checkboxes) when the group must submit as form fields — the group propagates the name to each internal checkbox so the browser serialises all checked values under that key.",
+    "DON'T use `checked='indeterminate'` on `Checkbox.Group` children — indeterminate is only meaningful on a parent 'select-all' control you wire manually; the group itself does not auto-compute it.",
+    "DON'T wrap a standalone Checkbox in `Field` manually — `Field` is the internal composition primitive that `Checkbox.Group` uses. For a single boolean with a label, pass the label as children (`<Checkbox …>label</Checkbox>`, the catalog example) — it renders the same row. Use `<Field id='x' label='…' description='…'><Checkbox id='x' … /></Field>` only when the row needs a description line — Field owns the label-to-control id wiring, the description slot and the row rhythm, and a hand-rolled flex row owns none of them; for a full labelled-checkbox with description, use `Field` directly only if you need a one-off item outside a group."
+  ],
+  "useCases": [
+    "A 'Select all' / bulk-action row above a DataTable — standalone Checkbox with `checked='indeterminate'` when some (not all) rows are selected, toggling between all-selected and none-selected.",
+    "A multi-step filter panel (e.g. filter invoices by payment status: Paid, Unpaid, Overdue) — `Checkbox.Group` with `options` prop and `orientation='vertical'`, controlled value wired to Toolbar state.",
+    "Confirmation or consent acknowledgement before a destructive action in a Dialog — standalone Checkbox with controlled state used to enable/disable the confirm Button.",
+    "Settings panel where each feature flag is a boolean toggle with a description line — `Checkbox.Group` with options carrying a `description` field so each row renders label + subtext via Field.",
+    "Bulk-edit form row in an accounting ledger (e.g. 'Apply to all selected entries') — standalone Checkbox with name + value inside a `<form>` for native HTML form submission.",
+    "Onboarding checklist (e.g. 'I have read the terms', 'I consent to data processing') with multiple distinct items whose values are independent — two separate standalone Checkboxes, each with their own id/state, not a Checkbox.Group (since each item maps to a different boolean field)."
+  ]
+}

package/agent/components/CheckboxGroup.json

@@ -0,0 +1,96 @@
+{
+  "example": "import { CheckboxGroup } from \"@godxjp/ui/data-entry\";\nimport { useState } from \"react\";\n\nconst PERMISSIONS = [\n  { label: \"View invoices\", value: \"invoices:read\" },\n  { label: \"Create invoices\", value: \"invoices:write\", description: \"Includes editing and deleting\" },\n  { label: \"Manage users\", value: \"users:manage\", disabled: true },\n];\n\n// Uncontrolled — use defaultValue\nexport function PermissionsForm() {\n  return (\n    <form method=\"post\">\n      <CheckboxGroup\n        name=\"permissions\"\n        options={PERMISSIONS}\n        defaultValue={[\"invoices:read\"]}\n        orientation=\"vertical\"\n      />\n    </form>\n  );\n}\n\n// Controlled — use value + onChange\nexport function ControlledExample() {\n  const [selected, setSelected] = useState<string[]>([\"invoices:read\"]);\n  return (\n    <CheckboxGroup\n      name=\"permissions\"\n      options={PERMISSIONS}\n      value={selected}\n      onValueChange={setSelected}\n    />\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "CheckboxGroup",
+  "props": [
+    {
+      "description": "Id của nhóm; `FormField` tự truyền xuống để nối nhãn ↔ control.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Data-driven mode: array of { label, value, disabled?, description? }. When provided and non-empty, renders all checkboxes automatically. When omitted, renders `children` instead.",
+      "name": "options",
+      "type": "ChoiceOptionProp[]"
+    },
+    {
+      "description": "Controlled selected values. When provided, the component is controlled and won't manage state internally — you must handle onChange to update it.",
+      "name": "value",
+      "type": "string[]"
+    },
+    {
+      "defaultValue": "[]",
+      "description": "Uncontrolled initial selection. Use this instead of `value` when you don't need to control state externally.",
+      "name": "defaultValue",
+      "type": "string[]"
+    },
+    {
+      "description": "Called with the full updated selection array whenever any checkbox is toggled. Works in both controlled and uncontrolled modes.",
+      "name": "onChange",
+      "type": "(value: string[]) => void"
+    },
+    {
+      "defaultValue": "\"vertical\"",
+      "description": "Layout direction of the checkbox items. Vertical stacks items; horizontal places them in a row.",
+      "name": "orientation",
+      "type": "\"vertical\" | \"horizontal\""
+    },
+    {
+      "description": "Disables the entire group. Individual options can also set their own disabled flag via ChoiceOptionProp.disabled.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "HTML form name applied to each underlying checkbox input. Required for native form submission — all checkboxes share the same name so the form collects multiple values.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Extra CSS class on the group container div.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Manual children mode: used when `options` is omitted or empty. Render Checkbox items directly as children. You are responsible for composing each Checkbox with a Field for correct label/description layout.",
+      "name": "children",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Fires with the checked values array.",
+      "name": "onValueChange",
+      "type": "(value: string[]) => void"
+    }
+  ],
+  "related": [
+    "RadioGroup — use when only ONE selection is allowed at a time (mutually exclusive). CheckboxGroup = multiple, RadioGroup = single.",
+    "Checkbox (standalone) — use a bare `Checkbox` for a single boolean toggle (e.g. 'I agree to terms'). Use CheckboxGroup when you have 2+ related choices.",
+    "Checkbox.Group — alias; the same component is also accessible as `Checkbox.Group` (the Checkbox export attaches CheckboxGroup as `.Group`). Both are equivalent — prefer the named `CheckboxGroup` import for clarity in larger files.",
+    "Switch / Field — for a single binary on/off toggle with immediate effect (not a form submission value). Do not use CheckboxGroup to fake toggle rows.",
+    "Select (multi) — for a long list (10+ items) where space is limited; CheckboxGroup is better for ≤10 visible options that benefit from scanning all at once."
+  ],
+  "rules": [
+    3,
+    6,
+    23,
+    31
+  ],
+  "storyPath": "data-entry/CheckboxGroup.stories.tsx",
+  "tagline": "Multi-select checkbox list from an options array or manual children — use `options` prop for the data-driven path, never hand-roll individual Checkbox items in a group.",
+  "usage": [
+    "DO use the `options` prop for any data-driven list — it auto-generates IDs, handles checked state, and wires up Field (label + description) for each item. NEVER hand-roll individual `<Checkbox>` elements inside a loop when you have an options array.",
+    "DO pass `name` when inside an HTML form so each checkbox submits its value under the same field name, giving the server a multi-value array. Without `name`, native form submission silently drops all values.",
+    "Controlled vs uncontrolled: pass `value` + `onChange` together for controlled usage (e.g. react-hook-form). Pass `defaultValue` alone for uncontrolled usage. Do NOT mix both — if `value` is provided, `defaultValue` is ignored and onChange must update value externally or the UI freezes.",
+    "Each option's `description` renders as a secondary line below its label via Field — use it for help text or sub-copy; keep `label` short.",
+    "Group-level `disabled` disables all checkboxes. Individual `options[n].disabled` disables only that item. Both can coexist.",
+    "DO NOT wrap this inside another ARIA group or fieldset without removing the built-in `role=\"group\"` — it already provides the correct grouping semantics. Pair the group with a `<legend>` or visible heading for a11y."
+  ],
+  "useCases": [
+    "Permission / role selectors in admin forms — e.g. 'Select applicable roles: Admin, Editor, Viewer' where users can pick multiple.",
+    "Filter panels — e.g. 'Filter by status: Active, Pending, Archived' with horizontal orientation for compact toolbar layout.",
+    "Feature flag or settings toggles where multiple independent boolean flags share a label/description pair, loaded from a config array.",
+    "Multi-category tagging forms — e.g. 'Tag this invoice: Recurring, Billable, Internal' driven by an options array fetched from an API.",
+    "Onboarding checklists or multi-step preference screens where selections persist across steps via controlled `value`.",
+    "Accounting module: select which cost centres or account codes apply to a transaction, driven by a normalized options list."
+  ]
+}

package/agent/components/CodeBlock.json

@@ -0,0 +1,64 @@
+{
+  "example": "import { CodeBlock } from \"@godxjp/ui/data-display\";\n\n<CodeBlock maxHeight=\"sm\" language=\"json\" aria-label=\"Response body\">{body}</CodeBlock>\n<CodeBlock size=\"xs\" maxHeight=\"md\" aria-label=\"Console\">{consoleText}</CodeBlock>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "CodeBlock",
+  "props": [
+    {
+      "description": "The text. Pass a string, or a highlighter's spans tagged `data-code-token` (the twelve Shiki createCssVariablesTheme token names) — the package colours them from the `--code-block-token-*` knobs, so the consumer never writes a colour.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Soft-wrap long lines (`white-space: pre-wrap; overflow-wrap: anywhere`). `false` keeps lines intact and scrolls horizontally.",
+      "name": "wrap",
+      "type": "boolean"
+    },
+    {
+      "description": "Token presets, or one explicit CSS length such as {value:\"16rem\"}. Still keyboard scrollable.",
+      "name": "maxHeight",
+      "type": "\"sm\" | \"md\" | \"lg\" | \"none\" | { value: string }"
+    },
+    {
+      "defaultValue": "\"sm\"",
+      "description": "Type size: `sm` for bodies and snippets, `xs` for dense logs.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\""
+    },
+    {
+      "description": "Lands on `data-language`. No highlighter is bundled — bring your own and tag its output with `data-code-token` (gh#784).",
+      "name": "language",
+      "type": "string"
+    },
+    {
+      "description": "Extra classes on the `pre`.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Prose - renders whole documents (Markdown, CMS bodies) and delegates its `pre` treatment to the same tokens; use Prose when the block sits inside rendered content, CodeBlock for a standalone block.",
+    "Text - `as=\"code\"` is inline monospace for an identifier in a sentence, not a block.",
+    "Descriptions - `Descriptions.Item mono` is a mono VALUE in a label/value row.",
+    "CredentialReveal - a masked secret with copy; not for arbitrary text."
+  ],
+  "rules": [],
+  "storyPath": "data-display/CodeBlock.stories.tsx",
+  "tagline": "A block of preformatted text (request and response bodies, console output, snippets): mono, muted surface, soft-wrapped long lines by default, and an optional height cap that scrolls inside the block instead of pushing the page.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { CodeBlock } from \"@godxjp/ui/data-display\";`",
+    "DO give a block that can scroll (`maxHeight` or `wrap={false}`) an `aria-label`: it becomes a keyboard tab stop so the content is reachable without a mouse.",
+    "DO cap the height of anything that can be large (a 64 KB response body, a console dump) with `maxHeight`; the page keeps its rhythm and the block scrolls.",
+    "DON'T hand-roll `<pre className=\"max-h-64 overflow-auto rounded bg-muted p-2 whitespace-pre-wrap\">`: every one of those values is a copy of a token this component reads.",
+    "DON'T reach for `Text as=\"code\"` for a block: that is inline monospace with no wrapping axis. Use `Text as=\"code\"` for an identifier inside a sentence, CodeBlock for a block.",
+    "DON'T use CodeBlock for a single value in a Descriptions row: `Descriptions.Item mono` owns that (it breaks the value, not the row).",
+    "SYNTAX COLOUR (gh#784): CodeBlock does not highlight, but it DOES own the palette. Tag each span from your highlighter with `data-code-token` — the twelve names are Shiki createCssVariablesTheme's verbatim (comment, keyword, string, string-expression, function, constant, parameter, punctuation, link, inserted, deleted, changed, plus the block foreground) — and the package colours them. DON'T put `style={{ color }}` or a palette `className` on the spans: both are visual overrides, and the colour is not the consumer's to choose. Retheme with the `--code-block-token-*-color` knobs, which are role-mirrors, so light and dark follow the theme with no second palette."
+  ],
+  "useCases": [
+    "Request and response bodies of an HTTP trace (HAR) in a bug-report inbox: JSON up to 64 KB, lines up to 240 characters, wrapped and capped at `maxHeight=\"sm\"`.",
+    "Console output attached to a bug report: `size=\"xs\"` for density, `maxHeight=\"md\"`.",
+    "An API example in developer documentation: `language=\"bash\"` or `\"json\"`, no height cap.",
+    "A stack trace in an error detail sheet: `wrap={false}` so frames stay on one line, scrolled horizontally."
+  ]
+}

package/agent/components/Collapsible.json

@@ -0,0 +1,74 @@
+{
+  "example": "{`import { useState } from \"react\";\nimport { ChevronDown } from \"lucide-react\";\n// Money goes through Intl — the symbol, the grouping and the minor units are all locale data.\nconst money = new Intl.NumberFormat(\"ja-JP\", { style: \"currency\", currency: \"JPY\" });\nimport {\n  Collapsible,\n  CollapsibleTrigger,\n  CollapsibleContent,\n} from \"@godxjp/ui/data-display\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\nimport { Button, Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n// --- Uncontrolled (simplest) ---\n// The icon needs no margin of its own: Button spaces its own icon slot. The gap between the\n// trigger and the revealed body belongs to the Flex around them, and the body is a Card — a\n// rounded-md border div is a hand-rolled surface with the radius frozen at the call site.\nexport function InvoiceLineDetail() {\n  return (\n    <Collapsible>\n      <Flex direction=\"col\" align=\"start\" gap=\"sm\">\n        <CollapsibleTrigger asChild>\n          <Button variant=\"ghost\" size=\"sm\">\n            <ChevronDown aria-hidden=\"true\" />\n            Show tax breakdown\n          </Button>\n        </CollapsibleTrigger>\n        <CollapsibleContent>\n          <Card>\n            <CardContent>\n              <Flex direction=\"col\" gap=\"xs\">\n                <Text size=\"sm\">Consumption tax (10%): {money.format(1234)}</Text>\n                <Text size=\"sm\">Withholding tax: {money.format(0)}</Text>\n              </Flex>\n            </CardContent>\n          </Card>\n        </CollapsibleContent>\n      </Flex>\n    </Collapsible>\n  );\n}\n\n// --- Controlled (open driven externally) ---\nexport function FilterSection() {\n  const [open, setOpen] = useState(false);\n  return (\n    <Collapsible open={open} onOpenChange={setOpen}>\n      <Flex direction=\"col\" align=\"start\" gap=\"sm\">\n        <CollapsibleTrigger asChild>\n          <Button variant=\"outline\" size=\"sm\">\n            Advanced filters\n            <ChevronDown aria-hidden=\"true\" />\n          </Button>\n        </CollapsibleTrigger>\n        <CollapsibleContent>\n          {/* place filter controls here */}\n          <Text size=\"sm\" tone=\"muted\">Date range, entity, status…</Text>\n        </CollapsibleContent>\n      </Flex>\n    </Collapsible>\n  );\n}`}",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Collapsible",
+  "props": [
+    {
+      "description": "Controlled open state. When provided, pair with onOpenChange to keep in sync. Omit for uncontrolled behaviour.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Initial open state when used uncontrolled. Useful for auto-expanding when a child is active (e.g. sidebar nav group).",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Callback fired when the open state changes. Required in controlled mode.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Prevents the trigger from toggling the content. The trigger is still rendered but inert.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Applied to the root Collapsible element. Use for layout (e.g. sb-nav-group) — the root renders a div.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "On CollapsibleTrigger only — merges Radix trigger behaviour onto the single child element (e.g. a godx-ui Button) instead of rendering a default button. The child must accept onClick and aria-* props.",
+      "name": "asChild (CollapsibleTrigger)",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Accordion (from @godxjp/ui/data-entry or Radix) — use Accordion when only ONE section can be open at a time across a group; use Collapsible when each section is independent and can be open simultaneously.",
+    "Popover — use Popover when the revealed content should float above the layout in a portal overlay; use Collapsible when the content should push surrounding content down inline.",
+    "Dialog/Sheet — use Dialog or Sheet for modal or slide-over panels that demand full user attention; Collapsible stays in-flow and non-modal.",
+    "Tree (@godxjp/ui/data-display) — use Tree for hierarchical data that expands, collapses and is navigated by keyboard; use Collapsible for ad-hoc single-level toggle regions."
+  ],
+  "rules": [
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-display/Collapsible.stories.tsx",
+  "subParts": [
+    "CollapsibleContent",
+    "CollapsibleTrigger"
+  ],
+  "tagline": "Three-part compound (Collapsible + CollapsibleTrigger + CollapsibleContent) that toggles a region open/closed — never use just one part alone.",
+  "usage": [
+    "DO compose all three parts together: <Collapsible> wraps both <CollapsibleTrigger> and <CollapsibleContent>. Never render CollapsibleContent without a parent Collapsible — the open state lives on the root.",
+    "DO use asChild on CollapsibleTrigger when you want a godx-ui Button (or any styled element) to act as the trigger: <CollapsibleTrigger asChild><Button>Toggle</Button></CollapsibleTrigger>. Without asChild the trigger renders its own plain button.",
+    "DO pass defaultOpen={true} (uncontrolled) when the section should auto-expand on mount — for example, a sidebar nav group whose active child matches the current route.",
+    "DO use controlled mode (open + onOpenChange) when external UI — a separate button, route change, or search filter — needs to drive the open state independently of the trigger.",
+    "DON'T add hidden native <details>/<summary> as a fallback — the Radix primitive is already accessible (aria-expanded, aria-controls) out of the box.",
+    "DON'T put interactive controls (Buttons, links, inputs) inside CollapsibleTrigger itself unless using asChild — nested focusable elements break keyboard navigation. Put them inside CollapsibleContent instead."
+  ],
+  "useCases": [
+    "Sidebar navigation group: a top-level nav item with children collapses/expands its sub-items in the rail (used directly in the godx-ui Sidebar component with defaultOpen={active}).",
+    "Invoice line-item detail: an invoice row that expands inline to show tax breakdown, allocation notes, or audit trail without navigating away.",
+    "Filter panel section: a labelled group of filter controls (date range, entity, status) that can be collapsed to save vertical space in a dense accounting dashboard.",
+    "Read-more / long description: a truncated journal entry or payment memo that expands to full text on demand.",
+    "Settings sub-section: an optional advanced settings block that is hidden by default and revealed only when the user opts in.",
+    "Audit log detail: a compact log entry row that expands to show full diff, user, timestamp, and before/after values."
+  ]
+}

package/agent/components/ColorPicker.json

@@ -0,0 +1,87 @@
+{
+  "example": "import { useState } from \"react\";\nimport { ColorPicker, FormField } from \"@godxjp/ui/data-entry\";\n\nexport function BrandColorField() {\n  const [color, setColor] = useState(\"#2563eb\");\n\n  return (\n    <FormField id=\"brand-color\" label=\"Brand color\" className=\"max-w-xs\">\n      <ColorPicker\n        id=\"brand-color\"\n        value={color}\n        onValueChange={setColor}\n      />\n    </FormField>\n  );\n}\n\n// Compact swatch-only variant (no hex input)\nexport function SwatchOnly() {\n  const [color, setColor] = useState(\"#16a34a\");\n  return <ColorPicker value={color} onValueChange={setColor} showHexInput={false} />;\n}\n\n// Disabled state\nexport function DisabledColor() {\n  return <ColorPicker value=\"#6b7280\" disabled />;\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "ColorPicker",
+  "props": [
+    {
+      "description": "Initial uncontrolled color.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Native form field name.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"#2563eb\"",
+      "description": "The current hex color string (3- or 6-digit, with leading #). Component auto-prepends # if missing. Invalid hex values are discarded and the previous valid value is kept.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Called with the normalized, validated hex string whenever the user commits a new color — via the native swatch picker or by pressing Enter / blurring the hex input. Not called for invalid hex drafts.",
+      "name": "onChange",
+      "type": "(hex: string) => void"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Disables both the swatch input and the hex text input, preventing all user interaction.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "When true (default), renders an editable godx-ui Input alongside the swatch that shows the current hex value and lets the user type a hex string. Set to false for a compact swatch-only control.",
+      "name": "showHexInput",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Extra CSS class(es) applied to the root wrapper div. Use for layout sizing; avoid overriding design-token colours.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "DOM id applied to the hidden native <input type='color'>. Pass the FormField id here so the label's htmlFor targets this control correctly.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Fires with the committed hex string.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    }
+  ],
+  "related": [
+    "Input — use for plain text/number entry; use ColorPicker when the value is specifically a color hex code and you want a visual swatch.",
+    "Select / SearchSelect — use for choosing from a fixed palette of named colors (e.g. 'Red', 'Blue'); use ColorPicker for freeform hex color entry."
+  ],
+  "rules": [
+    2,
+    3,
+    6,
+    13
+  ],
+  "storyPath": "data-entry/ColorPicker.stories.tsx",
+  "tagline": "Native color-swatch picker with an optional editable hex input — always pass a valid 3- or 6-digit hex `value`; invalid hex is silently ignored and the previous value is restored.",
+  "usage": [
+    "DO wrap in FormField when a label or validation message is needed — pass the same id to both FormField and ColorPicker so htmlFor wires up correctly: `<FormField id='brand' label='Brand color'><ColorPicker id='brand' value={v} onValueChange={setV} /></FormField>`.",
+    "DO use controlled mode (value + onChange) — there is no defaultValue/uncontrolled path; always supply value.",
+    "DON'T pass an invalid or empty string to value — the component will flash the invalid color on the preview swatch. Always initialize state to a valid 3- or 6-digit hex (e.g. '#2563eb').",
+    "The hex Input is a live draft field — onChange is NOT called until the user presses Enter or blurs; only then is the value validated and the parent notified. Do not rely on onChange firing on every keystroke.",
+    "Set showHexInput={false} only for compact/inline contexts (icon pickers, table cells) where space is tight and keyboard hex entry is not needed.",
+    "NEVER hand-roll a color picker with raw <input type='color'> — always use this component; it normalizes hex, debounces draft state, and respects the design-token control styles."
+  ],
+  "useCases": [
+    "Brand / campaign color selection in settings or campaign creation forms where users need to pick or type an exact hex value.",
+    "Invoice or document theme customization — letting users pick accent colors that are stored and applied to PDF output.",
+    "Accounting dashboard category tagging — assigning a color code to GL account categories or chart-of-accounts nodes for visual grouping.",
+    "Product or inventory label colors in admin panels where a compact swatch (showHexInput={false}) fits inside a table cell or sidebar.",
+    "Design-token or CSS variable editor pages where the user needs precise hex entry alongside a visual swatch preview.",
+    "User-profile or team avatar color personalization forms."
+  ]
+}