@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/inputs/SelectInput.d.ts

@@ -1,68 +1,208 @@
-import { IconVariant } from "../icons/Icon";
-import { TextVariant } from "../text/Text";
-import { InputSize, InputVariant } from "./Input";
-/** One choice in a select. */
-export interface SelectInputOption {
-    /** Stable identity — selection is matched on this, not on `value`. */
-    id: string;
-    /** What the user reads. */
-    label: string;
-    /** Your payload. Never inspected by the component. */
-    value: unknown;
-    /** Leading graphic, rendered as-is. */
-    icon?: React.ReactNode;
-    /** Color role for the label — for status-coded options. */
-    variant?: TextVariant;
+import { type Icon as PhosphorIcon } from "@phosphor-icons/react";
+import { type AriaAttributes, type CSSProperties, type ReactElement, type ReactNode, type RefAttributes } from "react";
+import { Placement } from "../theme/enums.js";
+/** Canonical rungs; SelectInput supports all five (the Input rung table). */
+export declare enum SelectInputSize {
+    /** 20px field, caption text, 12px icons, 10px caret; 24px rows, 12px row icons. */
+    X_SMALL = "X_SMALL",
+    /** 24px field, body_sm text, 12px icons, 10px caret; 24px rows, 12px row icons. */
+    SMALL = "SMALL",
+    /** 32px field, body_md text, 14px icons, 12px caret; 32px rows, 14px row icons. The default (1.x `MEDIUM` was 28px). */
+    MEDIUM = "MEDIUM",
+    /** 36px field, body_lg text, 14px icons, 12px caret; 32px rows, 14px row icons. */
+    LARGE = "LARGE",
+    /** 40px field, body_lg text, 16px icons, 12px caret; 32px rows, 14px row icons. */
+    X_LARGE = "X_LARGE"
+}
+/** Resting fill of the field (Constitution V-A surface set; 1.x `InputVariant` unchanged). */
+export declare enum SelectInputVariant {
+    /** `background.base` fill. */
+    BASE = "BASE",
+    /** `background.primary` fill. The default. */
+    PRIMARY = "PRIMARY",
+    /** `background.secondary` fill. */
+    SECONDARY = "SECONDARY",
+    /** `background.tertiary` fill. */
+    TERTIARY = "TERTIARY"
 }
-/** A shortcut row pinned above the option list. */
-export interface PinnedOption {
-    id: string;
+/** One choice in a SelectInput or MultiSelectInput. Assignable to `MenuRadioOption`. */
+export interface SelectOption<TId extends string = string> {
+    /** Stable identity; also the value reported by `onChange`. */
+    id: TId;
+    /** Row text and the field's text when selected. Typeahead and the filter match it. */
     label: string;
-    /** The `SelectInputOption.id` this shortcut selects. */
-    optionId: string;
+    /** Second line under the label, up to two lines. The filter matches it too. */
+    description?: string;
+    /** Phosphor icon component before the label, sized and colored by the row. */
+    icon?: PhosphorIcon;
+    /** Anything else before the label (an `Avatar`, a `Status`). Must not be interactive. */
+    leading?: ReactNode;
+    /** Heading of the section this option sits in. */
+    group?: string;
+    /** Cannot be chosen; stays reachable with the arrow keys. */
+    isDisabled?: boolean;
+    /** With `isDisabled`: why, shown in a tooltip beside the row while it is active. */
+    disabledReason?: string;
 }
-export interface SelectInputProps {
+/** State passed to `renderOption`. */
+export interface SelectOptionState {
+    /** The option is the selected value. */
+    isSelected: boolean;
+    /** The option is highlighted by the pointer or the arrow keys. */
+    isActive: boolean;
+}
+export interface SelectInputProps<TId extends string = string> extends AriaAttributes {
+    /** Every choice, in display order. Grouped by `group` in order of first appearance. */
+    options: SelectOption<TId>[];
+    /** Controlled selected id. `null` shows the placeholder. Pass it with `onChange`. */
+    value?: TId | null;
+    /**
+     * Initial selected id while uncontrolled.
+     * @default null
+     */
+    defaultValue?: TId | null;
+    /** Called with the chosen option's id, or `null` when the clear button is pressed. */
+    onChange?: (value: TId | null) => void;
+    /**
+     * Control rung: 20 / 24 / 32 / 36 / 40px tall. Rows in the panel are 24px for `X_SMALL` / `SMALL` and 32px otherwise.
+     * @default SelectInputSize.MEDIUM
+     */
+    size?: SelectInputSize;
+    /**
+     * Resting fill of the field, from the surface set. Ignored with `isGhost`.
+     * @default SelectInputVariant.PRIMARY
+     */
+    variant?: SelectInputVariant;
+    /**
+     * Ghost field: no fill and no hairline at rest; the frame appears on hover, focus and open (1.x
+     * `TRANSPARENT`). For selects set into a toolbar or a table cell. The panel is `PopoverVariant.BASE`.
+     * @default false
+     */
+    isGhost?: boolean;
+    /** Label above the field, rendered through `Field`. For a description or a horizontal layout, wrap the select in `Field` instead. */
     label?: string;
-    /** Trigger surface color. @default InputVariant.PRIMARY */
-    variant?: InputVariant;
-    /** @default InputSize.MEDIUM */
-    size?: InputSize;
-    /** Every choice. Order is preserved. */
-    options: SelectInputOption[];
-    /** Controlled selection. `null` shows the placeholder. */
-    value?: SelectInputOption | null;
-    /** @default "Select an option..." */
+    /**
+     * Shown in the field while nothing is selected, and in the search field while it is empty. Never the label.
+     * @default Select an option…
+     */
     placeholder?: string;
-    /** Called with the whole option, not just its id. */
-    onChange?: (value: SelectInputOption) => void;
-    /** Trigger width. A number is px. */
-    width?: number | string;
-    fillWidth?: boolean;
-    /** Panel width. By default, fits the options and is at least as wide as the trigger. */
-    dropdownWidth?: number | string;
+    /** 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. Shows the disabled look.
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Focusable and announced, shows the value, 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. 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, SelectInput calls `onOpenChange` and lets the caller decide. */
     isOpen?: boolean;
+    /**
+     * Initial open state while uncontrolled.
+     * @default false
+     */
+    defaultIsOpen?: boolean;
+    /** Called with the requested state on click, the keyboard, a choice, Escape, Tab, an outside press and blur. */
     onOpenChange?: (isOpen: boolean) => void;
-    /** Adds a clear button to the trigger. Omit and the selection can't be cleared. */
-    onReset?: () => void;
-    /** Shortcut rows above the list — "All", "None", a recent choice. */
-    pinnedOptions?: PinnedOption[];
-    /** 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;
+    /**
+     * The field becomes a text input while open; typing filters the options by label and description.
+     * @default false
+     */
+    isSearchable?: boolean;
+    /** 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;
+    /**
+     * Shows a clear button while a value is selected and the field is editable. It calls `onChange(null)`.
+     * @default false
+     */
+    isClearable?: boolean;
+    /**
+     * The options are loading: the panel shows a `Spinner` row (after the rows, or alone) 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 how the selected option shows in the field. Single line, non-interactive. */
+    renderValue?: (option: 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 SelectInput renders one, otherwise the field wrapper. */
+    className?: string;
+    /** Inline style on the root; only for setting CSS custom properties. */
+    style?: CSSProperties;
 }
-export declare const INPUT_VARIANT_TO_ICON_VARIANT_MAP: Record<InputVariant, IconVariant>;
 /**
- * Single-choice dropdown with keyboard navigation and optional search.
- *
- * Controlled: `value` is the selected option and `onChange` hands you the whole
- * option back. Passing `onSearch` turns the trigger into a search box — you own
- * the filtering, so it works equally well against a local list or a server.
+ * @internal Shared by SelectInput and MultiSelectInput; apps use those. Every SelectInput prop
+ * except the value triple and `renderValue`, plus the selection wiring.
+ */
+export type SelectInputRootProps<TId extends string = string> = Omit<SelectInputProps<TId>, "value" | "defaultValue" | "onChange" | "renderValue"> & {
+    /** The selected ids, in selection order. SelectInput passes `value === null ? [] : [value]`. */
+    selectedIds: readonly TId[];
+    /** `aria-multiselectable` on the listbox, and choosing a row keeps the panel open. */
+    isMultiple: boolean;
+    /** The public component name in dev warnings. @default "SelectInput" */
+    componentName?: string;
+    /** Called when an enabled option row is chosen. */
+    onOptionSelect: (id: TId) => void;
+    /** Called by the clear button. */
+    onClear: () => void;
+    /** Field content for a non-empty selection. */
+    renderSelection: (options: SelectOption<TId>[]) => ReactNode;
+    /** The selection as plain text (the combobox value for assistive tech), from the resolved selected options. */
+    getSelectionText: (options: SelectOption<TId>[]) => string;
+    /** When set, every unselected option is disabled with this reason (MultiSelectInput `maxSelected`). */
+    limitReason: string | undefined;
+    /** When set and the term is non-empty with no exact label match, a "Create" row ends the list. */
+    onCreate: ((label: string) => void) | undefined;
+};
+/** @internal Shared by SelectInput and MultiSelectInput; apps use those. */
+export declare const SelectInputRoot: <TId extends string = string>(props: SelectInputRootProps<TId> & RefAttributes<HTMLElement>) => ReactElement | null;
+/**
+ * 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 SelectInput: ({ label, variant, size, options, value, placeholder, onChange, width, fillWidth, dropdownWidth, isDisabled, isRequired, isOpen: controlledIsOpen, onOpenChange, onReset, pinnedOptions, error, onSearch, debounceMs, }: SelectInputProps) => import("react").JSX.Element;
+declare const SELECT_INPUT_SIGNATURE: <TId extends string = string>(_props: SelectInputProps<TId> & RefAttributes<HTMLElement>) => ReactElement | null;
+/** Choose one value from a list of options, in a field that opens a listbox. */
+declare const SelectInput: typeof SELECT_INPUT_SIGNATURE;
 export default SelectInput;