@agentero/design-system 0.33.0 → 0.34.0

package/mcp/manifests/components.json

@@ -2798,7 +2798,7 @@
           "id": "components-combobox--default",
           "name": "Default",
           "snippet": "const Default = () => (\n    <Combobox.Root items={STATES}>\n        <Combobox.Input placeholder=\"Search states\" aria-label=\"Search states\" />\n        <Combobox.Content>\n            <Combobox.Empty>No matches found</Combobox.Empty>\n            <Combobox.List>\n                {(state: string) => (\n                    <Combobox.Item key={state} value={state}>\n                        {state}\n                    </Combobox.Item>\n                )}\n            </Combobox.List>\n        </Combobox.Content>\n    </Combobox.Root>\n);",
-          "description": "The common case: options are already in memory and Base UI filters them against\nwhat you type. Selecting a row fills the input and closes the list. The field is\na search out of the box — a magnifier in front, a clear button once something is\npicked — and the list hangs from the whole field.",
+          "description": "The common case: options are already in memory and Base UI filters them against\nwhat you type. Selecting a row fills the input and closes the list. The field is\na search out of the box — a magnifier in front, a clear button once there is\ntext — and the list hangs from the whole field. Clearing drops the picked option.",
           "summary": "Search field with a magnifier and clear button over an in-memory list"
         },
         {
@@ -2837,20 +2837,20 @@
         {
           "id": "components-combobox--async-search",
           "name": "Async Search",
-          "snippet": "const AsyncSearch = () => {\n    const [query, setQuery] = useState('');\n\n    return (\n        // No `items` and `filter={null}`: the server did the filtering, the child renders what came\n        // back, and `isItemEqualToValue` keeps a re-fetched copy counting as the selected one.\n        <Combobox.Root\n            filter={null}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={(value, { reason }) => {\n                // Picking a row writes its label into the input; that is not a new search.\n                if (reason !== 'item-press') setQuery(value);\n            }}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content>\n                <Suspense fallback={<SkeletonRows />}>\n                    <AgencyItems query={query} />\n                </Suspense>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
-          "description": "Options fetched as you type, the way the apps load data: the rows are a component\nthat suspends on the request, so a `Suspense` boundary inside `Content` shows\nplaceholder rows until they land. Nothing tracks `loading` by hand and no stale\nlist lingers under the wait: the data is read by query, which is also what makes\nout-of-order responses harmless. Drop a `useSuspenseQuery` where `use()` is."
+          "snippet": "const AsyncSearch = () => {\n    const [query, setQuery] = useState('');\n    // The rows read the deferred query: while the new one suspends, React keeps rendering the\n    // old rows instead of falling back to the placeholders.\n    const deferredQuery = useDeferredValue(query);\n    const isStale = query !== deferredQuery;\n\n    return (\n        // No `items` and `filter={null}`: the server did the filtering, the child renders what came\n        // back, and `isItemEqualToValue` keeps a re-fetched copy counting as the selected one.\n        <Combobox.Root\n            filter={null}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={(value, { reason }) => {\n                // Picking a row writes its label into the input; that is not a new search.\n                if (reason !== 'item-press') setQuery(value);\n            }}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content aria-busy={isStale || undefined}>\n                <Suspense fallback={<SkeletonRows />}>\n                    <AgencyItems query={deferredQuery} />\n                </Suspense>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
+          "description": "Options fetched as you type, the way the apps load data: the rows are a component\nthat suspends on the request, so a `Suspense` boundary inside `Content` shows\nplaceholder rows until the first results land. The rows read a deferred copy of\nthe query, so a new search keeps the previous rows on screen while it loads and\n`Content` is marked busy until they are replaced; the placeholders never come\nback. Nothing tracks `loading` by hand, and reading the data by query is what\nmakes out-of-order responses harmless. With react-query, drop a\n`useSuspenseQuery` where `use()` is, or use `placeholderData: keepPreviousData`\nwith a plain `useQuery` for the same behaviour."
         },
         {
           "id": "components-combobox--async-search-with-status",
           "name": "Async Search With Status",
-          "snippet": "const AsyncSearchWithStatus = () => {\n    const [results, setResults] = useState<Agency[]>([]);\n    const [isLoading, setIsLoading] = useState(false);\n    // Only the latest request may land; fast typing returns responses out of order.\n    const latestRequest = useRef(0);\n\n    const onInputValueChange = async (query: string) => {\n        const request = ++latestRequest.current;\n        if (query.trim().length < MIN_QUERY_LENGTH) {\n            setResults([]);\n            setIsLoading(false);\n            return;\n        }\n\n        // The previous rows go before the wait starts: a list that no longer matches what is typed\n        // must not sit under the loading state.\n        setResults([]);\n        setIsLoading(true);\n        const agencies = await searchAgencies(query);\n        if (request !== latestRequest.current) return;\n\n        setResults(agencies);\n        setIsLoading(false);\n    };\n\n    return (\n        // `filter={null}` hands filtering to the server; `filteredItems` is what came back.\n        <Combobox.Root\n            items={results}\n            filteredItems={results}\n            filter={null}\n            minInputLength={MIN_QUERY_LENGTH}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={onInputValueChange}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content aria-busy={isLoading || undefined}>\n                {/* The rows show the wait; `Status` only announces it. */}\n                <Combobox.Status className=\"sr-only\">\n                    {isLoading ? 'Searching…' : undefined}\n                </Combobox.Status>\n                {isLoading && <SkeletonRows />}\n                <Combobox.Empty>{isLoading ? undefined : 'No agencies found'}</Combobox.Empty>\n                <Combobox.List>\n                    {(agency: Agency) => (\n                        <Combobox.Item key={agency.id} value={agency}>\n                            {agency.name}\n                        </Combobox.Item>\n                    )}\n                </Combobox.List>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
-          "description": "The same search without Suspense, for a consumer that gets a `loading` flag from\nits data layer instead: `filter={null}`, the rows arrive through `filteredItems`,\n`Content` is marked busy and `Status` announces the wait. The list is cleared\nbefore each request and a request that is no longer the latest is dropped.\n\n`minInputLength` keeps the list shut until two characters are typed — focusing\nthe field opens nothing, and deleting back under the minimum closes it — and\nno request goes out for a shorter query either.",
+          "snippet": "const AsyncSearchWithStatus = () => {\n    const [results, setResults] = useState<Agency[]>([]);\n    const [isLoading, setIsLoading] = useState(false);\n    // Only the latest request may land; fast typing returns responses out of order.\n    const latestRequest = useRef(0);\n\n    const onInputValueChange = async (query: string) => {\n        const request = ++latestRequest.current;\n        if (query.trim().length < MIN_QUERY_LENGTH) {\n            setResults([]);\n            setIsLoading(false);\n            return;\n        }\n\n        // The previous rows stay through the wait, marked busy, rather than blinking out and back.\n        setIsLoading(true);\n        const agencies = await searchAgencies(query);\n        if (request !== latestRequest.current) return;\n\n        setResults(agencies);\n        setIsLoading(false);\n    };\n\n    return (\n        // `filter={null}` hands filtering to the server; `filteredItems` is what came back.\n        <Combobox.Root\n            items={results}\n            filteredItems={results}\n            filter={null}\n            minInputLength={MIN_QUERY_LENGTH}\n            itemToStringLabel={(agency: Agency) => agency.name}\n            isItemEqualToValue={(a: Agency, b: Agency) => a.id === b.id}\n            onInputValueChange={onInputValueChange}>\n            <Combobox.Input placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n            <Combobox.Content aria-busy={isLoading || undefined}>\n                {/* The rows show the wait; `Status` only announces it. */}\n                <Combobox.Status className=\"sr-only\">\n                    {isLoading ? 'Searching…' : undefined}\n                </Combobox.Status>\n                {isLoading && results.length === 0 && <SkeletonRows />}\n                <Combobox.Empty>{isLoading ? undefined : 'No agencies found'}</Combobox.Empty>\n                <Combobox.List>\n                    {(agency: Agency) => (\n                        <Combobox.Item key={agency.id} value={agency}>\n                            {agency.name}\n                        </Combobox.Item>\n                    )}\n                </Combobox.List>\n            </Combobox.Content>\n        </Combobox.Root>\n    );\n};",
+          "description": "The same search without Suspense, for a consumer that gets a `loading` flag from\nits data layer instead: `filter={null}`, the rows arrive through `filteredItems`,\n`Content` is marked busy and `Status` announces the wait. Placeholder rows show\nonly while there is nothing to show yet; after that, the previous rows stay\nuntil the new ones replace them. A request that is no longer the latest is\ndropped.\n\n`minInputLength` keeps the list shut until two characters are typed — focusing\nthe field opens nothing, and deleting back under the minimum closes it — and\nno request goes out for a shorter query either.",
           "summary": "API search that waits for two characters, with loading status"
         },
         {
           "id": "components-combobox--inside-field-text",
           "name": "Inside Field Text",
-          "snippet": "const InsideFieldText = () => (\n    <FieldText invalid required>\n        <Label>Agency</Label>\n        <Combobox.Root items={STATES}>\n            <Combobox.Input placeholder=\"Search agencies\" />\n            <Combobox.Content>\n                <Combobox.Empty>No matches found</Combobox.Empty>\n                <Combobox.List>\n                    {(state: string) => (\n                        <Combobox.Item key={state} value={state}>\n                            {state}\n                        </Combobox.Item>\n                    )}\n                </Combobox.List>\n            </Combobox.Content>\n        </Combobox.Root>\n        <Field.Description>The agency this agent will be added to.</Field.Description>\n        <Field.Error errors={[{ message: 'Pick an agency from the list' }]} />\n    </FieldText>\n);",
+          "snippet": "const InsideFieldText = () => (\n    <FieldText invalid required>\n        <Label>Agency</Label>\n        <Combobox.Root items={STATES}>\n            <Combobox.Input placeholder=\"Search agencies\" />\n            <Combobox.Content>\n                <Combobox.Empty>No matches found</Combobox.Empty>\n                <Combobox.List>\n                    {(state: string) => (\n                        <Combobox.Item key={state} value={state}>\n                            {state}\n                        </Combobox.Item>\n                    )}\n                </Combobox.List>\n            </Combobox.Content>\n        </Combobox.Root>\n        <Field.Error errors={[{ message: 'Pick an agency from the list' }]} />\n        <Field.Description>The agency this agent will be added to.</Field.Description>\n    </FieldText>\n);",
           "description": "Dropped into a `FieldText`, the input takes the label, the description and\nthe error from the field with nothing wired by hand: `Combobox.Input` reads the\nsame `InputContext` the plain `Input` does. It also points `aria-labelledby`\nat the label, so the name survives the list opening: Base UI then hides the\nrest of the page from assistive technology, label included, and a\n`<label for>` alone would stop naming the input."
         },
         {
@@ -5295,7 +5295,7 @@
           "Field for a single-line text control, wiring the Input inside it"
         ],
         "example": [
-          "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</FieldText>"
+          "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</FieldText>"
         ]
       },
       "description": "FieldText is a `Field.Root` for a single-line text control. It provides\n`InputContext`, so the `Input` inside associates itself with the label and\nthe messages and takes `invalid`, `required`, `disabled` and `readOnly` from\nthe field — no `id`, `htmlFor`, `aria-describedby` or `aria-invalid` written\nby hand.\n\nIt knows nothing about form libraries, and its contexts compose: a provider\nnested inside it can extend `InputContext` with `value`, `onChange`, `onBlur`\nand `name`, and `FieldContext` with the errors, as the last story shows.",
