Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · listbox

Published foldkit-ui API declarations for listbox.

./listbox

@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/listbox'

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;

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;

AnchorListbox

AnchorListbox: Mount.MountDefinitionWithArgs<"AnchorListbox", {
    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>;
    }>;
    anchorMode: Schema.optional<Schema.Literals<readonly ["Trigger", "SelectedOrActiveItem"]>>;
    selectedItemId: Schema.optional<Schema.String>;
}, {
    readonly _tag: "CompletedAnchorListbox";
}>

BaseViewInputsCommon

Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field. The Listbox emits a `Selected({ value })` OutMessage on commit. Fold it in the Listbox's `Update.foldChild` config: single-select stores the value, while multi-select toggles its membership.

export type BaseViewInputsCommon<Item> = Readonly<{
    items: ReadonlyArray<Item>;
    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;
    isItemDisabled?: (item: Item, index: number) => boolean;
    itemToSearchText?: (item: Item, index: number) => string;
    isButtonDisabled?: boolean;
    buttonContent: Html;
    buttonClassName?: string;
    buttonAttributes?: ReadonlyArray<ChildAttribute>;
    itemsClassName?: string;
    itemsAttributes?: ReadonlyArray<ChildAttribute>;
    itemsScrollClassName?: string;
    itemsScrollAttributes?: ReadonlyArray<ChildAttribute>;
    /** Overrides the value of `data-active` on the active item. */
    activeItemAttributeValue?: string;
    backdropClassName?: string;
    backdropAttributes?: ReadonlyArray<ChildAttribute>;
    className?: string;
    attributes?: ReadonlyArray<ChildAttribute>;
    itemGroupKey?: (item: Item, index: number) => string;
    groupToHeading?: (groupKey: string) => GroupHeading | undefined;
    groupClassName?: string;
    groupAttributes?: ReadonlyArray<ChildAttribute>;
    separatorClassName?: string;
    separatorAttributes?: ReadonlyArray<ChildAttribute>;
    anchor?: AnchorConfig;
    name?: string;
    form?: string;
    /** Marks the Listbox unavailable with `aria-disabled="true"` on the button
     *  and `data-disabled` on the button and the wrapper, and removes the
     *  button's handlers so the dropdown cannot be opened. */
    isDisabled?: boolean;
    /** Prevents committing a selection while exposing read-only semantics
     *  with `aria-readonly="true"` and `data-readonly` on the items panel, and
     *  `data-readonly` on the wrapper, button, and every item. The Listbox
     *  still opens, navigates, and searches. Independent of `isDisabled`:
     *  setting both emits both attribute sets, and `isDisabled` still wins for
     *  interaction, since its button drops every handler, so a Listbox that is
     *  both read-only and disabled cannot be opened at all. */
    isReadOnly?: boolean;
    isInvalid?: boolean;
    ariaLabel?: string;
    ariaLabelledBy?: string;
}>;

BlurredItems

export type BlurredItems = typeof Message.BlurredItems.Type;

Bundle

The `view`, `update`, and programmatic helpers that `Listbox.create` returns, bound to one `Item` and `Value` pair. 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 = string, Value extends string = Item extends string ? Item : string> = Readonly<{
    view: SubmodelView<Model, Message, ViewInputs<Item, Value>>;
    update: (model: Model, message: Message) => BundleUpdateReturn<Value>;
    selectItem: (model: Model, item: Value) => BundleUpdateReturn<Value>;
    open: (model: Model) => BundleUpdateReturn<Value>;
    close: (model: Model) => BundleUpdateReturn<Value>;
}>;

buttonId

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

buttonId: (id: string) => string

ClickItem

Programmatically clicks the active listbox 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;

CompletedDelayClearSearch

export type CompletedDelayClearSearch = typeof Message.CompletedDelayClearSearch.Type;

create

Pairs the single-select listbox's `view` and `update` (and programmatic helpers) behind a single Item-typed entry point. Declaring the listbox once at module scope ensures the view's `Item` type and the update's OutMessage `item` type can't drift: ```ts const ColorListbox = Listbox.create<Color>() // In view: h.submodel({ view: ColorListbox.view, ... }) // In the parent update, pass ColorListbox.update to Update.foldChild and // handle Listbox.OutMessage<Color> in foldOutMessage. ``` Two type params support object-typed items with an `itemToValue` extractor: pass `<Person, string>` when items are objects whose extracted value is a plain string. `Value` defaults to `Item` when `Item extends string`, else defaults to `string`.

create: <Item = string, Value extends string = Item extends string ? Item : string>() => Bundle<Item, Value>

DeactivatedItem

export type DeactivatedItem = typeof Message.DeactivatedItem.Type;

DelayClearSearch

Waits for the typeahead search debounce period before clearing the query.

DelayClearSearch: Command.CommandDefinitionWithArgs<"DelayClearSearch", {
    version: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "CompletedDelayClearSearch";
    readonly version: number;
}, never, never>>

DetectMovementOrAnimationEnd

Detects whether the listbox button 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>>

FocusButton

Moves focus back to the listbox button after closing.

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

FocusItems

Moves focus to the listbox items container after opening.

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

GroupHeading

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

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

IgnoredMouseClick

export type IgnoredMouseClick = typeof Message.IgnoredMouseClick.Type;

InertOthers

