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 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'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;AnchorComboboxThe 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";
}>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;AttachComboboxPreventBlurThe 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";
}>AttachComboboxSelectOnFocusThe 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";
}>BaseViewInputsCommonPer-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;
}>;BlurredInputexport type BlurredInput = typeof Message.BlurredInput.Type;BundleThe `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>;
}>;ClearedSelectionexport type ClearedSelection = typeof OutMessage.ClearedSelection.Type;ClickItemProgrammatically 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>>Closedexport type Closed = typeof Message.Closed.Type;CompletedClickItemexport type CompletedClickItem = typeof Message.CompletedClickItem.Type;CompletedFocusInputexport type CompletedFocusInput = typeof Message.CompletedFocusInput.Type;CompletedInertOthersexport type CompletedInertOthers = typeof Message.CompletedInertOthers.Type;CompletedLockScrollexport type CompletedLockScroll = typeof Message.CompletedLockScroll.Type;CompletedRestoreInertexport type CompletedRestoreInert = typeof Message.CompletedRestoreInert.Type;CompletedScrollIntoViewexport type CompletedScrollIntoView = typeof Message.CompletedScrollIntoView.Type;CompletedUnlockScrollexport type CompletedUnlockScroll = typeof Message.CompletedUnlockScroll.Type;createPairs 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>DeactivatedItemexport type DeactivatedItem = typeof Message.DeactivatedItem.Type;DetectMovementOrAnimationEndDetects 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>>FocusInputMoves focus to the combobox input after selection or close.
FocusInput: Command.CommandDefinitionWithArgs<"FocusInput", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusInput";
}, never, never>>GroupHeadingConfiguration for a group heading rendered above a group of items.
export type GroupHeading = Readonly<{
content: Html;
className?: string;
}>;InertOthersMarks all elements outside the combobox as inert for modal behavior.
InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedInertOthers";
}, never, never>>initCreates an initial single-select combobox model from a config. Defaults to closed with no active item and an empty input.
init: (config: InitConfig) => ModelInitConfigConfiguration 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;inputIdReturns 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) => stringItemConfigConfiguration for an individual combobox item's appearance.
export type ItemConfig = Readonly<{
className?: string;
content: Html;
}>;LockScrollPrevents page scrolling while the combobox popup 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 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;
};
}>Modelexport type Model = typeof Model.Type;ModelSchema 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;
}>>;
}>MovedPointerOverItemexport type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;Multiexport { init, create, Model } from './multi.js';
export { inputId } from './shared.js';
export type { Bundle, InitConfig, ViewInputs } from './multi.js';Openedexport type Opened = typeof Message.Opened.Type;OutMessageGeneric 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;OutMessageUnion 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: {};
}>PortalComboboxBackdropThe 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";
}>PressedToggleButtonexport type PressedToggleButton = typeof Message.PressedToggleButton.Type;RequestedItemClickexport type RequestedItemClick = typeof Message.RequestedItemClick.Type;RestoreInertRemoves the inert attribute from elements outside the combobox.
RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedRestoreInert";
}, never, never>>ScrollIntoViewScrolls 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>>Selectedexport type Selected<Value extends string = string> = Readonly<{
readonly _tag: 'Selected';
readonly value: Value;
}>;SelectedItemexport type SelectedItem = typeof Message.SelectedItem.Type;SuppressedEmptyItemNavigationexport type SuppressedEmptyItemNavigation = typeof Message.SuppressedEmptyItemNavigation.Type;SuppressedItemCommitexport type SuppressedItemCommit = typeof Message.SuppressedItemCommit.Type;UnlockScrollRe-enables page scrolling after the combobox popup closes.
UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
readonly _tag: "CompletedUnlockScroll";
}, never, never>>UpdatedInputValueexport type UpdatedInputValue = typeof Message.UpdatedInputValue.Type;ViewInputsPer-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>;
}>;