@@ -5310,7 +5310,7 @@
             "Field for a single-line text control, wiring the Input inside it"
           ],
           "example": [
-            "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</FieldText>"
+            "<FieldText invalid={!!error} required>\n  <Label>Email</Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</FieldText>"
           ]
         },
         "props": {
@@ -5504,7 +5504,7 @@
           "Wraps a label, control, description and error into one field"
         ],
         "example": [
-          "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</Field.Root>"
+          "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</Field.Root>"
         ]
       },
       "description": "Field lays out a single form field — label, control, helper text and error —\nand wires the accessibility relationships between them. `Field.Root`\ngenerates the ids and shares them through context: `Label` reads\n`LabelContext`, `Field.Description` and `Field.Error` read `FieldContext`,\nand a `Field<X>` such as `FieldText` provides the control's context. Nobody\npasses an `id` by hand.\n\nPresentational and form-library agnostic: pass `invalid` and the error\nmessages from whatever validates the form. Spacing between fields belongs to\n`Field.Group`, never to a margin on the field itself.\n\n`Field.Description` and `Field.Error` register themselves with the root, so\nthe control's `aria-describedby` lists exactly the messages on screen and is\nabsent when there is none.",
@@ -5519,7 +5519,7 @@
             "Wraps a label, control, description and error into one field"
           ],
           "example": [
-            "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n  <Field.Error errors={[error]} />\n</Field.Root>"
+            "<Field.Root invalid={!!error} required>\n  <Field.Label>Email</Field.Label>\n  <Input type=\"email\" />\n  <Field.Error errors={[error]} />\n  <Field.Description>We only use this for policy documents.</Field.Description>\n</Field.Root>"
           ]
         },
         "props": {
@@ -5718,6 +5718,13 @@
           "description": "`Field.Error` renders nothing without a message, so it can stay mounted and\nreceive `undefined` entries while the field is valid. With no description\neither, the control carries no `aria-describedby` at all.",
           "summary": "Error stays mounted and renders nothing while valid"
         },
