@ssa-ui-kit/core 3.26.4 → 3.27.1

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

@@ -0,0 +1,378 @@
+import { CSSProperties, KeyboardEvent, MouseEvent, ReactNode, Ref } from 'react';
+import { ColumnResizeMode } from '../Table/types';
+/** Direction of a {@link DataTableSort}. */
+export type DataTableSortDirection = 'asc' | 'desc';
+/**
+ * How many rows of a {@link DataTable} the user can select: `multiple` adds a
+ * checkbox column with a select-all checkbox, `single` a radio column.
+ */
+export type DataTableSelectionMode = 'none' | 'single' | 'multiple';
+/**
+ * Attributes a {@link DataTable} adds to one body row or cell, returned by
+ * `getRowProps` on the table or `getCellProps` on a column. For styling a row
+ * or cell from its data.
+ *
+ * @example
+ * ```ts
+ * getRowProps: (row) => ({
+ *   className: row.excluded ? 'excluded' : undefined,
+ *   background: row.awaitingReply ? 'rgba(242, 136, 142, 0.08)' : undefined,
+ * })
+ * ```
+ */
+export interface DataTableElementProps {
+    /** Added to the element's class names. */
+    className?: string;
+    /**
+     * Inline style of the element. On a row, a `background` here is hidden by
+     * the cells, which paint their own; use the `background` field instead.
+     */
+    style?: CSSProperties;
+    /**
+     * A colour painted over the cells, such as a translucent tint. Laid over
+     * white, so frozen cells stay opaque. On a row, the hover and selected
+     * states show over it; on a cell, it stays.
+     */
+    background?: string;
+    /** `data-*` attributes, for CSS or tests. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+}
+/**
+ * The column a {@link DataTable} is sorted by. One column at a time; `null`
+ * when the rows are in the order they were given.
+ */
+export interface DataTableSort {
+    /** `id` of the sorted column. */
+    columnId: string;
+    direction: DataTableSortDirection;
+}
+/**
+ * One column of a {@link DataTable}.
+ *
+ * @example
+ * ```tsx
+ * const columns: DataTableColumn<Employee>[] = [
+ *   { id: 'name', header: 'Name', cell: (row) => row.name, sortable: true },
+ *   { id: 'salary', header: 'Salary', cell: (row) => fmt(row.salary), align: 'right' },
+ * ];
+ * ```
+ */
+export interface DataTableColumn<Row> {
+    /**
+     * Stable, unique id. Column state (order, widths, frozen, hidden) and the
+     * sort refer to columns by it, so it must not change between renders.
+     */
+    id: string;
+    /** Header cell content. */
+    header: ReactNode;
+    /**
+     * Body cell content for a row. `rowIndex` is the row's position as shown,
+     * after sorting, not its index in `data`.
+     */
+    cell: (row: Row, rowIndex: number) => ReactNode;
+    /**
+     * Text alignment of the header and body cells.
+     * @default 'left'
+     */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * Whether clicking the header sorts by this column.
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * The name the server knows this column by, when it differs from `id`.
+     * Handed to `onSortChange` as its second argument.
+     * @default id
+     */
+    sortKey?: string;
+    /**
+     * Sorts the rows in the browser while this column is the sorted one.
+     * Without it, sorting only reports the new sort through `onSortChange` and
+     * the rows are expected to arrive sorted, which is right for server data.
+     *
+     * Compare ascending; the table reverses the result for `desc`.
+     *
+     * @example
+     * ```ts
+     * sortFn: (a, b) => a.name.localeCompare(b.name)
+     * ```
+     */
+    sortFn?: (a: Row, b: Row) => number;
+    /**
+     * Starting width in pixels, used until the user resizes the column or
+     * `columnState.widths` says otherwise. Columns without one are measured on
+     * first layout.
+     */
+    width?: number;
+    /**
+     * Narrowest the user can resize this column to, in pixels. Overrides the
+     * table's `minColumnWidth`.
+     */
+    minWidth?: number;
+    /**
+     * Widest the user can resize this column to, in pixels. Overrides the
+     * table's `maxColumnWidth`.
+     */
+    maxWidth?: number;
+    /**
+     * Class name, style, background or data attributes for this column's body
+     * cell in a given row, such as colouring a cell by its value. Header cells
+     * are not affected.
+     *
+     * @example
+     * ```ts
+     * getCellProps: (row) => ({ background: heatColor(row.score) })
+     * ```
+     */
+    getCellProps?: (row: Row, rowIndex: number) => DataTableElementProps;
+    /**
+     * Whether the user can resize this column, in a table with
+     * `resizableColumns`. Turn it off for actions or checkbox columns.
+     * @default true
+     */
+    resizable?: boolean;
+    /**
+     * Whether the header offers the freeze menu, in a table with
+     * `freezeControls`. The column can still be frozen through `columnState`.
+     * @default true
+     */
+    freezable?: boolean;
+    /**
+     * Whether the user can move this column, in a table with
+     * `reorderableColumns`. A column that cannot move keeps its place, and the
+     * others move past it.
+     * @default true
+     */
+    reorderable?: boolean;
+    /**
+     * Whether the user can hide this column, from its header menu in a table
+     * with `hideableColumns`, or from `DataTableColumnPicker`. The column can
+     * still be hidden through `columnState`.
+     * @default true
+     */
+    hideable?: boolean;
+}
+/**
+ * Everything about a {@link DataTable}'s columns the user can change, keyed
+ * by column id, so it survives columns being added, removed or reordered.
+ * Store it whole to remember a user's layout.
+ */
+export interface DataTableColumnState {
+    /**
+     * Column ids in display order. Columns missing from it follow, in the
+     * order of `columns`.
+     */
+    order: string[];
+    /** Width in pixels per column id. */
+    widths: Record<string, number>;
+    /** Column ids frozen to each edge. */
+    frozen: {
+        start: string[];
+        end: string[];
+    };
+    /** Ids of columns that are not shown. */
+    hidden: string[];
+}
+/**
+ * Props of {@link DataTable}.
+ *
+ * @example
+ * ```tsx
+ * <DataTable data={rows} columns={columns} />
+ * ```
+ */
+export interface DataTableProps<Row> {
+    /** Rows to show, in the order to show them unless a column sorts them. */
+    data: Row[];
+    /**
+     * Column definitions. Every `id` must be unique. Need not be memoised:
+     * the table only rebuilds its model when the columns' ids or sort settings
+     * change, and always renders with the latest `header` and `cell`.
+     */
+    columns: DataTableColumn<Row>[];
+    /**
+     * Stable id of a row, for rows whose id is not in an `id` field, such as
+     * `employeeId` or a key built from several fields. Rows are keyed by it
+     * and selection and expanded state refer to it.
+     *
+     * Without it, a row's own `id` (string or number) is used. Rows without
+     * either are keyed by position, children under their parent (`"2.0"`),
+     * which remounts cells whenever the order changes.
+     * @default (row) => String(row.id)
+     */
+    getRowId?: (row: Row, index: number) => string;
+    /**
+     * Column layout, for the controlled case. Partial values are filled in
+     * with defaults. Hold it in state and update it from
+     * `onColumnStateChange`.
+     */
+    columnState?: Partial<DataTableColumnState>;
+    /** Starting column layout, for the uncontrolled case. */
+    defaultColumnState?: Partial<DataTableColumnState>;
+    /**
+     * Called whenever the user changes the layout: on every frame of a resize
+     * drag, when moving or hiding a column, and when freezing or unfreezing. Not called for widths the table
+     * measures itself on first layout.
+     */
+    onColumnStateChange?: (columnState: DataTableColumnState) => void;
+    /**
+     * Lets the user resize columns by dragging the right edge of the header.
+     * @default false
+     */
+    resizableColumns?: boolean;
+    /**
+     * How a resize spends width. `fit` keeps the table's width: the resizable
+     * columns to the right share the change, in proportion to their widths.
+     * `expand` grows or shrinks the table instead, so it scrolls sideways.
+     * @default 'fit'
+     */
+    columnResizeMode?: ColumnResizeMode;
+    /**
+     * Narrowest a column can be resized to, in pixels. A column's own
+     * `minWidth` wins.
+     * @default 64
+     */
+    minColumnWidth?: number;
+    /**
+     * Widest a column can be resized to, in pixels. A column's own `maxWidth`
+     * wins. Unbounded when omitted.
+     */
+    maxColumnWidth?: number;
+    /**
+     * Gives every header a menu to freeze its column to either edge.
+     * @default false
+     */
+    freezeControls?: boolean;
+    /**
+     * Lets the user move columns: by dragging the grip at the left of the
+     * header, or with "Move left" and "Move right" in the header menu. A column
+     * moves only among columns frozen to the same edge, or among the unfrozen
+     * ones. The order is kept in `columnState.order`.
+     * @default false
+     */
+    reorderableColumns?: boolean;
+    /**
+     * Adds "Hide column" to the header menu. The last visible column cannot be
+     * hidden. Hidden columns are kept in `columnState.hidden`; bring them back
+     * with `DataTableColumnPicker`.
+     * @default false
+     */
+    hideableColumns?: boolean;
+    /**
+     * Keeps the header in view while the rows scroll. Give the table a height
+     * limit through `maxHeight`.
+     * @default false
+     */
+    stickyHeader?: boolean;
+    /**
+     * Tallest the table gets before it scrolls vertically. Any CSS value.
+     * Unbounded when omitted, so only horizontal overflow scrolls.
+     */
+    maxHeight?: string | number;
+    /** Sorted column, for the controlled case. `null` for none. */
+    sort?: DataTableSort | null;
+    /** Starting sort, for the uncontrolled case. */
+    defaultSort?: DataTableSort | null;
+    /**
+     * Called when a sortable header is clicked. A column starts ascending and
+     * toggles between ascending and descending after that. The second argument
+     * is the column's `sortKey` (its `id` without one), ready for a request.
+     */
+    onSortChange?: (sort: DataTableSort | null, sortKey: string | null) => void;
+    /**
+     * Marks the table busy. Rows already shown stay, dimmed, so a re-fetch
+     * after sorting does not make the table jump; with no rows yet,
+     * `loadingState` is shown instead.
+     * @default false
+     */
+    isLoading?: boolean;
+    /**
+     * Shown in place of the rows while loading with none to show.
+     * @default 'Loading…'
+     */
+    loadingState?: ReactNode;
+    /**
+     * Shown in place of the rows when there are none.
+     * @default 'No results'
+     */
+    emptyState?: ReactNode;
+    /**
+     * Called when a row is clicked, or when Enter is pressed on a focused row;
+     * rows become focusable when this is set. Clicks on a button, link, input
+     * or menu inside the row keep their own behaviour.
+     *
+     * Screen readers do not announce a row as actionable, so also give the
+     * row a link or button in a cell when the action matters.
+     */
+    onRowClick?: (row: Row, event: MouseEvent<HTMLTableRowElement> | KeyboardEvent<HTMLTableRowElement>) => void;
+    /**
+     * Class name, style, background or data attributes for a body row, such as
+     * tinting rows that need attention. Each row also carries `data-row-id`.
+     *
+     * @example
+     * ```ts
+     * getRowProps: (row) => (row.excluded ? { className: 'excluded' } : {})
+     * ```
+     */
+    getRowProps?: (row: Row, rowIndex: number) => DataTableElementProps;
+    /**
+     * Children of a row, shown nested under it, to any depth. Rows with
+     * children get an expand button in a column at the start, and their own
+     * styling; children are indented. A sorted column sorts the children of
+     * each row among themselves.
+     *
+     * @example
+     * ```ts
+     * getSubRows: (team) => team.members
+     * ```
+     */
+    getSubRows?: (row: Row) => Row[] | undefined;
+    /** Ids of the expanded rows, for the controlled case. */
+    expandedRowIds?: string[];
+    /**
+     * Which rows start expanded, for the uncontrolled case: `true` for all,
+     * including rows that arrive later, or a list of ids.
+     * @default false
+     */
+    defaultExpanded?: boolean | string[];
+    /** Called with the ids of the expanded rows whenever the user changes them. */
+    onExpandedChange?: (expandedRowIds: string[]) => void;
+    /**
+     * Lets the user select rows: `multiple` adds a checkbox column whose header
+     * checkbox selects or clears the rows shown, `single` a radio column.
+     * With `getSubRows`, selecting a row selects everything under it, and a
+     * row with some of its children selected shows a partial check.
+     * Selection is kept as row ids (see `getRowId`), so rows selected on
+     * another page stay selected.
+     * @default 'none'
+     */
+    selectionMode?: DataTableSelectionMode;
+    /** Ids of the selected rows, for the controlled case. */
+    selectedRowIds?: string[];
+    /** Ids of the rows selected at first, for the uncontrolled case. */
+    defaultSelectedRowIds?: string[];
+    /** Called with the ids of the selected rows whenever the user changes them. */
+    onSelectionChange?: (selectedRowIds: string[]) => void;
+    /**
+     * Whether a row can be selected. Rows that cannot get a disabled checkbox
+     * and are skipped by the header checkbox.
+     *
+     * With `getSubRows`, a row that cannot be selected but has rows below it
+     * that can keeps an enabled checkbox, which selects those rows. Its own id
+     * is never in the selection, even when its checkbox shows checked.
+     */
+    isRowSelectable?: (row: Row) => boolean;
+    /**
+     * Accessible name of a row's selection checkbox, such as the person's
+     * name. Without it the row is named by its position.
+     * @default (row, rowIndex) => `Select row ${rowIndex + 1}`
+     */
+    getRowLabel?: (row: Row, rowIndex: number) => string;
+    /** Rendered below the table, such as `Pagination`. */
+    footer?: ReactNode;
+    /** Class name of the outer container. */
+    className?: string;
+    /** Forwarded to the `table` element. */
+    ref?: Ref<HTMLTableElement>;
+}

package/dist/components/DataTable/useColumnReorder.d.ts

@@ -0,0 +1,31 @@
+import { PointerEvent, RefObject } from 'react';
+/** A drag in progress: the column held, and the column it would drop on. */
+export interface ColumnDrag {
+    id: string;
+    overId: string | null;
+}
+interface UseColumnReorderOptions {
+    tableRef: RefObject<HTMLTableElement | null>;
+    /** Whether `id` may be dropped where `targetId` is. */
+    canDrop: (id: string, targetId: string) => boolean;
+    onDrop: (id: string, targetId: string) => void;
+}
+/**
+ * Drag-to-reorder for header grips. The pointer is captured by the grip, and
+ * the drop target is whichever header cell is under it horizontally, so the
+ * pointer can wander above or below the header. Escape cancels.
+ *
+ * State changes only when the target does, not on every move, so a drag
+ * re-renders the table a handful of times rather than once per frame.
+ */
+export declare const useColumnReorder: ({ tableRef, canDrop, onDrop, }: UseColumnReorderOptions) => {
+    drag: ColumnDrag | null;
+    getGripProps: (id: string) => {
+        onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+        onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onLostPointerCapture: () => void;
+    };
+};
+export {};

package/dist/components/DataTable/useDataTableModel.d.ts

@@ -0,0 +1,36 @@
+import { DataTableColumn, DataTableColumnState, DataTableSort } from './types';
+interface UseDataTableModelOptions<Row> {
+    data: Row[];
+    columns: DataTableColumn<Row>[];
+    getRowId?: (row: Row, index: number) => string;
+    getSubRows?: (row: Row) => Row[] | undefined;
+    /** Ids of the expanded rows, or `true` for all of them. */
+    expanded: true | string[];
+    columnState: DataTableColumnState;
+    sort: DataTableSort | null;
+}
+/** A visible row, in display order, with what rendering needs. */
+export interface DataTableModelRow<Row> {
+    id: string;
+    original: Row;
+    /** 0 for a top-level row, 1 for its children, and so on. */
+    depth: number;
+    hasChildren: boolean;
+    isExpanded: boolean;
+}
+/** Where a row sits in the tree, expanded or not. */
+export interface DataTableTreeNode<Row> {
+    original: Row;
+    parentId?: string;
+    childIds: string[];
+}
+/**
+ * Turns the public props into rows and columns in display order. The only
+ * place TanStack Table is used, so it never reaches the public API.
+ */
+export declare const useDataTableModel: <Row>({ data, columns, getRowId, getSubRows, expanded, columnState, sort, }: UseDataTableModelOptions<Row>) => {
+    visibleColumns: DataTableColumn<Row>[];
+    rows: DataTableModelRow<Row>[];
+    tree: Map<string, DataTableTreeNode<Row>>;
+};
+export {};

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

@@ -0,0 +1,82 @@
+import { CSSProperties } from 'react';
+import { DataTableColumn, DataTableColumnState, DataTableElementProps, DataTableSort } from './types';
+/** Width of the checkbox or radio column, in pixels. */
+export declare const SELECTION_COLUMN_WIDTH = 48;
+/** Width of the expand/collapse column, in pixels. */
+export declare const EXPANDER_COLUMN_WIDTH = 36;
+/** Extra left padding of a nested row's first cell, per level. */
+export declare const NESTED_INDENT = 24;
+export declare const EMPTY_COLUMN_STATE: DataTableColumnState;
+/** Fills a partial column state in with defaults. */
+export declare const toColumnState: (value?: Partial<DataTableColumnState>) => DataTableColumnState;
+/**
+ * What the TanStack model depends on. Header and cell renderers are left out
+ * on purpose: they are read from the latest `columns` at render time, so an
+ * inline `columns` array does not rebuild the model on every render.
+ */
+export declare const getColumnsSignature: <Row>(columns: DataTableColumn<Row>[]) => string;
+/**
+ * The sort after a click on a sortable header: the same column flips
+ * direction, another column starts ascending.
+ */
+export declare const getNextSort: (current: DataTableSort | null, columnId: string) => DataTableSort;
+/** Whether a click landed on something inside a row with its own behaviour. */
+export declare const isInteractiveTarget: (target: EventTarget | null, row: HTMLElement) => boolean;
+/**
+ * Every column id in display order: `order` first, skipping unknown ids, then
+ * the rest in the order of `columns`. The same rule TanStack applies.
+ */
+export declare const getFullOrder: <Row>(columns: DataTableColumn<Row>[], order: string[]) => string[];
+/** Where a column sits while scrolling: frozen to an edge, or not. */
+export declare const getFreezeZone: (frozen: DataTableColumnState["frozen"], id: string) => "start" | "end" | "scroll";
+/**
+ * Moves column `id` to where `targetId` is, shifting the columns between.
+ * Only the slots `canMoveTo` accepts take part, so every other column keeps
+ * its position. Returns `null` when the target is not one of those slots.
+ */
+export declare const moveColumn: (order: string[], id: string, targetId: string, canMoveTo: (id: string) => boolean) => string[] | null;
+/** The nearest slot `canMoveTo` accepts on one side of column `id`. */
+export declare const getAdjacentColumn: (order: string[], id: string, side: "left" | "right", canMoveTo: (id: string) => boolean) => string | null;
+/** How a row's checkbox shows. */
+export type CheckState = 'checked' | 'partial' | 'unchecked';
+/**
+ * Cascading selection over a tree of rows. A row with selectable
+ * descendants is not selected for itself: it follows the leaves below it,
+ * checked when all are, partly when some are. Its id is in the selection
+ * exactly when it is checked, so the ids still name every selected row —
+ * unless `canSelect` rejects it: its checkbox still selects the rows below,
+ * but its own id is never in the selection.
+ *
+ * Ids not in the tree, such as rows on another page, are left alone.
+ */
+export declare const createSelectionTree: (tree: Map<string, {
+    parentId?: string;
+    childIds: string[];
+}>, canSelect: (id: string) => boolean) => {
+    rowState: (id: string, selected: Set<string>) => CheckState;
+    /** Whether the row has anything to select, itself or below. */
+    isSelectable: (id: string) => boolean;
+    allState: (selected: Set<string>) => CheckState;
+    toggleRow: (ids: string[], id: string, on: boolean) => string[];
+    toggleAll: (ids: string[], on: boolean) => string[];
+};
+/**
+ * A row's own `id` field as a row id, when it has a string or number one.
+ * What a table without `getRowId` keys its rows by.
+ */
+export declare const getOwnRowId: (row: unknown) => string | undefined;
+/**
+ * Turns what `getRowProps` returned into props for the row element. The
+ * `background` travels as a custom property for the `tintedRow` style, so it
+ * reaches the cells, which paint their own background over the row's.
+ */
+export declare const toRowElementProps: ({ background, style, ...rest }?: DataTableElementProps) => Omit<DataTableElementProps, "background"> & {
+    isTinted: boolean;
+};
+/**
+ * Turns what a column's `getCellProps` returned into props for the cell
+ * element. The table's own style, the nested indent, wins over the column's,
+ * so a cell style cannot flatten the tree. The `background` is inline, so it
+ * outlasts the row's hover and selected states.
+ */
+export declare const toCellElementProps: ({ background, style, ...rest }?: DataTableElementProps, ownStyle?: CSSProperties) => Omit<DataTableElementProps, "background">;

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

@@ -94,5 +94,5 @@ import { DropdownProps } from './types';
  *
  * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
  */
-declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, disabled, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, avatarBorder, label, labelBadge, helperText, errors, success, icon, width, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, disabled, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, avatarBorder, label, labelBadge, helperText, errors, success, icon, width, searchable, searchPlaceholder, searchEmptyState, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Dropdown;

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

@@ -161,6 +161,36 @@ export interface DropdownProps<P extends DropdownOptionProps> extends CommonProp
      * ```
      */
     width?: string | number;
+    /**
+     * Adds a search box above the open list. Typing filters the options by
+     * their text (case-insensitive, anywhere in the text); a group stays while
+     * any of its options match. Options whose `children` is markup are matched
+     * by their `textValue`.
+     *
+     * Focus moves to the search box on open and keeps driving the list: arrows
+     * move the highlight, Enter picks, Escape clears the search, then closes.
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * <Dropdown searchable searchPlaceholder="Search country" onChange={setCountry}>
+     *   {countries.map((c) => (
+     *     <DropdownOption key={c.code} value={c.code} label={c.name} />
+     *   ))}
+     * </Dropdown>
+     * ```
+     */
+    searchable?: boolean;
+    /**
+     * Placeholder and accessible name of the search box.
+     * @default 'Search'
+     */
+    searchPlaceholder?: string;
+    /**
+     * Shown in the list when nothing matches the search.
+     * @default 'No results found'
+     */
+    searchEmptyState?: React.ReactNode;
     /**
      * Props object for sub-components
      * Allows fine-grained control over component parts
@@ -246,4 +276,8 @@ export interface DropdownContextType {
     activeValue?: string | number | null;
     /** Moves the highlight; called by the list on pointer moves. */
     setActiveValue?: (value: string | number | null) => void;
+    /** The list sits in the search card, which does the positioning. */
+    searchable?: boolean;
+    /** Shown when the list has no options. */
+    emptyState?: React.ReactNode;
 }

