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

package/dist/Grid.js

@@ -0,0 +1,379 @@
+/**
+ * Grid is a virtual-focus ARIA grid. The root retains DOM focus while the active cell id is
+ * exposed through aria-activedescendant; CellPosition supplies row and column coordinates for
+ * two-dimensional movement.
+ *
+ * @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 Dom from "./Dom.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Grid 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 Grid from "@typed/ui/Grid";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Grid.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({ activeId: Schema.NullOr(Schema.String) });
+/**
+ * Creates hydrated Grid state. activeId defaults to null.
+ *
+ * @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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Grid.makeState({});
+ *     const collection = yield* Grid.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 });
+}
+/**
+ * Creates a scoped Collection for Grid 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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Grid.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Sets activeId, including null to clear virtual focus.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Grid'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/Grid";` Extend the [Grid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FGrid%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* () {
+            if ((yield* options.state).activeId !== null)
+                return;
+            const first = Collection.byDomOrder(yield* options.collection)[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: "grid",
+        tabindex: 0,
+        "aria-label": property("label", undefined),
+        "aria-activedescendant": RefSubject.map(options.state, (state) => state.activeId ?? undefined),
+        "aria-multiselectable": property("multiselectable", false),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the focus-owning grid root and initializes the active cell from DOM order on first
+ * focus.
+ *
+ * @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/Grid";` Extend the [Grid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FGrid%23makeState). Replace the linked program's final snapshot
+ * read with `Root({ state, label: "Schedule", 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({ property, }) {
+    return { role: "row", "aria-rowindex": property("rowIndex", undefined) };
+}
+/**
+ * Renders an ARIA row and forwards an optional one-based aria-rowindex.
+ *
+ * @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
+ * ```ts
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const view = Grid.Row({ rowIndex: 1, content: "Cells" });
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Row(options, host) {
+    return Dom.renderHost()(options, host, rowInternalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function cellInternalProps(options, role) {
+    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 },
+            textValue: options.id,
+        });
+    return ({ property }) => ({
+        id: options.id,
+        role,
+        "aria-colindex": options.columnIndex,
+        "aria-rowindex": property("rowIndex", undefined),
+        "aria-selected": property("selected", undefined),
+        "?data-active": active,
+        ref: register,
+    });
+}
+function cell(options, host, role) {
+    return Dom.renderHost()(options, host, cellInternalProps(options, role), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+/**
+ * Renders and optionally registers a 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/Grid";` Extend the [Grid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FGrid%23makeState). Replace the linked program's final snapshot
+ * read with `Cell({ state, id: "r1c1", rowId: "r1", columnIndex: 1, content: "Monday" })`; render
+ * that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function Cell(options, host) {
+    return cell(options, host, "gridcell");
+}
+/**
+ * Renders the Cell contract with the columnheader role.
+ *
+ * @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 { ColumnHeader } from "@typed/ui/Grid";` Extend the [Grid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FGrid%23makeState). Replace the linked program's final snapshot
+ * read with `ColumnHeader({ state, id: "day", rowId: "headers", columnIndex: 1, content: "Day" })`;
+ * render that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function ColumnHeader(options, host) {
+    return cell(options, host, "columnheader");
+}
+/**
+ * Renders the Cell contract with the rowheader role.
+ *
+ * @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 { RowHeader } from "@typed/ui/Grid";` Extend the [Grid.makeState runnable
+ * setup](/reference/%40typed%2Fui%2FGrid%23makeState). Replace the linked program's final snapshot
+ * read with `RowHeader({ state, id: "week-1", rowId: "week-1", columnIndex: 1, content: "Week 1"
+ * })`; render that Fx before the same Scope closes.
+ * @since 1.0.0
+ * @category components
+ */
+export function RowHeader(options, host) {
+    return cell(options, host, "rowheader");
+}
+function onKeyDown(state, collection, event) {
+    return Effect.gen(function* () {
+        const items = Collection.byDomOrder(yield* collection);
+        const next = moveActiveId(items, (yield* state).activeId, event);
+        if (next === undefined)
+            return yield* state;
+        event.preventDefault();
+        return yield* activate(state, next);
+    });
+}
+/**
+ * Maps grid keys to a cell id: horizontal movement stays in-row, vertical movement stays
+ * in-column, and Ctrl+Home/End reaches grid endpoints.
+ *
+ * @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 Grid from "@typed/ui/Grid";
+ *
+ * const nextId = Grid.moveActiveId([{ id: "a", value: { rowId: "r1", columnIndex: 1 } }], "a", { key: "ArrowRight", ctrlKey: false });
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function moveActiveId(items, activeId, event) {
+    if (items.length === 0)
+        return undefined;
+    if (event.ctrlKey && event.key === "Home")
+        return items[0]?.id;
+    if (event.ctrlKey && event.key === "End")
+        return items.at(-1)?.id;
+    const active = activeId === null ? undefined : items.find((item) => item.id === activeId);
+    if (active === undefined || active.value === undefined)
+        return event.key === "Home" ? items[0]?.id : undefined;
+    const row = items.filter((item) => item.value?.rowId === active.value.rowId);
+    if (event.key === "ArrowLeft")
+        return row.at(Math.max(0, row.indexOf(active) - 1))?.id;
+    if (event.key === "ArrowRight")
+        return row.at(Math.min(row.length - 1, row.indexOf(active) + 1))?.id;
+    if (event.key === "Home")
+        return row[0]?.id;
+    if (event.key === "End")
+        return row.at(-1)?.id;
+    if (event.key !== "ArrowUp" && event.key !== "ArrowDown")
+        return undefined;
+    const column = items.filter((item) => item.value?.columnIndex === active.value.columnIndex);
+    return column.at(column.indexOf(active) + (event.key === "ArrowUp" ? -1 : 1))?.id ?? active.id;
+}

package/dist/Group.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Group supplies a neutral ARIA group host and an optional label host. Callers retain the normal
+ * Dom host-override contract and must provide either an accessible label or a labelled-by
+ * relationship where the surrounding widget requires one.
+ *
+ * @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 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";
+/**
+ * Inputs accepted by Group.Group in addition to the shared DOM host options.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The options type makes required state, content, accessible relationships, and custom-host inputs
+ * visible before rendering.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration is data or schema metadata and acquires no resources.
+ *
+ * ## Example
+ *
+ * Import with `import type { GroupOptions } from "@typed/ui/Group";` Extend the [Group.Group
+ * runnable setup](/reference/%40typed%2Fui%2FGroup%23Group). A labeled group host accepts
+ * `const options: GroupOptions = { label: "Formatting", content: "Controls" }`.
+ * @since 1.0.0
+ * @category models
+ */
+export interface GroupOptions extends Dom.HostOptions<HTMLDivElement> {
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Accessible label rendered through aria-label.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly label?: Renderable.Any<string | null | undefined>;
+    /**
+     * Id of the external element used through aria-labelledby.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly labelledBy?: Renderable.Any<string | null | undefined>;
+}
+declare function internalProps<const Options extends GroupOptions>({ property }: Dom.InternalPropsHelpers<Options>): {
+    role: string;
+    "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    "aria-labelledby": Exclude<Dom.Property<Options, "labelledBy">, Dom.Nullish> | undefined;
+};
+type GroupInternalProps<Options extends GroupOptions> = ReturnType<typeof internalProps<Options>>;
+/**
+ * Renders a div host with role=group and caller-controlled aria-label or aria-labelledby.
+ *
+ * @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
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Group({ label: "Formatting", content: "Controls" });
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function Group<const Options extends GroupOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, GroupInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Inputs accepted by Group.Label in addition to the shared DOM host options.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The options type makes required state, content, accessible relationships, and custom-host inputs
+ * visible before rendering.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration is data or schema metadata and acquires no resources.
+ *
+ * ## Example
+ *
+ * Import with `import type { LabelOptions } from "@typed/ui/Group";` Extend the [Group.Group
+ * runnable setup](/reference/%40typed%2Fui%2FGroup%23Group). A visible group label accepts
+ * `const options: LabelOptions = { content: "Formatting" }`.
+ * @since 1.0.0
+ * @category models
+ */
+export interface LabelOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly content: Renderable.Any;
+}
+/**
+ * Renders the group's visible label content without inventing an implicit id relationship.
+ *
+ * @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
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Label({ content: "Formatting" });
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function Label<const Options extends LabelOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, Record<never, never>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+export {};
+//# sourceMappingURL=Group.d.ts.map

package/dist/Group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Group.d.ts","sourceRoot":"","sources":["../src/Group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IACnE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IAEtG,IAAI;IACJ,YAAY;IACZ,iBAAiB;EAEpB;AAED,KAAK,kBAAkB,CAAC,OAAO,SAAS,YAAY,IAAI,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC7F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,GAC3G,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;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC7F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,GACpG,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/Group.js

@@ -0,0 +1,63 @@
+import { html } from "@typed/template";
+import * as Dom from "./Dom.js";
+function internalProps({ property }) {
+    return {
+        role: "group",
+        "aria-label": property("label", undefined),
+        "aria-labelledby": property("labelledBy", undefined),
+    };
+}
+/**
+ * Renders a div host with role=group and caller-controlled aria-label or aria-labelledby.
+ *
+ * @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
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Group({ label: "Formatting", content: "Controls" });
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Group(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+/**
+ * Renders the group's visible label content without inventing an implicit id relationship.
+ *
+ * @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
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Label({ content: "Formatting" });
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Label(options, host) {
+    return Dom.renderHost()(options, host, () => ({}), options.content, (props, content) => html `<span ...${props}>${content}</span>`);
+}

package/dist/Heading.d.ts

@@ -0,0 +1,86 @@
+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 an ARIA heading whose level may be reactive.
+ * @remarks
+ * ## Why
+ * Separating heading semantics from a fixed tag supports reusable components
+ * whose outline level is selected by their context.
+ * ## Ownership and lifetime
+ * The options are inert; rendering owns dynamic values for its Scope.
+ * @since 1.0.0
+ * @category models
+ */
+export interface HeadingOptions extends Dom.HostOptions<HTMLDivElement> {
+    /** Heading content and accessible name.
+     * @remarks
+     * ## Why
+     * Visible content participates directly in the accessibility tree.
+     * ## Ownership and lifetime
+     * Dynamic content follows the rendered Scope.
+     * @since 1.0.0
+     * @category content
+     */
+    readonly content: Renderable.Any;
+    /** ARIA heading level, defaulting to one.
+     * @remarks
+     * ## Why
+     * The level communicates document hierarchy even when the host tag is fixed.
+     * ## Ownership and lifetime
+     * The reflected value retains no resources.
+     * @since 1.0.0
+     * @category accessibility
+     */
+    readonly level?: Renderable.Any<number | null | undefined>;
+}
+declare function internalProps<const Options extends HeadingOptions>({ property, }: Dom.InternalPropsHelpers<Options>): {
+    role: string;
+    "aria-level": 1 | Exclude<Dom.Property<Options, "level">, Dom.Nullish>;
+};
+type HeadingInternalProps<Options extends HeadingOptions> = ReturnType<typeof internalProps<Options>>;
+/**
+ * Renders a host with `role="heading"` and a reactive `aria-level`.
+ * @remarks
+ * ## Why
+ * The primitive lets a design system preserve document-outline semantics when
+ * its visual host cannot be selected statically.
+ * ## Ownership and lifetime
+ * Running the returned Fx owns its dynamic attributes and content in an Effect
+ * Scope. A custom host must preserve `role` and `aria-level`.
+ * @example
+ * ```ts
+ * import { Heading } from "@typed/ui/Heading"
+ *
+ * const title = Heading({ level: 3, content: "Details" })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function Heading<const Options extends HeadingOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, HeadingInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Alias for `Heading` retained for level-oriented imports.
+ * @remarks
+ * ## Why
+ * The alias names the role the component plays in a contextual heading system.
+ * ## Ownership and lifetime
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category aliases
+ */
+export declare const Level: typeof Heading;
+/**
+ * Descriptive alias for `Heading`.
+ * @remarks
+ * ## Why
+ * The name remains available without duplicating an implementation contract.
+ * ## Ownership and lifetime
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category aliases
+ */
+export declare const HeadingLevel: typeof Heading;
+export {};
+//# sourceMappingURL=Heading.d.ts.map

package/dist/Heading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../src/Heading.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;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAe,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IACrE;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC5D;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,cAAc,EAAE,EAC3D,QAAQ,GACT,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IACzB,IAAI;IAAa,YAAY;EACvC;AAED,KAAK,oBAAoB,CAAC,OAAO,SAAS,cAAc,IAAI,UAAU,CACpE,OAAO,aAAa,CAAC,OAAO,CAAC,CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,KAAK,CAAC,OAAO,SAAS,cAAc,EACpC,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,oBAAoB,CAAC,OAAO,CAAC,CAAC,EAC3D,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;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,gBAAU,CAAC;AAC7B;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBAAU,CAAC"}