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

package/dist/Grid.js

@@ -8,6 +8,8 @@
  * 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 [Grid guide](/explore/ui-grid).
+ *
  * @since 1.0.0
  * @category modules
  * @packageDocumentation
@@ -22,15 +24,6 @@ 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";
@@ -39,19 +32,13 @@ import * as Dom from "./Dom.js";
  * const decodeState = Schema.decodeUnknownEffect(Grid.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Cell focus
  */
 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.
@@ -70,7 +57,7 @@ export const StateSchema = Schema.Struct({ activeId: Schema.NullOr(Schema.String
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Cell focus
  */
 export function makeState(initial = {}) {
     return RefSubject.hydrate(StateSchema, { activeId: initial.activeId ?? null });
@@ -79,12 +66,6 @@ export function makeState(initial = {}) {
  * 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.
  *
@@ -101,31 +82,18 @@ export function makeState(initial = {}) {
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Cell registration
  */
 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
+ * @category Cell focus
  */
 export function activate(state, activeId) {
     return RefSubject.update(state, (current) => ({ ...current, activeId }));
@@ -159,25 +127,12 @@ function rootInternalProps(options) {
  * 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
+ * @category Grid surface
  */
 export function Root(options, host) {
     return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
@@ -191,13 +146,6 @@ function rowInternalProps({ property, }) {
  * 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.
@@ -209,7 +157,7 @@ function rowInternalProps({ property, }) {
  * const view = Grid.Row({ rowIndex: 1, content: "Cells" });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Rows
  */
 export function Row(options, host) {
     return Dom.renderHost()(options, host, rowInternalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
@@ -242,25 +190,12 @@ function cell(options, host, role) {
  * 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
+ * @category Cells and headers
  */
 export function Cell(options, host) {
     return cell(options, host, "gridcell");
@@ -269,25 +204,12 @@ export function Cell(options, host) {
  * 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
+ * @category Cells and headers
  */
 export function ColumnHeader(options, host) {
     return cell(options, host, "columnheader");
@@ -296,25 +218,12 @@ export function ColumnHeader(options, host) {
  * 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
+ * @category Cells and headers
  */
 export function RowHeader(options, host) {
     return cell(options, host, "rowheader");
@@ -334,13 +243,9 @@ function onKeyDown(state, collection, event) {
  * 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.
  *
@@ -351,7 +256,7 @@ function onKeyDown(state, collection, event) {
  * const nextId = Grid.moveActiveId([{ id: "a", value: { rowId: "r1", columnIndex: 1 } }], "a", { key: "ArrowRight", ctrlKey: false });
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Spatial navigation
  */
 export function moveActiveId(items, activeId, event) {
     if (items.length === 0)

package/dist/Group.d.ts

@@ -1,15 +1,12 @@
 /**
- * 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.
+ * Explicitly named collections of related content.
+ * Group.Label is a span; connect its ID through labelledBy rather than assuming implicit wiring.
  *
- * @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.
+ * Read the [Group guide](/explore/ui-group) for a complete example.
  *
+ * [Platform reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role).
  * @since 1.0.0
- * @category modules
+ * @category Overview
  * @packageDocumentation
  */
 import type * as Scope from "effect/Scope";
@@ -18,43 +15,31 @@ import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/t
 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.
+ * Related content with either a direct accessible label or an external label ID.
  *
  * @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" }`.
+ * Use labelledBy when visible text already names the group; use label when that text is absent.
+ * Native fieldset/legend and composite keyboard behavior are not created by these options.
  * @since 1.0.0
- * @category models
+ * @category Component options
  */
 export interface GroupOptions extends Dom.HostOptions<HTMLDivElement> {
     /**
      * Renderable child content for the component host.
      * @since 1.0.0
-     * @category models
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /**
      * Accessible label rendered through aria-label.
      * @since 1.0.0
-     * @category models
+     * @category Accessible naming
      */
     readonly label?: Renderable.Any<string | null | undefined>;
     /**
      * Id of the external element used through aria-labelledby.
      * @since 1.0.0
-     * @category models
+     * @category Accessible naming
      */
     readonly labelledBy?: Renderable.Any<string | null | undefined>;
 }
@@ -65,73 +50,69 @@ declare function internalProps<const Options extends GroupOptions>({ property }:
 };
 type GroupInternalProps<Options extends GroupOptions> = ReturnType<typeof internalProps<Options>>;
 /**
- * Renders a div host with role=group and caller-controlled aria-label or aria-labelledby.
+ * Renders a semantic group with an explicit accessible name.
  *
  * @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.
+ * label becomes aria-label; labelledBy references existing visible text through aria-labelledby.
+ * The div does not implement fieldset disabling, toolbar navigation, or child selection. Name
+ * each interactive child independently.
  *
  * @example
  * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
  * import * as Group from "@typed/ui/Group";
  *
- * const view = Group.Group({ label: "Formatting", content: "Controls" });
+ * export const PreviewActions = component(function* () {
+ *   const rotation = yield* RefSubject.make(45);
+ *   const scale = yield* RefSubject.make(150);
+ *   return html`<section>
+ *     <p>Rotation: ${rotation} degrees. Scale: ${scale}%.</p>
+ *     ${Group.Label({
+ *       content: "Preview controls",
+ *       props: { id: "preview-control-label", class: "control-group-label" },
+ *     })}
+ *     ${Group.Group({
+ *       labelledBy: "preview-control-label",
+ *       props: { class: "preview-actions" },
+ *       content: [
+ *         Button({ content: "Reset rotation", onclick: RefSubject.set(rotation, 0) }),
+ *         Button({ content: "Reset scale", onclick: RefSubject.set(scale, 100) }),
+ *       ],
+ *     })}
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Structure and naming
  */
 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.
+ * Visible span content and host props for an explicitly linked group label.
  *
  * @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" }`.
+ * Set props.id and reference it through Group.labelledBy. There is no generated ID or implicit
+ * relationship.
  * @since 1.0.0
- * @category models
+ * @category Component options
  */
 export interface LabelOptions extends Dom.HostOptions<HTMLSpanElement> {
     /**
      * Renderable child content for the component host.
      * @since 1.0.0
-     * @category models
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
 /**
- * Renders the group's visible label content without inventing an implicit id relationship.
+ * Renders visible group-label text in a span.
  *
  * @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.
+ * Pass an ID through props and reference it from Group.labelledBy to create a relationship.
+ * Rendering this span beside a group does not connect them automatically, and it does not create
+ * heading semantics.
  *
  * @example
  * ```ts
@@ -140,7 +121,7 @@ export interface LabelOptions extends Dom.HostOptions<HTMLSpanElement> {
  * const view = Group.Label({ content: "Formatting" });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 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 {};

package/dist/Group.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"Group.d.ts","sourceRoot":"","sources":["../src/Group.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;AAEjD;;;;;;;;GAQG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;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

@@ -8,46 +8,54 @@ function internalProps({ property }) {
     };
 }
 /**
- * Renders a div host with role=group and caller-controlled aria-label or aria-labelledby.
+ * Renders a semantic group with an explicit accessible name.
  *
  * @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.
+ * label becomes aria-label; labelledBy references existing visible text through aria-labelledby.
+ * The div does not implement fieldset disabling, toolbar navigation, or child selection. Name
+ * each interactive child independently.
  *
  * @example
  * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
  * import * as Group from "@typed/ui/Group";
  *
- * const view = Group.Group({ label: "Formatting", content: "Controls" });
+ * export const PreviewActions = component(function* () {
+ *   const rotation = yield* RefSubject.make(45);
+ *   const scale = yield* RefSubject.make(150);
+ *   return html`<section>
+ *     <p>Rotation: ${rotation} degrees. Scale: ${scale}%.</p>
+ *     ${Group.Label({
+ *       content: "Preview controls",
+ *       props: { id: "preview-control-label", class: "control-group-label" },
+ *     })}
+ *     ${Group.Group({
+ *       labelledBy: "preview-control-label",
+ *       props: { class: "preview-actions" },
+ *       content: [
+ *         Button({ content: "Reset rotation", onclick: RefSubject.set(rotation, 0) }),
+ *         Button({ content: "Reset scale", onclick: RefSubject.set(scale, 100) }),
+ *       ],
+ *     })}
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Structure and naming
  */
 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.
+ * Renders visible group-label text in a span.
  *
  * @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.
+ * Pass an ID through props and reference it from Group.labelledBy to create a relationship.
+ * Rendering this span beside a group does not connect them automatically, and it does not create
+ * heading semantics.
  *
  * @example
  * ```ts
@@ -56,7 +64,7 @@ export function Group(options, host) {
  * const view = Group.Label({ content: "Formatting" });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 export function Label(options, host) {
     return Dom.renderHost()(options, host, () => ({}), options.content, (props, content) => html `<span ...${props}>${content}</span>`);

package/dist/Heading.d.ts

@@ -1,38 +1,29 @@
+/**
+ * Contextual heading semantics independent of typography.
+ * The default div uses role=heading and aria-level; fixed native headings remain useful.
+ *
+ * Read the [Heading guide](/explore/ui-heading) for a complete example.
+ *
+ * [Platform reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role).
+ * @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";
 /**
- * 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.
+    /**
+     * Heading content and accessible name.
      * @since 1.0.0
-     * @category content
+     * @category Rendered 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>;
 }
@@ -42,44 +33,54 @@ declare function internalProps<const Options extends HeadingOptions>({ property,
 };
 type HeadingInternalProps<Options extends HeadingOptions> = ReturnType<typeof internalProps<Options>>;
 /**
- * Renders a host with `role="heading"` and a reactive `aria-level`.
+ * Renders a div with heading semantics and an explicit 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`.
+ * level defaults to one and may be reactive; it does not choose font size, infer nesting, or
+ * validate the document outline. Use native h1–h6 markup when the level is fixed. A custom host
+ * must keep its native level and aria-level consistent.
+ *
  * @example
  * ```ts
- * import { Heading } from "@typed/ui/Heading"
+ * import { html } from "@typed/template";
+ * import { Heading } from "@typed/ui/Heading";
+ *
+ * export function AccountSection(level: 2 | 3) {
+ *   return html`<section aria-labelledby="account-section-title">
+ *     ${Heading({
+ *       level,
+ *       content: "Account security",
+ *       props: { id: "account-section-title", class: "section-title" },
+ *     })}
+ *     <p>Review the devices and credentials that can access this account.</p>
+ *   </section>`;
+ * }
  *
- * const title = Heading({ level: 3, content: "Details" })
+ * export const AccountPage = html`<main>
+ *     <h1>Account settings</h1>
+ *     ${AccountSection(2)}
+ *   </main>`;
  * ```
  * @since 1.0.0
- * @category components
+ * @category Structure and naming
  */
 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
+ * @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
+ * @category Aliases
  */
 export declare const HeadingLevel: typeof Heading;
 export {};