Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · combobox

Published foldkit-ui API declarations for combobox.

./combobox

@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit-ui/combobox'

Exported declarations

ActivatedItem

export type ActivatedItem = typeof Message.ActivatedItem.Type;

ActivationTrigger

Schema for the activation trigger: whether the user interacted via mouse or keyboard.

ActivationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>

ActivationTrigger

export type ActivationTrigger = typeof ActivationTrigger.Type;

AnchorCombobox

The anchor-positioning Mount this Combobox renders on its items panel. The panel is always anchored to the input wrapper via Floating UI and portaled to the document body, or into the enclosing `<dialog>` when there is one (opt out of portaling with `anchor.portal: false`), so it escapes ancestor stacking contexts and overflow clipping. The Mount also installs the `pointerdown`-cancelling capture listener that prevents input blur on item presses. Exposed so Scene tests can call `Scene.Mount.resolve(AnchorCombobox, CompletedAnchorCombobox())`.

AnchorCombobox: Mount.MountDefinitionWithArgs<"AnchorCombobox", {
    buttonId: Schema.String;
    anchor: Schema.Struct<{
        readonly placement: Schema.optional<Schema.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>;
        readonly gap: Schema.optional<Schema.Number>;
        readonly offset: Schema.optional<Schema.Number>;
        readonly padding: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Struct<{
            readonly top: Schema.optionalKey<Schema.Number>;
            readonly right: Schema.optionalKey<Schema.Number>;
            readonly bottom: Schema.optionalKey<Schema.Number>;
            readonly left: Schema.optionalKey<Schema.Number>;
        }>]>>;
        readonly portal: Schema.optional<Schema.Boolean>;
        readonly isPlacementLocked: Schema.optional<Schema.Boolean>;
    }>;
}, {
    readonly _tag: "CompletedAnchorCombobox";
}>

AnchorConfig

Static configuration for anchor-based positioning of a floating element relative to a button.

AnchorConfig: Schema.Struct<{
    readonly placement: Schema.optional<Schema.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>;
    readonly gap: Schema.optional<Schema.Number>;
    readonly offset: Schema.optional<Schema.Number>;
    readonly padding: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Struct<{
        readonly top: Schema.optionalKey<Schema.Number>;
        readonly right: Schema.optionalKey<Schema.Number>;
        readonly bottom: Schema.optionalKey<Schema.Number>;
        readonly left: Schema.optionalKey<Schema.Number>;
    }>]>>;
    readonly portal: Schema.optional<Schema.Boolean>;
    readonly isPlacementLocked: Schema.optional<Schema.Boolean>;
}>

AnchorConfig

export type AnchorConfig = typeof AnchorConfig.Type;

AttachComboboxPreventBlur

The Mount this Combobox renders to install a `pointerdown`-cancelling capture listener that prevents blur on item presses. Exposed so Scene tests can call `Scene.Mount.resolve(AttachComboboxPreventBlur, CompletedAttachComboboxPreventBlur())`.

AttachComboboxPreventBlur: Mount.MountDefinitionNoArgs<"AttachComboboxPreventBlur", {
    readonly _tag: "CompletedAttachComboboxPreventBlur";
}>

AttachComboboxSelectOnFocus

The Mount this Combobox renders to install the input's select-on-focus behavior. Exposed so Scene tests can call `Scene.Mount.resolve(AttachComboboxSelectOnFocus, CompletedAttachComboboxSelectOnFocus())`.

AttachComboboxSelectOnFocus: Mount.MountDefinitionNoArgs<"AttachComboboxSelectOnFocus", {
    readonly _tag: "CompletedAttachComboboxSelectOnFocus";
}>

