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 menu.
@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/menu'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;AnchorMenuThe anchor-positioning Mount this Menu renders on its panel. The panel is always anchored to the button 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. It also carries the open-focus for the anchored panel. An anchored panel renders `visibility: hidden` until Floating UI resolves its first position, and `.focus()` does not land on a hidden element, so `FocusItems` alone cannot focus it. `focusAfterPosition` focuses the panel as part of that first reveal. `FocusItems` still focuses the panel when no anchor is configured, where the panel is visible as soon as the render commits. Exposed so Scene tests can call `Scene.Mount.resolve(AnchorMenu, Message.CompletedAnchorMenu())`.
AnchorMenu: Mount.MountDefinitionWithArgs<"AnchorMenu", {
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: "CompletedAnchorMenu";
}>BlurredItemsexport type BlurredItems = typeof Message.BlurredItems.Type;Bundleexport 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, index: number) => BundleUpdateReturn<Item>;
open: (model: Model) => BundleUpdateReturn<Item>;
openAt: (model: Model, invocation: ContextInvocation) => BundleUpdateReturn<Item>;
close: (model: Model) => BundleUpdateReturn<Item>;
}>;buttonIdReturns the bare DOM id of the menu trigger button, derived from the menu's base id. Use this to associate an external label with the trigger via a native `<label for={Menu.buttonId(id)}>` or an `aria-labelledby` reference.
buttonId: (id: string) => stringClickItemProgrammatically clicks the active menu 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;ContextInvocationexport type ContextInvocation = typeof ContextInvocationSchema.Type;ContextInvocationSchemaSource invocation metadata for a contextual Menu opening.
ContextInvocationSchema: Schema.Struct<{
readonly invocation: Schema.Literals<readonly ["pointer", "keyboard", "touch"]>;
readonly sourceId: Schema.String;
readonly sourceToken: Schema.String;
readonly point: Schema.optional<Schema.Struct<{
readonly x: Schema.Number;
readonly y: Schema.Number;
}>>;
}>ContextLongPressWaits for a context-source touch hold before opening the Menu.
ContextLongPress: Command.CommandDefinitionWithArgs<"ContextLongPress", {
version: Schema.Number;
}, Effect.Effect<{
readonly _tag: "LongPressExpired";
readonly version: number;
}, never, never>>ContextMenuAnchorPositions and reveals a contextual Menu panel relative to its source, then focuses its active item once the first position is ready.
ContextMenuAnchor: (sourceId: string, maybePoint: ContextInvocation['point'], anchor?: AnchorConfig) => Mount.MountAction<Message>ContextMenuBundleexport type ContextMenuBundle<Value extends string> = Readonly<{
init: (config: ContextMenuConfig<Value>) => Menu.Model;
update: (model: Menu.Model, message: Menu.Message) => Update.ReturnWithOutMessage<Menu.Model, Menu.Message, Menu.OutMessage<Value>>;
open: (model: Menu.Model) => Update.ReturnWithOutMessage<Menu.Model, Menu.Message, Menu.OutMessage<Value>>;
openAt: (model: Menu.Model, invocation: Menu.ContextInvocation) => Update.ReturnWithOutMessage<Menu.Model, Menu.Message, Menu.OutMessage<Value>>;
close: (model: Menu.Model) => Update.ReturnWithOutMessage<Menu.Model, Menu.Message, Menu.OutMessage<Value>>;
selectItem: (model: Menu.Model, value: Value, index: number) => Update.ReturnWithOutMessage<Menu.Model, Menu.Message, Menu.OutMessage<Value>>;
view: (model: Menu.Model, config: ContextMenuConfig<Value>, h: HtmlBuilder<Menu.Message>) => Html;
}>;ContextMenuClassesexport type ContextMenuClasses = Readonly<{
panel?: string;
item?: string;
group?: string;
groupLabel?: string;
separator?: string;
}>;ContextMenuConfigexport type ContextMenuConfig<Value extends string> = Readonly<{
id: string;
sourceId: string;
sourceToken: string;
longPressMs?: 600;
items: ReadonlyArray<ContextMenuEntry<Value>>;
classes?: ContextMenuClasses;
color?: string;
anchor?: AnchorConfig;
}>;ContextMenuEntryexport type ContextMenuEntry<Value extends string> = ContextMenuItem<Value> | ContextMenuGroup<Value> | ContextMenuSeparator;ContextMenuGroupexport type ContextMenuGroup<Value extends string> = Readonly<{
id: string;
label: Html;
items: ReadonlyArray<ContextMenuItem<Value> | ContextMenuSeparator>;
}>;ContextMenuItemexport type ContextMenuItem<Value extends string> = Readonly<{
value: Value;
textValue: string;
isDisabled: boolean;
content: Html;
}>;ContextMenuSeparatorexport type ContextMenuSeparator = Readonly<{
kind: 'separator';
id: string;
}>;ContextSourceEventsOwns context invocation listeners on a source element.
ContextSourceEvents: (sourceId: string, sourceToken: string) => Mount.MountAction<Message>contextTriggerAttributesAttributes that make an element a keyboard and pointer context source.
contextTriggerAttributes: (sourceId: string, sourceToken: string, h: HtmlBuilder<Message>) => ReadonlyArray<Attribute<Message>>createPairs the menu's `view` and `update` (and programmatic helpers) behind a single Item-typed entry point. Declaring the menu once at module scope ensures the view's `Item` type and the OutMessage's `item` type can't drift: ```ts const ActionMenu = Menu.create<Action>() // In view: h.submodel({ view: ActionMenu.view, ... }) // In the parent update, pass ActionMenu.update to Update.foldChild and // handle Menu.OutMessage<Action> in foldOutMessage. ```
create: <Item extends string = string>() => Bundle<Item>createContextMenucreateContextMenu: <Value extends string>() => ContextMenuBundle<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 menu 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 menu button after closing.
FocusButton: Command.CommandDefinitionWithArgs<"FocusButton", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusButton";
}, never, never>>FocusItemsMoves focus to the menu items container after opening.
FocusItems: Command.CommandDefinitionWithArgs<"FocusItems", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusItems";
}, never, never>>FocusSourceRestores focus to the exact still-mounted contextual source token.
FocusSource: Command.CommandDefinitionWithArgs<"FocusSource", {
sourceId: Schema.String;
sourceToken: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedFocusButton";
}, 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 menu as inert for modal behavior.
InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedInertOthers";
}, never, never>>initCreates an initial menu model from a config. Defaults to closed with no active item.
init: (config: InitConfig) => ModelInitConfigConfiguration for creating a menu model with `init`. `isAnimated` enables animation coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`).
export type InitConfig = Readonly<{
id: string;
isAnimated?: boolean;
isModal?: boolean;
}>;ItemConfigConfiguration for an individual menu item's appearance.
export type ItemConfig = Readonly<{
className?: string;
content: Html;
}>;LockScrollPrevents page scrolling while the menu is open.
LockScroll: Command.CommandDefinitionNoArgs<"LockScroll", Effect.Effect<{
readonly _tag: "CompletedLockScroll";
}, never, never>>LongPressExpiredSchemaLongPressExpiredSchema: Schema.Struct<{
readonly _tag: Schema.Literal<"LongPressExpired">;
readonly version: Schema.Number;
}>Messageexport type Message = typeof Message.Type;MessageUnion of all messages the menu component can produce.
Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly Opened: {
maybeActiveItemIndex: Schema.Option<Schema.Number>;
};
readonly OpenedAt: {
invocation: Schema.Struct<{
readonly invocation: Schema.Literals<readonly ["pointer", "keyboard", "touch"]>;
readonly sourceId: Schema.String;
readonly sourceToken: Schema.String;
readonly point: Schema.optional<Schema.Struct<{
readonly x: Schema.Number;
readonly y: Schema.Number;
}>>;
}>;
};
readonly LongPressExpired: {
version: Schema.Number;
};
readonly SourceUnmounted: {
token: Schema.String;
};
readonly Closed: {};
readonly BlurredItems: {};
readonly ActivatedItem: {
index: Schema.Number;
activationTrigger: Schema.Literals<readonly ["Pointer", "Keyboard"]>;
};
readonly DeactivatedItem: {};
readonly SelectedItem: {
index: Schema.Number;
item: Schema.String;
};
readonly RequestedItemClick: {
index: Schema.Number;
};
readonly Searched: {
key: Schema.String;
maybeTargetIndex: Schema.Option<Schema.Number>;
};
readonly CompletedDelayClearSearch: {
version: Schema.Number;
};
readonly MovedPointerOverItem: {
index: Schema.Number;
screenX: Schema.Number;
screenY: Schema.Number;
};
readonly CompletedFocusItems: {};
readonly CompletedFocusButton: {};
readonly CompletedLockScroll: {};
readonly CompletedUnlockScroll: {};
readonly CompletedInertOthers: {};
readonly CompletedRestoreInert: {};
readonly CompletedScrollIntoView: {};
readonly CompletedClickItem: {};
readonly IgnoredMouseClick: {};
readonly SuppressedSpaceScroll: {};
readonly CompletedAnchorMenu: {};
readonly CompletedPortalMenuBackdrop: {};
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;
screenX: Schema.Number;
screenY: Schema.Number;
timeStamp: Schema.Number;
};
readonly ReleasedPointerOnItems: {
screenX: Schema.Number;
screenY: Schema.Number;
timeStamp: Schema.Number;
};
}>Modelexport type Model = typeof Model.Type;ModelSchema for the menu component's state.
Model: Schema.Struct<{
readonly id: Schema.String;
readonly isOpen: Schema.Boolean;
readonly isAnimated: Schema.Boolean;
readonly isModal: 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 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 maybePointerOrigin: Schema.Option<Schema.Struct<{
readonly screenX: Schema.Number;
readonly screenY: Schema.Number;
readonly timeStamp: Schema.Number;
}>>;
readonly maybeContextInvocation: Schema.withDecodingDefaultTypeKey<Schema.Option<Schema.Struct<{
readonly invocation: Schema.Literals<readonly ["pointer", "keyboard", "touch"]>;
readonly sourceId: Schema.String;
readonly sourceToken: Schema.String;
readonly point: Schema.optional<Schema.Struct<{
readonly x: Schema.Number;
readonly y: Schema.Number;
}>>;
}>>, never>;
readonly longPressVersion: Schema.withDecodingDefaultTypeKey<Schema.Number, never>;
}>MovedPointerOverItemexport type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;openAtOpens the Menu for a contextual invocation, retaining its source identity.
openAt: (model: Model, invocation: ContextInvocation) => UpdateReturnOpenedexport type Opened = typeof Message.Opened.Type;OpenedAtSchemaOpenedAtSchema: Schema.Struct<{
readonly _tag: Schema.Literal<"OpenedAt">;
readonly invocation: Schema.Struct<{
readonly invocation: Schema.Literals<readonly ["pointer", "keyboard", "touch"]>;
readonly sourceId: Schema.String;
readonly sourceToken: Schema.String;
readonly point: Schema.optional<Schema.Struct<{
readonly x: Schema.Number;
readonly y: Schema.Number;
}>>;
}>;
}>OutMessageGeneric over `Value extends string` so consumers using the typed `Menu.create<MyUnion>()` factory receive `value: MyUnion` in the `Selected` OutMessage. Defaults to `string`.
export type OutMessage<Value extends string = string> = Selected<Value>;OutMessageUnion of OutMessages the menu component can produce. The parent's `Update.foldChild` config handles them through `foldOutMessage`.
OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly Selected: {
value: Schema.String;
index: Schema.Number;
};
}>PortalMenuBackdropThe backdrop-portaling Mount this Menu renders. Exposed so Scene tests can call `Scene.Mount.resolve(PortalMenuBackdrop, Message.CompletedPortalMenuBackdrop())` to acknowledge the mount produced by the rendered backdrop.
PortalMenuBackdrop: Mount.MountDefinitionNoArgs<"PortalMenuBackdrop", {
readonly _tag: "CompletedPortalMenuBackdrop";
}>PressedPointerOnButtonexport type PressedPointerOnButton = typeof Message.PressedPointerOnButton.Type;ReleasedPointerOnItemsexport type ReleasedPointerOnItems = typeof Message.ReleasedPointerOnItems.Type;RequestedItemClickexport type RequestedItemClick = typeof Message.RequestedItemClick.Type;RestoreInertRemoves the inert attribute from elements outside the menu.
RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
id: Schema.String;
}, Effect.Effect<{
readonly _tag: "CompletedRestoreInert";
}, never, never>>ScrollIntoViewScrolls the active menu 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;
readonly index: number;
}>;SelectedItemexport type SelectedItem = typeof Message.SelectedItem.Type;SourceUnmountedSchemaSourceUnmountedSchema: Schema.Struct<{
readonly _tag: Schema.Literal<"SourceUnmounted">;
readonly token: Schema.String;
}>SuppressedSpaceScrollexport type SuppressedSpaceScroll = typeof Message.SuppressedSpaceScroll.Type;UnlockScrollRe-enables page scrolling after the menu closes.
UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
readonly _tag: "CompletedUnlockScroll";
}, never, never>>ViewInputsPer-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field. The Menu emits an `OutMessage.Selected({ value, index })` OutMessage on commit. The menu has already closed by the time this fires. Handle it in the `foldOutMessage` of the Menu's `Update.foldChild` config.
export type ViewInputs<Item extends string> = Readonly<{
items: ReadonlyArray<Item>;
itemToConfig: (item: Item, context: Readonly<{
isActive: boolean;
isDisabled: 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>;
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;
ariaLabel?: string;
ariaLabelledBy?: string;
}>;