@typed/ui 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/Composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composite.d.ts","sourceRoot":"","sources":["../src/Composite.ts"],"names":[],"mappings":"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"}

package/dist/Composite.js

@@ -0,0 +1,615 @@
+/**
+ * Composite contains the reusable policy behind roving tabindex and virtual focus. Its pure
+ * helpers define orientation, RTL, wrapping, disabled-item, typeahead, and DOM-order rules; Effect
+ * helpers perform focus and scrolling only when run.
+ *
+ * @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.
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { RefSubject } from "@typed/fx";
+import * as Collection from "./Collection.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Composite state.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A public schema makes hydration and serialized state use the same runtime validation as direct
+ * construction.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration is data or schema metadata and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Composite.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    activeId: Schema.NullOr(Schema.String),
+    orientation: Schema.Literals(["horizontal", "vertical", "both"]),
+    loop: Schema.Boolean,
+    rtl: Schema.Boolean,
+    virtualFocus: Schema.Boolean,
+});
+/**
+ * Creates hydrated Composite state. activeId defaults to null, orientation to horizontal, loop to
+ * true, RTL and virtual focus to false.
+ *
+ * @remarks
+ * ## Why
+ *
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * 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 Collection from "@typed/ui/Collection";
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Composite.makeState({});
+ *     const collection = yield* Collection.makeState<string>();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial = {}) {
+    return RefSubject.hydrate(StateSchema, {
+        activeId: initial.activeId ?? null,
+        orientation: initial.orientation ?? "horizontal",
+        loop: initial.loop ?? true,
+        rtl: initial.rtl ?? false,
+        virtualFocus: initial.virtualFocus ?? false,
+    });
+}
+/**
+ * Computes the next active id and updates state; collection and state failures/services are
+ * preserved in the returned Effect.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { move } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program invoke `yield* move({ state, collection }, "next")`, then read state to observe the next
+ * enabled registered id selected under the current loop policy.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function move(options, direction) {
+    return Effect.gen(function* () {
+        const current = yield* options.state;
+        const activeId = moveActiveId(yield* options.collection, current, direction, options.includeDisabled);
+        return yield* RefSubject.update(options.state, (state) => ({ ...state, activeId }));
+    });
+}
+/**
+ * Derives 0 only for the active item under roving focus; virtual-focus items always receive -1.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Creating the Computed value acquires nothing eagerly. The Scope that subscribes to it owns
+ * observation of the source RefSubject.
+ *
+ * ## Example
+ *
+ * Import with `import { tabIndex } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program read `const value = yield* tabIndex(state, "item-2")`; it is `0` only while that item
+ * owns roving focus and is `-1` under virtual focus.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function tabIndex(state, id) {
+    return RefSubject.map(state, (current) => current.virtualFocus ? -1 : current.activeId === id ? 0 : -1);
+}
+/**
+ * Derives activeId only under virtual focus, otherwise undefined.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Creating the Computed value acquires nothing eagerly. The Scope that subscribes to it owns
+ * observation of the source RefSubject.
+ *
+ * ## Example
+ *
+ * Import with `import { activeDescendant } from "@typed/ui/Composite";` Extend the
+ * [Composite.makeState runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside
+ * the linked Effect program read `const id = yield* activeDescendant(state)`; it is the active id
+ * only under virtual focus and otherwise `undefined`.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function activeDescendant(state) {
+    return RefSubject.map(state, (current) => current.virtualFocus && current.activeId ? current.activeId : undefined);
+}
+/**
+ * Derives 0 when the root owns focus and -1 once a roving-focus item is active.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Creating the Computed value acquires nothing eagerly. The Scope that subscribes to it owns
+ * observation of the source RefSubject.
+ *
+ * ## Example
+ *
+ * Import with `import { rootTabIndex } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program read `const value = yield* rootTabIndex(state)`; it is `0` while the root owns focus and
+ * `-1` after a roving-focus item becomes active.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function rootTabIndex(state) {
+    return RefSubject.map(state, (current) => current.virtualFocus || current.activeId === null ? 0 : -1);
+}
+/**
+ * Maps Home/End and orientation-aware Arrow keys to movement, reversing horizontal arrows for RTL.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const direction = Composite.keyMove({ key: "ArrowLeft" }, { orientation: "horizontal", rtl: true });
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function keyMove(event, options) {
+    if (event.key === "Home")
+        return "first";
+    if (event.key === "End")
+        return "last";
+    const orientation = options.orientation ?? "horizontal";
+    const rtl = options.rtl ?? false;
+    if (orientation !== "vertical" && event.key === "ArrowRight")
+        return rtl ? "previous" : "next";
+    if (orientation !== "vertical" && event.key === "ArrowLeft")
+        return rtl ? "next" : "previous";
+    if (orientation !== "horizontal" && event.key === "ArrowDown")
+        return "next";
+    if (orientation !== "horizontal" && event.key === "ArrowUp")
+        return "previous";
+    return undefined;
+}
+/**
+ * Prevents the native key default only when keyMove recognizes the key, then updates active state.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { moveByKey } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program run `yield* moveByKey({ key: "ArrowDown" }, { state, collection })`, then read state to
+ * observe the active id selected by the current orientation and RTL policy.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function moveByKey(event, options) {
+    return Effect.gen(function* () {
+        const direction = keyMove(event, yield* options.state);
+        if (direction === undefined)
+            return false;
+        event.preventDefault?.();
+        yield* move(options, direction);
+        return true;
+    });
+}
+/**
+ * Moves active state, then focuses and scrolls the mounted active item when virtual focus is
+ * disabled.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { moveAndFocus } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program run `yield* moveAndFocus({ state, collection }, "next")`; the returned state names the
+ * next id and its registered element receives native focus.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function moveAndFocus(options, direction) {
+    return Effect.tap(move(options, direction), Effect.andThen(focusActive(options), scrollActive(options)));
+}
+/**
+ * Focuses the registered active element unless state uses virtual focus or has no active id.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { focusActive } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program run `yield* focusActive({ state, collection })`; the active registered element receives
+ * native focus, with no state transition when no matching element exists.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function focusActive(options) {
+    return Effect.gen(function* () {
+        const state = yield* options.state;
+        if (state.virtualFocus || state.activeId === null)
+            return;
+        const item = (yield* options.collection).find((item) => item.id === state.activeId);
+        yield* focusElement(item?.element);
+    });
+}
+/**
+ * Calls an existing platform focus method inside Effect.sync and otherwise does nothing.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const focused = Composite.focusElement(document.querySelector("button") ?? undefined);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function focusElement(element) {
+    return Effect.sync(() => {
+        const focus = element === undefined ? undefined : Reflect.get(element, "focus");
+        if (typeof focus === "function")
+            focus.call(element);
+    });
+}
+/**
+ * Calls scrollIntoView with nearest block/inline alignment for the mounted active item.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Composite's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { scrollActive } from "@typed/ui/Composite";` Extend the [Composite.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Inside the linked Effect
+ * program run `yield* scrollActive({ state, collection })`; the active registered element receives
+ * `scrollIntoView({ block: "nearest", inline: "nearest" })` when that method is available.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function scrollActive(options) {
+    return Effect.gen(function* () {
+        const activeId = (yield* options.state).activeId;
+        if (activeId === null)
+            return;
+        const element = (yield* options.collection).find((item) => item.id === activeId)?.element;
+        const scrollIntoView = element === undefined ? undefined : Reflect.get(element, "scrollIntoView");
+        if (typeof scrollIntoView === "function") {
+            scrollIntoView.call(element, { block: "nearest", inline: "nearest" });
+        }
+    });
+}
+/**
+ * Returns the first enabled item id in DOM order whose textValue starts with the query.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const id = Composite.typeahead([{ id: "alpha", textValue: "Alpha" }], "al");
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function typeahead(items, search, text = (item) => item.textValue ?? item.id, includeDisabled = false) {
+    return typeaheadFrom(items, search, null, text, includeDisabled);
+}
+/**
+ * Returns only the id selected by typeahead, or null when no item matches.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const id = Composite.typeaheadFrom([{ id: "alpha", textValue: "Alpha" }], "al", null);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function typeaheadFrom(items, search, activeId, text = (item) => item.textValue ?? item.id, includeDisabled = false) {
+    const query = search.trim().toLocaleLowerCase();
+    if (query.length === 0)
+        return null;
+    const enabled = orderedItems(items, includeDisabled);
+    const index = activeId === null ? -1 : enabled.findIndex((item) => item.id === activeId);
+    const ordered = index === -1 ? enabled : [...enabled.slice(index + 1), ...enabled.slice(0, index + 1)];
+    const item = ordered.find((item) => text(item).toLocaleLowerCase().startsWith(query));
+    return item?.id ?? null;
+}
+/**
+ * Returns an unmodified one-character key exactly as provided; modified and multi-character keys
+ * return null.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const key = Composite.typeaheadKey({ key: "A" });
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function typeaheadKey(event) {
+    if (event.altKey || event.ctrlKey || event.metaKey)
+        return null;
+    return event.key.length === 1 ? event.key : null;
+}
+/**
+ * Appends within the timeout window and starts a new query after the buffer expires.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const buffer = Composite.updateTypeaheadBuffer({ value: "a", updatedAt: 100 }, "b", 200);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function updateTypeaheadBuffer(buffer, key, now, timeout = 500) {
+    return {
+        value: now - buffer.updatedAt > timeout ? key : buffer.value + key,
+        updatedAt: now,
+    };
+}
+/**
+ * Sorts a copy by mounted DOM order and then removes disabled items.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const items = Composite.orderedEnabledItems([{ id: "a" }, { id: "b", disabled: true }]);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function orderedEnabledItems(items) {
+    return Collection.enabledItems(Collection.byDomOrder(items));
+}
+/**
+ * Returns the id reached by first/last/next/previous with optional disabled inclusion and loop
+ * policy.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const id = Composite.moveActiveId([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function moveActiveId(items, state, direction, includeDisabled = false) {
+    return moveActiveItem(items, state, direction, includeDisabled)?.id ?? null;
+}
+/**
+ * Returns the full item selected by moveActiveId, or undefined when no item is reachable.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Composite from "@typed/ui/Composite";
+ *
+ * const item = Composite.moveActiveItem([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function moveActiveItem(items, state, direction, includeDisabled = false) {
+    const enabled = orderedItems(items, includeDisabled);
+    if (enabled.length === 0)
+        return undefined;
+    if (direction === "first")
+        return enabled[0];
+    if (direction === "last")
+        return enabled[enabled.length - 1];
+    const index = activeIndex(enabled, state.activeId, direction, state.loop);
+    return enabled[index];
+}
+function orderedItems(items, includeDisabled) {
+    return includeDisabled ? Collection.byDomOrder(items) : orderedEnabledItems(items);
+}
+function activeIndex(items, activeId, direction, loop) {
+    if (activeId === null)
+        return direction === "previous" && loop ? items.length - 1 : 0;
+    const current = items.findIndex((item) => item.id === activeId);
+    if (current === -1)
+        return direction === "previous" && loop ? items.length - 1 : 0;
+    const index = current;
+    const delta = direction === "next" ? 1 : -1;
+    const next = index + delta;
+    if (loop)
+        return (next + items.length) % items.length;
+    return Math.min(Math.max(next, 0), items.length - 1);
+}