@vunset/vue 0.0.0-stage → 1.0.0-rc.2

package/dist/shared/use-listbox.d.ts

@@ -0,0 +1,276 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from 'vue';
+import { type TransitionStatus } from './use-transition-status';
+import { type Align, type Side, type UsePositioningOptions } from './use-positioning';
+export type ListboxOptionValue = string | number;
+export interface ListboxOption {
+    /** Read from `valueKey` instead, when that is set. */
+    value?: ListboxOptionValue;
+    label?: string;
+    disabled?: boolean;
+    [key: string]: unknown;
+}
+export type ListboxOptionInput = ListboxOptionValue | ListboxOption;
+export interface ListboxGroup {
+    label: string;
+    disabled?: boolean;
+    options: ListboxOptionInput[];
+}
+export type ListboxItem = ListboxOptionInput | ListboxGroup;
+/** A named set of values, added or removed together. Multiple selection only. */
+export interface ListboxPreset {
+    label: string;
+    values: ListboxOptionValue[];
+    disabled?: boolean;
+}
+export interface ListboxPresetGroup {
+    label: string;
+    presets: ListboxPreset[];
+    /** Starts folded away; its heading opens it. */
+    collapsed?: boolean;
+}
+export type ListboxPresetItem = ListboxPreset | ListboxPresetGroup;
+export interface RenderedPreset {
+    preset: ListboxPreset;
+    label: string;
+    /** Whether every one of its values is selected. */
+    active: boolean;
+    disabled: boolean;
+}
+export interface RenderedPresetSection {
+    label?: string;
+    labelId?: string;
+    /** Whether its presets show. Only a labeled section folds, and none while a search is on. */
+    open: boolean;
+    presets: RenderedPreset[];
+}
+export declare function isListboxGroup(item: ListboxItem): item is ListboxGroup;
+export interface RenderedOption {
+    /** The option object as passed in, extra keys included. */
+    option: ListboxOption;
+    /** Its value. */
+    value: ListboxOptionValue;
+    /** Its text. */
+    label: string;
+    /** Whether it can't be chosen. */
+    disabled: boolean;
+    /** Whether it is part of the selection. */
+    selected: boolean;
+    /** Position in the flattened, filtered list. Ids and navigation both use it. */
+    index: number;
+    /** The row's element id, which `aria-activedescendant` points at. */
+    id: string;
+    /** Whether choosing this row coins a new value rather than picking one. */
+    create?: boolean;
+}
+export interface RenderedSection {
+    label?: string;
+    labelId?: string;
+    options: RenderedOption[];
+    /** Whether this run holds the create row rather than real options. */
+    create?: boolean;
+}
+export interface ListboxState {
+    /** `select` or `combobox`, fixed by the root. */
+    mode: ListboxMode;
+    /**
+     * Whether the popup is open.
+     * @attribute `data-open` while open, `data-closed` otherwise
+     */
+    open: boolean;
+    /** Whether it ignores interaction. */
+    disabled: boolean;
+    /** Whether the selection can be read but not changed. */
+    readOnly: boolean;
+    /** Whether a selection is needed before the form submits. */
+    required: boolean;
+    /** Whether the selection is invalid. */
+    invalid: boolean;
+    /** Whether more than one option can be chosen. */
+    multiple: boolean;
+    /** Whether the popup has a search box. */
+    searchable: boolean;
+    /** Whether the list is currently offering to coin the typed text. */
+    creating: boolean;
+    /** Whether anything is selected. */
+    filled: boolean;
+    /** Whether the search turned up nothing. */
+    empty: boolean;
+    /**
+     * Whether the popup is sitting over the trigger rather than beside it.
+     * @attribute `data-aligned-to-item` while true
+     */
+    alignedToItem: boolean;
+    /**
+     * The side of the trigger the popup ended up on.
+     * @attribute `data-side="…"`
+     */
+    side: Side;
+    /**
+     * How the popup lines up along that side.
+     * @attribute `data-align="…"`
+     */
+    align: Align;
+    /**
+     * Where the popup is in its enter or exit animation.
+     * @attribute `data-enter-from` as it enters, `data-leave-to` as it leaves
+     */
+    transitionStatus: TransitionStatus;
+}
+export type ListboxMode = 'select' | 'combobox';
+export type ListboxOrder = 'selected-first';
+export interface UseListboxOptions extends UsePositioningOptions {
+    /**
+     * `select` keeps the value in the trigger and any search box inside the
+     * popup. `combobox` makes the trigger a text input, which is what lets a
+     * typed value be committed. Implies `searchable`.
+     */
+    mode?: MaybeRefOrGetter<ListboxMode>;
+    /** The selection. An array when `multiple`. Supplying it makes the value controlled. */
+    value?: MaybeRefOrGetter<ListboxOptionValue | ListboxOptionValue[] | null | undefined>;
+    /** The initial selection while uncontrolled. */
+    defaultValue?: MaybeRefOrGetter<ListboxOptionValue | ListboxOptionValue[] | null | undefined>;
+    /** The options, flat or grouped. */
+    options?: MaybeRefOrGetter<ListboxItem[]>;
+    /** Whether more than one option can be chosen. */
+    multiple?: MaybeRefOrGetter<boolean>;
+    /** Whether the popup carries a search box. */
+    searchable?: MaybeRefOrGetter<boolean>;
+    /** Whether the whole selection can be dropped at once. Defaults to on when anything is selected. */
+    clearable?: MaybeRefOrGetter<boolean>;
+    /** How many of the chosen options the trigger names before the rest collapse */
+    flatten?: MaybeRefOrGetter<number | undefined>;
+    /** Whether text that matches no option can become a value */
+    creatable?: MaybeRefOrGetter<boolean | ((query: string) => boolean)>;
+    /** Whether choosing an option closes the popup. Defaults to on for a single select. */
+    closeOnSelect?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether arrow keys wrap at the ends. */
+    loop?: MaybeRefOrGetter<boolean>;
+    /** Place the popup so the chosen option sits on top of the trigger */
+    alignWithTrigger?: MaybeRefOrGetter<boolean>;
+    /** Render only the options near the scroll position. Needs `maxHeight`, so the list scrolls itself. Flat lists only; turns `alignWithTrigger` off. */
+    virtual?: MaybeRefOrGetter<boolean>;
+    /** Caps the list, which then scrolls. A number is pixels. */
+    maxHeight?: MaybeRefOrGetter<number | string | undefined>;
+    /** `selected-first` lifts what is selected to the top of its group, each time the popup opens. */
+    order?: MaybeRefOrGetter<ListboxOrder | undefined>;
+    /** Named sets of values, for a multiple select. Filtered by the search like the options. */
+    presets?: MaybeRefOrGetter<ListboxPresetItem[] | undefined>;
+    /** Names the presets outside a group, gathered into one section that folds like a group, where the first sits. */
+    presetsLabel?: MaybeRefOrGetter<string | undefined>;
+    /** Which key on an option holds its value. */
+    valueKey?: MaybeRefOrGetter<string | undefined>;
+    /** Which key on an option holds its text. */
+    labelKey?: MaybeRefOrGetter<string | undefined>;
+    /** Replaces the built-in substring search. */
+    filter?: (option: ListboxOption, query: string) => boolean;
+    /** Whether the control ignores interaction. Inherited from a surrounding field. */
+    disabled?: MaybeRefOrGetter<boolean>;
+    /** Whether the selection can be read but not changed. Inherited from a surrounding field. */
+    readOnly?: MaybeRefOrGetter<boolean>;
+    /** Whether a selection is required: announced and marked, not enforced. Inherited from a surrounding field. */
+    required?: MaybeRefOrGetter<boolean>;
+    /** Whether the control is marked invalid. Inherited from a surrounding field. */
+    invalid?: MaybeRefOrGetter<boolean>;
+    /** Name submitted with the form. */
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** The trigger's id. Taken from a surrounding field when there is one. */
+    id?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the popup is open. Supplying it makes openness controlled. */
+    open?: MaybeRefOrGetter<boolean | undefined>;
+    /** Called whenever the selection changes. */
+    onChange?: (value: ListboxOptionValue | ListboxOptionValue[] | null) => void;
+    /** Called with the coined text just before it is selected */
+    onCreate?: (value: string) => void;
+    /** Called whenever the popup opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+export type ListboxScrollDirection = 'up' | 'down';
+export interface UseListboxReturn {
+    value: WritableComputedRef<ListboxOptionValue | ListboxOptionValue[] | null>;
+    open: WritableComputedRef<boolean>;
+    /** The search text. Writable, so a caller can seed or clear it. */
+    query: Ref<string>;
+    state: ComputedRef<ListboxState>;
+    /** Whether the popup is in the DOM. Outlives `open` for the exit animation. */
+    present: Ref<boolean>;
+    /** The options to render, filtered and grouped. */
+    sections: ComputedRef<RenderedSection[]>;
+    /** The same options in one list, in order: what `activeIndex` counts. */
+    flatOptions: ComputedRef<RenderedOption[]>;
+    /** The highlighted option's place in `flatOptions`, or `-1`. */
+    activeIndex: Ref<number>;
+    /** The options to render and the space around them while virtual; `null` otherwise. */
+    virtualRows: ComputedRef<{
+        options: RenderedOption[];
+        before: number;
+        after: number;
+    } | null>;
+    /** Every option currently chosen, in selection order, resolved against `options`. */
+    selectedOptions: ComputedRef<RenderedOption[]>;
+    /** The chosen options the trigger names in full. */
+    visibleOptions: ComputedRef<RenderedOption[]>;
+    /** How many chosen options `visibleOptions` left out. */
+    hiddenCount: ComputedRef<number>;
+    /** The whole selection as one line: "Vue and 3 more". */
+    summary: ComputedRef<string>;
+    /** Whether anything was left out of `visibleOptions`. */
+    collapsed: ComputedRef<boolean>;
+    /** Whether the clear-all control has anything to do. */
+    showClear: ComputedRef<boolean>;
+    /** Whether the list has content beyond what is showing, that way. */
+    canScroll: (direction: ListboxScrollDirection) => boolean;
+    rootProps: ComputedRef<Record<string, unknown>>;
+    triggerProps: ComputedRef<Record<string, unknown>>;
+    clearProps: ComputedRef<Record<string, unknown>>;
+    positionerProps: ComputedRef<Record<string, unknown>>;
+    popupProps: ComputedRef<Record<string, unknown>>;
+    searchProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the combobox's text input. The trigger and the search box in one. */
+    inputProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the box holding the chips. */
+    chipsProps: ComputedRef<Record<string, unknown>>;
+    /** The presets that match the search, grouped. Empty unless `multiple`. */
+    presetSections: ComputedRef<RenderedPresetSection[]>;
+    presetsProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the row holding a preset's buttons. */
+    getPresetItemProps: (preset: RenderedPreset) => Record<string, unknown>;
+    /** Bind to a preset's button: toggles its values. */
+    getPresetProps: (preset: RenderedPreset) => Record<string, unknown>;
+    /** Bind to a button that replaces the selection with the preset's values. */
+    getPresetReplaceProps: (preset: RenderedPreset) => Record<string, unknown>;
+    getPresetGroupProps: (section: RenderedPresetSection) => Record<string, unknown>;
+    getPresetGroupLabelProps: (section: RenderedPresetSection) => Record<string, unknown>;
+    /** Bind to a labeled section's heading: folds its presets away and back. */
+    getPresetGroupTriggerProps: (section: RenderedPresetSection) => Record<string, unknown>;
+    /** Bind to what holds a section's presets: a labeled one's stays rendered, `inert` while folded, so it can animate. */
+    getPresetGroupPanelProps: (section: RenderedPresetSection) => Record<string, unknown>;
+    /** Bind to the hover-to-scroll affordance at that end of the list. */
+    getScrollProps: (direction: ListboxScrollDirection) => Record<string, unknown>;
+    /** Bind to the part of the trigger showing the value. Used to line the popup up with it. */
+    valueProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the open/closed indicator. */
+    indicatorProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the "nothing matched" message. */
+    emptyProps: ComputedRef<Record<string, unknown>>;
+    stateAttrs: ComputedRef<Record<string, string>>;
+    listboxProps: ComputedRef<Record<string, unknown>>;
+    getOptionProps: (option: RenderedOption) => Record<string, unknown>;
+    getGroupProps: (section: RenderedSection) => Record<string, unknown>;
+    getGroupLabelProps: (section: RenderedSection) => Record<string, unknown>;
+    getChipProps: (option: RenderedOption) => Record<string, unknown>;
+    getChipRemoveProps: (option: RenderedOption) => Record<string, unknown>;
+    /** One entry per value to submit. Render each as a hidden input. */
+    hiddenInputs: ComputedRef<Array<{
+        name: string;
+        value: ListboxOptionValue;
+    }>>;
+    /** Removes one value from the selection. */
+    deselect: (value: ListboxOptionValue) => void;
+    /** Drops the whole selection. */
+    clear: () => void;
+    /** Chooses an option, or unchooses it when `multiple`. */
+    toggle: (value: ListboxOptionValue) => void;
+    close: () => void;
+}
+export declare function useListbox(options?: UseListboxOptions): UseListboxReturn;
+export declare const provideListboxContext: (value: UseListboxReturn) => UseListboxReturn, useListboxContext: () => UseListboxReturn;