@synerise/ds-select 1.3.33 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.4.0](https://github.com/synerise/synerise-design/compare/@synerise/ds-select@1.3.34...@synerise/ds-select@1.4.0) (2026-07-24)
+
+### Bug Fixes
+
+- **select:** add onKeyDown, maxLength, dropdownAlign, popupClassName, maxTagPlaceholder ([1cf5f39](https://github.com/synerise/synerise-design/commit/1cf5f394055c10caee8b2bef81c83d04e19dcd6e))
+- **select:** add suffixIcon, tabIndex, option style/children parity shims ([10c0bbc](https://github.com/synerise/synerise-design/commit/10c0bbc584534f7950bd5093764d9363a526149b))
+- **select:** color clear/remove icons via currentColor, not svg fill ([0573124](https://github.com/synerise/synerise-design/commit/05731249ebc2d6d291879f0cb0f7443d8966a2b6))
+- **select:** fire onFocus/onBlur and split render into sub-components ([44f73ec](https://github.com/synerise/synerise-design/commit/44f73ec0dc705c920950048acfa61ea108ec8072))
+- **select:** forward data-_ and aria-_ attributes to the select root ([49294a8](https://github.com/synerise/synerise-design/commit/49294a8b1ab2b17967fc9d8ce9879eb48c5844cb))
+- **select:** mark the current option selected via ListItem selected prop ([b5cb80a](https://github.com/synerise/synerise-design/commit/b5cb80a9d6e8a0411752a58fb0e66770f5c19408))
+- **select:** move onClick off the dropdown trigger; focus inputs in interaction tests ([ed1a79c](https://github.com/synerise/synerise-design/commit/ed1a79c45bf056304a11e959ceb086dc1258b55e))
+- **select:** multiple chip keeps its label-defined width; X squeezes label on hover ([5c9908d](https://github.com/synerise/synerise-design/commit/5c9908d8ff86119aa3948a1f366497827598bd3d))
+- **select:** overlay search input and blur it on selection ([f312354](https://github.com/synerise/synerise-design/commit/f31235487542b29f31b2435c2b9951716803d20c))
+- **select:** restore antd-parity props for consumer back-compat ([ceac672](https://github.com/synerise/synerise-design/commit/ceac6729c4c4815ee918a927a98aa17de0407e8d))
+
+### Features
+
+- **select:** forward per-option data-_/aria-_ to the rendered option row ([1a8162d](https://github.com/synerise/synerise-design/commit/1a8162d9dae98a5cf96b0f35f70f9148eb025e88))
+- **select:** implement maxTagCount/maxTagTextLength/maxTagPlaceholder + onPopupScroll ([060d2c6](https://github.com/synerise/synerise-design/commit/060d2c6b74118c065d928786dad67aa1b88500c7))
+- **select:** keyboard-arrow option navigation + combobox/listbox ARIA ([74e5466](https://github.com/synerise/synerise-design/commit/74e5466b23dc2d062c0bd734cc84334f55b99ab8))
+
+## [1.3.34](https://github.com/synerise/synerise-design/compare/@synerise/ds-select@1.3.33...@synerise/ds-select@1.3.34) (2026-07-23)
+
+**Note:** Version bump only for package @synerise/ds-select
+
 ## [1.3.33](https://github.com/synerise/synerise-design/compare/@synerise/ds-select@1.3.32...@synerise/ds-select@1.3.33) (2026-06-17)
 
 **Note:** Version bump only for package @synerise/ds-select

package/CLAUDE.md

@@ -0,0 +1,175 @@
+# Select (`@synerise/ds-select`)
+
+> A DS-native select dropdown (no Ant Design): a selector trigger + floating options dropdown built
+> on `@synerise/ds-dropdown` (floating-ui) and `@synerise/ds-list-item`, wrapped in `FormField`.
+> Supports single-select, `multiple` (chips), `tags` (free-text) and in-selector search, with full
+> keyboard navigation, combobox/listbox ARIA, prefix/suffix addons, `readOnly`, and a `raw` variant.
+
+## Package structure
+
+```
+src/
+ Select.tsx — main component (forwardRef, compound with .Option); composes the sub-components below
+ Select.types.ts — SelectProps, SelectValue, SelectOption, SelectMode, SelectHandler, RawValueType, FilterOptionFn
+ Select.styles.ts — styled-components (Selector = the .ds-select box, SelectWrapper, chips, dropdown, …)
+ Option.tsx — declarative <Select.Option> marker (renders null) + OptionProps
+ index.ts — default export + types + SelectStyles namespace + getOptionsFromChildren/findOption
+ Select.figma.tsx — Figma Code Connect mapping
+ modules.d.ts — imports @testing-library/jest-dom
+ hooks/
+  useSelectOptions.ts — resolve options (prop → children), client filtering, tags create-row
+ components/
+  OptionList.tsx — dropdown overlay: loading / empty / scrollable listbox of options
+  SelectorContent.tsx — selector inner content: chips / selected label / placeholder + search input
+ utils/
+  getOptionsFromChildren.ts — read <Select.Option> children into SelectOption[]; findOption()
+  helpers.ts — cx(), toArray(), defaultFilter(), DEFAULT_LIST_HEIGHT
+ __specs__/
+  Select.spec.tsx — Vitest + React Testing Library tests
+```
+
+> No `style/` dir and no `antd` peerDep — the component is styled purely with styled-components. The
+> old antd-era LESS (`select.mixin.less`, `.ant-select-*` overrides) was relocated to `ds-table`
+> (`table/src/style/`), the only consumer that still renders antd selects.
+
+## Public exports
+
+```ts
+export { default } from './Select';                 // compound: Select + .Option
+export { Option, type OptionProps } from './Option';
+export type {
+  Props, SelectProps, SelectValue, SelectOption, SelectMode,
+  SelectHandler, RawValueType, FilterOptionFn,
+} from './Select.types';
+export * as SelectStyles from './Select.styles';
+export { getOptionsFromChildren, findOption } from './utils/getOptionsFromChildren';
+```
+
+### `Select` (default)
+
+`forwardRef<HTMLDivElement, SelectProps>`, augmented into a compound component with a single
+sub-component: **`Select.Option`** (the DS `Option` marker). `Select.OptGroup` is intentionally
+**not** reimplemented (zero real usage).
+
+`SelectValue = string | number | (string | number)[] | undefined` — antd-free (no `LabeledValue`).
+
+#### DS-specific props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` / `description` / `tooltip` / `tooltipConfig` | `ReactNode` / `TooltipProps` | `undefined` | `FormField` chrome (from `FormFieldCommonProps`). |
+| `errorText` | `ReactNode` | `undefined` | Error message below the field; also activates the error visual state. |
+| `error` | `boolean` | `undefined` | Error visual state without a message. |
+| `clearTooltip` | `string` | `undefined` | Tooltip on hover of the clear (×) control. |
+| `prefixel` / `suffixel` | `ReactNode` | `undefined` | Addon nodes attached left/right of the selector (shared border). |
+| `grey` | `boolean` | `undefined` | `grey-050` selector background when not in error state. |
+| `asFormElement` | `boolean` | `undefined` | Forces a 16 px bottom margin even without `errorText`/`description`. |
+| `raw` | `boolean` | `undefined` | Skips the `FormField` wrapper — renders only the selector; `ref` attaches to `SelectWrapper`. |
+| `readOnly` | `boolean` | `undefined` | Non-interactive with readable styling (white bg, `default` cursor, `grey-600` text). |
+| `disabled` | `boolean` | `undefined` | Standard disabled state; ORed with `readOnly` to block interaction. |
+| `selectorStyle` | `CSSObject` | `undefined` | Inline style object applied to the `Selector` box. |
+| `listHeight` | `number \| string` | `256` | Max dropdown list height (px). |
+| `style` | `CSSProperties` | `undefined` | Applied to `SelectWrapper` (the flex row: selector + addons). |
+| `className` | `string` | `undefined` | Added to the outer `SelectContainer`. |
+| `getPopupContainer` | `(node) => HTMLElement \| ParentNode \| null` | `defaultGetPopupContainer` (`@synerise/ds-utils`) | Container the dropdown mounts into. |
+| `size` | `'default' \| 'middle' \| 'large'` | `'default'` | Selector height (`middle` maps to `default`). |
+
+Native `data-*` / `aria-*` attributes are forwarded onto the select root (`.ds-select-wrapper`).
+
+#### antd-parity props (additive back-compat)
+
+Kept so antd-era consumers need no change: `searchValue`, `onClear`, `onClick`, `onInputKeyDown`,
+`onKeyDown`, `suffixIcon`, `clearIcon`, `maxLength`, `maxTagCount`, `maxTagTextLength`,
+`maxTagPlaceholder`, `onPopupScroll`, `popupClassName` (alias of `dropdownClassName`),
+`dropdownMatchSelectWidth` (`boolean | number`), `dropdownRender`, `showArrow`,
+`autoFocus`, `tabIndex`, `rowKey`, plus the standard
+`mode`/`options`/`showSearch`/`filterOption`/`allowClear`/`open`/`onChange`/`onSearch`/… surface.
+`SelectHandler` type and the `SelectStyles.Selector` styled export are re-exported for parity.
+
+`maxTagCount` (collapse extra chips into a `+N` overflow chip), `maxTagTextLength` (truncate chip
+labels) and `onPopupScroll` are fully implemented. `listItemHeight`, `dropdownAlign` and
+`defaultActiveFirstOption` are accepted for compatibility but have **no runtime effect**.
+
+## Usage patterns
+
+```tsx
+import Select from '@synerise/ds-select';
+
+const { Option } = Select;
+
+// Options as data (preferred)
+<Select label="Platform" options={[{ value: 'insta', label: 'Instagram' }]} defaultValue="insta" />
+
+// Declarative children (read only when `options` is absent)
+<Select label="Platform"><Option value="insta">Instagram</Option></Select>
+
+// Multiple (removable chips) / tags (free-text) / search
+<Select mode="multiple" placeholder="Select tags" allowClear options={opts} />
+<Select mode="tags" tokenSeparators={[',']} />
+<Select showSearch filterOption optionFilterProp="label" options={opts} />
+
+// Remote search: filter server-side, feed options from onSearch
+<Select showSearch filterOption={false} onSearch={fetchOptions} options={opts} />
+
+// readOnly / raw / prefix-suffix
+<Select readOnly value="locked" />
+<Select raw ref={myRef} placeholder="Compact" />
+<Select prefixel={<span>$</span>} suffixel={<span>USD</span>} />
+```
+
+## Styling
+
+**styled-components (`Select.styles.ts`) is the source of truth.** Key styled parts:
+- `SelectContainer` — column flex; adds a 16 px bottom margin when `hasBottomMargin`.
+- `SelectWrapper` (`.ds-select-wrapper`) — the flex row (selector + addons); carries the root
+  `onFocus`/`onBlur`/`onClick` and `data-*`/`aria-*` passthrough.
+- `Selector` (`.ds-select`) — the trigger box; `large` height, `withPrefixel`/`withSuffixel`
+  border-radius removal, open/focus ring (`blue-600`/`blue-050`), error (`red-600`/`red-050`),
+  `readOnly` vs `disabled` differentiation, and the `selectorStyle` interpolation.
+- `PrefixWrapper` / `SuffixWrapper` — `grey-050` addons with flush border join.
+- Dropdown / options: `DropdownWrapper`, `ScrollList`, `Inner` (`role="listbox"`), `OptionItem`
+  (styled `ds-list-item`), `NotFound`, `Loading`. Selector content: `SelectionItem`, `Placeholder`,
+  `MultiValueArea`, `Chip`/`ChipLabel`/`ChipRemove`, `Arrow`, `ClearWrapper`, `SearchInputEl`.
+
+Class hooks are `ds-select-*` (`.ds-select`, `.ds-select-selection-item`, `.ds-select-dropdown`,
+`.ds-select-arrow`, `.ds-select-clear`, `.ds-select-search`, …).
+
+## Key dependencies
+
+- `@synerise/ds-dropdown` — floating-ui popover positioning + overlay (the `Selector` is the `asChild` trigger).
+- `@synerise/ds-list-item` — the option row (`OptionItem`) and list wrapper (`ScrollList`).
+- `@synerise/ds-scrollbar` / `@synerise/ds-loader` — dropdown scroll container / loading spinner.
+- `@synerise/ds-form-field` — label / description / error layout (skipped when `raw`).
+- `@synerise/ds-icon` — `AngleDownS` (arrow), `Close3M` (clear), `CloseS` (chip remove).
+- `@synerise/ds-tooltip` — wraps the clear control for `clearTooltip`.
+- `@synerise/ds-utils` — default `getPopupContainer`.
+- `@synerise/ds-core` — theme tokens (peerDep). **No `antd` peerDep** — the component imports zero
+  antd; the LESS that pulled `~antd/lib/select/style` was relocated to `ds-table` (see below).
+
+## Implementation notes
+
+- **Option resolution** — `useSelectOptions` returns `resolvedOptions` (from `options` prop, else
+  `getOptionsFromChildren(children)`) and `displayedOptions` (after client filtering and, in `tags`
+  mode, a create-row prepended for the typed text). `filterOption={false}` disables local filtering.
+- **`Option.value` is optional** — falls back to the element's React `key` (antd parity); callbacks
+  expose `option.key`.
+- **Keyboard nav is hand-rolled (not ds-dropdown's)** — Select is a *combobox*: focus stays on the
+  input/selector via `aria-activedescendant`, whereas ds-dropdown uses roving DOM focus. `activeIndex`
+  + `moveActive` + three effects drive highlight; `handleKeyDown` handles Arrow/Home/End/Enter/Escape/
+  Space and Backspace (drop last chip).
+- **Focus / blur** — `onFocus`/`onBlur` fire on the root only when focus truly enters/leaves the
+  select (relatedTarget guard ignores selector↔input moves). `autoFocus` focuses the `Selector` in
+  select-only mode (no search input to receive it). The dropdown `onMouseDown` prevents focus loss so
+  selecting an option / scrolling isn't treated as a blur (needed by `subtle-form`'s revert-on-blur).
+- **`readOnly` is implemented via `disabled`** — both flags are ORed into `isDisabled`; the visual
+  distinction comes from the `$readOnly` transient prop on `Selector`.
+- **Controlled/uncontrolled** — `value`/`open`/`searchValue` are controlled when defined, else backed
+  by internal state; `onSearch` still fires when `searchValue` is controlled.
+- **antd-free; no LESS** — styling is entirely styled-components. The old antd-era LESS
+  (`style/index.less` + `select.mixin.less`, `.ant-select-*` overrides for antd selects) was
+  **relocated to `ds-table`** (`table/src/style/select.mixin.less` + a direct
+  `@import '~antd/lib/select/style'`), since `ds-table` (out of scope, stays on antd) was the only
+  remaining consumer. ds-select ships no `dist/style` and no longer declares an `antd` peerDep.
+- **Tests** — Vitest + React Testing Library (`src/__specs__/Select.spec.tsx`): render/parity,
+  keyboard + ARIA, and focus/blur (autofocus, onBlur on leave / not on internal move, onFocus).
+```

package/README.md

@@ -3,9 +3,13 @@ id: select
 title: Select
 ---
 
-Select UI Component
+Select UI Component.
 
-Based on [Ant Design Select](https://ant.design/components/select/)
+A fully DS-native select (no Ant Design): a selector trigger plus a floating options
+dropdown built on [`@synerise/ds-dropdown`](https://design.synerise.com/docs/components/dropdown)
+(floating-ui) and `@synerise/ds-list-item`, wrapped in a `FormField` label/description/error
+layer. Supports single-select, `multiple` (chip selector), `tags` (free-text) and in-selector
+search, with full keyboard navigation and combobox/listbox ARIA.
 
 ## Installation
 
@@ -22,112 +26,172 @@ pnpm add @synerise/ds-select
 ```jsx
 import Select from '@synerise/ds-select';
 
-const { Option, OptGroup } = Select;
+// Options as data
+<Select
+  label="Platform"
+  description="Choose your platform"
+  defaultValue="insta"
+  options={[
+    { value: 'insta', label: 'Instagram' },
+    { value: 'fb', label: 'Facebook' },
+  ]}
+/>;
+
+// Or declarative <Select.Option> children (read only when `options` is absent)
+const { Option } = Select;
 
 <Select defaultValue="insta">
-  <OptGroup label="Platform">
-    <Option value="insta">Instagram</Option>
-    <Option value="fb">Facebook</Option>
-  </OptGroup>
-  <OptGroup label="Followers">
-    <Option value="1M">1 Million</Option>
-    <Option value="1B">1 Billion</Option>
-  </OptGroup>
+  <Option value="insta">Instagram</Option>
+  <Option value="fb">Facebook</Option>
 </Select>;
 ```
 
-## Select default
-
-<iframe src="/storybook-static/iframe.html?id=components-select-basic--default"></iframe>
+> There is **no `OptGroup`** — the antd `Select.OptGroup` is intentionally not reimplemented.
 
-## Select multiple mode
+## Examples
 
+<iframe src="/storybook-static/iframe.html?id=components-select--default"></iframe>
 <iframe src="/storybook-static/iframe.html?id=components-select--multiple-mode"></iframe>
+<iframe src="/storybook-static/iframe.html?id=components-select--with-search"></iframe>
+<iframe src="/storybook-static/iframe.html?id=components-select--tags"></iframe>
 
-## Select with options group
+## API
 
-<iframe src="/storybook-static/iframe.html?id=components-select--with-optgroup"></iframe>
+`Select` also extends `FormFieldCommonProps` (`label`, `description`, `errorText`, `tooltip`,
+`tooltipConfig`) and `AriaAttributes`, and forwards native `data-*` / `aria-*` attributes to the
+select root.
+
+### Value & selection
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| value / defaultValue | Controlled / uncontrolled value. Array for `multiple` / `tags`. | `SelectValue` (`string \| number \| (string \| number)[]`) | - |
+| mode | Omit for single-select; `multiple` = chips; `tags` = free-text create. | `'multiple' \| 'tags'` | - |
+| onChange | Fired when the selection changes. | `(value, option?) => void` | - |
+| onSelect / onDeselect | Fired when an option is added / removed. | `(value, option?) => void` | - |
+| onClear | Fired when the clear affordance is used. | `() => void` | - |
+| allowClear | Show a clear control (replaces the chevron on hover) when a value is set. | `boolean` | `false` |
+| clearIcon | Custom clear icon. | `ReactNode` | - |
+| clearTooltip | Tooltip on hover of the clear button. | `string` | - |
+
+### Options & search
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| options | Options as data; when absent, `<Select.Option>` children are read. | `SelectOption[]` | - |
+| showSearch | Render an in-selector search input. | `boolean` | `false` |
+| searchValue | Controlled search-input value (pairs with `onSearch`). | `string` | - |
+| onSearch | Fired on each keystroke in the search input (remote search). | `(value: string) => void` | - |
+| filterOption | Client filtering. `false` = remote (feed `options` from `onSearch`); a function = custom predicate. | `boolean \| ((input, option) => boolean)` | `true` |
+| optionFilterProp | Option field the built-in filter matches against. | `string` | label |
+| optionLabelProp | Option field rendered in the selector. | `string` | label |
+| notFoundContent | Shown when there are no (filtered) options. | `ReactNode` | `'No data'` |
+| tokenSeparators | Characters that create a tag in `tags` mode. | `string[]` | - |
+| loading | Show a spinner inside the dropdown. | `boolean` | `false` |
+| rowKey | Item key extractor for options / children. | `(option) => Key` | - |
+
+### Dropdown
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| open / defaultOpen | Controlled / initial dropdown visibility. | `boolean` | - |
+| onDropdownVisibleChange | Fired when dropdown visibility changes. | `(open: boolean) => void` | - |
+| onPopupScroll | Fired as the open option list scrolls (e.g. to page in more options). | `(event: UIEvent<HTMLDivElement>) => void` | - |
+| getPopupContainer | Container the floating dropdown mounts into. | `(node: HTMLElement) => HTMLElement \| ParentNode \| null` | ds-utils default |
+| placement | Dropdown placement. | `DropdownPlacement` | - |
+| dropdownClassName / popupClassName | Class on the dropdown overlay (`popupClassName` is the antd v4 alias). | `string` | - |
+| dropdownAlign | Dropdown alignment config (accepted for compatibility). | `object` | - |
+| dropdownStyle | Inline style on the dropdown overlay. | `CSSProperties` | - |
+| dropdownMatchSelectWidth | Match dropdown width to the selector; a number fixes the width (px). | `boolean \| number` | `true` |
+| dropdownRender | Wrap the rendered option menu (custom footer / scroll container). | `(menu: ReactElement) => ReactNode` | - |
+| listHeight | Max dropdown list height (px). | `number \| string` | `256` |
+| listItemHeight | Fixed height per option row (accepted; list is non-virtualised). | `number` | - |
+
+### Display & tags
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| placeholder | Placeholder of the select. | `ReactNode` | - |
+| showArrow | Show the dropdown chevron. | `boolean` | `true` |
+| suffixIcon | Custom icon replacing the dropdown arrow. | `ReactNode` | - |
+| maxTagCount | Max tags shown before collapsing (multiple / tags). | `number` | - |
+| maxTagTextLength | Max characters per tag. | `number` | - |
+| maxTagPlaceholder | Node shown for the collapsed overflow count. | `ReactNode` | - |
+| size | Selector height. | `'default' \| 'middle' \| 'large'` | `'default'` |
+| grey | `grey-050` selector background (when not in error state). | `boolean` | `false` |
+
+### State & focus
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| disabled | Disabled state; blocks interaction and opening. | `boolean` | `false` |
+| readOnly | Non-interactive with readable styling (white bg, `default` cursor, `grey-600` text) instead of the disabled look. | `boolean` | - |
+| error | Error visual state without a message. | `boolean` | - |
+| errorText | Error message below the field; also activates the error state. | `ReactNode` | - |
+| autoFocus | Focus the selector / search input on mount. | `boolean` | `false` |
+| defaultActiveFirstOption | Accepted for antd back-compat; **no effect** — the dropdown always highlights the selected / first option on open. | `boolean` | - |
+| tabIndex | Tab index forwarded to the selector / search input. | `number` | - |
+| onFocus / onBlur | Fired when focus enters / leaves the whole select. | `(event) => void` | - |
+| onClick | Click handler on the selector box. | `(event) => void` | - |
+| onKeyDown / onInputKeyDown | Keydown on the selector / on the inner search input. | `(event) => void` | - |
+
+### Layout & DS-specific
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| label / description / tooltip / tooltipConfig | `FormField` chrome (label, helper text, info tooltip). | `ReactNode` / `TooltipProps` | - |
+| prefixel / suffixel | Addon nodes attached to the left / right of the selector (shared border). | `ReactNode` | - |
+| raw | Skip the `FormField` wrapper; render only the selector. `ref` attaches to the selector wrapper. | `boolean` | - |
+| asFormElement | Force a 16 px bottom margin even when `errorText` / `description` are absent. | `boolean` | - |
+| selectorStyle | Inline style object applied to the selector box. | `CSSObject` | - |
+| style | Applied to the selector wrapper (flex row: selector + addons). | `CSSProperties` | - |
+| className | Added to the outer container. | `string` | - |
+| id | Forwarded to the search input. | `string` | - |
+
+### `Select.Option` props
+
+Marker component — renders nothing; `Select` reads its props to build the option list when the
+`options` prop is absent.
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| value | Option value. Optional — falls back to the element's React `key` when omitted. | `string \| number` | - |
+| children | Rendered content / label of the option. | `ReactNode` | - |
+| label | Rendered in the selector instead of `children` (antd `optionLabelProp`). | `ReactNode` | - |
+| disabled | Disable this option. | `boolean` | `false` |
+| title | Native hover title (any node; coerced to a string at render). | `ReactNode` | - |
+| style | Forwarded to the rendered option row. | `CSSProperties` | - |
+| className | Added to the option row. | `string` | - |
+
+## Exports
+
+```ts
+import Select, {
+  Option,
+  SelectStyles, // styled-components namespace (Selector, SelectWrapper, …)
+  getOptionsFromChildren,
+  findOption,
+} from '@synerise/ds-select';
+
+import type {
+  SelectProps,
+  SelectValue,
+  SelectOption,
+  SelectMode,
+  SelectHandler,
+  RawValueType,
+  FilterOptionFn,
+  OptionProps,
+} from '@synerise/ds-select';
+```
 
-## API
+## Notes
 
-### Select props
-
-| Property                 | Description                                                                                       | Type                                                                              | Default                                      |
-| ------------------------ | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------- |
-| allowClear               | Show clear button.                                                                                | boolean                                                                           | `false`                                      |
-| autoClearSearchValue     | Whether the current search will be cleared on selecting an item                                   | boolean                                                                           | `true`                                       |
-| autoFocus                | Get focus by default                                                                              | boolean                                                                           | `false`                                      |
-| clearIcon                | The custom clear icon                                                                             | React.ReactNode                                                                   | -                                            |
-| defaultActiveFirstOption | Whether active first option by default                                                            | boolean                                                                           | `true`                                       |
-| defaultOpen              | Initial open state of dropdown                                                                    | boolean                                                                           | -                                            |
-| defaultValue             | Initial selected option.                                                                          | `string` / `string[]` / `number` / `number[]` / `LabeledValue` / `LabeledValue[]` | -                                            |
-| description              | input description                                                                                 | ReactNode                                                                         | -                                            |
-| disabled                 | Whether disabled select                                                                           | boolean                                                                           | `false`                                      |
-| dropdownClassName        | className of dropdown menu                                                                        | string                                                                            | -                                            |
-| dropdownMatchSelectWidth | Whether dropdown's width is same with select.                                                     | boolean                                                                           | `true`                                       |
-| dropdownMenuStyle        | additional style applied to dropdown menu                                                         | React.CSSProperties                                                               | -                                            |
-| dropdownRender           | Customize dropdown content                                                                        | (menuNode: React.ReactNode, props) => React.ReactNode                             | -                                            |
-| dropdownStyle            | style of dropdown menu                                                                            | React.CSSProperties                                                               | -                                            |
-| errorText                | error message, if provided input will be set in error state                                       | ReactNode                                                                         | -                                            |
-| error                    | if provided input will be set in error state, without error message                               | boolean                                                                           | -                                            |
-| filterOption             | If true, filter options by input, if function, filter options against it.                         | boolean / (inputValue: string / number / LabeledValue, option: Option) => void    | `true`                                       |
-| firstActiveValue         | Value of action option by default                                                                 | string or string[]                                                                | -                                            |
-| grey                     | Turn on grey background of the component                                                          | boolean                                                                           | false                                        |
-| getPopupContainer        | Parent Node which the selector should be rendered to. Default to body                             | (triggerNode: React.ReactNode) => void                                            | () => document.body                          |
-| label                    | input label                                                                                       | ReactNode                                                                         | -                                            |
-| labelInValue             | whether to embed label in value                                                                   | boolean                                                                           | `false`                                      |
-| loading                  | indicate loading state                                                                            | Boolean                                                                           | `false`                                      |
-| maxTagCount              | Max tag count to show                                                                             | number                                                                            | -                                            |
-| maxTagPlaceholder        | Placeholder for not showing tags                                                                  | React.ReactNode/function(omittedValues)                                           | -                                            |
-| maxTagTextLength         | Max tag count to show                                                                             | number                                                                            | -                                            |
-| menuItemSelectedIcon     | The custom menuItemSelected icon with multiple options                                            | React.ReactNode                                                                   | -                                            |
-| mode                     | Set mode of Select                                                                                | `default` / `multiple` / `tags`                                                   | `default`                                    |
-| notFoundContent          | Specify content to show when no result matches.                                                   | string                                                                            | `Not Found`                                  |
-| onBlur                   | Called when blur                                                                                  | (e: Event) => void                                                                | -                                            |
-| onChange                 | Called when select an option or input value change, or value of input is changed in combobox mode | (value: string / number / LabeledValue, option: Option / Option[]) => void        | -                                            |
-| onDeselect               | Called when a option is deselected, param is the selected option's value.                         | (value: string / number / LabeledValue) => void                                   | -                                            |
-| onDropdownVisibleChange  | Call when dropdown open                                                                           | (open: boolean) => void                                                           | -                                            |
-| onFocus                  | Called when focus                                                                                 | (e: Event) => void                                                                | -                                            |
-| onInputKeyDown           | Called when key pressed                                                                           | (e: Event) => void                                                                | -                                            |
-| onMouseEnter             | Called when mouse enter                                                                           | (e: Event) => void                                                                | -                                            |
-| onMouseLeave             | Called when mouse leave                                                                           | (e: Event) => void                                                                | -                                            |
-| onPopupScroll            | Called when dropdown scrolls                                                                      | (e: Event) => void                                                                | -                                            |
-| onSearch                 | Callback function that is fired when input changed.                                               | (value: string) => void                                                           |                                              |
-| onSelect                 | Called when a option is selected, the params are option's value (or key) and option instance.     | (value: string / number / LabeledValue, option:Option) => void                    | -                                            |
-| open                     | Controlled open state of dropdown                                                                 | boolean                                                                           | -                                            |
-| optionFilterProp         | Which prop value of option will be used for filter if filterOption is `true`                      | string                                                                            | value                                        |
-| optionLabelProp          | Which prop value of option will render as content of select.                                      | string                                                                            | value for combobox, children for other modes |
-| placeholder              | Placeholder of select                                                                             | string / React.ReactNode                                                          | -                                            |
-| removeIcon               | The custom remove icon                                                                            | React.ReactNode                                                                   | -                                            |
-| showArrow                | Whether to show the drop-down arrow                                                               | boolean                                                                           | `true`                                       |
-| showSearch               | Whether show search input in single mode.                                                         | boolean                                                                           | `false`                                      |
-| size                     | Size of Select input. `default` or `large`. `small` is deprecated                                 | string                                                                            | `default`                                    |
-| suffixIcon               | The custom suffix icon                                                                            | React.ReactNode                                                                   | -                                            |
-| tokenSeparators          | Separator used to tokenize on tag/multiple mode                                                   | string[]                                                                          |                                              |
-| tooltip                  | Tooltip content                                                                                   | React.ReactNode                                                                   | -                                            |
-| tooltipConfig            | Config of tooltip                                                                                 | [TooltipProps](https://design.synerise.com/docs/components/tooltip#api)           | -                                            |
-| value                    | Current selected option.                                                                          | `string` / `string[]` / `number` / `number[]` / `LabeledValue` / `LabeledValue[]` | -                                            |
-| asFormElement            | Forces 16px bottom margin even when `errorText` and `description` are absent                     | boolean                                                                           | -                                            |
-| clearTooltip             | Tooltip text shown on hover of the clear (×) button                                               | string                                                                            | -                                            |
-| prefixel                 | Addon node attached to the left of the selector                                                   | React.ReactNode                                                                   | -                                            |
-| raw                      | Skips the FormField wrapper; renders only the selector div                                        | boolean                                                                           | -                                            |
-| readOnly                 | Disables selection while using readable styling (white bg, default cursor, grey-600 text)         | boolean                                                                           | -                                            |
-| selectorStyle            | Additional CSS applied to the inner `.ant-select-selector` element                                | CSSObject                                                                         | -                                            |
-| suffixel                 | Addon node attached to the right of the selector                                                  | React.ReactNode                                                                   | -                                            |
-
-### Option props
-
-| Property  | Description                                                                                                                      | Type   | Default |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- |
-| disabled  | Disable this option                                                                                                              | boolean | `false` |
-| key       | Same usage as value. If React request you to set this property, you can set it to value of option, and then omit value property. | string |         |
-| title     | title of Select after select this Option                                                                                         | string | -       |
-| value     | default to filter with this property string                                                                                      | number | -       |
-| className | additional class to option string                                                                                                | -      |         |
-
-### Option group props
-
-| Property | Description      | Type    | Default        |     |
-| -------- | ---------------- | ------- | -------------- | --- |
-| key      | Key of an option | string  | -              |     |
-| label    | Group label      | `string | React.Element` | -   |
+- **Class hooks are `ds-select-*`** — the antd `.ant-select-*` classes are gone; target
+  `.ds-select`, `.ds-select-wrapper`, `.ds-select-selection-item`, `.ds-select-dropdown`, etc.
+- **Remote search** — set `filterOption={false}` and update `options` from your `onSearch`
+  handler; the component won't filter locally in that mode.
+- **Keyboard & ARIA** — Arrow / Home / End / Enter / Escape / Space (and Backspace to drop the
+  last chip in multiple mode), with combobox / listbox `aria-activedescendant`.
+- **Not reimplemented from antd** — `OptGroup`, `labelInValue` / `LabeledValue`,
+  `autoClearSearchValue`, `firstActiveValue`, `menuItemSelectedIcon`.

package/dist/Option.d.ts

@@ -0,0 +1,28 @@
+import { CSSProperties, ReactNode } from 'react';
+import { RawValueType } from './Select.types';
+export type OptionProps = {
+    /** antd parity: optional — falls back to the element's React `key` when omitted. */
+    value?: RawValueType;
+    disabled?: boolean;
+    /** Native title (hover text). antd parity: accepts any node (coerced to a string title at render). */
+    title?: ReactNode;
+    /** When set, rendered in the selector instead of `children` (antd `optionLabelProp`). */
+    label?: ReactNode;
+    children?: ReactNode;
+    /** antd parity: forwarded to the rendered option row. */
+    style?: CSSProperties;
+    className?: string;
+    /** antd parity: native `data-*` / `aria-*` attributes, forwarded to the rendered option row. */
+    [dataAttr: `data-${string}`]: unknown;
+    [ariaAttr: `aria-${string}`]: unknown;
+};
+/**
+ * Declarative option marker. Renders nothing on its own — `Select` reads its
+ * props (`value`, `children` → label, `disabled`, `title`) to build the internal
+ * options list. Kept for back-compat with the antd `Select.Option` API. The antd
+ * `Select.OptGroup` is intentionally NOT reimplemented (zero real usage).
+ */
+export declare const Option: {
+    (_props: OptionProps): null;
+    displayName: string;
+};

package/dist/Option.js

@@ -0,0 +1,5 @@
+const Option = (_props) => null;
+Option.displayName = "Select.Option";
+export {
+  Option
+};