@typed/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/TreeGrid.js

@@ -0,0 +1,308 @@
+/**
+ * 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.
+ *
+ * Learn the interaction in the [TreeGrid guide](/explore/ui-tree-grid).
+ *
+ * @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
+ * @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 Hierarchy and cell focus
+ */
+export const StateSchema = Tree.StateSchema;
+/**
+ * Creates hydrated TreeGrid state. Uses Tree state and defaults.
+ *
+ * @remarks
+ * 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 Hierarchy and cell focus
+ */
+export const makeState = Tree.makeState;
+/**
+ * Tests membership in expandedIds without touching the DOM; this is the Tree helper exposed from
+ * the TreeGrid entrypoint.
+ *
+ * @remarks
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * 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 Row expansion
+ */
+export const isExpanded = Tree.isExpanded;
+/**
+ * Adds a row id once to expandedIds using the Tree state transition.
+ *
+ * @remarks
+ * The operation exposes TreeGrid's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Row expansion
+ */
+export const expand = Tree.expand;
+/**
+ * Removes a row id from expandedIds using the Tree state transition.
+ *
+ * @remarks
+ * The operation exposes TreeGrid's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Row expansion
+ */
+export const collapse = Tree.collapse;
+/**
+ * Sets the active TreeGrid row or cell id without changing expansion.
+ *
+ * @remarks
+ * The operation exposes TreeGrid's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Hierarchy and cell focus
+ */
+export const activate = Tree.activate;
+/**
+ * Creates a scoped Collection for TreeGrid items.
+ *
+ * @remarks
+ * 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 Cell registration
+ */
+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
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Treegrid surface
+ */
+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
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Hierarchical rows
+ */
+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
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Navigable cells
+ */
+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
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Child row visibility
+ */
+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,68 @@
+/**
+ * Text clipped visually but retained for accessible names and descriptions.
+ * The clipping style has no focus-reveal behavior and must not hide interactive descendants.
+ *
+ * Read the [VisuallyHidden guide](/explore/ui-visually-hidden) for a complete example.
+ *
+ * [Platform reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
+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";
+/**
+ */
+export interface VisuallyHiddenOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /**
+     * Content retained in the document and accessibility tree.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+}
+declare function internalProps(): {
+    style: string;
+};
+type VisuallyHiddenInternalProps = ReturnType<typeof internalProps>;
+/**
+ * Clips text visually while retaining it for accessible naming and reading.
+ *
+ * @remarks
+ * The span uses absolute positioning and a one-pixel clipping recipe. It has no focus-reveal
+ * behavior: do not hide interactive controls or use it alone as a skip link. An aria-hidden
+ * ancestor still removes its content from accessibility exposure. Custom hosts must preserve the
+ * supplied style.
+ *
+ * @example
+ * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/template";
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden";
+ *
+ * export const ResetCounter = component(function* () {
+ *   const count = yield* RefSubject.make(3);
+ *   return html`<div>
+ *     <p>Selected items: ${count}</p>
+ *     ${Button({
+ *     content: html`
+ *       <span aria-hidden="true">×</span>
+ *       ${VisuallyHidden({ content: "Clear selection" })}
+ *     `,
+ *     props: { class: "icon-action" },
+ *     onclick: RefSubject.set(count, 0),
+ *     })}
+ *   </div>`;
+ * });
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+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;;;;;;;;;;GAUG;AACH,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;GACG;AACH,MAAM,WAAW,qBAAsB,SAAQ,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC;IAC7E;;;;OAIG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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,44 @@
+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 };
+}
+/**
+ * Clips text visually while retaining it for accessible naming and reading.
+ *
+ * @remarks
+ * The span uses absolute positioning and a one-pixel clipping recipe. It has no focus-reveal
+ * behavior: do not hide interactive controls or use it alone as a skip link. An aria-hidden
+ * ancestor still removes its content from accessibility exposure. Custom hosts must preserve the
+ * supplied style.
+ *
+ * @example
+ * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/template";
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden";
+ *
+ * export const ResetCounter = component(function* () {
+ *   const count = yield* RefSubject.make(3);
+ *   return html`<div>
+ *     <p>Selected items: ${count}</p>
+ *     ${Button({
+ *     content: html`
+ *       <span aria-hidden="true">×</span>
+ *       ${VisuallyHidden({ content: "Clear selection" })}
+ *     `,
+ *     props: { class: "icon-action" },
+ *     onclick: RefSubject.set(count, 0),
+ *     })}
+ *   </div>`;
+ * });
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+export function VisuallyHidden(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<span ...${props}>${content}</span>`);
+}