BaseViewInputsCommon

Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field. The Combobox emits a `Selected({ value })` OutMessage on commit. Fold it in the Combobox's `Update.foldChild` config: single-select stores the value, while multi-select toggles the value's membership. `restingInputValue` is the text the input returns to on close (the selection's display text for single-select, empty for multi-select). The selection is not part of this shared shape. Each variant adds its own selection field.

export type BaseViewInputsCommon<Item extends string> = Readonly<{
    items: ReadonlyArray<Item>;
    restingInputValue: string;
    itemToConfig: (item: Item, context: Readonly<{
        isActive: boolean;
        isDisabled: boolean;
        /** Mirrors the view input of the same name, so `itemToConfig` can
         *  style items for read-only state without closing over `viewInputs`. */
        isReadOnly: boolean;
        isSelected: boolean;
    }>) => ItemConfig;
    itemToValue: (item: Item, index: number) => Item;
    itemToDisplayText: (item: Item, index: number) => string;
    isItemDisabled?: (item: Item, index: number) => boolean;
    inputClassName?: string;
    inputAttributes?: ReadonlyArray<ChildAttribute>;
    inputPlaceholder?: string;
    inputWrapperClassName?: string;
    inputWrapperAttributes?: ReadonlyArray<ChildAttribute>;
    itemsClassName?: string;
    itemsAttributes?: ReadonlyArray<ChildAttribute>;
    itemsScrollClassName?: string;
    itemsScrollAttributes?: ReadonlyArray<ChildAttribute>;
    backdropClassName?: string;
    backdropAttributes?: ReadonlyArray<ChildAttribute>;
    /** CSS class for the outer wrapper. Keep the wrapper positioned when the
     *  Combobox renders a backdrop, so the input paints above it. */
    className?: string;
    attributes?: ReadonlyArray<ChildAttribute>;
    buttonContent?: Html;
    buttonClassName?: string;
    buttonAttributes?: ReadonlyArray<ChildAttribute>;
    formName?: string;
    /** Marks the Combobox unavailable with `aria-disabled="true"` on the input
     *  and the toggle button and `data-disabled` on both plus the wrapper, and
     *  removes their handlers so the dropdown cannot be opened. */
    isDisabled?: boolean;
    /** Prevents committing a selection while exposing read-only semantics with
     *  the native `readonly` attribute plus `aria-readonly="true"` on the input,
     *  `aria-readonly="true"` on the items panel, and `data-readonly` on the
     *  wrapper, input, toggle button, items panel, and every item. The Combobox
     *  still opens, navigates, and closes, and the input still takes focus and
     *  allows text selection and copying. Typing is frozen, since the input
     *  value doubles as the display of the selection. Independent of
     *  `isDisabled`: setting both emits both attribute sets, and `isDisabled`
     *  still wins for interaction, since it drops every handler, so a Combobox
     *  that is both read-only and disabled cannot be opened at all. */
    isReadOnly?: boolean;
    isInvalid?: boolean;
    openOnFocus?: boolean;
    itemGroupKey?: (item: Item, index: number) => string;
    groupToHeading?: (groupKey: string) => GroupHeading | undefined;
    groupClassName?: string;
    groupAttributes?: ReadonlyArray<ChildAttribute>;
    separatorClassName?: string;
    separatorAttributes?: ReadonlyArray<ChildAttribute>;
    anchor?: AnchorConfig;
    ariaLabel?: string;
    ariaLabelledBy?: string;
}>;

BlurredInput

export type BlurredInput = typeof Message.BlurredInput.Type;

Bundle

The `view`, `update`, and programmatic helpers that `Combobox.create` returns, bound to one `Item` type. Name it to annotate a value that holds a created bundle, such as a field on a config object or a function parameter that takes the bundle rather than calling `create` itself.

export type Bundle<Item extends string = string> = Readonly<{
    view: SubmodelView<Model, Message, ViewInputs<Item>>;
    update: (model: Model, message: Message) => BundleUpdateReturn<Item>;
    selectItem: (model: Model, item: Item, displayText: string) => BundleUpdateReturn<Item>;
    open: (model: Model) => BundleUpdateReturn<Item>;
    close: (model: Model, restingInputValue: string) => BundleUpdateReturn<Item>;
}>;

ClearedSelection

export type ClearedSelection = typeof OutMessage.ClearedSelection.Type;

ClickItem

Programmatically clicks the active combobox item's DOM element.

ClickItem: Command.CommandDefinitionWithArgs<"ClickItem", {
    id: Schema.String;
    index: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "CompletedClickItem";
}, never, never>>

Closed

export type Closed = typeof Message.Closed.Type;

CompletedClickItem

export type CompletedClickItem = typeof Message.CompletedClickItem.Type;

CompletedFocusInput

export type CompletedFocusInput = typeof Message.CompletedFocusInput.Type;

CompletedInertOthers

export type CompletedInertOthers = typeof Message.CompletedInertOthers.Type;

CompletedLockScroll

export type CompletedLockScroll = typeof Message.CompletedLockScroll.Type;

CompletedRestoreInert

export type CompletedRestoreInert = typeof Message.CompletedRestoreInert.Type;

CompletedScrollIntoView

export type CompletedScrollIntoView = typeof Message.CompletedScrollIntoView.Type;

CompletedUnlockScroll

export type CompletedUnlockScroll = typeof Message.CompletedUnlockScroll.Type;

create

Pairs the single-select combobox's `view` and `update` (and programmatic helpers) behind a single Item-typed entry point. See `Listbox.create` for the rationale; the combobox factory follows the same shape with `selectItem` taking both `item` and `displayText`. `selectItem` emits `Selected({ value })` with the input resting on `displayText`; what the selection becomes is the parent's fold to decide.

create: <Item extends string = string>() => Bundle<Item>

DeactivatedItem

export type DeactivatedItem = typeof Message.DeactivatedItem.Type;

DetectMovementOrAnimationEnd

Detects whether the combobox input wrapper moved or the leave animation ended. Whichever comes first; both outcomes signal the Animation submodel that leave is complete.

DetectMovementOrAnimationEnd: Command.CommandDefinitionWithArgs<"DetectMovementOrAnimationEnd", {
    id: Schema.String;
    generation: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "GotAnimationMessage";
    readonly message: {
        readonly _tag: "CompletedWaitForPaint";
        readonly generation: number;
    } | {
        readonly _tag: "EndedAnimation";
        readonly generation: number;
    } | {
        readonly _tag: "Hid";
    } | {
        readonly _tag: "Showed";
    };
}, never, never>>

FocusInput

Moves focus to the combobox input after selection or close.

FocusInput: Command.CommandDefinitionWithArgs<"FocusInput", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedFocusInput";
}, never, never>>