+        {
+          "id": "components-field--error-before-description",
+          "name": "Error Before Description",
+          "snippet": "const ErrorBeforeDescription = () => {\n    const [error, setError] = useState<string>();\n\n    return (\n        <div className=\"flex flex-col items-start gap-4\">\n            <Field.Root\n                orientation=\"vertical\"\n                disabled={false}\n                readOnly={false}\n                required={false}\n                invalid={!!error}>\n                <Label>Tax ID</Label>\n                <DemoInput inputMode=\"numeric\" />\n                <Field.Error id=\"tax-id-error\">{error}</Field.Error>\n                <Field.Description>Nine digits, with or without the dash.</Field.Description>\n            </Field.Root>\n            <button type=\"button\" onClick={() => setError('Enter the tax ID.')}>Validate\n                                </button>\n        </div>\n    );\n};",
+          "description": "The error sits right under the control and is announced before the\ndescription, even when it appears after the description is on screen and\ncarries an `id` of its own.",
+          "summary": "Error announced before the description, whenever it appears"
+        },
         {
           "id": "components-field--disabled",
           "name": "Disabled",
@@ -5795,7 +5802,7 @@
         "displayName": "FormText",
         "exportName": "FormText",
         "filePath": "/home/runner/work/design-system/design-system/src/form-text/index.ts",
-        "description": "A complete text field bound to one react-hook-form value: label, `Input`,\nhelper text and validation error, laid out in the standard order and wired\nthrough `useController`. It renders inside a `Form.Root`, which provides the\nform, and needs only a `name`, which on a typed form must point at a string\n(`FormTextPath`). The `required`, `invalid` and error states\nreach the label, the input's `aria-*` attributes and the message with no\nids written by hand.\n\nUse it for the common case: a labelled single-line input in a form. When\nthe layout is different — an input with addons, another control, a\nmessage rendered elsewhere — compose the primitives yourself:\n`useController` with [FieldText](?path=/docs/components-fieldtext--docs),\n`Label`, `Input`, `Field.Description` and `Field.Error`. `FormText` adds no\nbehaviour of its own over that composition.\n\nErrors come from `useController`'s per-field state, never from\n`formState.errors`, so the message stays fresh under the React Compiler.\nWith `criteriaMode: 'all'` on the form the error carries every rule that\nfailed and `Field.Error` lists them all. An error on an array or object path\n(`error.root`) is not this field's: render a `Field.Error` for it where the\ngroup lives.",
+        "description": "A complete text field bound to one react-hook-form value: label, `Input`,\nvalidation error and helper text, laid out in the standard order and wired\nthrough `useController`. It renders inside a `Form.Root`, which provides the\nform, and needs only a `name`, which on a typed form must point at a string\n(`FormTextPath`). The `required`, `invalid` and error states\nreach the label, the input's `aria-*` attributes and the message with no\nids written by hand.\n\nUse it for the common case: a labelled single-line input in a form. When\nthe layout is different — an input with addons, another control, a\nmessage rendered elsewhere — compose the primitives yourself:\n`useController` with [FieldText](?path=/docs/components-fieldtext--docs),\n`Label`, `Input`, `Field.Description` and `Field.Error`. `FormText` adds no\nbehaviour of its own over that composition.\n\nErrors come from `useController`'s per-field state, never from\n`formState.errors`, so the message stays fresh under the React Compiler.\nWith `criteriaMode: 'all'` on the form the error carries every rule that\nfailed and `Field.Error` lists them all. An error on an array or object path\n(`error.root`) is not this field's: render a `Field.Error` for it where the\ngroup lives.",
         "jsDocTags": {
           "summary": [
             "Label, Input, description and error bound to one react-hook-form field"
@@ -6021,7 +6028,7 @@
             "type": {
               "name": "ReactNode"
             },
-            "description": "Helper text shown under the control and announced through its\n`aria-describedby`. Use it for guidance the user needs before typing; put\ndetails worth a click in `tooltip` instead.",
+            "description": "Helper text shown under the control, below the error when there is one,\nand announced through its `aria-describedby`. Use it for guidance the\nuser needs before typing; put details worth a click in `tooltip` instead.",
             "defaultValue": null,
             "parent": {
               "name": "FormTextProps",
@@ -6156,6 +6163,13 @@
           "description": "`rules` are react-hook-form's, and `name` accepts nested paths typed against\nthe form's values through the generic. `rules.required` validates but does\nnot mark the field required: that stays an explicit `required` prop.",
           "summary": "Nested path with validation rules, typed through the generic"
         },
+        {
+          "id": "components-formtext--error-and-description",
+          "name": "Error And Description",
+          "snippet": "const ErrorAndDescription = () => {\n    const methods = useForm<TaxValues>({ defaultValues: { taxId: '' } });\n\n    return (\n        <Form.Root\n            methods={methods}\n            onSubmit={onSubmit}\n            aria-label=\"Tax details\"\n            className=\"flex flex-col items-start gap-7\">\n            <FormText\n                name=\"taxId\"\n                label=\"Tax ID\"\n                description=\"Nine digits, with or without the dash.\"\n                rules={{ required: 'Enter the tax ID.' }}\n                inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}\n            />\n            <Button type=\"submit\">Save</Button>\n        </Form.Root>\n    );\n};",
+          "description": "The error sits right under the input and the description stays below it, so\nthe message lands next to the value it is about. Screen readers announce\nthem in the same order.",
+          "summary": "Error under the input, above the helper text"
+        },
         {
           "id": "components-formtext--all-errors",
           "name": "All Errors",
@@ -6538,7 +6552,7 @@
           "id": "components-inputgroup--default",
           "name": "Default",
           "snippet": "const Default = () => (\n    <InputGroup.Root>\n        <InputGroup.Addon>\n            <IconSearch />\n        </InputGroup.Addon>\n        <Input type=\"search\" placeholder=\"Search agencies\" aria-label=\"Search agencies\" />\n    </InputGroup.Root>\n);",
-          "description": "A search field: the icon leads and the input takes the rest of the frame.\nPressing the icon focuses the input, and the frame — not the input — draws the\nfocus ring, so the two never show a double border.",
+          "description": "A search field: the icon leads and the input takes the rest of the frame.\nPressing the icon focuses the input, and the frame — not the input — draws the\nfocus ring, so the two never show a double border. A search field with a\nclear button and a loading state is\n[InputSearch](?path=/docs/components-inputsearch--docs), built on this frame.",
           "summary": "Leading icon addon with the frame drawing the focus ring"
         },
         {
@@ -6595,11 +6609,6 @@
           "description": "Inside a `FieldText` nothing changes for the group: the `Input` reads the\nfield's context at any depth, so the label names it and the description\ndescribes it with no ids written by hand. The frame is not in the way.",
           "summary": "Label and description reaching the input through the frame"
         },
-        {
-          "id": "components-inputgroup--search-field",
-          "name": "Search Field",
-          "snippet": "const SearchField = () => (\n    <form onSubmit={handleSearchSubmit}>\n        <FieldStates\n            label=\"Agency\"\n            tooltip=\"Search by agency name or NPN.\"\n            required\n            error=\"Pick an agency from the list.\">\n            <SearchInput />\n        </FieldStates>\n    </form>\n);"
-        },
         {
           "id": "components-inputgroup--email-field",
           "name": "Email Field",
@@ -6622,7 +6631,7 @@
           "summary": "Phone field with a leading country code picker, valid and invalid"
         }
       ],
-      "import": "import {\n    Button,\n    Divider,\n    DropdownMenu,\n    Field,\n    FieldText,\n    IconCancel,\n    IconKeyboardArrowDown,\n    IconSearch,\n    Input,\n    InputGroup,\n    Label,\n    Tag,\n} from \"@agentero/design-system\";"
+      "import": "import {\n    Button,\n    Divider,\n    DropdownMenu,\n    Field,\n    FieldText,\n    IconKeyboardArrowDown,\n    IconSearch,\n    Input,\n    InputGroup,\n    Label,\n    Tag,\n} from \"@agentero/design-system\";"
     },
     "components-inputpassword": {
       "id": "components-inputpassword",
@@ -6730,6 +6739,168 @@
       ],
       "import": "import { Field, FieldText, InputPassword, Label } from \"@agentero/design-system\";"
     },
