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

package/dist/Listbox.js

@@ -0,0 +1,316 @@
+/**
+ * Listbox separates active and selected values, registers options in a Collection, and combines
+ * vertical keyboard movement with buffered typeahead. It supports roving focus by default and uses
+ * real focus, keydown, and click 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.
+ *
+ * @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 { EventHandler, html, } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Composite from "./Composite.js";
+import * as Dom from "./Dom.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Listbox 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 Listbox from "@typed/ui/Listbox";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Listbox.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    value: Schema.NullOr(Schema.String),
+    activeId: Schema.NullOr(Schema.String),
+    orientation: Schema.Literals(["vertical"]),
+    loop: Schema.Boolean,
+    rtl: Schema.Boolean,
+    virtualFocus: Schema.Boolean,
+});
+/**
+ * Creates hydrated Listbox state. value and activeId default to null, loop defaults to true, and
+ * roving focus is used.
+ *
+ * @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 Listbox from "@typed/ui/Listbox";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Listbox.makeState({});
+ *     const collection = yield* Listbox.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial = {}) {
+    return RefSubject.hydrate(StateSchema, {
+        value: initial.value ?? null,
+        activeId: initial.activeId ?? null,
+        orientation: "vertical",
+        loop: initial.loop ?? true,
+        rtl: false,
+        virtualFocus: false,
+    });
+}
+/**
+ * Creates a scoped Collection for Listbox items.
+ *
+ * @remarks
+ * ## Why
+ *
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * 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 Listbox from "@typed/ui/Listbox";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Listbox.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Sets both activeId and selected value in one update.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Listbox'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 { select } from "@typed/ui/Listbox";` Extend the [Listbox.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FListbox%23makeState). Inside the linked Effect program invoke
+ * `yield* select(state, "nyc", "New York")`, then read state to observe selection and active focus
+ * update together.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function select(state, id, value) {
+    return RefSubject.update(state, (current) => ({ ...current, activeId: id, value }));
+}
+/**
+ * Moves through the registered options, synchronizes value when the target has one, then focuses
+ * and scrolls the active option.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Listbox'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/Listbox";` Extend the [Listbox.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FListbox%23makeState). Inside the linked Effect program invoke
+ * `yield* move(state, collection, "next")`, then read the state snapshot to observe the transition
+ * described above.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function move(state, collection, direction) {
+    return Effect.gen(function* () {
+        const current = yield* state;
+        const items = yield* collection;
+        const activeId = Composite.moveActiveId(items, current, direction);
+        const item = activeId === null ? undefined : items.find((item) => item.id === activeId);
+        const next = yield* RefSubject.update(state, (value) => ({
+            ...value,
+            activeId,
+            value: item?.value ?? value.value,
+        }));
+        yield* Composite.focusActive({ state, collection });
+        yield* Composite.scrollActive({ state, collection });
+        return next;
+    });
+}
+function rootProps(options) {
+    let typeahead = { value: "", updatedAt: 0 };
+    const onfocus = options.collection === undefined
+        ? undefined
+        : Effect.gen(function* () {
+            const current = yield* options.state;
+            if (current.activeId !== null)
+                return;
+            const item = Composite.moveActiveItem(yield* options.collection, current, "first");
+            if (item?.value === undefined)
+                return;
+            yield* select(options.state, item.id, item.value);
+            yield* Composite.focusActive({ state: options.state, collection: options.collection });
+            yield* Composite.scrollActive({ state: options.state, collection: options.collection });
+        });
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn(function* (event) {
+            const key = Composite.typeaheadKey(event);
+            if (key !== null) {
+                typeahead = Composite.updateTypeaheadBuffer(typeahead, key, Date.now());
+                const id = Composite.typeaheadFrom(yield* options.collection, typeahead.value, (yield* options.state).activeId);
+                if (id !== null) {
+                    event.preventDefault();
+                    const item = (yield* options.collection).find((item) => item.id === id);
+                    if (item?.value !== undefined)
+                        yield* select(options.state, item.id, item.value);
+                    yield* Composite.focusActive({
+                        state: options.state,
+                        collection: options.collection,
+                    });
+                }
+                return;
+            }
+            const direction = Composite.keyMove(event, { orientation: "vertical" });
+            if (direction !== undefined) {
+                event.preventDefault();
+                yield* move(options.state, options.collection, direction);
+            }
+        }));
+    return ({ property }) => ({
+        role: "listbox",
+        "aria-label": property("label", undefined),
+        "aria-activedescendant": Composite.activeDescendant(options.state),
+        tabindex: Composite.rootTabIndex(options.state),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the listbox root, initializes selection on focus, and handles vertical movement and
+ * typeahead in DOM order.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The component applies the family behavior while leaving callers free to supply a custom host
+ * through the shared DOM boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * 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
+ *
+ * Import with `import { Root } from "@typed/ui/Listbox";` Extend the [Listbox.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FListbox%23makeState). Replace the linked program's final
+ * snapshot read with `Root({ state, label: "City", content: "Options" })`; render that Fx before
+ * the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Root(options, host) {
+    return Dom.renderHost()(options, host, rootProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function optionProps(options) {
+    const selected = RefSubject.map(options.state, (state) => state.value === options.value);
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.value,
+            textValue: options.textValue ?? options.value,
+            disabled: options.disabled,
+        });
+    return () => ({
+        id: options.id,
+        role: "option",
+        "aria-selected": selected,
+        "aria-disabled": options.disabled ?? false,
+        tabindex: Composite.tabIndex(options.state, options.id),
+        onclick: options.disabled === true ? Effect.void : select(options.state, options.id, options.value),
+        onfocus: options.disabled === true ? Effect.void : select(options.state, options.id, options.value),
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers an option; focus or click selects it unless disabled.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The component applies the family behavior while leaving callers free to supply a custom host
+ * through the shared DOM boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * 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
+ *
+ * Import with `import { Option } from "@typed/ui/Listbox";` Extend the [Listbox.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FListbox%23makeState). Replace the linked program's final
+ * snapshot read with `Option({ state, id: "nyc", value: "New York", content: "New York" })`; render
+ * that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Option(options, host) {
+    return Dom.renderHost()(options, host, optionProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}