Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · menu

Published foldkit-ui API declarations for menu.

./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'

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;

AnchorMenu

The 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";
}>

BlurredItems

export type BlurredItems = typeof Message.BlurredItems.Type;

Bundle

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, index: number) => BundleUpdateReturn<Item>;
    open: (model: Model) => BundleUpdateReturn<Item>;
    openAt: (model: Model, invocation: ContextInvocation) => BundleUpdateReturn<Item>;
    close: (model: Model) => BundleUpdateReturn<Item>;
}>;

buttonId

Returns 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) => string

ClickItem

Programmatically 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>>

Closed

export type Closed = typeof Message.Closed.Type;

CompletedDelayClearSearch

export type CompletedDelayClearSearch = typeof Message.CompletedDelayClearSearch.Type;

ContextInvocation

export type ContextInvocation = typeof ContextInvocationSchema.Type;

ContextInvocationSchema

Source 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;
    }>>;
}>

ContextLongPress

Waits 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>>

ContextMenuAnchor

Positions 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>

ContextMenuBundle

export 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;
}>;

ContextMenuClasses

export type ContextMenuClasses = Readonly<{
    panel?: string;
    item?: string;
    group?: string;
    groupLabel?: string;
    separator?: string;
}>;

ContextMenuConfig

export type ContextMenuConfig<Value extends string> = Readonly<{
    id: string;
    sourceId: string;
    sourceToken: string;
    longPressMs?: 600;
    items: ReadonlyArray<ContextMenuEntry<Value>>;
    classes?: ContextMenuClasses;
    color?: string;
    anchor?: AnchorConfig;
}>;

ContextMenuEntry

export type ContextMenuEntry<Value extends string> = ContextMenuItem<Value> | ContextMenuGroup<Value> | ContextMenuSeparator;

ContextMenuGroup

export type ContextMenuGroup<Value extends string> = Readonly<{
    id: string;
    label: Html;
    items: ReadonlyArray<ContextMenuItem<Value> | ContextMenuSeparator>;
}>;

ContextMenuItem

export type ContextMenuItem<Value extends string> = Readonly<{
    value: Value;
    textValue: string;
    isDisabled: boolean;
    content: Html;
}>;

ContextMenuSeparator

export type ContextMenuSeparator = Readonly<{
    kind: 'separator';
    id: string;
}>;

ContextSourceEvents

Owns context invocation listeners on a source element.

ContextSourceEvents: (sourceId: string, sourceToken: string) => Mount.MountAction<Message>

contextTriggerAttributes

Attributes that make an element a keyboard and pointer context source.

contextTriggerAttributes: (sourceId: string, sourceToken: string, h: HtmlBuilder<Message>) => ReadonlyArray<Attribute<Message>>

create

Pairs 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>

createContextMenu

createContextMenu: <Value extends string>() => ContextMenuBundle<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 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>>

FocusButton

Moves focus back to the menu button after closing.

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

FocusItems

Moves focus to the menu items container after opening.

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

FocusSource

Restores 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>>

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 menu as inert for modal behavior.

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

init

Creates an initial menu model from a config. Defaults to closed with no active item.

init: (config: InitConfig) => Model

InitConfig

Configuration 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;
}>;

ItemConfig

Configuration for an individual menu item's appearance.

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

LockScroll

Prevents page scrolling while the menu is open.

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

LongPressExpiredSchema

LongPressExpiredSchema: Schema.Struct<{
    readonly _tag: Schema.Literal<"LongPressExpired">;
    readonly version: Schema.Number;
}>

Message

export type Message = typeof Message.Type;

Message

Union 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;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema 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>;
}>

MovedPointerOverItem

export type MovedPointerOverItem = typeof Message.MovedPointerOverItem.Type;

openAt

Opens the Menu for a contextual invocation, retaining its source identity.

openAt: (model: Model, invocation: ContextInvocation) => UpdateReturn

Opened

export type Opened = typeof Message.Opened.Type;

OpenedAtSchema

OpenedAtSchema: 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;
        }>>;
    }>;
}>

OutMessage

Generic 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>;

OutMessage

Union 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;
    };
}>

PortalMenuBackdrop

The 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";
}>

PressedPointerOnButton

export type PressedPointerOnButton = typeof Message.PressedPointerOnButton.Type;

ReleasedPointerOnItems

export type ReleasedPointerOnItems = typeof Message.ReleasedPointerOnItems.Type;

RequestedItemClick

export type RequestedItemClick = typeof Message.RequestedItemClick.Type;

RestoreInert

Removes the inert attribute from elements outside the menu.

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

ScrollIntoView

Scrolls 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>>

Searched

export type Searched = typeof Message.Searched.Type;

Selected

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

SelectedItem

export type SelectedItem = typeof Message.SelectedItem.Type;

SourceUnmountedSchema

SourceUnmountedSchema: Schema.Struct<{
    readonly _tag: Schema.Literal<"SourceUnmounted">;
    readonly token: Schema.String;
}>

SuppressedSpaceScroll

export type SuppressedSpaceScroll = typeof Message.SuppressedSpaceScroll.Type;

UnlockScroll

Re-enables page scrolling after the menu closes.

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

ViewInputs

Per-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;
}>;