@typed/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/Menu.js

@@ -0,0 +1,569 @@
+/**
+ * Menu coordinates trigger, manual native popover content, registered items, and nested submenu
+ * state. Keyboard handling covers opening, Escape, directional parent/child traversal, roving
+ * focus, and typeahead without synthetic events.
+ *
+ * @remarks
+ * The module keeps policy, state transitions, and DOM rendering separable so applications can use
+ * the state and pure operations without mounting UI, or supply custom hosts without replacing native
+ * events and browser-owned focus.
+ *
+ * Learn the interaction in the [Menu guide](/explore/ui-menu).
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import * as Schema from "effect/Schema";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, html, } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Composite from "./Composite.js";
+import * as Dom from "./Dom.js";
+import * as NativePopover from "./NativePopover.js";
+const invokers = new WeakMap();
+const submenuOwners = new WeakMap();
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Menu state.
+ *
+ * @remarks
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Menu from "@typed/ui/Menu";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Menu.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category Popup state
+ */
+export const StateSchema = Schema.Struct({
+    id: Schema.String,
+    open: Schema.Boolean,
+    activeId: Schema.NullOr(Schema.String),
+    orientation: Schema.Literals(["vertical"]),
+    loop: Schema.Boolean,
+    rtl: Schema.Boolean,
+    virtualFocus: Schema.Boolean,
+});
+/**
+ * Creates hydrated Menu state. The caller supplies id; open defaults false, activeId null, loop
+ * true, and orientation vertical.
+ *
+ * @remarks
+ * The returned Effect creates the RefSubject when run. That state is renderer-independent;
+ * collection registrations belong to the separate Scope that runs register or ref, not to state
+ * creation.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as Menu from "@typed/ui/Menu";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Menu.makeState({ id: "file-menu" });
+ *     const collection = yield* Menu.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Popup state
+ */
+export function makeState(initial) {
+    return RefSubject.hydrate(StateSchema, {
+        id: initial.id,
+        open: initial.open ?? false,
+        activeId: initial.activeId ?? null,
+        orientation: "vertical",
+        loop: initial.loop ?? true,
+        rtl: false,
+        virtualFocus: false,
+    });
+}
+/**
+ * Creates a scoped Collection for Menu items.
+ *
+ * @remarks
+ * The returned Effect allocates the RefSubject in the caller's Scope. Each later registration is
+ * owned by the Scope that runs register, independently of this construction Effect.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as Menu from "@typed/ui/Menu";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Menu.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Command registration
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Updates only the menu's explicit open state.
+ *
+ * @remarks
+ * The operation exposes Menu's transition directly so callers can compose it in Effect programs
+ * and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Popup state
+ */
+export function setOpen(state, open) {
+    return RefSubject.update(state, (value) => ({ ...value, open }));
+}
+function triggerProps(options) {
+    const id = RefSubject.map(options.state, (state) => state.id);
+    const open = RefSubject.map(options.state, (state) => state.open);
+    return () => ({
+        type: "button",
+        popovertarget: id,
+        popovertargetaction: "toggle",
+        "aria-haspopup": "menu",
+        "aria-expanded": open,
+        onkeydown: EventHandler.make((event) => {
+            if (event.key !== "ArrowDown")
+                return;
+            event.preventDefault();
+            Dom.currentTarget(event).click();
+        }),
+        ref: Dom.composeRefs(options.state, invokerRef(options.state)),
+    });
+}
+function invokerRef(state) {
+    return Effect.fn(function* (element) {
+        invokers.set(state, element);
+        const scope = yield* Effect.scope;
+        yield* Scope.addFinalizer(scope, Effect.sync(() => {
+            if (invokers.get(state) === element)
+                invokers.delete(state);
+        }));
+    });
+}
+/**
+ * Renders a native button targeting menu popover content and opens the menu on ArrowDown.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Opening a menu
+ */
+export function Trigger(options, host) {
+    return Dom.renderHost()(options, host, triggerProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+/**
+ * Consumer-facing alias of the canonical Menu component with identical behavior and lifetime.
+ *
+ * @remarks
+ * The alias acquires nothing. Rendering it has exactly the canonical component's Scope and DOM
+ * ownership contract.
+ *
+ * @since 1.0.0
+ * @category Opening a menu
+ */
+export const Button = Trigger;
+function contentProps(options) {
+    const id = RefSubject.map(options.state, (state) => state.id);
+    let typeahead = { value: "", updatedAt: 0 };
+    let restoreParentFocus = false;
+    let restoreOwnerFocus = false;
+    let restoreInvokerFocus = false;
+    let invoker;
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn(function* (event) {
+            const direction = Composite.keyMove(event, { orientation: "vertical" });
+            if (direction !== undefined) {
+                event.preventDefault();
+                yield* Composite.moveAndFocus({ state: options.state, collection: options.collection, includeDisabled: true }, direction);
+                return;
+            }
+            if (event.key === "ArrowRight") {
+                const activeId = (yield* options.state).activeId;
+                const item = activeId === null
+                    ? undefined
+                    : (yield* options.collection).find((item) => item.id === activeId);
+                const element = item?.submenu === true ? item.element : undefined;
+                const click = element === undefined ? undefined : Reflect.get(element, "click");
+                if (typeof click === "function") {
+                    event.preventDefault();
+                    yield* Effect.sync(() => click.call(element));
+                }
+                return;
+            }
+            if (event.key === "ArrowLeft") {
+                event.preventDefault();
+                const element = Dom.currentTarget(event);
+                const hidePopover = Reflect.get(element, "hidePopover");
+                if (typeof hidePopover === "function") {
+                    if (options.parent === undefined && submenuOwners.has(options.state))
+                        restoreOwnerFocus = true;
+                    else if (options.parent === undefined)
+                        restoreInvokerFocus = true;
+                    else
+                        restoreParentFocus = true;
+                    yield* Effect.sync(() => hidePopover.call(element));
+                }
+                else {
+                    yield* setOpen(options.state, false);
+                    if (options.parent === undefined && submenuOwners.has(options.state)) {
+                        yield* submenuOwners.get(options.state)?.onArrowLeft ?? Effect.void;
+                    }
+                    else if (options.parent === undefined)
+                        yield* Composite.focusElement(invoker ?? invokers.get(options.state));
+                    else {
+                        yield* RefSubject.update(options.parent.state, (state) => ({
+                            ...state,
+                            activeId: options.parent.triggerId,
+                        }));
+                        yield* Composite.focusActive({
+                            state: options.parent.state,
+                            collection: options.parent.collection,
+                        });
+                    }
+                }
+                return;
+            }
+            if (event.key === "Escape") {
+                restoreInvokerFocus = true;
+                yield* setOpen(options.state, false);
+                return;
+            }
+            if (event.key === "Tab") {
+                yield* setOpen(options.state, false);
+                return;
+            }
+            if (event.key === "Enter" || event.key === " ") {
+                const activeId = (yield* options.state).activeId;
+                const element = activeId === null
+                    ? undefined
+                    : (yield* options.collection).find((item) => item.id === activeId)?.element;
+                const click = element === undefined ? undefined : Reflect.get(element, "click");
+                if (typeof click === "function") {
+                    event.preventDefault();
+                    yield* Effect.sync(() => click.call(element));
+                }
+                return;
+            }
+            const key = Composite.typeaheadKey(event);
+            if (key === null)
+                return;
+            typeahead = Composite.updateTypeaheadBuffer(typeahead, key, Date.now());
+            const activeId = Composite.typeaheadFrom(yield* options.collection, typeahead.value, (yield* options.state).activeId, undefined, true);
+            if (activeId === null)
+                return;
+            event.preventDefault();
+            yield* RefSubject.update(options.state, (state) => ({ ...state, activeId }));
+            yield* Composite.focusActive({ state: options.state, collection: options.collection });
+        }));
+    const restoreFocus = Effect.gen(function* () {
+        if (restoreParentFocus && options.parent !== undefined) {
+            restoreParentFocus = false;
+            yield* RefSubject.update(options.parent.state, (state) => ({
+                ...state,
+                activeId: options.parent.triggerId,
+            }));
+            yield* Composite.focusActive({
+                state: options.parent.state,
+                collection: options.parent.collection,
+            });
+        }
+        if (restoreOwnerFocus) {
+            restoreOwnerFocus = false;
+            yield* submenuOwners.get(options.state)?.onArrowLeft ?? Effect.void;
+        }
+        if (restoreInvokerFocus) {
+            restoreInvokerFocus = false;
+            yield* Composite.focusElement(invoker ?? invokers.get(options.state));
+        }
+    });
+    const toggle = EventHandler.make(Effect.fn(function* (event) {
+        const open = Dom.toggleState(event) === "open";
+        const source = Reflect.get(event, "source");
+        if (isElement(source))
+            invoker = source;
+        const current = yield* options.state;
+        if (current.open === open) {
+            if (!open)
+                yield* restoreFocus;
+            return current;
+        }
+        if (open && options.collection !== undefined) {
+            const activeId = Composite.moveActiveId(yield* options.collection, current, "first", true);
+            const next = yield* RefSubject.update(options.state, (state) => ({
+                ...state,
+                open,
+                activeId,
+            }));
+            yield* Composite.focusActive({ state: options.state, collection: options.collection });
+            yield* Composite.scrollActive({ state: options.state, collection: options.collection });
+            return next;
+        }
+        const next = yield* setOpen(options.state, open);
+        if (!open)
+            yield* restoreFocus;
+        return next;
+    }));
+    return ({ property }) => ({
+        id,
+        role: "menu",
+        popover: "manual",
+        "aria-label": property("label", undefined),
+        onkeydown,
+        ontoggle: toggle,
+        ref: Dom.composeRefs(options.state, NativePopover.ref(options.state)),
+    });
+}
+function isElement(value) {
+    return typeof value === "object" && value !== null && "nodeType" in value;
+}
+/**
+ * Renders manual-popover menu content and coordinates focus, typeahead, Escape, and nested-menu
+ * traversal.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Menu surface
+ */
+export function Content(options, host) {
+    return Dom.renderHost()(options, host, contentProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+/**
+ * Consumer-facing alias of the canonical Menu component with identical behavior and lifetime.
+ *
+ * @remarks
+ * The alias acquires nothing. Rendering it has exactly the canonical component's Scope and DOM
+ * ownership contract.
+ *
+ * @since 1.0.0
+ * @category Menu surface
+ */
+export const Menu = Content;
+function itemProps(options) {
+    const closesOnActivate = options.role === undefined || options.role === "menuitem";
+    const activate = options.disabled === true
+        ? Effect.void
+        : RefSubject.update(options.state, (state) => ({
+            ...state,
+            activeId: options.id,
+            open: closesOnActivate ? false : state.open,
+        }));
+    const focus = RefSubject.update(options.state, (state) => ({ ...state, activeId: options.id }));
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.id,
+            textValue: options.textValue ?? options.id,
+            disabled: options.disabled,
+        });
+    return () => ({
+        id: options.id,
+        role: options.role ?? "menuitem",
+        "aria-disabled": options.disabled ?? false,
+        "aria-checked": options.role === "menuitem" || options.role === undefined
+            ? undefined
+            : (options.checked ?? false),
+        tabindex: Composite.tabIndex(options.state, options.id),
+        onclick: activate,
+        onfocus: focus,
+        onmouseenter: focus,
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers a menu item; disabled items remain announced but do not
+ * activate.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Commands
+ */
+export function Item(options, host) {
+    return Dom.renderHost()(options, host, itemProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function submenuTriggerProps(options) {
+    const submenuId = RefSubject.map(options.submenu, (state) => state.id);
+    const expanded = RefSubject.map(options.submenu, (state) => state.open);
+    const focusEffect = RefSubject.update(options.state, (state) => ({
+        ...state,
+        activeId: options.id,
+    }));
+    const activateEffect = options.disabled === true ? Effect.void : focusEffect;
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.id,
+            textValue: options.textValue ?? options.id,
+            disabled: options.disabled,
+            submenu: true,
+        });
+    return () => ({
+        id: options.id,
+        type: "button",
+        role: "menuitem",
+        popovertarget: submenuId,
+        popovertargetaction: "toggle",
+        "aria-haspopup": "menu",
+        "aria-expanded": expanded,
+        "aria-disabled": options.disabled ?? false,
+        tabindex: Composite.tabIndex(options.state, options.id),
+        onclick: activateEffect,
+        onfocus: focusEffect,
+        onmouseenter: options.disabled === true
+            ? Effect.void
+            : Effect.andThen(activateEffect, setOpen(options.submenu, true)),
+        ref: Dom.composeRefs(register, Dom.composeRefs(options.ref, submenuOwnerRef(options.submenu, options.state, options.collection, options.id))),
+    });
+}
+function submenuOwnerRef(submenu, state, collection, triggerId) {
+    return Effect.fn(function* () {
+        const owner = {
+            onArrowLeft: Effect.gen(function* () {
+                if (collection === undefined)
+                    return;
+                if ((yield* state).orientation === "horizontal") {
+                    yield* Composite.moveAndFocus({ state, collection, includeDisabled: true }, "previous");
+                }
+                else {
+                    yield* RefSubject.update(state, (value) => ({ ...value, activeId: triggerId }));
+                    yield* Composite.focusActive({ state, collection });
+                }
+            }),
+        };
+        submenuOwners.set(submenu, owner);
+        const scope = yield* Effect.scope;
+        yield* Scope.addFinalizer(scope, Effect.sync(() => {
+            if (submenuOwners.get(submenu) === owner)
+                submenuOwners.delete(submenu);
+        }));
+    });
+}
+/**
+ * Renders a menuitem that targets nested popover content and coordinates parent/child directional
+ * focus.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Nested menus
+ */
+export function SubmenuTrigger(options, host) {
+    return Dom.renderHost()(options, host, submenuTriggerProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+/**
+ * Renders Item with menuitemcheckbox semantics and caller-supplied checked state.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Checked commands
+ */
+export function CheckboxItem(options, host) {
+    return Item({ ...options, role: "menuitemcheckbox" }, host);
+}
+/**
+ * Renders Item with menuitemradio semantics and caller-supplied checked state.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Checked commands
+ */
+export function RadioItem(options, host) {
+    return Item({ ...options, role: "menuitemradio" }, host);
+}
+function groupProps(_options) {
+    return ({ property }) => ({
+        role: "group",
+        "aria-label": property("label", undefined),
+    });
+}
+/**
+ * Renders a labelled ARIA group inside menu content.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @example
+ * ```ts
+ * import * as Menu from "@typed/ui/Menu";
+ *
+ * const view = Menu.Group({ label: "View", content: "Choices" });
+ * ```
+ * @since 1.0.0
+ * @category Command grouping
+ */
+export function Group(options, host) {
+    return Dom.renderHost()(options, host, groupProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+/**
+ * Consumer-facing alias of the canonical Menu component with identical behavior and lifetime.
+ *
+ * @remarks
+ * The alias acquires nothing. Rendering it has exactly the canonical component's Scope and DOM
+ * ownership contract.
+ *
+ * @since 1.0.0
+ * @category Commands
+ */
+export const Dismiss = Item;
+function separatorProps(_options) {
+    return ({ property }) => ({
+        role: "separator",
+        "aria-orientation": property("orientation", "horizontal"),
+    });
+}
+/**
+ * Renders a separator with explicit horizontal or vertical orientation.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @example
+ * ```ts
+ * import * as Menu from "@typed/ui/Menu";
+ *
+ * const view = Menu.Separator({ orientation: "horizontal" });
+ * ```
+ * @since 1.0.0
+ * @category Command grouping
+ */
+export function Separator(options, host) {
+    return Dom.renderHost()(options, host, separatorProps(options), "", (props) => html `<hr ...${props} />`);
+}