ActivatedItem
export type ActivatedItem = typeof Message.ActivatedItem.Type;Effect-native UI toolkit
Interactive demosPublished API · 0.1.0-rc.1
Published foldkit-ui API declarations for 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'ActivatedItemexport type ActivatedItem = typeof Message.ActivatedItem.Type;ActivationTriggerSchema for the activation trigger: whether the user interacted via mouse or keyboard.
ActivationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>ActivationTriggerexport type ActivationTrigger = typeof ActivationTrigger.Type;AnchorConfigStatic 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>;
}>AnchorConfigexport type AnchorConfig = typeof AnchorConfig.Type;AnchorListboxAnchorListbox: 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";
}>BaseViewInputsCommonPer-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;
}>;BlurredItemsexport type BlurredItems = typeof Message.BlurredItems.Type;BundleThe `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>;
}>;buttonIdReturns 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) => stringClickItemProgrammatically 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>>Closedexport type Closed = typeof Message.Closed.Type;CompletedDelayClearSearchexport type CompletedDelayClearSearch = typeof Message.CompletedDelayClearSearch.Type;createPairs 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>DeactivatedItemexport type DeactivatedItem = typeof Message.DeactivatedItem.Type;DelayClearSearchWaits 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>>DetectMovementOrAnimationEndDetects 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>>FocusButtonMoves focus back to the listbox button after closing.
FocusButton: Command.CommandDefinitionWithArgs<"FocusButton", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusButton";
}, never, never>>FocusItemsMoves focus to the listbox items container after opening.
FocusItems: Command.CommandDefinitionWithArgs<"FocusItems", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusItems";
}, never, never>>GroupHeadingConfiguration for a group heading rendered above a group of items.
export type GroupHeading = Readonly<{
content: Html;
className?: string;
}>;IgnoredMouseClickexport type IgnoredMouseClick = typeof Message.IgnoredMouseClick.Type;InertOthersMarks all elements outside the listbox as inert for modal behavior.
InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedInertOthers";
}, never, never>>initCreates an initial single-select listbox model from a config. Defaults to closed with no active item.
init: (config: InitConfig) => ModelInitConfigConfiguration 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;ItemConfigConfiguration for an individual listbox item's appearance.
export type ItemConfig = Readonly<{
className?: string;
content: Html | ReadonlyArray<Html>;
}>;ItemToValueInputThe `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;
}>;LockScrollPrevents page scrolling while the listbox is open in modal mode.
LockScroll: Command.CommandDefinitionNoArgs<"LockScroll", Effect.Effect<{
readonly _tag: "CompletedLockScroll";
}, never, never>>Messageexport type Message = typeof Message.Type;MessageUnion 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;
};
}>Modelexport type Model = typeof Model.Type;ModelSchema 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>;
}>MovedPointerOverItemexport type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;Multiexport { init, create, Model } from './multi.js';
export { buttonId } from './shared.js';
export type { Bundle, InitConfig, ViewInputs } from './multi.js';Openedexport type Opened = typeof Message.Opened.Type;Orientationexport type Orientation = typeof Orientation.Type;OrientationSchema for the listbox orientation: whether items flow vertically or horizontally.
Orientation: Schema.Literals<readonly ["Vertical", "Horizontal"]>OutMessageGeneric 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>;OutMessageUnion 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;
};
}>PortalListboxBackdropThe 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";
}>PressedPointerOnButtonexport type PressedPointerOnButton = typeof Message.PressedPointerOnButton.Type;RequestedItemClickexport type RequestedItemClick = typeof Message.RequestedItemClick.Type;RestoreInertRemoves the inert attribute from elements outside the listbox.
RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedRestoreInert";
}, never, never>>ScrollIntoViewScrolls 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>>Searchedexport type Searched = typeof Message.Searched.Type;Selectedexport type Selected<Value extends string = string> = Readonly<{
readonly _tag: 'Selected';
readonly value: Value;
}>;SelectedItemexport type SelectedItem = typeof Message.SelectedItem.Type;SuppressedItemCommitexport type SuppressedItemCommit = typeof Message.SuppressedItemCommit.Type;SuppressedSpaceScrollexport type SuppressedSpaceScroll = typeof Message.SuppressedSpaceScroll.Type;UnlockScrollRe-enables page scrolling after the listbox closes.
UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
readonly _tag: "CompletedUnlockScroll";
}, never, never>>ViewInputsPer-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>;