@ssa-ui-kit/core 3.25.0 → 3.25.1

package/dist/ai/source-map.md

@@ -4,7 +4,7 @@ Generated from the TypeScript program at build time — do not edit by hand.
 
 **Everything below is imported from the package root:** `import { X } from '@ssa-ui-kit/core'`
 
-192 components · 20 contexts · 23 hooks · 17 functions · 16 constants · 325 exported types
+193 components · 20 contexts · 23 hooks · 20 functions · 16 constants · 340 exported types
 
 ## Reading this file
 
@@ -16,7 +16,7 @@ Generated from the TypeScript program at build time — do not edit by hand.
 
 ## Component roster
 
-**Action & Form Controls** — BreadcrumbMenu, Breadcrumbs, Button, ButtonGroup, ButtonGroupButton, Checkbox, ColorPicker, DatePicker, DateRangePicker, DateRangePickerFormBridge, Dropdown, DropdownArrow, DropdownBase, DropdownOption, DropdownOptions, DropdownToggle, FileAttachment, FileUpload, FloatingActionButton, IconButton, Input, MultipleDropdown, MultipleDropdownNotification, MultipleDropdownOptions, NumberField, Radio, RadioGroup, SearchBox, SearchBoxCrossIcon, SearchBoxInput, SearchBoxWrapper, Slider, SliderInputsRow, SliderLabel, SliderMarkItem, SliderMarkLabel, SliderMarksRow, SliderMarkTick, SliderNumberInput, SliderRangeInput, SliderRoot, SliderTrackBg, SliderTrackFill, SliderTrackRow, SliderTrackWrapper, SliderValueLabel, SliderValueLabelsContainer, Switch, Textarea, TextField, Typeahead, TypeaheadItemIcon, TypeaheadItemImage, TypeaheadOption, TypeaheadOptions
+**Action & Form Controls** — BreadcrumbMenu, Breadcrumbs, Button, ButtonGroup, ButtonGroupButton, Checkbox, ColorPicker, ContextMenu, DatePicker, DateRangePicker, DateRangePickerFormBridge, Dropdown, DropdownArrow, DropdownBase, DropdownOption, DropdownOptions, DropdownToggle, FileAttachment, FileUpload, FloatingActionButton, IconButton, Input, MultipleDropdown, MultipleDropdownNotification, MultipleDropdownOptions, NumberField, Radio, RadioGroup, SearchBox, SearchBoxCrossIcon, SearchBoxInput, SearchBoxWrapper, Slider, SliderInputsRow, SliderLabel, SliderMarkItem, SliderMarkLabel, SliderMarksRow, SliderMarkTick, SliderNumberInput, SliderRangeInput, SliderRoot, SliderTrackBg, SliderTrackFill, SliderTrackRow, SliderTrackWrapper, SliderValueLabel, SliderValueLabelsContainer, Switch, Textarea, TextField, Typeahead, TypeaheadItemIcon, TypeaheadItemImage, TypeaheadOption, TypeaheadOptions
 
 **Form Structure** — Filters, FiltersMultiSelect, FiltersMultiSelectEmpty, FiltersMultiSelectOption, FiltersMultiSelectOptions, Form, FormAction, FormCheckbox, FormGroup, FormHelperText, FormRadioGroup
 
@@ -122,6 +122,25 @@ Form control for selecting one or more options
   - `classnames?: { trigger, content, button, colorPicker, colorDropdown, output }`
   - `onChange?: (color: string) => void`
 
+#### ContextMenu<V>
+The list of options shown inside a dropdown, typeahead, filter or action menu.
+
+  - `items: ContextMenuEntry<V>[]` — Options and groups, in display order.
+  - `indicator?: ContextMenuIndicator` — How selected rows are marked. Defaults to `check` for `single`, `checkbox` for `multiple` and `none`…
+  - `onAction?: (value: V) => void` — Fires when an option is chosen by click, Enter or Space, in every mode — the hook for closing a popup.
+  - `activeValue?: V | null` — Controlled highlighted option (pointer or keyboard).
+  - `defaultActiveValue?: V | null` — Initially highlighted option when uncontrolled.
+  - `onActiveValueChange?: (value: V | null) => void` — Fires when the highlighted option changes.
+  - `renderItem?: (item: ContextMenuItem<V>, state: ContextMenuItemState) => ReactNode` — Replaces the row content between the start and end indicators.
+  - `renderGroupLabel?: (group: ContextMenuGroup<V>) => ReactNode` — Replaces the content of group titles.
+  - `emptyState?: ReactNode` `= 'No items'` — Shown when `items` has no options.
+  - `maxHeight?: string | number` — Scrolls the list beyond this height (px or any CSS length).
+  - `selectionMode?: 'none' | 'multiple' | 'single' | 'includeExclude'`
+  - `value?: V | V[] | ContextMenuIncludeExcludeEntry<V>[] | null` — Controlled selected value. `null` for none. Controlled selected values. Controlled chosen rows.
+  - `defaultValue?: V | V[] | ContextMenuIncludeExcludeEntry<V>[] | null` — Initially selected value when uncontrolled. Initially selected values when uncontrolled. Initially chosen…
+  - `onChange?: ((value: V) => void) | ((value: V[], toggled: V) => void) | …(1 more)` — Fires with the newly selected value. Choosing the selected option again keeps it selected. Fires with the new…
+  - _plus native element attributes_
+
 #### DatePicker
 Masked date input with a popover calendar. Use inside **`FormProvider`** (react-hook-form): the field value is the formatted string; **`onChange`** receives a JavaScript…
 