+    "components-inputsearch": {
+      "id": "components-inputsearch",
+      "name": "InputSearch",
+      "path": "./src/input-search/input-search.stories.tsx",
+      "jsDocTags": {
+        "summary": [
+          "Search input with a leading icon, a clear button and a loading slot"
+        ],
+        "dataAttribute": [
+          "{string} data-slot - Always set to \"input-search\" on the frame"
+        ],
+        "example": [
+          "<InputSearch\n  aria-label=\"Search agencies\"\n  value={query}\n  onChange={event => setQuery(event.target.value)}\n  isLoading={isFetching}\n/>"
+        ]
+      },
+      "description": "InputSearch is a search field with a magnifier in front and a clear button\nonce there is text. It is an `Input` of `type=\"search\"` inside an\n`InputGroup`: `className` styles the frame and every other prop reaches the\n`<input>`. Clearing reports a real change event with an empty value, and\n`isLoading` swaps the clear button for a spinner.",
+      "summary": "Search input with a leading icon, a clear button and a loading slot",
+      "reactComponentMeta": {
+        "displayName": "InputSearch",
+        "exportName": "InputSearch",
+        "filePath": "/home/runner/work/design-system/design-system/src/input-search/input-search.tsx",
+        "description": "InputSearch is a search field: a magnifier in front of the text and, once\nthere is text, a clear button after it, named \"Clear search\" unless\n`clearLabel` says otherwise. The clear button empties the field\nand puts focus back in it, and it reports the change through `onChange` like\na keystroke would: a real change event whose `event.target.value` is `''`,\nso a controlled field, an uncontrolled one and one registered with\nreact-hook-form all clear the same way. While `isLoading` is set, a spinner\ntakes the clear button's place. The clear button is not rendered while the\ninput is disabled, whether `disabled` comes from the prop, from a\nsurrounding `FieldText` or from a `<fieldset disabled>`.\n\nIt is an [Input](?path=/docs/components-input--docs) of `type=\"search\"`\ninside an [InputGroup](?path=/docs/components-inputgroup--docs) frame, so\nit is announced as a search box. `className` styles the frame. Every other\nprop goes to the `<input>`: the `ref`, `id`, `name`, `value`, `onChange`,\n`aria-*` and every other standard attribute. Only `type` is not accepted.\n`placeholder` defaults to `'Search'`. Inside a `FieldText` the input takes\nits label, messages and states from the field as a plain `Input` does. The\ninvalid state comes from `aria-invalid`, and the frame paints the\ndestructive border.\n\nDo not use it to pick a value from a list; that is\n[Combobox](?path=/docs/components-combobox--docs), whose `search` field is\ndrawn by InputSearch. For a filter that should\nrun only once the user pauses typing, use `DebouncedInputSearch`.",
+        "jsDocTags": {
+          "summary": [
+            "Search input with a leading icon, a clear button and a loading slot"
+          ],
+          "dataAttribute": [
+            "{string} data-slot - Always set to \"input-search\" on the frame"
+          ],
+          "example": [
+            "<InputSearch\n  aria-label=\"Search agencies\"\n  value={query}\n  onChange={event => setQuery(event.target.value)}\n  isLoading={isFetching}\n/>"
+          ]
+        },
+        "props": {
+          "size": {
+            "name": "size",
+            "required": false,
+            "type": {
+              "name": "enum",
+              "raw": "\"sm\" | \"md\" | \"lg\"",
+              "value": [
+                {
+                  "value": "\"sm\""
+                },
+                {
+                  "value": "\"md\""
+                },
+                {
+                  "value": "\"lg\""
+                }
+              ]
+            },
+            "description": "Control height. Defaults to `'md'`.\n- `sm` (32px) — dense layouts where vertical space is tight.\n- `md` (40px) — standard form density.\n- `lg` (48px) — low-density forms and larger touch targets. Also raises\n  the text to `base` and the corner radius to `lg`.",
+            "defaultValue": null,
+            "parent": {
+              "name": "InputProps",
+              "fileName": "src/input/input.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/input/input.tsx"
+              }
+            ]
+          },
+          "isLoading": {
+            "name": "isLoading",
+            "required": false,
+            "type": {
+              "name": "boolean"
+            },
+            "description": "Shows a spinner at the end of the frame, in place of the clear button,\nwhile the results for the current text are on their way. Defaults to\n`false`.",
+            "defaultValue": {
+              "value": "false"
+            },
+            "parent": {
+              "name": "InputSearchProps",
+              "fileName": "src/input-search/input-search.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/input-search/input-search.tsx"
+              }
+            ]
+          },
+          "clearLabel": {
+            "name": "clearLabel",
+            "required": false,
+            "type": {
+              "name": "string"
+            },
+            "description": "Accessible name of the clear button. Defaults to `'Clear search'`; name it\nafter what is searched (`'Clear agency search'`) when a page carries\nseveral search fields.",
+            "defaultValue": {
+              "value": "'Clear search'"
+            },
+            "parent": {
+              "name": "InputSearchProps",
+              "fileName": "src/input-search/input-search.tsx"
+            },
+            "declarations": [
+              {
+                "name": "TypeLiteral",
+                "fileName": "src/input-search/input-search.tsx"
+              }
+            ]
+          }
+        }
+      },
+      "stories": [
+        {
+          "id": "components-inputsearch--default",
+          "name": "Default",
+          "snippet": "const Default = () => {\n    const [query, setQuery] = useState('');\n\n    return (\n        <InputSearch\n            aria-label=\"Search agencies\"\n            value={query}\n            onChange={event => {\n                setQuery(event.target.value);\n                args.onChange?.(event);\n            }} />\n    );\n};",
+          "description": "A controlled search. The clear button appears once there is text; pressing\nit calls `onChange` with an empty `event.target.value`, so the state that\nowns the query empties too, and focus goes back to the input. The browser's\nown cancel button is hidden.",
+          "summary": "Controlled search with a clear button that empties the query"
+        },
+        {
+          "id": "components-inputsearch--loading",
+          "name": "Loading",
+          "snippet": "const Loading = () => <InputSearch\n    aria-label=\"Search agencies\"\n    onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n    isLoading\n    defaultValue=\"Acme\" />;",
+          "description": "While `isLoading` is set a spinner takes the clear button's place, even with\ntext in the field.",
+          "summary": "Spinner in place of the clear button while results load"
+        },
+        {
+          "id": "components-inputsearch--uncontrolled",
+          "name": "Uncontrolled",
+          "snippet": "const Uncontrolled = () => <InputSearch\n    aria-label=\"Search agencies\"\n    onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n    defaultValue=\"Acme Insurance\" />;",
+          "description": "An uncontrolled search with a `defaultValue`. The clear button follows what\nis in the field, and clearing still calls `onChange` with an empty value.",
+          "summary": "Uncontrolled search starting from a default value"
+        },
+        {
+          "id": "components-inputsearch--disabled",
+          "name": "Disabled",
+          "snippet": "const Disabled = () => <div style={{ display: 'grid', gap: '1rem' }}>\n    <InputSearch\n        aria-label=\"Search agencies\"\n        onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n        disabled\n        defaultValue=\"Acme\" />\n    <fieldset disabled style={{ border: 0, margin: 0, padding: 0 }}>\n        <InputSearch\n            onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n            aria-label=\"Search carriers\"\n            defaultValue=\"Travelers\" />\n    </fieldset>\n</div>;",
+          "description": "A disabled search has no clear button, whether `disabled` is set on the\ninput itself or comes from a `<fieldset disabled>` around it.",
+          "summary": "Disabled search with the clear button removed"
+        },
+        {
+          "id": "components-inputsearch--all-sizes",
+          "name": "All Sizes",
+          "snippet": "const AllSizes = () => <div style={{ display: 'grid', gap: '1rem' }}>\n    <InputSearch\n        onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n        size=\"sm\"\n        aria-label=\"Small\"\n        defaultValue=\"Acme\" />\n    <InputSearch\n        onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n        size=\"md\"\n        aria-label=\"Medium\"\n        defaultValue=\"Acme\" />\n    <InputSearch\n        onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n        size=\"lg\"\n        aria-label=\"Large\"\n        defaultValue=\"Acme\" />\n</div>;",
+          "description": "The three sizes match Input's: the frame is 32, 40 or 48px tall.",
+          "summary": "The three sizes side by side"
+        },
+        {
+          "id": "components-inputsearch--inside-field-text",
+          "name": "Inside Field Text",
+          "snippet": "const InsideFieldText = () => (\n    <div style={{ display: 'grid', gap: '1.5rem' }}>\n        <FieldText>\n            <Label>Agency</Label>\n            <InputSearch defaultValue=\"Acme\" />\n            <Field.Description>Search by agency name or NPN.</Field.Description>\n        </FieldText>\n        <FieldText disabled>\n            <Label>Carrier</Label>\n            <InputSearch defaultValue=\"Travelers\" />\n        </FieldText>\n    </div>\n);",
+          "description": "Inside a `FieldText` the input takes its label, description and states from\nthe field through the frame. A disabled field removes the clear button too.",
+          "summary": "Label and disabled state reaching the input through the frame"
+        },
+        {
+          "id": "components-inputsearch--clear-label",
+          "name": "Clear Label",
+          "snippet": "const ClearLabel = () => <InputSearch\n    aria-label=\"Search agencies\"\n    onChange={fn((event: ChangeEvent<HTMLInputElement>) => event.target.value)}\n    defaultValue=\"Acme\"\n    clearLabel=\"Clear agency search\" />;",
+          "description": "`clearLabel` names the clear button after what is searched, so a page with\nseveral search fields does not read \"Clear search\" twice.",
+          "summary": "Clear button named after what the field searches"
+        }
+      ],
+      "import": "import { Field, FieldText, InputSearch, Label } from \"@agentero/design-system\";"
+    },
     "components-input": {
       "id": "components-input",
       "name": "Input",
@@ -9696,6 +9867,6 @@
   },
   "meta": {
     "docgen": "react-component-meta",
-    "durationMs": 4742
+    "durationMs": 3754
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentero/design-system",
-	"version": "0.33.0",
+	"version": "0.34.0",
 	"description": "A React component library built with Tailwind CSS v4 and Radix UI primitives",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -101,6 +101,10 @@
 			"types": "./src/input-password/index.d.ts",
 			"import": "./src/input-password/index.js"
 		},
