@ceed/ads 1.35.0 → 1.35.1

package/dist/components/SearchBar/SearchBar.d.ts

@@ -1,13 +1,15 @@
 import * as React from 'react';
+import { type BoxProps } from '@mui/joy/Box';
 export type SearchBarSlot = 'root';
 export interface SearchBarOption {
     label: string;
     value: string;
     placeholder?: string;
 }
-export interface SearchBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
-    hideSelect?: boolean;
+export interface SearchBarProps extends Omit<BoxProps, 'onChange'> {
+    showSelect?: boolean;
     options?: SearchBarOption[];
+    placeholder?: string;
     value: string;
     onChange: (value: string) => void;
     onSearch?: (params: {
@@ -15,6 +17,5 @@ export interface SearchBarProps extends Omit<React.HTMLAttributes<HTMLDivElement
         inputValue: string;
     }) => void;
 }
-export interface SearchBarOwnerState extends Required<Pick<SearchBarProps, 'hideSelect'>> {
-}
-export declare const SearchBar: React.ForwardRefExoticComponent<SearchBarProps & React.RefAttributes<HTMLDivElement>>;
+export type SearchBarOwnerState = Required<Pick<SearchBarProps, 'showSelect'>>;
+export declare const SearchBar: React.ForwardRefExoticComponent<Omit<SearchBarProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/SearchBar/index.d.ts

@@ -1,2 +1,3 @@
-export { SearchBar } from './SearchBar';
-export type { SearchBarOption, SearchBarOwnerState, SearchBarProps, SearchBarSlot } from './SearchBar';
+import { SearchBar } from './SearchBar';
+export * from './SearchBar';
+export default SearchBar;

package/dist/components/index.d.ts

@@ -49,8 +49,7 @@ export { ProfileMenu } from './ProfileMenu';
 export { Radio, RadioGroup } from './Radio';
 export { RadioTileGroup } from './RadioTileGroup';
 export { RadioList } from './RadioList';
-export { SearchBar } from './SearchBar';
-export type { SearchBarOption, SearchBarOwnerState, SearchBarProps, SearchBarSlot } from './SearchBar';
+export { SearchBar, type SearchBarProps, type SearchBarOwnerState, type SearchBarSlot, type SearchBarOption, } from './SearchBar';
 export { Select, Option } from './Select';
 export { Sheet } from './Sheet';
 export { Stack } from './Stack';

package/dist/components/inputs/SearchBar.md

@@ -2,58 +2,89 @@
 
 ## Introduction
 
-A search input component that optionally includes a category Select for filtering search by keyword type.
-
-> 💡 **Placeholder guidance**
->
-> When `options` are provided, each option can include a `placeholder` field to hint at the expected input format for that category. This helps users understand what value to enter.
->
-> - Account #: `e.g. 1234567`
-> - Jira Issue #: `e.g. PROC-1234`
+A search input component combining a text field and a search button. Optionally includes a category Select that lets users narrow results by keyword type. Hovering over the input while it has a value reveals a clear (✕) button to reset the field. Sizes to its content by default (`inline-flex`) and accepts all `Box` props for layout control.
 
 ```tsx
-<SearchBar options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+<SearchBar value={value} onChange={setValue} />
 ```
 
-| Field      | Description | Default |
-| ---------- | ----------- | ------- |
-| hideSelect | —           | —       |
-| options    | —           | —       |
-| value      | —           | —       |
-| onChange   | —           | —       |
-| onSearch   | —           | —       |
+| Field       | Description | Default |
+| ----------- | ----------- | ------- |
+| showSelect  | —           | —       |
+| options     | —           | —       |
+| placeholder | —           | —       |
+| value       | —           | —       |
+| onChange    | —           | —       |
+| onSearch    | —           | —       |
 
 ## Usage
 
 ```tsx
 import { SearchBar } from '@ceed/ads';
 
+// Basic
+<SearchBar value={query} onChange={setQuery} onSearch={({ inputValue }) => fetch(inputValue)} />
+
+// With category Select
 <SearchBar
-  value={query}
-  onChange={setQuery}
+  showSelect
   options={[
     { label: 'Account #', value: 'account', placeholder: 'e.g. 1234567' },
     { label: 'Jira Issue #', value: 'jira', placeholder: 'e.g. PROC-1234' },
   ]}
-  onSearch={({ selectValue, inputValue }) => console.log(selectValue, inputValue)}
+  value={query}
+  onChange={setQuery}
+  onSearch={({ selectValue, inputValue }) => fetch(selectValue, inputValue)}
 />
 ```
 