@@ -407,6 +426,7 @@ Dropdown component for multi-select and single-select
   - _plus native element attributes_
 
 #### MultipleDropdownOptions
+Options menu container for MultipleDropdown
 
   - `aria-labelledby?: string` — ARIA label reference Associates the listbox with its label
   - `ariaLabelledby?: string` — ARIA label reference Associates the listbox with its label
@@ -758,8 +778,9 @@ Props for TypeaheadOption component Record type that allows any string or number
   - `aria-selected?: boolean` — ARIA selected state
 
 #### TypeaheadOptions
+The Typeahead's option list: a `ContextMenu` driven from the Typeahead's input. The options themselves come from the `TypeaheadOption` children of `Typeahead`, filtered…
 
-  - `children?: ReactNode`
+  - `children?: ReactNode` — Ignored: the options come from the `TypeaheadOption` children of `Typeahead`, through context.
   - `noItemsMessage?: string`
 
 ### Form Structure
@@ -802,12 +823,14 @@ Props for TypeaheadOption component Record type that allows any string or number
   - _plus native element attributes_
 
 #### FiltersMultiSelectOption
+One filter row of a `FiltersMultiSelect`.
 
-  - `filter: Filter`
-  - `children: ReactNode`
+  - `filter: Filter` — The filter this row adds. `group: true` makes it a select-only row.
+  - `children: ReactNode` — Row content.
   - `selected?: boolean`
 
 #### FiltersMultiSelectOptions
+The options list of a `FiltersMultiSelect`.
 
   - `children: React.ReactNode`
   - _plus native element attributes_
@@ -2327,7 +2350,10 @@ A sticky action bar across the bottom of the panel.
 - `clearButtonStyles`
 - `deriveBreadcrumbs` — Pure derivation of breadcrumb items from a route tree and a pathname. Extracted from the hook so it can be unit-tested without a router.
 - `filterButtonStyles`
+- `getContextMenuOptionId` — DOM id of an option, for `aria-activedescendant` on an element outside the list (e.g. a combobox input). `menuId` is the `id` given to the ContextMenu. Characters not…
+- `getNextActiveValue` — Where a navigation key moves the highlight: ArrowDown / ArrowUp step over disabled options and wrap, Home / End jump to the ends. Returns `undefined` for any other key,…
 - `highlightInputMatch`