package/dist/components/DropdownOption/DropdownOption.d.ts

@@ -18,6 +18,11 @@ export interface DropdownItemProps extends CommonProps, Omit<React.LiHTMLAttribu
     children?: React.ReactNode;
     /** Avatar or icon to display before the option content (e.g. <Avatar size={20} image={url} />) */
     avatar?: React.ReactNode;
+    /**
+     * Plain text of the option, for search and type-to-find. Needed when
+     * `children` is markup rather than text; defaults to the text label.
+     */
+    textValue?: string;
 }
 /**
  * DropdownOption - A single selectable row inside `Dropdown` or

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

@@ -0,0 +1,25 @@
+import { KeyboardEvent, ReactNode } from 'react';
+/** Props of {@link DropdownSearch}. */
+export interface DropdownSearchProps {
+    /** Typed text. */
+    query: string;
+    onQueryChange: (query: string) => void;
+    placeholder: string;
+    /** Id of the list the input drives. */
+    listId: string;
+    /** Opens upward or downward from the toggle. */
+    placement?: 'top' | 'bottom';
+    zIndex?: number;
+    /** The highlighted option's id. */
+    'aria-activedescendant'?: string;
+    onKeyDown: (event: KeyboardEvent<HTMLInputElement>) => void;
+    onKeyUp?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    /** The options list. */
+    children: ReactNode;
+}
+/**
+ * The open list of a searchable `Dropdown` / `MultipleDropdown`: a search box,
+ * focused on open, above the options. The box is the combobox while the list
+ * is open — it keeps focus and points at the highlighted option.
+ */
+export declare const DropdownSearch: ({ query, onQueryChange, placeholder, listId, placement, zIndex, children, ...inputProps }: DropdownSearchProps) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -2,7 +2,7 @@ import { KeyboardEvent } from 'react';
 import { ContextMenuEntry } from '../ContextMenu';
 import { OptionValue } from './utils';
 /** Options of {@link useToggleListKeys}. */