-## Without Select
+## With Select
+
+Use `showSelect` together with `options` to display a category Select to the left of the text input. The selected category is passed as `selectValue` in the `onSearch` callback.
+
+```tsx
+<SearchBar showSelect options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+```
+
+## Clearable Input
+
+When the input has a value, hovering over the component reveals a clear (✕) button at the right of the text field. Clicking it calls `onChange('')` without triggering `onSearch`.
+
+```tsx
+<Stack alignItems="flex-start" gap={2}>
+  <Typography level="body-sm">Hover over the input to reveal the clear (✕) button.</Typography>
+  <SearchBar value={value} onChange={setValue} />
+</Stack>
+```
+
+## Placeholder
 
-Use `hideSelect` to hide the category Select and render a narrower input-only layout.
+Each `SearchBarOption` can include a `placeholder` field that is shown in the text input while that category is selected. Pass a `placeholder` prop directly to override the option-level placeholder for all categories.
 
 ```tsx
-<SearchBar hideSelect options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+<Stack alignItems="flex-start" gap={3}>
+  <Stack alignItems="flex-start" gap={1}>
+    <Typography level="body-xs" fontWeight="md">
+      No placeholder prop — uses the active option's placeholder
+    </Typography>
+    <SearchBar showSelect options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+  </Stack>
+  <Stack alignItems="flex-start" gap={1}>
+    <Typography level="body-xs" fontWeight="md">
+      placeholder="Search by keyword" — overrides option-level placeholder
+    </Typography>
+    <SearchBar showSelect options={SAMPLE_OPTIONS} placeholder="Search by keyword" value={value} onChange={setValue} />
+  </Stack>
+</Stack>
 ```
 
 ## onSearch
 
-`onSearch` fires when the search button is clicked or the Enter key is pressed. It receives both the active `selectValue` (omitted when `hideSelect` is `true`) and the current `inputValue`.
+`onSearch` fires when the search button is clicked or the Enter key is pressed. It receives `inputValue` (always present) and `selectValue` (only present when `showSelect` is `true`).
 
 ```tsx
-<Stack gap={2}>
-  <SearchBar options={SAMPLE_OPTIONS} value={value} onChange={setValue} onSearch={setLastSearch} />
+<Stack alignItems="flex-start" gap={2}>
+  <SearchBar showSelect options={SAMPLE_OPTIONS} value={value} onChange={setValue} onSearch={setLastSearch} />
   <Typography level="body-sm">value: "{value}"</Typography>
   {lastSearch && <Typography level="body-sm">
   onSearch: [{lastSearch.selectValue}] "{lastSearch.inputValue}"
@@ -61,43 +92,89 @@ Use `hideSelect` to hide the category Select and render a narrower input-only la
 </Stack>
 ```
 
-## Props and Customization
+When `showSelect` is `false`, `selectValue` is omitted from the payload entirely — not `undefined` as a key, but absent.
+
+```tsx
+<Stack alignItems="flex-start" gap={2}>
+  <Typography level="body-sm">
+    When <code>showSelect</code> is <code>false</code>, <code>selectValue</code> is omitted from the{' '}
+    <code>onSearch</code> payload.
+  </Typography>
+  <SearchBar value={value} onChange={setValue} onSearch={setLastSearch} />
+  {lastSearch && <Stack alignItems="flex-start" gap={0.5}>
+  <Typography level="body-sm">inputValue: "{lastSearch.inputValue}"</Typography>
+  <Typography level="body-sm" sx={{
+    color: lastSearch.selectValue === undefined ? 'success.500' : 'danger.500'
+  }}>
+  selectValue: {lastSearch.selectValue === undefined ? 'undefined ✅' : `"${lastSearch.selectValue}" ❌`}
+</Typography>
+</Stack>}
+</Stack>
+```
 
-| Prop         | Type                                                             | Default | Description                                                                                                                                                                                            |
-| ------------ | ---------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `value`      | `string`                                                         | —       | Current text input value                                                                                                                                                                               |
-| `onChange`   | `(value: string) => void`                                        | —       | Called when the text input value changes                                                                                                                                                               |
-| `onSearch`   | `(params: { selectValue?: string; inputValue: string }) => void` | —       | Called on search button click or Enter key                                                                                                                                                             |
-| `hideSelect` | `boolean`                                                        | `false` | Hide the category Select and show a narrower input-only layout                                                                                                                                         |
-| `options`    | `SearchBarOption[]`                                              | —       | List of selectable categories rendered in the category Select. Each item may include a `placeholder` hint shown in the text input when that category is active. Required when `hideSelect` is `false`. |
+## Width
 
