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

package/dist/Tabs.js

@@ -0,0 +1,346 @@
+/**
+ * Tabs separates active focus from selected tab and supports automatic or manual activation. List
+ * handles orientation-aware movement; Tab publishes stable aria-controls state; Panel retains its
+ * node while hidden.
+ *
+ * @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 Tabs 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 Tabs from "@typed/ui/Tabs";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Tabs.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    selectedId: Schema.String,
+    activeId: Schema.String,
+    activationMode: Schema.Literals(["automatic", "manual"]),
+    orientation: Schema.Literals(["horizontal", "vertical"]),
+    loop: Schema.Boolean,
+    rtl: Schema.Boolean,
+    virtualFocus: Schema.Boolean,
+});
+/**
+ * Creates hydrated Tabs state. The caller supplies value; activeId defaults to value, activation
+ * is automatic, orientation horizontal, and loop true.
+ *
+ * @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 Tabs from "@typed/ui/Tabs";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Tabs.makeState({ selectedId: "overview" });
+ *     const collection = yield* Tabs.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial) {
+    return RefSubject.hydrate(StateSchema, {
+        selectedId: initial.selectedId,
+        activeId: initial.activeId ?? initial.selectedId,
+        activationMode: initial.activationMode ?? "automatic",
+        orientation: initial.orientation ?? "horizontal",
+        loop: initial.loop ?? true,
+        rtl: initial.rtl ?? false,
+        virtualFocus: false,
+    });
+}
+/**
+ * Creates a scoped Collection for Tabs 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 Tabs from "@typed/ui/Tabs";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Tabs.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Selects a tab and makes it the active roving-focus item.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Tabs'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/Tabs";` Extend the [Tabs.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTabs%23makeState). Inside the linked Effect program invoke
+ * `yield* select(state, "settings")`, then read state to observe both `selectedId` and `activeId`
+ * become `"settings"`.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function select(state, selectedId) {
+    return RefSubject.update(state, (current) => ({ ...current, activeId: selectedId, selectedId }));
+}
+/**
+ * Moves activeId through registered tabs without selecting under manual activation.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Tabs'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/Tabs";` Extend the [Tabs.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTabs%23makeState). Inside the linked Effect program invoke
+ * `yield* move(state, yield* collection, "next")`, then read state to observe focus move—and, in
+ * automatic mode, selection move—to the next enabled tab.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function move(state, items, direction) {
+    return Effect.gen(function* () {
+        const current = yield* state;
+        const activeId = Composite.moveActiveId(items, current, direction);
+        if (activeId === null)
+            return current;
+        return yield* RefSubject.update(state, (value) => ({
+            ...value,
+            activeId,
+            selectedId: value.activationMode === "automatic" ? activeId : value.selectedId,
+        }));
+    });
+}
+function moveAndFocus(state, collection, direction) {
+    return Effect.gen(function* () {
+        const next = yield* move(state, yield* collection, direction);
+        yield* Composite.focusActive({ state, collection });
+        yield* Composite.scrollActive({ state, collection });
+        return next;
+    });
+}
+function listInternalProps(options) {
+    const orientation = RefSubject.map(options.state, (state) => state.orientation);
+    const onkeydown = options.collection === undefined && options.items === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn(function* (event) {
+            const direction = Composite.keyMove(event, yield* options.state);
+            if (direction !== undefined) {
+                event.preventDefault();
+                if (options.collection !== undefined) {
+                    yield* moveAndFocus(options.state, options.collection, direction);
+                }
+                else {
+                    yield* move(options.state, options.items, direction);
+                }
+                return;
+            }
+            if ((event.key === "Enter" || event.key === " ") &&
+                (yield* options.state).activationMode === "manual") {
+                event.preventDefault();
+                yield* select(options.state, (yield* options.state).activeId);
+            }
+        }));
+    return ({ property }) => ({
+        role: "tablist",
+        "aria-label": property("label", undefined),
+        "aria-orientation": orientation,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the tablist and applies orientation-aware movement plus Enter/Space activation in manual
+ * mode.
+ *
+ * @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 { List } from "@typed/ui/Tabs";` Extend the [Tabs.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTabs%23makeState). Replace the linked program's final snapshot
+ * read with `List({ state, label: "Account", content: "Tabs" })`; render that Fx before the same
+ * Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function List(options, host) {
+    return Dom.renderHost()(options, host, listInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function tabInternalProps(options) {
+    const selected = RefSubject.map(options.state, (state) => state.selectedId === options.id);
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.id,
+            textValue: options.id,
+            disabled: options.disabled,
+        });
+    return () => ({
+        id: options.id,
+        type: "button",
+        role: "tab",
+        "aria-controls": options.panelId,
+        "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),
+        onfocus: options.disabled === true
+            ? Effect.void
+            : RefSubject.update(options.state, (state) => state.activationMode === "automatic"
+                ? { ...state, activeId: options.id, selectedId: options.id }
+                : { ...state, activeId: options.id }),
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers a tab with stable aria-controls, selected state, and roving
+ * tabindex.
+ *
+ * @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 { Tab } from "@typed/ui/Tabs";` Extend the [Tabs.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTabs%23makeState). Replace the linked program's final snapshot
+ * read with `Tab({ state, id: "overview", panelId: "overview-panel", content: "Overview" })`;
+ * render that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Tab(options, host) {
+    return Dom.renderHost()(options, host, tabInternalProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+function panelInternalProps(options) {
+    const selected = RefSubject.map(options.state, (state) => state.selectedId === options.tabId);
+    return () => ({
+        id: options.id,
+        role: "tabpanel",
+        "aria-labelledby": options.tabId,
+        tabindex: 0,
+        "?hidden": RefSubject.map(selected, (value) => !value),
+    });
+}
+/**
+ * Renders a labelled tabpanel and hides it reactively when its tab is not selected.
+ *
+ * @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 { Panel } from "@typed/ui/Tabs";` Extend the [Tabs.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTabs%23makeState). Replace the linked program's final snapshot
+ * read with `Panel({ state, id: "overview-panel", tabId: "overview", content: "Account overview"
+ * })`; render that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Panel(options, host) {
+    return Dom.renderHost()(options, host, panelInternalProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}