-export interface UseToggleListKeysOptions {
+export interface UseToggleListKeysOptions<E extends HTMLElement = HTMLButtonElement> {
     /** Id of the ContextMenu the toggle controls. */
     listId: string;
     isOpen: boolean;
@@ -16,18 +16,24 @@ export interface UseToggleListKeysOptions {
     close: () => void;
     /** Enter or Space on the highlighted option. */
     onPick: (value: OptionValue) => void;
+    /**
+     * Keys go to a text input (the search box): Space types a space and
+     * Home / End move the caret instead of the highlight.
+     */
+    typing?: boolean;
     /** Consumer handlers, run first; `preventDefault()` skips the built-in keys. */
-    onKeyDown?: (event: KeyboardEvent<HTMLButtonElement>) => void;
-    onKeyUp?: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    onKeyDown?: (event: KeyboardEvent<E>) => void;
+    onKeyUp?: (event: KeyboardEvent<E>) => 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`.
+ * `aria-activedescendant`. With `typing`, drives the list from a search input
+ * instead.
  */
-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;
+export declare const useToggleListKeys: <E extends HTMLElement = HTMLButtonElement>({ listId, isOpen, disabled, menuItems, activeValue, setActiveValue, open, close, onPick, typing, onKeyDown, onKeyUp, }: UseToggleListKeysOptions<E>) => {
+    onKeyDown: (event: KeyboardEvent<E>) => void;
+    onKeyUp: (event: KeyboardEvent<E>) => void;
     'aria-activedescendant': string | undefined;
 };

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

@@ -14,3 +14,10 @@ export declare const flattenDropdownOptions: (children: React.ReactNode) => Reac
  * `children` → `label` → `value`, as it always has.
  */
 export declare const toDropdownMenuItems: (children: React.ReactNode) => ContextMenuEntry<OptionValue>[];
+/**
+ * The `DropdownOption` children whose text contains `query` (case-insensitive),
+ * in display order. A `DropdownOptionGroup` is kept, holding only its matching
+ * options, while any of them match. An empty query returns the children as is.
+ * Options with no text (custom markup and no `textValue`) never match.
+ */
+export declare const filterDropdownOptions: (children: React.ReactNode, query: string) => React.ReactElement[];