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

package/dist/Tree.js

@@ -0,0 +1,434 @@
+/**
+ * Tree stores active item and expanded ids independently. Its key policy follows hierarchical tree
+ * navigation, while Item and Group expose explicit levels, expansion, and visibility without
+ * reconstructing nodes.
+ *
+ * @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 Tree 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 Tree from "@typed/ui/Tree";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Tree.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    activeId: Schema.NullOr(Schema.String),
+    expandedIds: Schema.Array(Schema.String),
+    loop: Schema.Boolean,
+});
+/**
+ * Creates hydrated Tree state. activeId defaults null and expandedIds defaults empty.
+ *
+ * @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 Tree from "@typed/ui/Tree";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Tree.makeState({});
+ *     const collection = yield* Tree.makeCollection();
+ *     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,
+        expandedIds: [...(initial.expandedIds ?? [])],
+        loop: initial.loop ?? true,
+    });
+}
+/**
+ * Creates a scoped Collection for Tree 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 Tree from "@typed/ui/Tree";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Tree.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Tests membership in expandedIds without touching the DOM.
+ *
+ * @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 Tree from "@typed/ui/Tree";
+ *
+ * const expanded = Tree.isExpanded({ activeId: null, expandedIds: ["parent"], loop: true }, "parent");
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function isExpanded(state, id) {
+    return state.expandedIds.includes(id);
+}
+/**
+ * Adds an id once to expandedIds.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Tree'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 { expand } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Inside the linked Effect program invoke
+ * `yield* expand(state, "item-2")`, then read the state snapshot to observe the transition
+ * described above.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function expand(state, id) {
+    return RefSubject.update(state, (current) => isExpanded(current, id) ? current : { ...current, expandedIds: [...current.expandedIds, id] });
+}
+/**
+ * Removes an id from expandedIds.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Tree'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 { collapse } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Inside the linked Effect program invoke
+ * `yield* collapse(state, "item-2")`, then read the state snapshot to observe the transition
+ * described above.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function collapse(state, id) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        expandedIds: current.expandedIds.filter((expanded) => expanded !== id),
+    }));
+}
+/**
+ * Sets the active tree item id without changing expansion.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Tree'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 { activate } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Inside the linked Effect program invoke
+ * `yield* activate(state, "item-2")`, then read the state snapshot to observe the transition
+ * described above.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function activate(state, activeId) {
+    return RefSubject.update(state, (current) => ({ ...current, activeId }));
+}
+function rootInternalProps(options) {
+    const onfocus = options.collection === undefined
+        ? undefined
+        : Effect.gen(function* () {
+            const current = yield* options.state;
+            if (current.activeId !== null)
+                return;
+            const first = Composite.moveActiveId(visibleItems(yield* options.collection, current), current, "first");
+            if (first === null)
+                return;
+            yield* activate(options.state, first);
+            yield* focusItem(options.collection, first);
+        });
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn((event) => onKeyDown(options.state, options.collection, event)));
+    return ({ property }) => ({
+        role: "tree",
+        "aria-label": property("label", undefined),
+        tabindex: RefSubject.map(options.state, (state) => (state.activeId === null ? 0 : -1)),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the tree root and applies hierarchy-aware keyboard navigation to registered items.
+ *
+ * @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/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
+ * read with `Root({ state, label: "Files", content: "Items" })`; render that Fx before the same
+ * Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Root(options, host) {
+    return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function itemInternalProps(options) {
+    const hasChildren = options.hasChildren ?? false;
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: { parentId: options.parentId, hasChildren },
+            textValue: options.id,
+            disabled: options.disabled,
+        });
+    return ({ property }) => ({
+        id: options.id,
+        role: "treeitem",
+        "aria-level": property("level", 1),
+        "aria-expanded": hasChildren
+            ? RefSubject.map(options.state, (state) => isExpanded(state, options.id))
+            : undefined,
+        "aria-disabled": options.disabled ?? false,
+        tabindex: RefSubject.map(options.state, (state) => (state.activeId === options.id ? 0 : -1)),
+        onfocus: activate(options.state, options.id),
+        onclick: options.disabled === true ? Effect.void : activate(options.state, options.id),
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers a treeitem with level, expanded, disabled, and roving-focus
+ * state.
+ *
+ * @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 { Item } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
+ * read with `Item({ state, id: "src", hasChildren: true, content: "src" })`; render that Fx before
+ * the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Item(options, host) {
+    return Dom.renderHost()(options, host, itemInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function groupInternalProps(options) {
+    return () => ({
+        role: "group",
+        "?hidden": RefSubject.map(options.state, (state) => !isExpanded(state, options.parentId)),
+    });
+}
+/**
+ * Renders a child group and hides it while its parent id is not expanded.
+ *
+ * @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 { Group } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
+ * read with `Group({ state, parentId: "src", content: "Children" })`; render that Fx before the
+ * same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Group(options, host) {
+    return Dom.renderHost()(options, host, groupInternalProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function onKeyDown(state, collection, event) {
+    return Effect.gen(function* () {
+        const current = yield* state;
+        const items = visibleItems(yield* collection, current);
+        if (event.key === "Enter" || event.key === " ") {
+            const active = current.activeId === null
+                ? undefined
+                : items.find((item) => item.id === current.activeId && item.disabled !== true);
+            const element = active?.element;
+            const click = element === undefined ? undefined : Reflect.get(element, "click");
+            if (typeof click === "function") {
+                event.preventDefault();
+                yield* Effect.sync(() => click.call(element));
+            }
+            return yield* state;
+        }
+        const direction = Composite.keyMove(event, { orientation: "vertical" });
+        if (direction !== undefined) {
+            event.preventDefault();
+            const next = Composite.moveActiveId(items, current, direction);
+            if (next === null)
+                return current;
+            yield* activate(state, next);
+            yield* focusItem(collection, next);
+            return yield* state;
+        }
+        const active = current.activeId === null
+            ? undefined
+            : (yield* collection).find((item) => item.id === current.activeId);
+        if (active === undefined)
+            return current;
+        const value = active.value;
+        if (event.key === "ArrowRight" && value?.hasChildren) {
+            event.preventDefault();
+            if (!isExpanded(current, active.id))
+                return yield* expand(state, active.id);
+            const child = items.find((item) => item.value?.parentId === active.id);
+            if (child === undefined)
+                return current;
+            yield* activate(state, child.id);
+            yield* focusItem(collection, child.id);
+            return yield* state;
+        }
+        if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            if (value?.hasChildren && isExpanded(current, active.id))
+                return yield* collapse(state, active.id);
+            if (value?.parentId === undefined)
+                return current;
+            yield* activate(state, value.parentId);
+            yield* focusItem(collection, value.parentId);
+            return yield* state;
+        }
+        return current;
+    });
+}
+function visibleItems(items, state) {
+    const ordered = Collection.byDomOrder(items);
+    return ordered.filter((item) => {
+        let parentId = item.value?.parentId;
+        while (parentId !== undefined) {
+            if (!isExpanded(state, parentId))
+                return false;
+            parentId = ordered.find((candidate) => candidate.id === parentId)?.value?.parentId;
+        }
+        return true;
+    });
+}
+function focusItem(collection, id) {
+    return Effect.flatMap(collection, (items) => Composite.focusElement(items.find((item) => item.id === id)?.element));
+}