{ "example": "{`import {\n Command,\n CommandEmpty,\n CommandGroup,\n CommandInput,\n CommandItem,\n CommandList,\n} from \"@godxjp/ui/data-entry\";\n\nfunction AccountQuickPick({ onSelect }: { onSelect: (id: string) => void }) {\n return (\n \n \n \n No accounts found.\n \n \n Sales Revenue\n \n \n Service Revenue\n \n \n \n \n Rent Expense\n \n \n Deprecated Account\n \n \n \n \n );\n}`}", "group": "data-entry", "importPath": "@godxjp/ui/data-entry", "name": "Command", "props": [ { "description": "Accessible label for the command menu. Not shown visually — used by screen readers.", "name": "label", "type": "string" }, { "defaultValue": "true", "description": "Set to false to disable automatic filtering and sorting. When false, you must conditionally render matching items yourself based on the search query.", "name": "shouldFilter", "type": "boolean" }, { "description": "Custom filter function. Returns a score between 0 (hidden) and 1 (best match). Defaults to command-score library scoring.", "name": "filter", "type": "(value: string, search: string, keywords?: string[]) => number" }, { "description": "Default selected item value on initial render (uncontrolled).", "name": "defaultValue", "type": "string" }, { "description": "Controlled state of the currently selected item value.", "name": "value", "type": "string" }, { "description": "Called when the selected item changes.", "name": "onValueChange", "type": "(value: string) => void" }, { "defaultValue": "false", "description": "When true, keyboard arrow-key navigation wraps from last item back to first and vice versa.", "name": "loop", "type": "boolean" }, { "defaultValue": "false", "description": "When true, pointer events cannot select items — keyboard only.", "name": "disablePointerSelection", "type": "boolean" }, { "defaultValue": "true", "description": "Set to false to disable ctrl+n/j/p/k vim-style navigation shortcuts.", "name": "vimBindings", "type": "boolean" }, { "defaultValue": "false", "description": "antd List `split`. Draws the list as ONE ruled box: group/list padding 0, rows full-bleed to the panel edge with a square highlight, a hairline border-block-end between rows and none after the last visible row, row content aligned with CommandInput's leading glyph. Sets `data-split` on the root; the parts need no prop. Tokens: --command-list-split-padding, --command-list-split-inset, --command-item-divider-width, --command-item-divider-color. Select does NOT render its popup split (it is a picker; compact unruled rows).", "name": "split", "type": "boolean" }, { "description": "Additional CSS classes merged onto the root div via cn().", "name": "className", "type": "string" }, { "description": "Controlled search string for the input.", "name": "CommandInput.value", "type": "string" }, { "description": "Called when the search input text changes.", "name": "CommandInput.onValueChange", "type": "(search: string) => void" }, { "description": "Accessible label for the list of suggestions. Not shown visually.", "name": "CommandList.label", "type": "string" }, { "description": "Unique value for this item. If omitted, inferred from children textContent — must be stable; provide explicitly when text changes between renders.", "name": "CommandItem.value", "type": "string" }, { "description": "Called when this item is selected via click or keyboard.", "name": "CommandItem.onSelect", "type": "(value: string) => void" }, { "defaultValue": "false", "description": "Prevents this item from being selected.", "name": "CommandItem.disabled", "type": "boolean" }, { "description": "Additional keywords matched during filtering that are not part of the visible label.", "name": "CommandItem.keywords", "type": "string[]" }, { "defaultValue": "false", "description": "When true, renders this item regardless of filtering results.", "name": "CommandItem.forceMount", "type": "boolean" }, { "description": "Visible heading rendered above items in this group.", "name": "CommandGroup.heading", "type": "React.ReactNode" }, { "description": "Required unique identifier for the group when no heading is provided.", "name": "CommandGroup.value", "type": "string" }, { "defaultValue": "false", "description": "When true, renders this group regardless of filtering.", "name": "CommandGroup.forceMount", "type": "boolean" }, { "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 \"\"` 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": [ "Select — `showSearch` / `loadOptions` is the fully managed (async) combobox built on Command + Popover; use it instead of building your own with Command.", "Select — simple dropdown for static option lists without type-to-filter; use Select when there are fewer than ~10 options and no search is needed.", "SearchInput — standalone text input with a search icon; use SearchInput for filtering visible page content (tables, lists) not for selecting from a command menu.", "CommandInput (sub-part) — the styled search input that only works inside a Command root; never use it alone as a general search field." ], "rules": [ 2, 3, 6, 23 ], "storyPath": "data-entry/command.tsx", "subParts": [ "CommandEmpty", "CommandGroup", "CommandInput", "CommandItem", "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": [ "DO compose the full tree: Command > CommandInput + CommandList > (CommandEmpty | CommandGroup > CommandItem | CommandItem). Every interactive element must live inside CommandList; items outside it are invisible to the keyboard engine.", "DO set shouldFilter={false} and manage filtering yourself when the options list comes from a server/async source (e.g. Select `loadOptions`). With shouldFilter=true the default client-side scoring runs over all rendered items automatically.", "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 ``, then `+ Create \"{q}\"` 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." ], "useCases": [ "Command palette / global action launcher (Cmd+K menu): wraps Command + CommandInput + grouped CommandItems for quick navigation across pages or actions.", "Popover-based combobox with server-side search: Command with shouldFilter={false} inside a Popover, managing the query state externally and filtering options before rendering — this is exactly how Select `showSearch` is built internally.", "Tree/cascader search panel: inject Command + CommandInput as a search header above a custom scroll area (no CommandList needed for the tree body) to get a styled, accessible search input — as Cascader and TreeSelect do.", "Multi-group option picker: use CommandGroup with heading to visually separate option categories (e.g. 'Accounts', 'Contacts', 'Documents') inside one dropdown with a single search box.", "Keyboard-first admin shortcut bar: embed Command with loop={true} and vimBindings={true} in a persistent sidebar for power-user keyboard navigation without page reloads." ] }