@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/SearchInput.json

@@ -0,0 +1,98 @@
+{
+  "example": "import { SearchInput } from \"@godxjp/ui/data-entry\";\n\n<SearchInput placeholder=\"クーポン名・IDで検索\" value={search} onSearch={setSearch} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "SearchInput",
+  "props": [
+    {
+      "description": "Validation state the field paints — Ant Design `status`. `error` also reports `aria-invalid`, so the red boundary and what a screen reader hears are one fact; `warning` paints only, because a warning is not a validity failure. antd's `success`/`validating` are not implemented: antd only draws them together with its `hasFeedback` icon slot, which FormField owns here.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "defaultValue": "\"outlined\"",
+      "description": "Chrome level — Ant Design `variant`. `outlined` is the historical field; `filled` swaps the boundary for a tinted surface (dense forms); `borderless` drops both, for a field inside a box that already draws one. antd's fourth member `underlined` is deliberately absent — a single bottom rule is a Material convention and SmartHR, the JP authority here, draws every field as a full box.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "Called after a changed query settles. Never fires for the initial value on mount or callback-only rerenders. Optional when filtering uses onValueChange.",
+      "name": "onSearch",
+      "type": "(q: string) => void"
+    },
+    {
+      "description": "Controlled value.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"\"",
+      "description": "Initial uncontrolled value.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Input placeholder.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "defaultValue": "250",
+      "description": "Debounce delay (ms).",
+      "name": "debounce",
+      "type": "number"
+    },
+    {
+      "description": "Input id; pair with `label` or an external `<label htmlFor>`.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Optional visible label rendered above the search box (falls back to an sr-only label).",
+      "name": "label",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Fires on EVERY keystroke (immediate) — required to keep a controlled `value` responsive.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Accessible search name when there is no visible label.",
+      "name": "ariaLabel",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disable search input and clearing.",
+      "name": "disabled",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Input — use `Input` (inside `FormField`) when the search field is part of a submitted form and needs a `name` attribute, or when you need full `onChange` control without any debounce or clear button. SearchInput is the right pick when the field only triggers filtering, not form submission.",
+    "Toolbar — SearchInput is almost always placed as a direct child of `Toolbar`, which provides the surrounding strip, clear-all button, and active-filter state. Do not use SearchInput as a standalone header widget when a full filter strip (with selects etc.) already exists — compose them together.",
+    "Command — use `Command` + `CommandInput` when you need a keyboard-navigable command palette or combobox list with grouped items and keyboard selection. `Command` is only meaningful when paired with `CommandList`; SearchInput is the right pick for a plain filter box with no item-selection behavior.",
+    "Select (with showSearch) — when users must pick a value from a list AND search to narrow it, use `<Select options={...} showSearch>` (which has its own built-in search input). SearchInput is for filtering an external data set, not for value selection from an option list."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "data-entry/SearchInput.stories.tsx",
+  "tagline": "Debounced search box with a clear button. Fires onSearch (NOT onChange) after the debounce. Controlled (value) or uncontrolled (defaultValue).",
+  "usage": [
+    "DO: listen to `onSearch`, not `onChange`. The component debounces internally (default 250 ms) and fires `onSearch(q)` after the delay — never wire your filter logic to `onChange` on SearchInput because it does not expose one.",
+    "DO: choose controlled vs uncontrolled deliberately. Pass `value` + `onValueChange` together for controlled mode; optionally add `onSearch` for debounced effects (e.g. when search state lives in a URL param or shared parent). For local-only ephemeral search pass only `defaultValue` + `onSearch` — omitting `value` puts the component in uncontrolled mode.",
+    "DO: supply an `ariaLabel` (or visible `label`) when no adjacent label exists. Without either prop, SearchInput falls back to the i18n key `common.search` rendered as a visually-hidden `<Label>` — still accessible, but providing a context-specific string (e.g. `ariaLabel='請求書を検索'`) is more descriptive for screen readers.",
+    "DON'T: use SearchInput inside a `<form>` expecting native form submission. The component has no `name` prop and does not emit a form field value — it is a filter-trigger widget. For a form search field, use a plain `Input` inside `FormField`.",
+    "DON'T: hand-roll a debounced input when you need a search box. SearchInput ships the debounce, clear button (×), search icon, and accessible label — recreating these with a raw `<Input>` adds code and misses the UX contract.",
+    "DON'T: place SearchInput inside a `ToolbarGroup` wrapper — `ToolbarGroup` is for Select/DatePicker controls with a label chip. SearchInput goes directly as a child of `Toolbar` (or standalone above a table), not wrapped in `ToolbarGroup`."
+  ],
+  "useCases": [
+    "List-page filter bar: placed as the first child of `Toolbar` (before any `ToolbarGroup` children) to drive text-based filtering of a `DataTable`. The `onSearch` callback updates a query param or state variable that the table's data fetch reads.",
+    "Inline client-side search over a small in-memory list (e.g. a sidebar nav list, a transfer panel, a settings category list) where results narrow immediately as the user types without a server round-trip — use uncontrolled mode (`defaultValue`) so no state is needed in the parent.",
+    "URL-synced search: controlled mode where `value` comes from `useSearchParams()` and `onSearch` pushes to the URL, enabling deep-linkable, bookmarkable filtered views on invoice/transaction/customer index pages.",
+    "Panel or dialog search: filtering a long dropdown list, a tree, or a multi-item selection panel that does not use the built-in `Command` palette — SearchInput provides the search box while the parent renders the filtered result set.",
+    "Toolbar search on a data-heavy accounting page (e.g. journal-entry search, partner lookup in a subledger view) where the 250 ms debounce prevents a flood of API calls on every keystroke without requiring the developer to implement debounce logic."
+  ]
+}

package/agent/components/Segmented.json

@@ -0,0 +1,96 @@
+{
+  "example": "import { Segmented } from \"@godxjp/ui/data-entry\";\n\n<Segmented\n  aria-label=\"Theme\"\n  value={theme}\n  onValueChange={(next) => setTheme(next as AppTheme)}\n  options={[\n    { value: \"light\", label: \"Light\" },\n    { value: \"dark\", label: \"Dark\" },\n    { value: \"system\", label: \"System\" },\n  ]}\n/>\n\n<Segmented\n  aria-label=\"Status filter\"\n  value={status}\n  onValueChange={setStatus}\n  options={[\n    { value: \"all\", label: \"All\", count: 128 },\n    { value: \"active\", label: \"Active\", count: 96 },\n  ]}\n/>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Segmented",
+  "props": [
+    {
+      "defaultValue": "false",
+      "description": "antd `block` — stretch the bar to its container and share the width EQUALLY between the choices, so the selected pill does not resize as the label under it changes length.",
+      "name": "block",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd `vertical` — stack the choices in a column. It changes the ARROW KEYS as well as the layout: the primitive reads `orientation` to decide which arrows move the roving focus.",
+      "name": "vertical",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Control height tier — reads the shared `--control-height` ladder: xs 24px · sm 28px · md 32px · lg 36px. The TRACK measures exactly one control height, so the bar sits level with an Input, a Button or a ToggleGroup of the same step on the same row. Pick the step the ROW already has: xs (gh#719) is the one that fits a 24px-dense toolbar or audit-log row — before it, that row could only get a hand-rolled set of Buttons, which loses the radiogroup semantics and the arrow keys. xs is the DENSE step, not a smaller default: the track spends its 2px inset at every step, so the individual SEGMENT measures 20px and clears WCAG 2.2 SC 2.5.8 through the Spacing exception (adjacent segments 26.47px apart for a one-glyph label) rather than the 24px minimum. Keep labels at a glyph or more, and stay on sm or md wherever the row height is yours to choose.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "The closed set of choices, in reading order. `label` is the visible content AND the item's accessible name. Use `count` for a filter total — do not nest `Badge` in `label` (gh#602).",
+      "name": "options",
+      "type": "{ value: string; label: ReactNode; icon?: ReactNode; disabled?: boolean; count?: number | string; overflowCount?: number; showZero?: boolean; countLabel?: string }[]"
+    },
+    {
+      "description": "Controlled selection.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial selection.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Selection callback.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Disable the whole group.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Form field name — submits the selected value with a native form.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Root id, for a label that points at it.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Root class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "ToggleGroup (independently pressed buttons, or a multi-select toolbar)",
+    "RadioGroup (the same semantics with a vertical, described list)",
+    "Select (the same choice when the set is long or hidden by default)",
+    "Tabs (switches PANELS, not a value)"
+  ],
+  "rules": [
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-entry/Segmented.stories.tsx",
+  "tagline": "One-of-N from a small, closed, always-visible set — the enterprise Segmented / filter bar drawn on react-aria-components' RadioGroup. A track with the chosen item as a lifted slab. Reach for it INSTEAD OF a Select when there are 2-4 options and all of them fit on screen, and instead of ToggleGroup when exactly one must always be chosen.",
+  "usage": [
+    "DO use it for a closed set of 2-4 peer choices that are cheap to show — theme, view mode, a date range preset.",
+    "DO give it an aria-label (or aria-labelledby) — the group needs a name, and each item takes its own from its label.",
+    "DON'T use ToggleGroup for a one-of-N choice unless you also pass `disallowEmptySelection`: without it, type=single is a row of aria-pressed toggle buttons that can end up with nothing selected, which a setting can never be (gh#744). Segmented is the one-of-N control and needs no such switch.",
+    "DON'T use it past ~4 options — that is a Select. Up to four, a horizontal track WRAPS to a second row when its options cannot share one (a phone-width status filter with counts), so no label or count is truncated while its item fits on a row. `block` is the exception: it promises EQUAL widths, so it still truncates — don't use `block` for four labelled options at phone width.",
+    "DO show a short mark and speak a long name by putting BOTH in `label`: an aria-hidden span for the glyph and a VisuallyHidden for the words. `label` is a ReactNode, the item takes its accessible name from its content, and the glyph drops out of that name once it is aria-hidden — so a bar of circle/triangle/cross marks still announces the state in words. There is no separate accessible-name prop and there does not need to be.",
+    "DO pass per-option totals via `count` — the DS paints an opaque pill that reads on both the recessed track and the selected slab. Do not put `Badge` in `label` for counts: `secondary` is `--muted`, which is the track fill (1.00:1, gh#602).",
+    "DO stack with `vertical` when the labels are too long to sit side by side: a stacked row is a WHOLE `--control-height` tall, where a horizontal bar spends part of that height on the track padding so the bar as a whole lines up with an Input beside it. Inside a MobileShell, which scopes the control tier to the touch step, that is what makes each row a 44px target.",
+    "DO remember that `size` and any scoped `--control-height` both reach the track: the item height is composed on the Segmented root, not frozen at :root.",
+    "DO set `size=\"xs\"` for a 24px-dense row — an audit-log toolbar, a table header strip, a row that already carries `<Button size=\"xs\">` or an `xs` ToggleGroup. All three measure 24px off the same `--control-height-xs` step, so the row stays level, and the label type and the item inline padding step down with the band (gh#719). DON'T hand-roll that row out of Buttons to get the height: a segmented control is a radiogroup, and a row of buttons loses the arrow keys and the \"1 of 3, selected\" announcement."
+  ],
+  "useCases": [
+    "Theme switch (light / dark / system)",
+    "List vs board vs calendar view mode",
+    "Chart range: day / week / month",
+    "Status filter above a list, each option carrying its count (All 128 / Active 96 / Pending 12 / Archived 0)"
+  ]
+}

package/agent/components/Select.json

@@ -0,0 +1,397 @@
+{
+  "absorbed": [
+    "Combobox",
+    "Autocomplete",
+    "CountrySelect",
+    "SearchSelect",
+    "Typeahead",
+    "AsyncSelect"
+  ],
+  "example": "import {\n  Select,\n  SelectContent,\n  SelectGroup,\n  SelectItem,\n  SelectLabel,\n  SelectSeparator,\n  SelectTrigger,\n  SelectValue,\n} from \"@godxjp/ui/data-entry\";\nimport { Text } from \"@godxjp/ui/general\";\n// as=\"span\" on both: an option row is a phrasing context, so a <div> would be invalid HTML.\nimport { Flex } from \"@godxjp/ui/layout\";\n\n// ── 1. Data-driven (Ant-style) — static list, no search ──────────────────────\nexport function StatusSelect({ value, onChange }) {\n  return (\n    <Select\n      value={value}\n      onValueChange={onChange}\n      options={[\n        { value: \"draft\",    label: \"Draft\" },\n        { value: \"sent\",     label: \"Sent\" },\n        { value: \"paid\",     label: \"Paid\" },\n        { value: \"overdue\",  label: \"Overdue\" },\n      ]}\n      placeholder=\"Select status\"\n      name=\"status\"\n      id=\"status\"\n    />\n  );\n}\n\n// ── 2. Data-driven, searchable static list with groups ────────────────────────\nexport function CurrencySelect({ value, onChange }) {\n  return (\n    <Select\n      value={value}\n      onValueChange={onChange}\n      showSearch\n      options={[\n        { value: \"JPY\", label: \"Japanese Yen\",  group: \"Asia\" },\n        { value: \"VND\", label: \"Vietnamese Dong\", group: \"Asia\" },\n        { value: \"EUR\", label: \"Euro\",           group: \"Europe\" },\n        { value: \"GBP\", label: \"Pound Sterling\", group: \"Europe\" },\n      ]}\n      placeholder=\"Select currency\"\n      searchPlaceholder=\"Search currencies…\"\n      name=\"currency\"\n    />\n  );\n}\n\n// ── 3. Data-driven, async (loadOptions) ──────────────────────────────────────\nexport function AccountSelect({ value, onChange, selectedLabel }) {\n  async function loadOptions({ query, page }) {\n    const res = await fetch(`/api/accounts?q=${query}&page=${page}`);\n    const json = await res.json();\n    return { options: json.data, hasMore: json.hasMore };\n  }\n  return (\n    <Select\n      value={value}\n      onValueChange={onChange}\n      loadOptions={loadOptions}\n      selectedLabel={selectedLabel}\n      placeholder=\"Search accounts…\"\n      renderOption={(opt) => (\n        <Flex as=\"span\" align=\"center\" gap=\"xs\">\n          <Text as=\"span\" tone=\"muted\" mono>\n            {opt.value}\n          </Text>\n          {opt.label}\n        </Flex>\n      )}\n      name=\"account_id\"\n    />\n  );\n}\n\n// ── 4. Compound API — custom trigger content ──────────────────────────────────\nexport function PrioritySelect({ value, onValueChange }) {\n  return (\n    <Select value={value} onValueChange={onValueChange}>\n      <SelectTrigger size=\"sm\" id=\"priority\">\n        <SelectValue placeholder=\"Priority\" />\n      </SelectTrigger>\n      <SelectContent>\n        <SelectGroup>\n          <SelectLabel>Urgency</SelectLabel>\n          <SelectItem value=\"high\">High</SelectItem>\n          <SelectItem value=\"medium\">Medium</SelectItem>\n        </SelectGroup>\n        <SelectSeparator />\n        <SelectItem value=\"low\">Low</SelectItem>\n      </SelectContent>\n    </Select>\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Select",
+  "props": [
+    {
+      "description": "Select several options; value/defaultValue become string arrays. `tags` additionally ACCEPTS what was typed (a value that is not in the list), which is antd's own split between the two. The popup list of either mode renders as `Command split` (rows ruled, list padding 0, gh#699); retune it with --command-item-divider-color / --command-item-divider-width.",
+      "name": "mode",
+      "type": "\"multiple\" | \"tags\""
+    },
+    {
+      "description": "Maximum selected options; selected items remain removable.",
+      "name": "maxCount",
+      "type": "number"
+    },
+    {
+      "description": "Collapse extra selected labels.",
+      "name": "maxTagCount",
+      "type": "number"
+    },
+    {
+      "description": "Static option list. Passing this (or loadOptions) switches Select from the compound API to the data-driven API. An entry may be one of antd's nested GROUPS ({ label, options }) instead of a row; its heading becomes the same `group` a flat row carries. Rows in a foreign shape ({id,name}) go through fieldNames. Each option has { value, label, sublabel?, icon?, group?, disabled? }. `icon` (avatar / flag / lucide node) renders before the label in the rows AND on the trigger once selected. group buckets the option under an optgroup-style heading.",
+      "name": "options",
+      "type": "(SearchSelectOptionProp | { label: string; options: SearchSelectOptionProp[] })[]"
+    },
+    {
+      "description": "Async remote fetcher. Receives { query, page } (1-based). Must return { options, hasMore? }. Implies showSearch=true automatically.",
+      "name": "loadOptions",
+      "type": "(params: SearchSelectLoadParamsProp) => Promise<SearchSelectLoadResultProp>"
+    },
+    {
+      "defaultValue": "true when loadOptions is set or mode is multiple/tags, false otherwise",
+      "description": "Toggle the searchable combobox mode vs the plain listbox. The OBJECT form is antd's and configures the search in one place (passing it also turns search ON). NOTE the argument order: `showSearch.filterOption(input, option)` is antd's, while the long-standing top-level `filterOption(option, query)` keeps this library's; `filterOption: false` keeps every row, for a list the server already filtered.",
+      "name": "showSearch",
+      "type": "boolean | { filterOption?: boolean | ((input, option) => boolean); optionFilterProp?: \"label\" | \"value\" | \"sublabel\"; filterSort?; searchValue?: string; onSearch?: (value: string) => void; autoClearSearchValue?: boolean }"
+    },
+    {
+      "defaultValue": "\"\"",
+      "description": "Controlled selected value (data-driven API). Pass an empty string to represent no selection.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial value (data-driven API). The trigger shows the matching option's label at rest — including in searchable (showSearch) mode — so an edit form pre-filled from server data renders the label, not the placeholder. Selected option is marked by a background tint (no check icon).",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Change handler for the data-driven API. Receives the new value string and the matching option object. The signature follows `mode` / `labelInValue`, and a bare `(value, option) => …` is inferred for each (no annotation needed under `strict`, gh#679): single `string` / `SelectOption | undefined`; `mode=\"multiple\" | \"tags\"` `string[]` / `SelectOption[] | undefined`; `labelInValue` the `{ value, label }` shapes.",
+      "name": "onValueChange",
+      "type": "(value: string, option?: SearchSelectOptionProp) => void"
+    },
+    {
+      "description": "Custom per-option renderer for the dropdown ROWS. Defaults to label + optional sublabel. Does not change the trigger — use `labelRender` for that.",
+      "name": "renderOption",
+      "type": "(option: SearchSelectOptionProp) => React.ReactNode"
+    },
+    {
+      "description": "Custom renderer for the SELECTED value shown on the TRIGGER (`labelRender`) — avatar + name + role badge, etc. `option` is undefined for an async preset whose page hasn't loaded. Only used while a value is selected; the placeholder still shows when empty.",
+      "name": "labelRender",
+      "type": "(selected: { value: string; label: React.ReactNode; option?: SearchSelectOptionProp }) => React.ReactNode"
+    },
+    {
+      "description": "Display label for the current value when its option is not in the loaded page (async). Prevents a flash of the raw id.",
+      "name": "selectedLabel",
+      "type": "string"
+    },
+    {
+      "description": "Leading icon shown on the trigger for the current value when its option isn't loaded yet (async preset) — the trigger counterpart of `selectedLabel`, so an edit form pre-filled from the server shows the avatar/flag at rest.",
+      "name": "selectedIcon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Placeholder shown in the trigger when no value is selected.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "description": "Placeholder inside the search input (combobox mode only).",
+      "name": "searchPlaceholder",
+      "type": "string"
+    },
+    {
+      "description": "Message rendered when the filtered list is empty.",
+      "name": "emptyMessage",
+      "type": "string"
+    },
+    {
+      "description": "Message rendered while loadOptions is resolving.",
+      "name": "loadingMessage",
+      "type": "string"
+    },
+    {
+      "description": "Message rendered when an async loadOptions REJECTS — a distinct state from empty/loading. Defaults to a localized 'Couldn’t load options'. The panel shows this instead of a blank surface or a misleading 'no results'.",
+      "name": "errorMessage",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Show the clear ✕ when a value is selected (data-driven API). Off by default, as antd `allowClear` — a required select is never one click from empty. Pass it (or `allowClear`) on an optional field whose empty state is a valid answer.",
+      "name": "clearable",
+      "type": "boolean"
+    },
+    {
+      "description": "Label for the clear row (data-driven combobox mode).",
+      "name": "clearLabel",
+      "type": "string"
+    },
+    {
+      "description": "Disables the entire select.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Searchable mode only (showSearch/loadOptions). Value is shown (and the clear affordance hidden) but the popover cannot be opened — no new pick, no search. Mirrors the Input/NumberInput readOnly contract: stays focusable and still submits its value, unlike disabled.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Searchable mode only. Height tier forwarded to the SearchSelect trigger Button. For the compound API use SelectTrigger's own size prop instead (below).",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"full\"",
+      "description": "Trigger width on the data-driven API (options / loadOptions), searchable or not — the same axis SelectTrigger carries on the compound API. `full` is what a form field wants; `auto` is what a filter bar wants, so two Selects share one row instead of stacking (CONSUMER-RULES rule 5); `bounded` holds one width from --control-bounded-width for a trigger whose value varies in length. Never wrap a Select in a fixed-width Flex to get this.",
+      "name": "width",
+      "type": "\"full\" | \"auto\" | \"bounded\""
+    },
+    {
+      "description": "Searchable mode only. Controlled popover open state (uncontrolled by default). Pair with onOpenChange.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Searchable mode only. Fires on every open/close attempt — including ones ignored because open is externally pinned — so a controlled consumer stays in sync.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Searchable mode only. Controlled search-box query (uncontrolled by default). Pair with onSearchChange.",
+      "name": "search",
+      "type": "string"
+    },
+    {
+      "description": "Searchable mode only. Fires on every keystroke in the search box.",
+      "name": "onSearchChange",
+      "type": "(query: string) => void"
+    },
+    {
+      "description": "Searchable mode only, static options (ignored with loadOptions, which owns its own server-side filtering). Overrides the default label/value substring filter. Only consulted while the query is non-empty.",
+      "name": "filterOption",
+      "type": "(option: SearchSelectOptionProp, query: string) => boolean"
+    },
+    {
+      "description": "Searchable mode only. Custom error slot, overriding the default errorMessage row. retry() reloads from the first page.",
+      "name": "renderError",
+      "type": "(params: { message: string; retry: () => void }) => React.ReactNode"
+    },
+    {
+      "description": "Searchable mode only. Custom 'load more' affordance appended below the list while another page is available — pairs with (does not replace) the built-in scroll-triggered pagination.",
+      "name": "renderLoadMore",
+      "type": "(params: { hasMore: boolean; loading: boolean; loadMore: () => void }) => React.ReactNode"
+    },
+    {
+      "description": "Form field name. Submits the selected value via a hidden input (data-driven API). Required for uncontrolled form submission.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "HTML id for the trigger element. Wire to a <label htmlFor> for a11y.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Additional CSS classes applied to the trigger.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Test id on the trigger. Option items get ${data-testid}-option-${value} automatically.",
+      "name": "data-testid",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Compound API only. Size variant on the SelectTrigger sub-component.",
+      "name": "SelectTrigger size",
+      "type": "\"sm\" | \"md\""
+    },
+    {
+      "defaultValue": "\"full\"",
+      "description": "Compound API only. `full` fills the field column (inside FormField). `auto` sizes the trigger to its label — use it in a PageContainer `extra` slot, a toolbar or a footer row, where a full-width trigger swallows the row and truncates its siblings.",
+      "name": "SelectTrigger width",
+      "type": "\"full\" | \"auto\""
+    },
+    {
+      "defaultValue": "true",
+      "description": "Compound API only. Set false to omit the built-in chevron disclosure indicator from the DOM entirely (not a CSS hide) — for specialized triggers (icon-only, etc.) that render their own affordance, so no consumer descendant CSS is needed.",
+      "name": "SelectTrigger showIndicator",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `status`. `error` recolours the control AND sets aria-invalid (a colour-only error fails WCAG 2.2 SC 1.4.1); `warning` recolours only. An aria-invalid injected by FormField always wins.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "antd `variant` — the control surface. Default `outlined`. Drawn from --control-{surface,filled,borderless}-* tokens, so a theme retunes all three at once.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "antd `loading` — the FIELD is in flight: the trailing chevron becomes a spinner and the trigger reports aria-busy. Distinct from the list-level spinner an async loadOptions shows inside the popup.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `defaultOpen` — uncontrolled initial popup state. The popup opens once every running ancestor animation has finished (a Popover sliding in), so inside a Popover the listbox is placed below its settled trigger exactly like a click-open (gh#708); with nothing animating it is open on the first render. onOpenChange is not called for this initial open.",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd `allowClear` — the clear ✕ on the trigger while a value is selected. Default false, as in antd. The object form replaces the ✕ icon and/or its accessible label. Beats `clearable` when both are given.",
+      "name": "allowClear",
+      "type": "boolean | { clearIcon?: React.ReactNode; label?: string }"
+    },
+    {
+      "description": "antd `onClear` — fires after the value is cleared through the ✕.",
+      "name": "onClear",
+      "type": "() => void"
+    },
+    {
+      "description": "antd `notFoundContent` — the node shown when the popup has nothing to list. Outranks the string-only emptyMessage.",
+      "name": "notFoundContent",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `autoClearSearchValue` (default true) — clear the search box after a pick / on close. Set false to resume the same filtered list on the next open.",
+      "name": "autoClearSearchValue",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `filterSort` — orders what filterOption kept. Static options only; with loadOptions the server owns the order. Never mutates the caller's array.",
+      "name": "filterSort",
+      "type": "(a: SearchSelectOptionProp, b: SearchSelectOptionProp, info: { searchValue: string }) => number"
+    },
+    {
+      "description": "antd `optionRender` — per-option renderer in antd's own (option, { index }) shape. Outranks the older renderOption.",
+      "name": "optionRender",
+      "type": "(option: SearchSelectOptionProp, info: { index: number }) => React.ReactNode"
+    },
+    {
+      "description": "antd `menuItemSelectedIcon` — a decorative mark on the picked row. Off by default: the picked row is already marked by fill + weight, which costs no width.",
+      "name": "menuItemSelectedIcon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `popupMatchSelectWidth`. true (default) pins the popup to the trigger width, false lets it hug its rows, a number pins it to that many pixels.",
+      "name": "popupMatchSelectWidth",
+      "type": "boolean | number"
+    },
+    {
+      "description": "antd `fieldNames` — read rows in a FOREIGN shape ({id,name,children}) without copying them into a second array first. The same spelling Cascader and TreeSelect take. A foreign row needs a cast at the call site, exactly as theirs does.",
+      "name": "fieldNames",
+      "type": "{ label?: string; value?: string; options?: string; groupLabel?: string; disabled?: string }"
+    },
+    {
+      "description": "antd `labelInValue` — value and onValueChange speak {value,label} instead of a bare string (an array of them in multiple/tags). It earns its place on the async EDIT form: a record holding {value:'52',label:'東京本社'} renders the pick immediately, with no options page loaded and no flash of the raw id.",
+      "name": "labelInValue",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `prefix` — a node pinned BEFORE the value on the trigger (a currency mark, an icon). Deliberately not aria-hidden: for role=combobox the trigger's text is the VALUE, and a prefix that is part of the value belongs in it. The NAME still comes from the label.",
+      "name": "prefix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `suffixIcon` — replaces the trailing chevron; `null` removes the indicator entirely (antd's own replacement for the deprecated showArrow). While a value is clearable the ✕ owns that seat, as in antd.",
+      "name": "suffixIcon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `placement`, spelled on the LOGICAL inline axis (antd's bottomLeft/topRight cannot mirror for an RTL layout). Absent = below, start-aligned, with collision flipping — what a picker wants.",
+      "name": "placement",
+      "type": "\"bottomStart\" | \"bottomEnd\" | \"topStart\" | \"topEnd\""
+    },
+    {
+      "description": "antd `popupRender` — wrap the popup's own node to add a footer, a 'create' action or a hint line. It must still render originNode: dropping it leaves a popup with no options.",
+      "name": "popupRender",
+      "type": "(originNode: React.ReactNode) => React.ReactNode"
+    },
+    {
+      "description": "antd `listHeight` — the option list's max height in px for THIS instance. It overrides the --select-content-max-height token rather than hard-coding a height, so the token stays the default everywhere else.",
+      "name": "listHeight",
+      "type": "number"
+    },
+    {
+      "description": "antd `onPopupScroll` — fires on the option list's own scroll. It runs BESIDE the built-in infinite scroll (loadOptions paging), never instead of it.",
+      "name": "onPopupScroll",
+      "type": "(event: React.UIEvent<HTMLElement>) => void"
+    },
+    {
+      "description": "antd `optionFilterProp` — which field the default filter matches while searching. Unset matches BOTH label and value (this library's long-standing behaviour); antd's own default is value alone.",
+      "name": "optionFilterProp",
+      "type": "\"label\" | \"value\" | \"sublabel\""
+    },
+    {
+      "description": "antd `tokenSeparators` (multiple/tags) — characters that commit what has been typed. Typing or PASTING 'a,b,c' commits three values in ONE onValueChange. A pasted run is read off the clipboard, so a '\\n' separator works even though a single-line input strips newlines.",
+      "name": "tokenSeparators",
+      "type": "string[]"
+    },
+    {
+      "description": "antd `maxTagTextLength` (multiple/tags) — cut each chip's TEXT to this many characters (an ellipsis marks the cut). The value keeps its whole label.",
+      "name": "maxTagTextLength",
+      "type": "number"
+    },
+    {
+      "description": "antd `tagRender` (multiple/tags) — render one chip yourself. Exactly the shape TagInput's tagRender takes. The onClose handed in is the same remover the built-in ✕ calls, so a custom chip cannot end up unremovable; supplying tagRender withdraws the built-in ✕.",
+      "name": "tagRender",
+      "type": "(props: { value: string; label: React.ReactNode; onClose: () => void; index: number; disabled: boolean }) => React.ReactNode"
+    },
+    {
+      "description": "antd `onSelect` / `onDeselect` — fires as one option JOINS or LEAVES the selection, beside onValueChange (which reports the whole value).",
+      "name": "onSelect / onDeselect",
+      "type": "(value: string, option: SearchSelectOptionProp) => void"
+    },
+    {
+      "description": "antd `maxTagPlaceholder` — the node standing in for the values maxTagCount hid. A function receives the omitted values, so '+3 件' or a tooltip listing them is possible.",
+      "name": "maxTagPlaceholder",
+      "type": "React.ReactNode | ((omitted: { value: string; label: React.ReactNode }[]) => React.ReactNode)"
+    }
+  ],
+  "related": [
+    "Segmented — the same choice when the option set is small and worth showing at once. Select hides its options behind a trigger; Segmented lays them out, which reads better for 2-4 mutually exclusive options.",
+    "SearchSelect — the combobox engine Select delegates to when showSearch=true or loadOptions is set. Prefer Select with showSearch instead of reaching for SearchSelect directly (SearchSelect is now deprecated as a public API).",
+    "TreeSelect — use when options are hierarchical (parent/child tree). Not a drop-in for Select; has expand/collapse and a separate treeData prop.",
+    "Select with showSearch — use Select (with the `showSearch` prop) for typeahead/autocomplete lookup patterns instead of the removed Autocomplete component.",
+    "RadioGroup — use instead of Select when there are 2-4 mutually exclusive choices that must all be visible at once without opening a popover.",
+    "Combobox (if present) — compound cmdk-powered combobox for free-text + suggestion; Select is for strict value lists only."
+  ],
+  "rules": [
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-entry/Select.stories.tsx",
+  "subParts": [
+    "SelectContent",
+    "SelectGroup",
+    "SelectItem",
+    "SelectLabel",
+    "SelectScrollDownButton",
+    "SelectScrollUpButton",
+    "SelectSeparator",
+    "SelectTrigger",
+    "SelectValue"
+  ],
+  "tagline": "Polymorphic single-select: pass options/loadOptions for the data-driven (Ant-style) API, or compose sub-parts manually — never use a raw <select>.",
+  "usage": [
+    "DO use the data-driven API (options/loadOptions) for straightforward selects — it handles grouping, search, async, and custom rendering automatically. Only reach for the compound API when you need to inject arbitrary content into the trigger or listbox.",
+    "DO pass name= on the data-driven Select so the value is submitted with a native form or Inertia useForm. Without name= the value is React-only and will not appear in form data.",
+    "READING THE SELECTED CODE FROM THE DOM: the trigger publishes `data-value` = the selected VALUE, alongside the `data-field` key it inherits from FormField. Use that in e2e tests and screen automation — the trigger's visible text is the option LABEL (東京本社), and the only other place the code lives is the aria-hidden, 1px-clipped native <select> react-aria renders so a native submit (and browser autofill) carries the value. `data-value` is absent while nothing is selected, and it tracks uncontrolled picks too.",
+    "DO use loadOptions + selectedLabel together for async selects: selectedLabel prevents a flash of the raw id string while the first page loads.",
+    "A Select is safe inside a draggable element (a Kanban card with draggable=true) and inside a `contain: paint` / `transform` app region: the aria-hidden native <select> fallback is held at its static position beside the trigger (position: absolute, 1px clipped), so the browser's drag image stays the card's own box instead of reaching to the region's corner (gh#708). No wrapper or consumer CSS is needed.",
+    "DO name the control with FormField, aria-label, or a <label htmlFor> pointing at the trigger id — all three work. (An earlier version of this entry said htmlFor does NOT name the trigger. That was wrong: the trigger is a <button>, which is a labelable element, so <label for> does name it — src/components/data-entry/__tests__/select-rac.test.tsx pins it on both the old Radix base and the react-aria one, because 17 godx-task files name their Selects exactly that way.) What role=combobox does NOT do is take a name from its own content, so the visible value is the VALUE, never the name — a Select with no label of any kind is anonymous. Wrapping in <FormField label=…> stays the route that also wires helper, error and required. This holds for BOTH APIs; anything set directly on SelectTrigger wins.",
+    "DO treat loading / no-options / error / disabled as DISTINCT states. A data-driven Select never opens a blank popover: a static options=[] list auto-disables the trigger (opening it would show nothing), while an async loadOptions shows a loading row, then either the options, a localized empty affordance (override with emptyMessage), or an error affordance if the fetch rejects (override with errorMessage). Disable the Select when there is nothing to pick AND no async loader; keep it enabled (it opens to load/search) whenever loadOptions is set.",
+    "DON'T mix the two APIs: once you pass options or loadOptions, Select is data-driven — all compound sub-parts (SelectTrigger, SelectContent, SelectItem) are rendered internally. Do not wrap them manually.",
+    "DON'T use a raw <select> element. Select is the one control for all single-select use cases. The only allowed raw <select> is a hidden aria-hidden sr-only element kept as an e2e hook paired with a visible Select.",
+    "COMPOUND API sub-parts (when NOT using options/loadOptions): Select → SelectTrigger (contains SelectValue) → SelectContent → SelectItem. Optionally wrap items in SelectGroup + SelectLabel for headings, or add SelectSeparator between sections.",
+    "DO reach for open/onOpenChange (searchable mode) to drive the popover from outside — e.g. opening it programmatically after a validation error — and search/onSearchChange to seed or read the query text. Both fall back to internal state when omitted; onOpenChange/onSearchChange still fire either way so a controlled consumer stays in sync.",
+    "DO use readOnly (searchable mode) for a value that must stay visible and submittable but not editable in this view — it differs from disabled: the control stays focusable and its value still submits. allowClear / clearable is ignored while readOnly.",
+    "DO use filterOption (searchable mode, static options) when the default label/value substring match isn't right — e.g. filtering by a hidden code field. It is NOT consulted when loadOptions is set (that fetcher owns its own filtering).",
+    "DO use renderError + renderLoadMore (searchable mode) to replace the default error row with a branded retry affordance, or to pair a manual 'load more' button with (not instead of) the built-in scroll-triggered pagination.",
+    "DO set SelectTrigger showIndicator={false} (compound API) on a specialized trigger — icon-only, or one with its own affordance — instead of hiding [data-slot=select-chevron] with consumer CSS."
+  ],
+  "useCases": [
+    "Status filter on an invoice list — pass options=[{value:'draft',label:'Draft'},{value:'paid',label:'Paid'}] with onChange to drive a query param; no search needed so omit showSearch.",
+    "Legal-entity switcher — static options list with showSearch=true for client-side filtering when there are many entities; use selectedLabel to show the entity name before the full list loads.",
+    "Account category picker backed by an API — pass loadOptions to stream pages of accounts as the user types; use renderOption to show account code + name side by side; pass selectedLabel so the trigger shows the name on first render.",
+    "Grouped currency picker — set option.group='Asia' / 'Europe' on each option; the plain (non-search) data-driven mode renders SelectGroup headings automatically.",
+    "Form field in an accounting entry — use the compound API when the trigger must show a currency flag icon alongside the SelectValue; wire SelectTrigger size='sm' for dense table rows.",
+    "Required department select in a HR form — leave allowClear off (the default) so the user cannot clear the field once set; pair with name='department_id' for Inertia useForm submission. An OPTIONAL filter select passes allowClear so the user can return to 'no filter'.",
+    "Async account picker whose API can fail — pass loadOptions plus errorMessage so a rejected fetch shows a clear error affordance in the panel (not a blank surface or a false 'no results'); the loading and empty states are handled automatically."
+  ]
+}