+- `nextIncludeExcludeType` — Where Enter moves an `includeExclude` row: none → include → exclude → none, or none ⇄ selected for `selectOnly` rows. For driving that cycle from an input that keeps…
 - `resetDeprecationWarnings` — Clears the once-per-pair warning cache.
 - `resolveAriaProp` — Shorthand for the camelCase-ARIA → native-ARIA renames (issue #656, chunk 3 item 1).
 - `resolveDeprecatedProp` — Resolves a prop that is mid-rename: returns the new prop's value when it is defined, otherwise falls back to the deprecated one and warns in dev.
@@ -2395,15 +2421,19 @@ _Names only — read the `.d.ts` for their shape._
 `CollapsibleNavBarItem` · `ColoredButtonTextProps` · `ColorsKeys` · `ColumnFreezeApi`
 `ColumnFreezeMenuProps` · `ColumnFreezeOptions` · `ColumnId` · `ColumnResizeApi`
 `ColumnResizeHandleProps` · `ColumnResizeMode` · `ColumnResizeOptions` · `CommonProps`
-`ContextType` · `ControlledButtonProps` · `CounterProps` · `CounterSizes` · `CounterVariants`
-`CustomIconProps` · `CustomTagStyles` · `DatePickerContextProps` · `DatePickerFormat`
-`DatePickerProps` · `DateRangePickerContextProps` · `DateRangePickerFormBridgeProps`
-`DateRangePickerFormBridgeValue` · `DateRangePickerOnChangeDates` · `DateRangePickerProps`
-`DateRangePresetValue` · `DateRangePreset` · `DateTimeTuple` · `DeprecatedOpenStateProps`
-`DropdownContextType` · `DropdownOptionProps` · `DropdownPositions` · `DropdownProps`
-`DropdownToggleProps` · `DynamicAlertParams` · `DynamicNotificationParams` · `DynamicToastParams`
-`FieldContextValue` · `FieldControlProps` · `FieldDescriptionProps` · `FieldErrorProps`
-`FieldLabelProps` · `FieldProps` · `FieldSuccessProps` · `FileAttachmentFile`
+`ContextMenuBaseProps` · `ContextMenuEntry` · `ContextMenuGroup` · `ContextMenuIncludeExcludeEntry`
+`ContextMenuIncludeExcludeSelectionProps` · `ContextMenuIncludeExcludeType` · `ContextMenuIndicator`
+`ContextMenuItemState` · `ContextMenuItem` · `ContextMenuMultipleSelectionProps`
+`ContextMenuNoSelectionProps` · `ContextMenuProps` · `ContextMenuSelectionProps`
+`ContextMenuSingleSelectionProps` · `ContextMenuValue` · `ContextType` · `ControlledButtonProps`
+`CounterProps` · `CounterSizes` · `CounterVariants` · `CustomIconProps` · `CustomTagStyles`
+`DatePickerContextProps` · `DatePickerFormat` · `DatePickerProps` · `DateRangePickerContextProps`
+`DateRangePickerFormBridgeProps` · `DateRangePickerFormBridgeValue` · `DateRangePickerOnChangeDates`
+`DateRangePickerProps` · `DateRangePresetValue` · `DateRangePreset` · `DateTimeTuple`
+`DeprecatedOpenStateProps` · `DropdownContextType` · `DropdownOptionProps` · `DropdownPositions`
+`DropdownProps` · `DropdownToggleProps` · `DynamicAlertParams` · `DynamicNotificationParams`
+`DynamicToastParams` · `FieldContextValue` · `FieldControlProps` · `FieldDescriptionProps`
+`FieldErrorProps` · `FieldLabelProps` · `FieldProps` · `FieldSuccessProps` · `FileAttachmentFile`
 `FileAttachmentProps` · `FileRejectionReason` · `FileUploadProgressEntry` · `FileUploadProgress`
 `FileUploadProps` · `Filter` · `FiltersMultiSelectEmptyProps` · `FiltersMultiSelectOptionProps`
 `FiltersMultiSelectProps` · `FloatingActionButtonAction` · `FloatingActionButtonColor`

package/dist/components/Breadcrumbs/styles.d.ts

@@ -6,4 +6,4 @@ export declare const crumbLink: import("@emotion/react").SerializedStyles;
 export declare const crumbText: import("@emotion/react").SerializedStyles;
 export declare const crumbCurrent: import("@emotion/react").SerializedStyles;
 export declare const menu: import("@emotion/react").SerializedStyles;
-export declare const menuItem: import("@emotion/react").SerializedStyles;
+export declare const menuLink: import("@emotion/react").SerializedStyles;

package/dist/components/ContextMenu/ContextMenu.d.ts

@@ -0,0 +1,74 @@
+import { ReactElement, Ref } from 'react';
+import { ContextMenuProps, ContextMenuValue } from './types';
+/**
+ * ContextMenu - The list of options shown inside a dropdown, typeahead,
+ * filter or action menu.
+ *
+ * It renders only the list: open state, the trigger and positioning belong to
+ * the component hosting it, which places it inline or inside a `Popover`.
+ *
+ * ### Selection
+ * `selectionMode` picks the behaviour and the shape of `value` / `onChange`:
+ * - `none` (default): an action menu (`role="menu"`); rows only fire `onAction`
+ * - `single`: one value; marked with a check by default
+ * - `multiple`: an array of values; marked with checkboxes by default
+ * - `includeExclude`: `{ value, type }` entries; every row has + / − controls,
+ *   `selectOnly` rows a single check-circle. Clicking the active control clears
+ *   it; Enter cycles none → include → exclude → none.
+ *
+ * `indicator` overrides how selected rows are marked. Use `startContent` /
+ * `endContent` for anything the design does not cover.
+ *
+ * ### Rows
+ * Each option can carry an avatar, a status dot, a right-hand description and
+ * free start / end content. Text labels ellipsise and show the full text in a
+ * tooltip after a hover. Pass a `ContextMenuGroup` among `items` for a titled
+ * section; groups are separated by a divider.
+ *
+ * ### Keyboard
+ * The list is a single tab stop. Arrow keys, Home and End move the highlight
+ * (announced through `aria-activedescendant`), Enter or Space choose, and
+ * typing jumps to the next option starting with the typed text. Escape is left
+ * to the host. A host that keeps focus elsewhere (e.g. in an input) can drive
+ * the highlight with `activeValue` / `onActiveValueChange`.
+ *
+ * @category Components
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <ContextMenu
+ *   selectionMode="single"
+ *   value={value}
+ *   onChange={setValue}
+ *   items={[
+ *     {
+ *       id: 'project',
+ *       label: 'Project Members',
+ *       items: [
+ *         { value: 'ann', label: 'Ann Lee', avatar: annPhotoUrl },
+ *         { value: 'bob', label: 'Bob Stone', avatar: bobPhotoUrl },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Include / exclude filters
+ * <ContextMenu
+ *   selectionMode="includeExclude"
+ *   value={filters}
+ *   onChange={setFilters}
+ *   items={[
+ *     { value: 'remote', label: 'Remote' },
+ *     { value: 'my-team', label: 'My team', selectOnly: true },
+ *   ]}
+ * />
+ * ```
+ */
+export declare const ContextMenu: <V extends ContextMenuValue = ContextMenuValue>(props: ContextMenuProps<V> & {
+    ref?: Ref<HTMLUListElement>;
+}) => ReactElement;

package/dist/components/ContextMenu/ContextMenuOption.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { ContextMenuIncludeExcludeType, ContextMenuIndicator, ContextMenuItem, ContextMenuItemState, ContextMenuValue } from './types';
+export interface ContextMenuOptionProps<V extends ContextMenuValue> {
+    id: string;
+    item: ContextMenuItem<V>;
+    state: ContextMenuItemState;
+    role: 'option' | 'menuitem';
+    /** Resolved indicator; `null` in `includeExclude` mode. */
+    indicator: ContextMenuIndicator | null;
+    renderItem?: (item: ContextMenuItem<V>, state: ContextMenuItemState) => ReactNode;
+    /** Row click. Not called for include / exclude rows, whose controls choose. */
+    onActivate: () => void;
+    /** An include / exclude control was clicked. */
+    onIncludeExclude: (type: ContextMenuIncludeExcludeType) => void;
+    onHover: () => void;
+}
+/** One option row of a `ContextMenu`. Internal. */
+export declare const ContextMenuOption: <V extends ContextMenuValue>({ id, item, state, role, indicator, renderItem, onActivate, onIncludeExclude, onHover, }: ContextMenuOptionProps<V>) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,3 @@
+export * from './ContextMenu';
+export type * from './types';
+export { getContextMenuOptionId, getNextActiveValue, nextIncludeExcludeType, } from './utils';

package/dist/components/ContextMenu/styles.d.ts

@@ -0,0 +1,17 @@
+import { Theme } from '@emotion/react';
+/** Row height for options and group titles (Figma draws 32 and 34; 34 wins). */
+export declare const ROW_HEIGHT = 34;
+export declare const menu: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const group: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const groupList: import("@emotion/react").SerializedStyles;
+export declare const groupLabel: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const option: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const empty: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const label: import("@emotion/react").SerializedStyles;
+export declare const description: (theme: Theme) => import("@emotion/react").SerializedStyles;
+export declare const status: import("@emotion/react").SerializedStyles;
+export declare const slot: import("@emotion/react").SerializedStyles;
+export declare const checkbox: import("@emotion/react").SerializedStyles;
+export declare const includeExcludeControls: import("@emotion/react").SerializedStyles;
+export declare const includeExcludeControl: import("@emotion/react").SerializedStyles;
+export declare const visuallyHidden: import("@emotion/react").SerializedStyles;

package/dist/components/ContextMenu/types.d.ts

@@ -0,0 +1,153 @@
+import { HTMLAttributes, ReactNode } from 'react';
+/** Value type a {@link ContextMenu} option can carry. */
+export type ContextMenuValue = string | number;
+/**
+ * One selectable row of a {@link ContextMenu}.
+ *
+ * The row is laid out as `[indicator] [status | avatar] [startContent] label
+ * [description] [endContent] [indicator]`; every part but the label is
+ * optional.
+ */
+export interface ContextMenuItem<V extends ContextMenuValue = ContextMenuValue> {
+    /** Identifies the option in `value`, `onChange` and `onAction`. Unique per menu. */
+    value: V;
+    /** Row content. Strings and numbers ellipsise and get a hover tooltip. */
+    label: ReactNode;
+    /**
+     * Plain-text form of `label`, used for type-to-find and the tooltip when
+     * `label` is a node. Defaults to `label` when that is a string or number.
+     */
+    textValue?: string;
+    /** Secondary text at the right of the row, e.g. a date. */
+    description?: ReactNode;
+    /** Image URL (rendered as a 24px `Avatar`) or any node placed before the label. */
+    avatar?: string | ReactNode;
+    /** CSS color or gradient of a 12px status dot placed before the label. */
+    status?: string;
+    /** Extra content placed before the label, after the status dot / avatar. */
+    startContent?: ReactNode;
+    /** Extra content placed after the label and description. */
+    endContent?: ReactNode;
+    /** Skipped by keyboard navigation and ignores clicks. */
+    disabled?: boolean;
+    /**
+     * `includeExclude` mode only: the row is selected as a whole (one blue
+     * check-circle) instead of being included or excluded — e.g. a saved
+     * filter group.
+     */
+    selectOnly?: boolean;
+    /** Class name added to the option's `<li>`. */
+    className?: string;
+    /** Test id set on the option's `<li>`. */
+    'data-testid'?: string;
+}
+/** A titled group of options. The title is not selectable. */
+export interface ContextMenuGroup<V extends ContextMenuValue = ContextMenuValue> {
+    /** Unique per menu. */
+    id: string;
+    /** Group title. */
+    label: ReactNode;
+    items: ContextMenuItem<V>[];
+}
+/** A top-level entry of `items`: an option or a group of options. */
+export type ContextMenuEntry<V extends ContextMenuValue = ContextMenuValue> = ContextMenuItem<V> | ContextMenuGroup<V>;
+/**
+ * How a selected option is marked. Selected rows also get the selected
+ * background, except in `includeExclude` mode.
+ * - `check`: a check mark at the end of selected rows
+ * - `checkbox`: a checkbox at the start of every row
+ * - `checkCircle`: a blue check-circle at the end of every row, filled when selected
+ * - `none`: background only
+ */
+export type ContextMenuIndicator = 'check' | 'checkbox' | 'checkCircle' | 'none';
+/** State of a row in `includeExclude` mode. `selected` is used by `selectOnly` rows. */
+export type ContextMenuIncludeExcludeType = 'include' | 'exclude' | 'selected';
+/** One chosen row in `includeExclude` mode. */
+export interface ContextMenuIncludeExcludeEntry<V extends ContextMenuValue = ContextMenuValue> {
+    value: V;
+    type: ContextMenuIncludeExcludeType;
+}
+/** State passed to `renderItem`. */
+export interface ContextMenuItemState {
+    /** The option is selected (in `includeExclude` mode: included, excluded or selected). */
+    selected: boolean;
+    /** The option is highlighted by the pointer or the keyboard. */
+    active: boolean;
+    disabled: boolean;
+    /** `includeExclude` mode only. */
+    includeExcludeType?: ContextMenuIncludeExcludeType;
+}
+/** Selection props for an action menu: rows only fire `onAction`. */
+export interface ContextMenuNoSelectionProps {
+    selectionMode?: 'none';
+    value?: never;
+    defaultValue?: never;
+    onChange?: never;
+}
+/** Selection props for picking one option. */
+export interface ContextMenuSingleSelectionProps<V extends ContextMenuValue> {
+    selectionMode: 'single';
+    /** Controlled selected value. `null` for none. */
+    value?: V | null;
+    /** Initially selected value when uncontrolled. */
+    defaultValue?: V | null;
+    /** Fires with the newly selected value. Choosing the selected option again keeps it selected. */
+    onChange?: (value: V) => void;
+}
+/** Selection props for picking any number of options. */
+export interface ContextMenuMultipleSelectionProps<V extends ContextMenuValue> {
+    selectionMode: 'multiple';
+    /** Controlled selected values. */
+    value?: V[];
+    /** Initially selected values when uncontrolled. */
+    defaultValue?: V[];
+    /** Fires with the new selection and the option that was toggled. */
+    onChange?: (value: V[], toggled: V) => void;
+}
+/**
+ * Selection props for include / exclude filters. Each row is included,
+ * excluded or neither (`selectOnly` rows: selected or not).
+ */
+export interface ContextMenuIncludeExcludeSelectionProps<V extends ContextMenuValue> {
+    selectionMode: 'includeExclude';
+    /** Controlled chosen rows. */
+    value?: ContextMenuIncludeExcludeEntry<V>[];
+    /** Initially chosen rows when uncontrolled. */
+    defaultValue?: ContextMenuIncludeExcludeEntry<V>[];
+    /** Fires with the new list and the option that changed. */
+    onChange?: (value: ContextMenuIncludeExcludeEntry<V>[], changed: V) => void;
+}
+/** Selection behaviour of a {@link ContextMenu}, keyed by `selectionMode`. */
+export type ContextMenuSelectionProps<V extends ContextMenuValue> = ContextMenuNoSelectionProps | ContextMenuSingleSelectionProps<V> | ContextMenuMultipleSelectionProps<V> | ContextMenuIncludeExcludeSelectionProps<V>;
+/** Props shared by every `selectionMode` of a {@link ContextMenu}. */
+export interface ContextMenuBaseProps<V extends ContextMenuValue> extends Omit<HTMLAttributes<HTMLUListElement>, 'onChange' | 'defaultValue' | 'children'> {
+    /** Options and groups, in display order. */
+    items: ContextMenuEntry<V>[];
+    /**
+     * How selected rows are marked. Defaults to `check` for `single`,
+     * `checkbox` for `multiple` and `none` otherwise. Ignored by
+     * `includeExclude`, which always shows include / exclude controls.
+     */
+    indicator?: ContextMenuIndicator;
+    /**
+     * Fires when an option is chosen by click, Enter or Space, in every mode —
+     * the hook for closing a popup.
+     */
+    onAction?: (value: V) => void;
+    /** Controlled highlighted option (pointer or keyboard). */
+    activeValue?: V | null;
+    /** Initially highlighted option when uncontrolled. */
+    defaultActiveValue?: V | null;
+    /** Fires when the highlighted option changes. */
+    onActiveValueChange?: (value: V | null) => void;
+    /** Replaces the row content between the start and end indicators. */
+    renderItem?: (item: ContextMenuItem<V>, state: ContextMenuItemState) => ReactNode;
+    /** Replaces the content of group titles. */
+    renderGroupLabel?: (group: ContextMenuGroup<V>) => ReactNode;
+    /** Shown when `items` has no options. @default 'No items' */
+    emptyState?: ReactNode;
+    /** Scrolls the list beyond this height (px or any CSS length). */
+    maxHeight?: number | string;
+}
+/** Props of {@link ContextMenu}. */
+export type ContextMenuProps<V extends ContextMenuValue = ContextMenuValue> = ContextMenuBaseProps<V> & ContextMenuSelectionProps<V>;

package/dist/components/ContextMenu/utils.d.ts

@@ -0,0 +1,79 @@
+import { ContextMenuEntry, ContextMenuGroup, ContextMenuIncludeExcludeType, ContextMenuItem, ContextMenuValue } from './types';
+/**
+ * Long enough that the label tooltip does not fire while the pointer is
+ * travelling down the list, short enough to feel like a deliberate hover
+ * (#669).
+ */
+export declare const LABEL_TOOLTIP_DELAY = 1000;
+/** Keeps a long label from producing a tooltip as wide as the list itself. */
+export declare const LABEL_TOOLTIP_MAX_WIDTH = 320;
+/**
+ * Only a primitive is safe to repeat inside a tooltip. Rendering the same
+ * element twice mounts two independent copies of it, so labels made of
+ * components get no tooltip.
+ */
+export declare const asText: (value: unknown) => string | number | undefined;
+export declare const isGroup: <V extends ContextMenuValue>(entry: ContextMenuEntry<V>) => entry is ContextMenuGroup<V>;
+/** Every option in display order, groups unwrapped. */
+export declare const flattenItems: <V extends ContextMenuValue>(entries: ContextMenuEntry<V>[]) => ContextMenuItem<V>[];
+/** Text used for type-to-find and the label tooltip. */
+export declare const getTextValue: <V extends ContextMenuValue>(item: ContextMenuItem<V>) => string | undefined;
+/**
+ * Where Enter moves an `includeExclude` row: none → include → exclude → none,
+ * or none ⇄ selected for `selectOnly` rows. For driving that cycle from an
+ * input that keeps focus while it highlights rows.
+ *
+ * @example
+ * ```ts
+ * nextIncludeExcludeType(undefined, false); // 'include'
+ * nextIncludeExcludeType('include', false); // 'exclude'
+ * nextIncludeExcludeType('exclude', false); // undefined
+ * nextIncludeExcludeType(undefined, true); // 'selected'
+ * ```
+ */
+export declare const nextIncludeExcludeType: (current: ContextMenuIncludeExcludeType | undefined, selectOnly: boolean) => ContextMenuIncludeExcludeType | undefined;
+/**
+ * The enabled option `step` places away from `from`, wrapping around the
+ * ends. With no `from`, ArrowDown lands on the first option and ArrowUp on
+ * the last.
+ */
+export declare const getSteppedIndex: (enabled: boolean[], from: number, step: 1 | -1) => number;
+/**
+ * Makes any string safe inside an id and an IDREF list: characters other than
+ * letters, digits and `-` become `_<hex>_`, so distinct inputs stay distinct.
+ */
+export declare const escapeId: (value: string) => string;
+/**
+ * DOM id of an option, for `aria-activedescendant` on an element outside the
+ * list (e.g. a combobox input). `menuId` is the `id` given to the ContextMenu.
+ * Characters not allowed in an id are escaped, so any value is safe.
+ *
+ * @example
+ * ```tsx
+ * <input
+ *   aria-controls="people-menu"
+ *   aria-activedescendant={
+ *     active == null ? undefined : getContextMenuOptionId('people-menu', active)
+ *   }
+ * />
+ * <ContextMenu id="people-menu" items={items} activeValue={active} />
+ * ```
+ */
+export declare const getContextMenuOptionId: (menuId: string, value: ContextMenuValue) => string;
+/**
+ * Where a navigation key moves the highlight: ArrowDown / ArrowUp step over
+ * disabled options and wrap, Home / End jump to the ends. Returns `undefined`
+ * for any other key, so a host driving the list from its own input can tell
+ * whether the key was a navigation key.
+ *
+ * @example
+ * ```tsx
+ * const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+ *   const next = getNextActiveValue(items, active, event.key);
+ *   if (next === undefined) return; // not a navigation key
+ *   event.preventDefault();
+ *   setActive(next);
+ * };
+ * ```
+ */
+export declare const getNextActiveValue: <V extends ContextMenuValue>(entries: ContextMenuEntry<V>[], activeValue: V | null | undefined, key: string) => V | null | undefined;

package/dist/components/Dropdown/types.d.ts

@@ -232,4 +232,11 @@ export interface DropdownContextType {
      * Computed by Dropdown based on dropdownPosition prop and available viewport space
      */
     placement?: 'top' | 'bottom';
+    /**
+     * Option highlighted by the keyboard or the pointer. Focus stays on the
+     * toggle, so the list is driven from there.
+     */
+    activeValue?: string | number | null;
+    /** Moves the highlight; called by the list on pointer moves. */
+    setActiveValue?: (value: string | number | null) => void;
 }

package/dist/components/DropdownOptions/DropdownOptions.d.ts

@@ -2,8 +2,9 @@ import { DropdownItemsListProps } from './types';
 /**
  * DropdownOptions - Options menu container for Dropdown component
  *
- * Renders the scrollable list of options that appears when the dropdown is open.
- * Provides proper ARIA attributes for accessibility and keyboard navigation.
+ * Renders the `DropdownOption` children as a `ContextMenu` placed under (or
+ * above) the Dropdown toggle. Focus stays on the toggle; the highlighted
+ * option is driven from there and announced through `aria-activedescendant`.
  *
  * Placement (opening upward or downward) is driven entirely by the parent
  * Dropdown via context — this component does not calculate position itself.
@@ -31,9 +32,8 @@ import { DropdownItemsListProps } from './types';
  * @see {@link DropdownOption} - Individual option components
  *
  * @accessibility
- * - Uses role="listbox" for proper ARIA semantics
- * - Supports keyboard navigation (Arrow keys, Enter, Escape)
- * - Screen reader friendly
+ * - Uses role="listbox" with role="option" rows
+ * - Arrow keys, Home, End, Enter, Space and Escape on the toggle
  */
 declare const DropdownOptions: ({ "aria-labelledby": ariaLabelledbyNative, ariaLabelledby, id, children, }: DropdownItemsListProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default DropdownOptions;

package/dist/components/DropdownOptions/useToggleListKeys.d.ts

@@ -0,0 +1,33 @@
+import { KeyboardEvent } from 'react';
+import { ContextMenuItem } from '../ContextMenu';
+import { OptionValue } from './utils';
+/** Options of {@link useToggleListKeys}. */
+export interface UseToggleListKeysOptions {
+    /** Id of the ContextMenu the toggle controls. */
+    listId: string;
+    isOpen: boolean;
+    disabled?: boolean;
+    menuItems: ContextMenuItem<OptionValue>[];
+    /** Highlighted option. */
+    activeValue: OptionValue | null;
+    setActiveValue: (value: OptionValue | null) => void;
+    /** Opens the list; `key` is the arrow that opened it. */
+    open: (key: string) => void;
+    close: () => void;
+    /** Enter or Space on the highlighted option. */
+    onPick: (value: OptionValue) => void;
+    /** Consumer handlers, run first; `preventDefault()` skips the built-in keys. */
+    onKeyDown?: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    onKeyUp?: (event: KeyboardEvent<HTMLButtonElement>) => void;
+}
+/**
+ * Keyboard for a dropdown toggle that keeps focus while it drives its list:
+ * arrows open it, then Arrow/Home/End move the highlight, Enter/Space pick,
+ * Escape/Tab close. Returns the toggle's handlers and its
+ * `aria-activedescendant`.
+ */
+export declare const useToggleListKeys: ({ listId, isOpen, disabled, menuItems, activeValue, setActiveValue, open, close, onPick, onKeyDown, onKeyUp, }: UseToggleListKeysOptions) => {
+    onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    onKeyUp: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    'aria-activedescendant': string | undefined;
+};

package/dist/components/DropdownOptions/utils.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { ContextMenuItem } from '../ContextMenu';
+/** Value of a Dropdown option as the list sees it. */
+export type OptionValue = string | number;
+/**
+ * Reads `DropdownOption` children into ContextMenu items. The label resolves
+ * as `children` → `label` → `value`, as it always has.
+ */
+export declare const toDropdownMenuItems: (children: React.ReactNode) => ContextMenuItem<OptionValue>[];

package/dist/components/FiltersMultiSelect/FiltersMultiSelectProvider.d.ts

@@ -1,7 +1,16 @@
+import { MutableRefObject } from 'react';
 import { UseFiltersMultiSelectStore } from './useFiltersMultiSelect';
+import type { FilterMenuItem } from './utils';
 export interface FiltersMultiSelectContextValue {
     store: UseFiltersMultiSelectStore;
     emptyNode?: React.ReactNode;
+    /** Id of the options list, referenced by the search input. */
+    listId?: string;
+    /** Highlighted option, driven from the search input and the pointer. */
+    activeValue?: string | null;
+    setActiveValue?: (value: string | null) => void;
+    /** The rendered options, kept here for the search input's keyboard. */
+    itemsRef?: MutableRefObject<FilterMenuItem[]>;
 }
 export declare const FiltersMultiSelectProvider: ({ children, value, }: {
     value: FiltersMultiSelectContextValue;

package/dist/components/FiltersMultiSelect/components/FiltersMultiSelectOption.d.ts

@@ -1,7 +1,37 @@
 import { Filter } from '../useFiltersMultiSelect';
 export interface FiltersMultiSelectOptionProps {
+    /** The filter this row adds. `group: true` makes it a select-only row. */
     filter: Filter;
+    /** Row content. */
     children: React.ReactNode;
+    /**
+     * @deprecated Ignored — the row's state comes from the store's selected
+     * filters. Removed in the next major release.
+     */
     selected?: boolean;
 }
-export declare const FiltersMultiSelectOption: ({ filter, children, selected, }: FiltersMultiSelectOptionProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * FiltersMultiSelectOption - One filter row of a `FiltersMultiSelect`.
+ *
+ * Declarative: `FiltersMultiSelectOptions` reads its props and renders the
+ * row, so it renders nothing on its own. Regular filters get + (include) and
+ * − (exclude) controls; `group` filters get a single check-circle.
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * <FiltersMultiSelectOptions>
+ *   <FiltersMultiSelectOption filter={{ id: '1', label: 'Active' }}>
+ *     Active
+ *   </FiltersMultiSelectOption>
+ *   <FiltersMultiSelectOption filter={{ id: 'g', label: 'Saved', group: true }}>
+ *     Saved
+ *   </FiltersMultiSelectOption>
+ * </FiltersMultiSelectOptions>
+ * ```
+ *
+ * @see {@link FiltersMultiSelectOptions} - The list that renders it
+ */
+export declare const FiltersMultiSelectOption: (_props: FiltersMultiSelectOptionProps) => null;