/** Why a selection change happened: user-driven (keyboard or pointer) or set by the application. */
export type SelectionChangeReason = 'keyboard' | 'pointer' | 'programmatic';
/** The payload every single-or-many control's change event carries — the strict-out shape. */
export interface SelectionChangeDetail {
    /** The whole selection, always an array, in single and multiple mode alike. */
    value: string[];
    /** The first selected value, or `null` when nothing is selected. */
    selectedValue: string | null;
    /** The selection this change replaced, in the same array shape as `value`. */
    previousValue?: string[];
    /** What drove the change — see {@link SelectionChangeReason}. */
    reason?: SelectionChangeReason;
}
/** Options {@link toSelectionValues} needs to apply the single-selection rule. */
export interface SelectionValueOptions {
    /** Whether the control may hold more than one value at once — `multiple`, or `type === 'multiple'` on the families that spell it that way. */
    multiple: boolean;
    /** The component and member named in the development error, e.g. `Select value`, so the message says which of a page's selects is wrong. */
    label: string;
}
/** Every selected value as an array, whatever shape was passed; `''` and `undefined` mean nothing selected. */
export declare function toValues(value: string | string[] | undefined): string[];
/**
 * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
 *
 * @param input the value the consumer supplied, in any accepted shape
 * @param options cardinality and label for errors — see {@link SelectionValueOptions}
 * @returns the selection as an array; at most one element unless `multiple`
 * @throws RangeError in development when an entry is not a string or a single-select gets multiple values
 */
export declare function toSelectionValues(input: string | readonly string[] | null | undefined, { multiple, label }: SelectionValueOptions): string[];
/**
 * The `selectedValue` half of the rule's output: the first selected value, or `null` (never `undefined` or `''`).
 *
 * @param values the normalized selection, as {@link toSelectionValues} returns it
 * @returns the first selected value, or `null` when nothing is selected
 */
export declare function selectedValueOf(values: readonly string[]): string | null;
/**
 * The selection after choosing `value`: replaces it, or toggles it within the set when `multiple`.
 *
 * @param selected the current selection, already normalized
 * @param value the option value the user committed
 * @param multiple whether choosing toggles within a set rather than replacing
 * @param deselectable whether re-choosing the only selected value clears it (single-select only)
 * @returns the new selection as an array in both cardinalities
 */
export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
/** Whether two selections are indistinguishable to a consumer: same values in the same order. */
export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;
/**
 * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
 *
 * @param attribute the raw attribute string, or `null` when absent
 * @param options cardinality and label for errors
 * @returns the selection as an array
 */
export declare function parseSelectionAttribute(attribute: string | null | undefined, options: SelectionValueOptions): string[];