GroupHeading

Configuration for a group heading rendered above a group of items.

export type GroupHeading = Readonly<{
    content: Html;
    className?: string;
}>;

InertOthers

Marks all elements outside the combobox as inert for modal behavior.

InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedInertOthers";
}, never, never>>

init

Creates an initial single-select combobox model from a config. Defaults to closed with no active item and an empty input.

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a single-select combobox model with `init`. `isAnimated` enables CSS transition coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`).

export type InitConfig = BaseInitConfig;

inputId

Returns the bare DOM id of the combobox input, derived from the combobox's base id. Use this to associate an external label with the input via a native `<label for={Combobox.inputId(id)}>` or an `aria-labelledby` reference. Mirrors `inputSelector`, which returns the CSS selector form (`#${id}-input`) rather than the bare id.

inputId: (id: string) => string

ItemConfig

Configuration for an individual combobox item's appearance.

export type ItemConfig = Readonly<{
    className?: string;
    content: Html;
}>;

LockScroll

Prevents page scrolling while the combobox popup is open in modal mode.

LockScroll: Command.CommandDefinitionNoArgs<"LockScroll", Effect.Effect<{
    readonly _tag: "CompletedLockScroll";
}, never, never>>

Message

export type Message = typeof Message.Type;

Message

Union of all messages the combobox component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Opened: {
        maybeActiveItemIndex: Schema.Option<Schema.Number>;
    };
    readonly Closed: {
        restingInputValue: Schema.String;
        isClearable: Schema.Boolean;
    };
    readonly BlurredInput: {
        restingInputValue: Schema.String;
        isClearable: Schema.Boolean;
    };
    readonly ActivatedItem: {
        index: Schema.Number;
        activationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>;
        maybeImmediateSelection: Schema.Option<Schema.Struct<{
            readonly item: Schema.String;
        }>>;
    };
    readonly DeactivatedItem: {};
    readonly SelectedItem: {
        item: Schema.String;
        displayText: Schema.String;
        wasSelected: Schema.Boolean;
    };
    readonly MovedPointerOverItem: {
        index: Schema.Number;
        screenX: Schema.Number;
        screenY: Schema.Number;
    };
    readonly RequestedItemClick: {
        index: Schema.Number;
    };
    readonly SuppressedItemCommit: {};
    readonly SuppressedEmptyItemNavigation: {};
    readonly CompletedLockScroll: {};
    readonly CompletedUnlockScroll: {};
    readonly CompletedInertOthers: {};
    readonly CompletedRestoreInert: {};
    readonly CompletedFocusInput: {};
    readonly CompletedScrollIntoView: {};
    readonly CompletedClickItem: {};
    readonly CompletedAnchorCombobox: {};
    readonly CompletedAttachComboboxPreventBlur: {};
    readonly CompletedAttachComboboxSelectOnFocus: {};
    readonly CompletedPortalComboboxBackdrop: {};
    readonly GotAnimationMessage: {
        message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
            readonly Showed: {};
            readonly Hid: {};
            readonly CompletedWaitForPaint: {
                generation: Schema.Number;
            };
            readonly EndedAnimation: {
                generation: Schema.Number;
            };
        }>;
    };
    readonly UpdatedInputValue: {
        value: Schema.String;
    };
    readonly PressedToggleButton: {
        restingInputValue: Schema.String;
        isClearable: Schema.Boolean;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the single-select combobox's private interaction state (open/closed status, active item, activation trigger, typed input value). The selection is owned by the parent and passed in via `ViewInputs.maybeSelectedValue`.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly isOpen: Schema.Boolean;
    readonly isAnimated: Schema.Boolean;
    readonly isModal: Schema.Boolean;
    readonly nullable: Schema.Boolean;
    readonly immediate: Schema.Boolean;
    readonly selectInputOnFocus: Schema.Boolean;
    readonly animation: Schema.Struct<{
        readonly id: Schema.String;
        readonly isShowing: Schema.Boolean;
        readonly transitionState: Schema.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
        readonly transitionGeneration: Schema.Number;
    }>;
    readonly maybeActiveItemIndex: Schema.Option<Schema.Number>;
    readonly activationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>;
    readonly inputValue: Schema.String;
    readonly maybeLastPointerPosition: Schema.Option<Schema.Struct<{
        readonly screenX: Schema.Number;
        readonly screenY: Schema.Number;
    }>>;
}>

