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

package/dist/TreeGrid.js

@@ -0,0 +1,420 @@
+/**
+ * TreeGrid combines tree expansion with virtual-focus grid movement. Rows carry hierarchy and
+ * expansion, cells carry column positions, and the root retains focus while aria-activedescendant
+ * identifies the active cell.
+ *
+ * @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 { RefSubject } from "@typed/fx";
+import { EventHandler, html, } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Dom from "./Dom.js";
+import * as Grid from "./Grid.js";
+import * as Tree from "./Tree.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate TreeGrid 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 TreeGrid from "@typed/ui/TreeGrid";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(TreeGrid.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Tree.StateSchema;
+/**
+ * Creates hydrated TreeGrid state. Uses Tree state and defaults.
+ *
+ * @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 TreeGrid from "@typed/ui/TreeGrid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* TreeGrid.makeState({});
+ *     const collection = yield* TreeGrid.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeState = Tree.makeState;
+/**
+ * Tests membership in expandedIds without touching the DOM; this is the Tree helper exposed from
+ * the TreeGrid entrypoint.
+ *
+ * @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 TreeGrid from "@typed/ui/TreeGrid";
+ *
+ * const expanded = TreeGrid.isExpanded({ activeId: null, expandedIds: ["parent"], loop: true }, "parent");
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export const isExpanded = Tree.isExpanded;
+/**
+ * Adds a row id once to expandedIds using the Tree state transition.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes TreeGrid'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/TreeGrid";` Extend the [TreeGrid.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Inside the linked Effect
+ * program run `yield* expand(state, "parent")`, then read state to observe the id in expandedIds.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const expand = Tree.expand;
+/**
+ * Removes a row id from expandedIds using the Tree state transition.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes TreeGrid'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/TreeGrid";` Extend the [TreeGrid.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Inside the linked Effect
+ * program run `yield* collapse(state, "parent")`, then read state to observe the id removed from
+ * expandedIds.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const collapse = Tree.collapse;
+/**
+ * Sets the active TreeGrid row or cell id without changing expansion.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes TreeGrid'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/TreeGrid";` Extend the [TreeGrid.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Inside the linked Effect
+ * program run `yield* activate(state, "cell-1")`, then read state to observe activeId.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const activate = Tree.activate;
+/**
+ * Creates a scoped Collection for TreeGrid 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 TreeGrid from "@typed/ui/TreeGrid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* TreeGrid.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+function rootInternalProps(options) {
+    const onfocus = options.collection === undefined
+        ? undefined
+        : Effect.gen(function* () {
+            const current = yield* options.state;
+            if (current.activeId !== null)
+                return;
+            const first = visibleItems(yield* options.collection, current)[0];
+            if (first !== undefined)
+                yield* activate(options.state, first.id);
+        });
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn((event) => onKeyDown(options.state, options.collection, event)));
+    return ({ property }) => ({
+        role: "treegrid",
+        tabindex: 0,
+        "aria-label": property("label", undefined),
+        "aria-activedescendant": RefSubject.map(options.state, (state) => state.activeId ?? undefined),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the focus-owning treegrid root and applies combined grid and expansion keys.
+ *
+ * @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/TreeGrid";` Extend the [TreeGrid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Replace the linked program's final
+ * snapshot read with `Root({ state, label: "Files", content: "Rows" })`; 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 rowInternalProps(options) {
+    const hasChildren = options.hasChildren ?? false;
+    return ({ property }) => ({
+        id: options.rowId,
+        role: "row",
+        "aria-level": property("level", 1),
+        "aria-expanded": hasChildren
+            ? RefSubject.map(options.state, (state) => isExpanded(state, options.rowId))
+            : undefined,
+    });
+}
+/**
+ * Renders a hierarchical row with level and optional expanded 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 { Row } from "@typed/ui/TreeGrid";` Extend the [TreeGrid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Replace the linked program's final
+ * snapshot read with `Row({ state, rowId: "src", content: "Cells" })`; render that Fx before the
+ * same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Row(options, host) {
+    return Dom.renderHost()(options, host, rowInternalProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function cellInternalProps(options) {
+    const active = RefSubject.map(options.state, (state) => state.activeId === options.id);
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: {
+                rowId: options.rowId,
+                columnIndex: options.columnIndex,
+                parentId: options.parentId,
+                hasChildren: options.hasChildren ?? false,
+            },
+            textValue: options.id,
+        });
+    return () => ({
+        id: options.id,
+        role: "gridcell",
+        "aria-colindex": options.columnIndex,
+        "?data-active": active,
+        ref: register,
+    });
+}
+/**
+ * Renders and optionally registers one gridcell with row and column coordinates.
+ *
+ * @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 { Cell } from "@typed/ui/TreeGrid";` Extend the [TreeGrid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Replace the linked program's final
+ * snapshot read with `Cell({ state, id: "src-name", rowId: "src", columnIndex: 1, content: "src"
+ * })`; render that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Cell(options, host) {
+    return Dom.renderHost()(options, host, cellInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function groupInternalProps(options) {
+    return () => ({
+        role: "rowgroup",
+        "?hidden": RefSubject.map(options.state, (state) => !isExpanded(state, options.parentId)),
+    });
+}
+/**
+ * Renders a rowgroup and hides it while its parent row is collapsed.
+ *
+ * @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/TreeGrid";` Extend the [TreeGrid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FTreeGrid%23makeState). Replace the linked program's final
+ * snapshot read with `Group({ state, parentId: "src", content: "Rows" })`; 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 all = yield* collection;
+        const visible = visibleItems(all, current);
+        const active = current.activeId === null ? undefined : all.find((item) => item.id === current.activeId);
+        const activeValue = active?.value;
+        if (activeValue?.columnIndex === 1 &&
+            (event.key === "ArrowRight" || event.key === "ArrowLeft")) {
+            if (event.key === "ArrowRight" && activeValue.hasChildren) {
+                event.preventDefault();
+                if (!isExpanded(current, activeValue.rowId))
+                    return yield* expand(state, activeValue.rowId);
+                const child = visible.find((item) => item.value?.parentId === activeValue.rowId && item.value?.columnIndex === 1);
+                return child === undefined ? current : yield* activate(state, child.id);
+            }
+            if (event.key === "ArrowLeft") {
+                event.preventDefault();
+                if (activeValue.hasChildren && isExpanded(current, activeValue.rowId))
+                    return yield* collapse(state, activeValue.rowId);
+                const parent = activeValue.parentId === undefined
+                    ? undefined
+                    : visible.find((item) => item.value?.rowId === activeValue.parentId && item.value?.columnIndex === 1);
+                return parent === undefined ? current : yield* activate(state, parent.id);
+            }
+        }
+        const next = Grid.moveActiveId(visible, current.activeId, event);
+        if (next === undefined)
+            return current;
+        event.preventDefault();
+        return yield* activate(state, next);
+    });
+}
+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.value?.rowId === parentId)?.value?.parentId;
+        }
+        return true;
+    });
+}

package/dist/VisuallyHidden.d.ts

@@ -0,0 +1,54 @@
+import type * as Scope from "effect/Scope";
+import type { Fx } from "@typed/fx/Fx";
+import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * Options for content hidden visually but retained for assistive technology.
+ * @remarks
+ * ## Why
+ * Some controls need an accessible name or instruction that should not alter
+ * the visual layout.
+ * ## Ownership and lifetime
+ * The options are inert; dynamic content follows the rendered Scope.
+ * @since 1.0.0
+ * @category models
+ */
+export interface VisuallyHiddenOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /** Content retained in the document and accessibility tree.
+     * @remarks
+     * ## Why
+     * Unlike `hidden` or `display: none`, clipped content remains perceivable to
+     * screen readers.
+     * ## Ownership and lifetime
+     * Dynamic content is released when the component Scope closes.
+     * @since 1.0.0
+     * @category content
+     */
+    readonly content: Renderable.Any;
+}
+declare function internalProps(): {
+    style: string;
+};
+type VisuallyHiddenInternalProps = ReturnType<typeof internalProps>;
+/**
+ * Renders screen-reader-accessible content with standard clipping styles.
+ * @remarks
+ * ## Why
+ * The primitive supplies a tested visual-hiding recipe without removing the
+ * node from semantic layout or the accessibility tree.
+ * ## Ownership and lifetime
+ * Running the Fx owns the rendered span and dynamic content in its Effect
+ * Scope. A custom host must preserve the supplied clipping styles.
+ * @example
+ * ```ts
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden"
+ *
+ * const label = VisuallyHidden({ content: "Open navigation" })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function VisuallyHidden<const Options extends VisuallyHiddenOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, VisuallyHiddenInternalProps>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+export {};
+//# sourceMappingURL=VisuallyHidden.d.ts.map

package/dist/VisuallyHidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VisuallyHidden.d.ts","sourceRoot":"","sources":["../src/VisuallyHidden.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAKjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAsB,SAAQ,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC;IAC7E;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED,iBAAS,aAAa;;EAErB;AAED,KAAK,2BAA2B,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,CAAC,OAAO,SAAS,qBAAqB,EAC3C,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAErC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,2BAA2B,CAAC,EACzD,OAAO,CAAC,SAAS,CAAC,EAClB,IAAI,CACL,GACA,EAAE,CACH,WAAW,EACX,UAAU,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAChC,UAAU,CAAC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,cAAc,CACnE,CAQA"}

package/dist/VisuallyHidden.js

@@ -0,0 +1,27 @@
+import { html } from "@typed/template";
+import * as Dom from "./Dom.js";
+const style = "border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;white-space:nowrap;width:1px";
+function internalProps() {
+    return { style };
+}
+/**
+ * Renders screen-reader-accessible content with standard clipping styles.
+ * @remarks
+ * ## Why
+ * The primitive supplies a tested visual-hiding recipe without removing the
+ * node from semantic layout or the accessibility tree.
+ * ## Ownership and lifetime
+ * Running the Fx owns the rendered span and dynamic content in its Effect
+ * Scope. A custom host must preserve the supplied clipping styles.
+ * @example
+ * ```ts
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden"
+ *
+ * const label = VisuallyHidden({ content: "Open navigation" })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function VisuallyHidden(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<span ...${props}>${content}</span>`);
+}