Marks all elements outside the listbox 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 listbox model from a config. Defaults to closed with no active item.

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a single-select listbox 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;

ItemConfig

Configuration for an individual listbox item's appearance.

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

ItemToValueInput

The `itemToValue` extractor piece of a Listbox's view inputs. The extractor is optional when `Item` is itself a string (the default returns the item unchanged) and required when items are objects, so the OutMessage payload type can't drift from what the consumer actually emits.

export type ItemToValueInput<Item, Value extends string = string> = [
    Item
] extends [string] ? Readonly<{
    itemToValue?: (item: Item) => Value;
}> : Readonly<{
    itemToValue: (item: Item) => Value;
}>;

LockScroll

Prevents page scrolling while the listbox 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 listbox component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Opened: {
        maybeActiveItemIndex: Schema.Option<Schema.Number>;
    };
    readonly Closed: {};
    readonly BlurredItems: {};
    readonly ActivatedItem: {
        index: Schema.Number;
        activationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>;
    };
    readonly DeactivatedItem: {};
    readonly SelectedItem: {
        item: Schema.String;
    };
    readonly MovedPointerOverItem: {
        index: Schema.Number;
        screenX: Schema.Number;
        screenY: Schema.Number;
    };
    readonly RequestedItemClick: {
        index: Schema.Number;
    };
    readonly Searched: {
        key: Schema.String;
        maybeTargetIndex: Schema.Option<Schema.Number>;
    };
    readonly CompletedDelayClearSearch: {
        version: Schema.Number;
    };
    readonly CompletedLockScroll: {};
    readonly CompletedUnlockScroll: {};
    readonly CompletedInertOthers: {};
    readonly CompletedRestoreInert: {};
    readonly CompletedFocusButton: {};
    readonly CompletedFocusItems: {};
    readonly CompletedScrollIntoView: {};
    readonly CompletedClickItem: {};
    readonly IgnoredMouseClick: {};
    readonly SuppressedSpaceScroll: {};
    readonly SuppressedItemCommit: {};
    readonly CompletedAnchorListbox: {};
    readonly CompletedPortalListboxBackdrop: {};
    readonly GotAnimationMessage: {
        message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
            readonly Showed: {};
            readonly Hid: {};
            readonly CompletedWaitForPaint: {
                generation: Schema.Number;
            };
            readonly EndedAnimation: {
                generation: Schema.Number;
            };
        }>;
    };
    readonly PressedPointerOnButton: {
        pointerType: Schema.String;
        button: Schema.Number;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the single-select listbox's private interaction state (open/closed status, active item, activation trigger, typeahead search). 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 orientation: Schema.Literals<readonly ["Vertical", "Horizontal"]>;
    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 searchQuery: Schema.String;
    readonly searchVersion: Schema.Number;
    readonly maybeLastPointerPosition: Schema.Option<Schema.Struct<{
        readonly screenX: Schema.Number;
        readonly screenY: Schema.Number;
    }>>;
    readonly maybeLastButtonPointerType: Schema.Option<Schema.String>;
    readonly anchorMode: Schema.withDecodingDefaultKey<Schema.Literals<readonly ["Trigger", "SelectedOrActiveItem"]>, never>;
}>

MovedPointerOverItem

export type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;

Multi

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

Opened

export type Opened = typeof Message.Opened.Type;

Orientation

export type Orientation = typeof Orientation.Type;

Orientation

Schema for the listbox orientation: whether items flow vertically or horizontally.

Orientation: Schema.Literals<readonly ["Vertical", "Horizontal"]>

OutMessage

Generic over `Value extends string` so consumers who create the listbox via `Listbox.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>;

OutMessage

Union of out-messages the listbox component can produce. The parent folds `Selected` into the selection it owns: single-select stores the value, multi-select toggles the value's membership.

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

PortalListboxBackdrop

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

PortalListboxBackdrop: Mount.MountDefinitionNoArgs<"PortalListboxBackdrop", {
    readonly _tag: "CompletedPortalListboxBackdrop";
}>

PressedPointerOnButton

export type PressedPointerOnButton = typeof Message.PressedPointerOnButton.Type;

RequestedItemClick

export type RequestedItemClick = typeof Message.RequestedItemClick.Type;

RestoreInert

Removes the inert attribute from elements outside the listbox.

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

ScrollIntoView

Scrolls the active listbox item into view after keyboard navigation.

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

Searched

export type Searched = typeof Message.Searched.Type;

Selected

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

SelectedItem

export type SelectedItem = typeof Message.SelectedItem.Type;

SuppressedItemCommit

export type SuppressedItemCommit = typeof Message.SuppressedItemCommit.Type;

SuppressedSpaceScroll

export type SuppressedSpaceScroll = typeof Message.SuppressedSpaceScroll.Type;

UnlockScroll

Re-enables page scrolling after the listbox closes.

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

ViewInputs

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

export type ViewInputs<Item, Value extends string = string> = BaseViewInputsCommon<Item> & Readonly<{
    /** The selection the parent owns, passed in fresh on every render.
     *  `Option` because a single-select listbox may have no selection yet.
     *  Drives `aria-selected` and `data-selected` on items, which item the
     *  Listbox highlights when it opens onto a selection, and the hidden
     *  form input submitted under `name`. */
    maybeSelectedValue: Option.Option<Value>;
}> & ItemToValueInput<Item, Value>;