MovedPointerOverItem

export type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;

Multi

export { init, create, Model } from './multi.js';
export { inputId } from './shared.js';
export type { Bundle, InitConfig, ViewInputs } from './multi.js';

Opened

export type Opened = typeof Message.Opened.Type;

OutMessage

Generic over `Value extends string` so consumers who create the combobox via `Combobox.create<MyUnion>()` receive `value: MyUnion` in the `Selected` OutMessage from the factory's `update`, instead of `value: string`. Defaults to `string`.

export type OutMessage<Value extends string = string> = Selected<Value> | ClearedSelection;

OutMessage

Union of out-messages the combobox component can produce. The parent folds `Selected` into the selection it owns and clears that selection on `ClearedSelection`.

OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Selected: {
        value: Schema.String;
    };
    readonly ClearedSelection: {};
}>

PortalComboboxBackdrop

The backdrop-portaling Mount this Combobox renders. Exposed so Scene tests can call `Scene.Mount.resolve(PortalComboboxBackdrop, CompletedPortalComboboxBackdrop())` to acknowledge the mount produced by the rendered backdrop.

PortalComboboxBackdrop: Mount.MountDefinitionNoArgs<"PortalComboboxBackdrop", {
    readonly _tag: "CompletedPortalComboboxBackdrop";
}>

PressedToggleButton

export type PressedToggleButton = typeof Message.PressedToggleButton.Type;

RequestedItemClick

export type RequestedItemClick = typeof Message.RequestedItemClick.Type;

RestoreInert

Removes the inert attribute from elements outside the combobox.

RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
    id: Schema.String;
}, Effect.Effect<{
    readonly _tag: "CompletedRestoreInert";
}, never, never>>

ScrollIntoView

Scrolls the active combobox item into view after keyboard navigation.

ScrollIntoView: Command.CommandDefinitionWithArgs<"ScrollIntoView", {
    id: Schema.String;
    index: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "CompletedScrollIntoView";
}, never, never>>

Selected

export type Selected<Value extends string = string> = Readonly<{
    readonly _tag: 'Selected';
    readonly value: Value;
}>;

SelectedItem

export type SelectedItem = typeof Message.SelectedItem.Type;

SuppressedEmptyItemNavigation

export type SuppressedEmptyItemNavigation = typeof Message.SuppressedEmptyItemNavigation.Type;

SuppressedItemCommit

export type SuppressedItemCommit = typeof Message.SuppressedItemCommit.Type;

UnlockScroll

Re-enables page scrolling after the combobox popup closes.

UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
    readonly _tag: "CompletedUnlockScroll";
}, never, never>>

UpdatedInputValue

export type UpdatedInputValue = typeof Message.UpdatedInputValue.Type;

ViewInputs

Per-render view inputs passed to the view via `h.submodel`'s `viewInputs` field.

export type ViewInputs<Item extends string> = BaseViewInputsCommon<Item> & Readonly<{
    /** The selection the parent owns, passed in fresh on every render.
     *  `Option` because a single-select combobox may have no selection
     *  yet. Marks the selected item and drives the hidden form input
     *  submitted under `formName`. */
    maybeSelectedValue: Option.Option<Item>;
}>;