-> **Note**: Also accepts all standard HTML `div` attributes (`className`, `style`, `sx`, etc.).
+SearchBar sizes to its content by default. Pass any `Box` width prop to constrain or stretch it.
 
-### SearchBarOption
+```tsx
+<Stack alignItems="flex-start" gap={3}>
+  <Stack alignItems="flex-start" gap={1}>
+    <Typography level="body-xs" fontWeight="md">
+      width="100%" — stretches to parent width
+    </Typography>
+    <Box sx={{
+      border: '1px dashed',
+      borderColor: 'neutral.300',
+      padding: 1
+    }}>
+    <SearchBar width="100%" value={value} onChange={setValue} />
+  </Box>
+</Stack>
+<Stack alignItems="flex-start" gap={1}>
+  <Typography level="body-xs" fontWeight="md">
+    width={400} — fixed 400px
+  </Typography>
+  <SearchBar width={400} value={value} onChange={setValue} />
+</Stack>
+<Stack alignItems="flex-start" gap={1}>
+  <Typography level="body-xs" fontWeight="md">
+    No width prop — sizes to content (inline-flex default)
+  </Typography>
+  <SearchBar value={value} onChange={setValue} />
+</Stack>
+</Stack>
+```
 
-Each element of the `options` array has the following shape:
+## Props and Customization
 
-| Field         | Type     | Required | Description                                                                                 |
-| ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
-| `label`       | `string` | ✓        | Display text shown in the Select dropdown                                                   |
-| `value`       | `string` | ✓        | Internal identifier passed as `selectValue` in the `onSearch` callback                      |
-| `placeholder` | `string` | —        | Hint text shown in the text input while this category is selected (e.g. `"e.g. PROC-1234"`) |
+| Prop          | Type                                                             | Default | Description                                                                         |
+| ------------- | ---------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `value`       | `string`                                                         | —       | Current value of the text input. Required.                                          |
+| `onChange`    | `(value: string) => void`                                        | —       | Called when the text input value changes. Required.                                 |
+| `onSearch`    | `(params: { selectValue?: string; inputValue: string }) => void` | —       | Called on search button click or Enter key.                                         |
+| `showSelect`  | `boolean`                                                        | `false` | Show the category Select alongside the input.                                       |
+| `options`     | `SearchBarOption[]`                                              | —       | Category options for the Select. Required when `showSelect` is `true`.              |
+| `placeholder` | `string`                                                         | —       | Placeholder text for the input. Takes priority over the option-level `placeholder`. |
 
-### CSS Custom Properties
+> **Note**: Also accepts all `Box` props (`width`, `sx`, `className`, `style`, etc.).
 
-| Variable                 | Default                               | Description                                     |
-| ------------------------ | ------------------------------------- | ----------------------------------------------- |
-| `--ceed-SearchBar-width` | `300px` / `220px` (when `hideSelect`) | Component width; override per instance via `sx` |
+### SearchBarOption
 
-Override example: `<SearchBar sx={{ '--ceed-SearchBar-width': '400px' }} … />`
+| Field         | Type     | Required | Description                                                                                                                             |
+| ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`       | `string` | ✓        | Display text shown in the Select dropdown.                                                                                              |
+| `value`       | `string` | ✓        | Identifier passed as `selectValue` in the `onSearch` callback.                                                                          |
+| `placeholder` | `string` | —        | Hint text shown in the input while this category is selected (e.g. `"e.g. PROC-1234"`). Overridden by the top-level `placeholder` prop. |
 
 ## Best Practices
 
-- Always provide meaningful `label` values in `options` — they are the primary affordance for selecting a search category.
-- Use `placeholder` on each option to show the expected format for that category rather than a generic hint.
-- Prefer `onSearch` over reacting to every `onChange` keystroke for server-side search to reduce unnecessary requests.
+- Always provide `options` when `showSelect` is `true` — the Select renders nothing if `options` is omitted.
+- Add a `placeholder` to each option to show the expected input format for that category.
+- Use the top-level `placeholder` prop only when a single hint applies regardless of category.
+- Prefer handling `onSearch` over `onChange` for server-side queries — fire the request once on explicit submission rather than on every keystroke.
 
 ## Accessibility
 
 - The search button has `aria-label="Search"` and the clear button has `aria-label="Clear"`.
-- The text input is a native `<input>` element and supports keyboard navigation; pressing Enter triggers `onSearch`.
+- The text input is a native `<input>` element; pressing Enter triggers `onSearch`.
+- The clear button uses `onMouseDown` with `e.preventDefault()` to prevent the input from losing focus when clicked.