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

package/dist/TreeGrid.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 [TreeGrid guide](/explore/ui-tree-grid).
+ *
  * @since 1.0.0
  * @category modules
  * @packageDocumentation
@@ -23,15 +25,6 @@ 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";
@@ -40,19 +33,13 @@ import * as Tree from "./Tree.js";
  * const decodeState = Schema.decodeUnknownEffect(TreeGrid.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Hierarchy and cell focus
  */
 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.
@@ -71,7 +58,7 @@ export const StateSchema = Tree.StateSchema;
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Hierarchy and cell focus
  */
 export const makeState = Tree.makeState;
 /**
@@ -79,13 +66,9 @@ export const makeState = Tree.makeState;
  * 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.
  *
@@ -96,89 +79,46 @@ export const makeState = Tree.makeState;
  * const expanded = TreeGrid.isExpanded({ activeId: null, expandedIds: ["parent"], loop: true }, "parent");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Row expansion
  */
 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
+ * @category Row expansion
  */
 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
+ * @category Row expansion
  */
 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
+ * @category Hierarchy and cell focus
  */
 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.
  *
@@ -195,7 +135,7 @@ export const activate = Tree.activate;
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Cell registration
  */
 export const makeCollection = Collection.makeState;
 function rootInternalProps(options) {
@@ -226,25 +166,12 @@ function rootInternalProps(options) {
  * 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
+ * @category Treegrid surface
  */
 export function Root(options, host) {
     return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
@@ -266,25 +193,12 @@ function rowInternalProps(options) {
  * 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
+ * @category Hierarchical rows
  */
 export function Row(options, host) {
     return Dom.renderHost()(options, host, rowInternalProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
@@ -315,25 +229,12 @@ function cellInternalProps(options) {
  * 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
+ * @category Navigable cells
  */
 export function Cell(options, host) {
     return Dom.renderHost()(options, host, cellInternalProps(options), options.content, (props, content) => {
@@ -350,25 +251,12 @@ function groupInternalProps(options) {
  * 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
+ * @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>`);

package/dist/VisuallyHidden.d.ts

@@ -1,29 +1,26 @@
+/**
+ * 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";
 /**
- * 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.
+    /**
+     * Content retained in the document and accessibility tree.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
@@ -32,22 +29,39 @@ declare function internalProps(): {
 };
 type VisuallyHiddenInternalProps = ReturnType<typeof internalProps>;
 /**
- * Renders screen-reader-accessible content with standard clipping styles.
+ * Clips text visually while retaining it for accessible naming and reading.
+ *
  * @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.
+ * 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 { VisuallyHidden } from "@typed/ui/VisuallyHidden"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden";
  *
- * const label = VisuallyHidden({ content: "Open navigation" })
+ * 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 components
+ * @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 {};

package/dist/VisuallyHidden.d.ts.map

@@ -1 +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"}
+{"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

@@ -5,22 +5,39 @@ function internalProps() {
     return { style };
 }
 /**
- * Renders screen-reader-accessible content with standard clipping styles.
+ * Clips text visually while retaining it for accessible naming and reading.
+ *
  * @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.
+ * 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 { VisuallyHidden } from "@typed/ui/VisuallyHidden"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
+ * import { VisuallyHidden } from "@typed/ui/VisuallyHidden";
  *
- * const label = VisuallyHidden({ content: "Open navigation" })
+ * 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 components
+ * @category Structure and naming
  */
 export function VisuallyHidden(options, host) {
     return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<span ...${props}>${content}</span>`);