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

package/dist/Tree.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 [Tree guide](/explore/ui-tree).
+ *
  * @since 1.0.0
  * @category modules
  * @packageDocumentation
@@ -23,15 +25,6 @@ import * as Dom from "./Dom.js";
  * Effect Schema used by makeState to encode, decode, and hydrate Tree 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,7 +33,7 @@ import * as Dom from "./Dom.js";
  * const decodeState = Schema.decodeUnknownEffect(Tree.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Hierarchy state
  */
 export const StateSchema = Schema.Struct({
     activeId: Schema.NullOr(Schema.String),
@@ -51,12 +44,6 @@ export const StateSchema = Schema.Struct({
  * Creates hydrated Tree state. activeId defaults null and expandedIds defaults empty.
  *
  * @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.
@@ -75,7 +62,7 @@ export const StateSchema = Schema.Struct({
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Hierarchy state
  */
 export function makeState(initial = {}) {
     return RefSubject.hydrate(StateSchema, {
@@ -88,12 +75,6 @@ export function makeState(initial = {}) {
  * Creates a scoped Collection for Tree 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.
  *
@@ -110,20 +91,16 @@ export function makeState(initial = {}) {
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Node registration
  */
 export const makeCollection = Collection.makeState;
 /**
  * Tests membership in expandedIds without touching the DOM.
  *
  * @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.
  *
@@ -134,7 +111,7 @@ export const makeCollection = Collection.makeState;
  * const expanded = Tree.isExpanded({ activeId: null, expandedIds: ["parent"], loop: true }, "parent");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Expansion
  */
 export function isExpanded(state, id) {
     return state.expandedIds.includes(id);
@@ -143,24 +120,11 @@ export function isExpanded(state, id) {
  * Adds an id once to expandedIds.
  *
  * @remarks
- * ## Why
- *
  * The operation exposes Tree'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/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%23makeState). Inside the linked Effect program invoke
- * `yield* expand(state, "item-2")`, then read the state snapshot to observe the transition
- * described above.
  * @since 1.0.0
- * @category combinators
+ * @category Expansion
  */
 export function expand(state, id) {
     return RefSubject.update(state, (current) => isExpanded(current, id) ? current : { ...current, expandedIds: [...current.expandedIds, id] });
@@ -169,24 +133,11 @@ export function expand(state, id) {
  * Removes an id from expandedIds.
  *
  * @remarks
- * ## Why
- *
  * The operation exposes Tree'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/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%23makeState). Inside the linked Effect program invoke
- * `yield* collapse(state, "item-2")`, then read the state snapshot to observe the transition
- * described above.
  * @since 1.0.0
- * @category combinators
+ * @category Expansion
  */
 export function collapse(state, id) {
     return RefSubject.update(state, (current) => ({
@@ -198,24 +149,11 @@ export function collapse(state, id) {
  * Sets the active tree item id without changing expansion.
  *
  * @remarks
- * ## Why
- *
  * The operation exposes Tree'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/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%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 Node focus
  */
 export function activate(state, activeId) {
     return RefSubject.update(state, (current) => ({ ...current, activeId }));
@@ -249,25 +187,12 @@ function rootInternalProps(options) {
  * Renders the tree root and applies hierarchy-aware keyboard navigation to registered items.
  *
  * @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/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
- * read with `Root({ state, label: "Files", content: "Items" })`; render that Fx before the same
- * Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Tree surface
  */
 export function Root(options, host) {
     return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
@@ -303,25 +228,12 @@ function itemInternalProps(options) {
  * 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 { Item } from "@typed/ui/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
- * read with `Item({ state, id: "src", hasChildren: true, content: "src" })`; render that Fx before
- * the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Tree nodes
  */
 export function Item(options, host) {
     return Dom.renderHost()(options, host, itemInternalProps(options), options.content, (props, content) => {
@@ -338,25 +250,12 @@ function groupInternalProps(options) {
  * Renders a child group and hides it while its parent id is not expanded.
  *
  * @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/Tree";` Extend the [Tree.makeState runnable
- * setup](/reference/%40typed%2Fui%2FTree%23makeState). Replace the linked program's final snapshot
- * read with `Group({ state, parentId: "src", content: "Children" })`; render that Fx before the
- * same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Child visibility
  */
 export function Group(options, host) {
     return Dom.renderHost()(options, host, groupInternalProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);