+		"./input-search": {
+			"types": "./src/input-search/index.d.ts",
+			"import": "./src/input-search/index.js"
+		},
 		"./label": {
 			"types": "./src/label/index.d.ts",
 			"import": "./src/label/index.js"

package/src/combobox/combobox.d.ts

@@ -145,7 +145,8 @@ type InputProps = Omit<ComponentPropsWithRef<typeof ComboboxPrimitive.Input>, 's
      */
     variant?: 'search' | 'plain' | 'select';
     /**
-     * Whether a clear button follows the input once an option is picked.
+     * Whether a clear button follows the input: on `search` once there is text,
+     * on the others once an option is picked.
      * Defaults to `true` for `search` and `false` for `plain` and `select`; pass
      * it to override the variant. On a `select` it replaces the chevron while
      * there is a value. Ignored under a `multiple` root, which never
@@ -185,11 +186,13 @@ type InputProps = Omit<ComponentPropsWithRef<typeof ComboboxPrimitive.Input>, 's
  *   the user may want to browse before typing.
  *
  * Only `search` carries a clear button by default; `showClear` adds it to the
- * other two or drops it from `search`. On a `select`, the clear button takes the
- * chevron's place once an option is picked; the list still opens from the input. Base UI mounts it only once there is
- * something to clear — a picked option — so an untouched field shows nothing. Name it with
- * `clearLabel`, and the chevron with `triggerLabel`, when a page has more than
- * one combobox.
+ * other two or drops it from `search`. The `search` field is an
+ * [InputSearch](?path=/docs/components-inputsearch--docs): its clear button
+ * shows as soon as there is text, typed or picked, and pressing it empties the
+ * text, which drops the picked option and closes the list. On a `select`, the
+ * clear button takes the chevron's place once an option is picked; the list
+ * still opens from the input. Name it with `clearLabel`, and the chevron with
+ * `triggerLabel`, when a page has more than one combobox.
  *
  * Under a `multiple` root there is neither: the list stays open between picks,
  * so a chevron has nothing to toggle, and Base UI's clear button would drop the
@@ -198,7 +201,9 @@ type InputProps = Omit<ComponentPropsWithRef<typeof ComboboxPrimitive.Input>, 's
  * remove each entry.
  *
  * Every native input attribute is accepted and forwarded to the `<input>` —
- * `placeholder`, `disabled`, `autoComplete` — and so is `className`.
+ * `placeholder`, `disabled`, `autoComplete`. `className` styles the `<input>`
+ * too, except on the `search` field with a clear button, where it styles the
+ * frame, as on InputSearch.
  *
  * @summary Search, plain or select field that opens and filters the list
  * @dataAttribute {string} data-slot - Always set to "combobox-input"