@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/inputs/MultiSelectInput.d.ts

@@ -1,65 +1,176 @@
-import { type ReactNode } from "react";
-import type { Icon as PhosphorIcon } from "@phosphor-icons/react";
-import { DropdownPosition } from "../dropdown/Dropdown";
-import { InputSize, InputVariant } from "./Input";
-import { type SelectInputOption } from "./SelectInput";
-export interface PinnedOptions {
-    id: string;
-    label: string;
-    /** The `SelectInputOption.id`s this shortcut selects, all at once. */
-    optionIds: string[];
+import { type AriaAttributes, type CSSProperties, type ReactElement, type ReactNode, type RefAttributes } from "react";
+import type { Placement } from "../theme/enums.js";
+import { type SelectOption, type SelectOptionState } from "./SelectInput.js";
+/** Canonical rungs; MultiSelectInput supports all five (SelectInput's rung table). */
+export declare enum MultiSelectInputSize {
+    /** 20px field, 16px chips, 24px rows. */
+    X_SMALL = "X_SMALL",
+    /** 24px field, 16px chips, 24px rows. */
+    SMALL = "SMALL",
+    /** 32px field, 20px chips, 32px rows. The default. */
+    MEDIUM = "MEDIUM",
+    /** 36px field, 24px chips, 32px rows. */
+    LARGE = "LARGE",
+    /** 40px field, 28px chips, 32px rows. */
+    X_LARGE = "X_LARGE"
 }
-export interface MultiSelectInputProps {
+/** Resting fill of the field (Constitution V-A surface set; 1.x `InputVariant` unchanged). */
+export declare enum MultiSelectInputVariant {
+    /** `background.base` fill. */
+    BASE = "BASE",
+    /** `background.primary` fill. The default. */
+    PRIMARY = "PRIMARY",
+    /** `background.secondary` fill. */
+    SECONDARY = "SECONDARY",
+    /** `background.tertiary` fill. */
+    TERTIARY = "TERTIARY"
+}
+/** Every MultiSelectInput prop except the `isSearchable` / `onCreate` pair. */
+export interface MultiSelectInputBaseProps<TId extends string = string> extends AriaAttributes {
+    /** Every choice, in display order. Grouped by `group` in order of first appearance. */
+    options: SelectOption<TId>[];
+    /** Controlled selected ids, in selection order. Pass it with `onChange`. */
+    value?: TId[];
+    /**
+     * Initial selected ids while uncontrolled.
+     * @default []
+     */
+    defaultValue?: TId[];
+    /** Called with the full next selection: a chosen id appended, an unchosen id removed, or `[]` from the clear button. */
+    onChange?: (value: TId[]) => void;
+    /**
+     * Control rung: 20 / 24 / 32 / 36 / 40px tall. Chips and rows scale with it.
+     * @default MultiSelectInputSize.MEDIUM
+     */
+    size?: MultiSelectInputSize;
+    /**
+     * Resting fill of the field, from the surface set. Ignored with `isGhost`.
+     * @default MultiSelectInputVariant.PRIMARY
+     */
+    variant?: MultiSelectInputVariant;
+    /**
+     * Ghost field: no fill and no hairline at rest; the frame appears on hover, focus and open (1.x
+     * `TRANSPARENT`, SelectInput's `isGhost`). For filters set into a toolbar.
+     * @default false
+     */
+    isGhost?: boolean;
+    /** Label above the field, rendered through `Field`. For a description or a horizontal layout, wrap it in `Field` instead. */
     label?: string;
-    /** Phosphor icon *component* on the trigger. */
-    icon?: PhosphorIcon;
-    /** Trigger surface color. @default InputVariant.PRIMARY */
-    variant?: InputVariant;
-    /** @default InputSize.MEDIUM */
-    size?: InputSize;
-    /** Every choice. Order is preserved. */
-    options: SelectInputOption[];
-    /** Controlled selection. Empty array shows the placeholder. */
-    value: SelectInputOption[];
+    /**
+     * Shown in the field while nothing is selected, and in the search field while it is empty. Never the label.
+     * @default Select options…
+     */
     placeholder?: string;
-    /** Trigger width. A number is px. */
-    width?: number | string;
-    fillWidth?: boolean;
-    /** Panel width. Defaults to matching the trigger. */
-    dropdownWidth?: number | string;
-    /** Where the panel opens relative to the trigger. */
-    dropdownPlacement?: DropdownPosition;
-    /** Called with the full next selection, not a delta. */
-    onChange?: (value: SelectInputOption[]) => void;
+    /** Message from the app, shown under the field through `Field`. Also turns the border red and sets `aria-invalid`. */
+    error?: string;
+    /**
+     * Error border and `aria-invalid` without a message. `error` implies it.
+     * @default false
+     */
+    isError?: boolean;
+    /**
+     * Not focusable, never opens. Chips and text show the disabled look.
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Focusable and announced, shows the chips, but never opens and has no clear button.
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Required marker on the `label` (via `Field`) and `aria-required`. No validation.
+     * @default false
+     */
     isRequired?: boolean;
-    /** Controlled open state. Pair it with `onOpenChange`. */
+    /**
+     * Stretch to the parent's width (more chips fit). Without it, the field is 200px wide.
+     * @default false
+     */
+    fillWidth?: boolean;
+    /** Accessible name when there is no visible label (no `label` and no wrapping `Field`). */
+    ariaLabel?: string;
+    /** Controlled open state of the panel. When set, MultiSelectInput calls `onOpenChange` and lets the caller decide. */
     isOpen?: boolean;
-    /** Render `icon` after the label instead of before. */
-    isIconTrailing?: boolean;
+    /**
+     * Initial open state while uncontrolled.
+     * @default false
+     */
+    defaultIsOpen?: boolean;
+    /** Called with the requested state on click, the keyboard, Escape, Tab, an outside press and blur. Choosing a row does not close the panel. */
     onOpenChange?: (isOpen: boolean) => void;
-    /** Adds a clear button to the trigger. */
-    onReset?: () => void;
-    /** Shortcut rows that select several options at once. */
-    pinnedOptions?: PinnedOptions[];
-    /** How many selections to name before collapsing to "+N more". */
-    maxDisplayItems?: number;
-    /** Replace the trigger's summary string. */
-    renderSelectedText?: (selectedOptions: SelectInputOption[], placeholder: string) => string;
-    /** Replace the trigger's summary entirely — chips, avatars, whatever. */
-    renderSelectedContent?: (selectedOptions: SelectInputOption[], placeholder: string) => ReactNode;
-    /** Message under the field; also switches the border to the error color. */
-    error?: string;
-    /** Supplying this turns the trigger into a search box. Return the filtered list. */
-    onSearch?: (searchTerm: string, options: SelectInputOption[]) => SelectInputOption[];
-    /** Debounce before `onSearch` fires, in ms. @default 300 */
-    debounceMs?: number;
+    /** App-side search: receives the term 150ms after typing pauses (and `""` when the panel closes). The app updates `options`; built-in filtering is off. Needs `isSearchable`. */
+    onSearch?: (term: string) => void;
+    /** At most this many choices. At the limit, unselected options are disabled with the reason "Limit of {maxSelected} reached". Floored; values below 1 mean no limit. */
+    maxSelected?: number;
+    /**
+     * Shows a clear button while something is selected and the field is editable. It calls `onChange([])`.
+     * @default false
+     */
+    isClearable?: boolean;
+    /**
+     * The options are loading: the panel shows a `Spinner` row and the listbox is `aria-busy`. The field stays usable.
+     * @default false
+     */
+    isLoading?: boolean;
+    /**
+     * Shown in the panel when there are no options to show (none given, or none match the term).
+     * @default No results
+     */
+    emptyMessage?: string;
+    /** Called once when the list is scrolled (or arrowed) to its last option, for paging. Called again only after `options` grows. */
+    onEndReached?: () => void;
+    /** Replaces a row's content (icon, leading, label, description). The row keeps its padding, highlight and check mark. Must not be interactive. */
+    renderOption?: (option: SelectOption<TId>, state: SelectOptionState) => ReactNode;
+    /** Replaces the chips in the field with a custom summary of the selected options. Single line, non-interactive. Not called while nothing is selected. */
+    renderValue?: (options: SelectOption<TId>[]) => ReactNode;
+    /** Options shown in a section above the list, in this order, whatever the search term. */
+    pinnedIds?: TId[];
+    /**
+     * Preferred side and alignment of the panel. It flips and shifts to stay in the viewport.
+     * @default Placement.BOTTOM_START
+     */
+    placement?: Placement;
+    /**
+     * DOM id of the combobox element. A wrapping `Field`'s label points to it.
+     * @default useId()
+     */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the combobox element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root: the `Field` wrapper when one is rendered, otherwise the field wrapper. */
+    className?: string;
+    /** Inline style on the root; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** Searchable: the term can become a new option. */
+interface MultiSelectInputSearchableProps {
+    /**
+     * The field becomes a text input while open; typing filters the options by label and description.
+     * @default false
+     */
+    isSearchable: true;
+    /** Turns on creating: when the term matches no option's label, a "Create" row ends the list and choosing it calls this with the trimmed term. The app adds the option to `options` and its id to `value`. */
+    onCreate?: (label: string) => void;
+}
+/** Not searchable: there is no term to create from. */
+interface MultiSelectInputPlainProps {
+    /**
+     * The field becomes a text input while open; typing filters the options by label and description.
+     * @default false
+     */
+    isSearchable?: false;
+    /** Creating needs `isSearchable` (the label comes from the term). */
+    onCreate?: never;
 }
+/** MultiSelectInput props: creating (`onCreate`) is only available with `isSearchable`. */
+export type MultiSelectInputProps<TId extends string = string> = MultiSelectInputBaseProps<TId> & (MultiSelectInputSearchableProps | MultiSelectInputPlainProps);
 /**
- * Multi-choice dropdown. Same option shape and search contract as `SelectInput`,
- * but the panel stays open across picks and the trigger summarizes what's chosen.
- *
- * Controlled: `onChange` hands back the complete next selection, not a delta.
+ * The public, generic call signature (`TId` inferred from `options`). Never called: it only types
+ * the default export. An arrow function rather than a type literal, so react-docgen-typescript
+ * reads the props for the Docs tab (the ToggleInput precedent).
  */
-declare const MultiSelectInput: ({ label, icon, variant, size, options, value, placeholder, onChange, width, fillWidth, dropdownWidth, dropdownPlacement, isDisabled, isRequired, isOpen: controlledIsOpen, isIconTrailing, onOpenChange, onReset, pinnedOptions, maxDisplayItems, renderSelectedText, renderSelectedContent, error, onSearch, debounceMs, }: MultiSelectInputProps) => import("react").JSX.Element;
+declare const MULTI_SELECT_INPUT_SIGNATURE: <TId extends string = string>(_props: MultiSelectInputProps<TId> & RefAttributes<HTMLElement>) => ReactElement | null;
+/** Choose several values from a list of options; the choices show as chips in the field. */
+declare const MultiSelectInput: typeof MULTI_SELECT_INPUT_SIGNATURE;
 export default MultiSelectInput;