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

package/dist/Toolbar.js

@@ -7,6 +7,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 [Toolbar guide](/explore/ui-toolbar).
+ *
  * @since 1.0.0
  * @category modules
  * @packageDocumentation
@@ -21,15 +23,6 @@ import * as Dom from "./Dom.js";
  * Effect Schema used by makeState to encode, decode, and hydrate Toolbar 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";
@@ -38,19 +31,13 @@ import * as Dom from "./Dom.js";
  * const decodeState = Schema.decodeUnknownEffect(Toolbar.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Command focus
  */
 export const StateSchema = Composite.StateSchema;
 /**
  * Creates hydrated Toolbar state. Uses Composite defaults unless overridden.
  *
  * @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.
@@ -69,7 +56,7 @@ export const StateSchema = Composite.StateSchema;
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Command focus
  */
 export function makeState(initial = {}) {
     return Composite.makeState(initial);
@@ -78,12 +65,6 @@ export function makeState(initial = {}) {
  * Creates a scoped Collection for Toolbar 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.
  *
@@ -100,7 +81,7 @@ export function makeState(initial = {}) {
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Command registration
  */
 export const makeCollection = Collection.makeState;
 function rootProps(options) {
@@ -146,25 +127,12 @@ function rootProps(options) {
  * Renders the toolbar root and moves roving focus through registered items in DOM order.
  *
  * @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/Toolbar";` Extend the [Toolbar.makeState runnable
- * setup](/reference/%40typed%2Fui%2FToolbar%23makeState). Replace the linked program's final
- * snapshot read with `Root({ state, label: "Formatting", content: "Buttons" })`; render that Fx
- * before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Toolbar surface
  */
 export function Root(options, host) {
     return Dom.renderHost()(options, host, rootProps(options), options.content, (props, content) => {
@@ -175,24 +143,11 @@ export function Root(options, host) {
  * Consumer-facing alias of the canonical Toolbar component with identical behavior and lifetime.
  *
  * @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 alias acquires nothing. Rendering it has exactly the canonical component's Scope and DOM
  * ownership contract.
  *
- * ## Example
- *
- * Import with `import { Toolbar } from "@typed/ui/Toolbar";` Extend the [Toolbar.makeState runnable
- * setup](/reference/%40typed%2Fui%2FToolbar%23makeState). Replace the linked program's final
- * snapshot read with `Toolbar({ state, label: "Formatting", content: "Buttons" })`; render that Fx
- * before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Toolbar surface
  */
 export const Toolbar = Root;
 function itemProps(options) {
@@ -220,25 +175,12 @@ function itemProps(options) {
  * Renders and optionally registers a toolbar button; focus activates it unless disabled.
  *
  * @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/Toolbar";` Extend the [Toolbar.makeState runnable
- * setup](/reference/%40typed%2Fui%2FToolbar%23makeState). Replace the linked program's final
- * snapshot read with `Item({ state, id: "bold", content: "Bold" })`; render that Fx before the same
- * Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Toolbar commands
  */
 export function Item(options, host) {
     return Dom.renderHost()(options, host, itemProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);

package/dist/Tooltip.d.ts

@@ -14,7 +14,7 @@ import type { HostResult } from "./Dom/Types.js";
  * ## Ownership and lifetime
  * Plain state retains no resources; RefSubject observation is Scope-owned.
  * @since 1.0.0
- * @category state
+ * @category Open state
  */
 export interface State {
     /** Stable id used by `aria-describedby` and tooltip content.
@@ -24,7 +24,7 @@ export interface State {
      * ## Ownership and lifetime
      * Plain data acquires no resources.
      * @since 1.0.0
-     * @category relationships
+     * @category Identity and relationships
      */
     readonly id: string;
     /** Whether tooltip content is open.
@@ -34,7 +34,7 @@ export interface State {
      * ## Ownership and lifetime
      * Plain data acquires no resources.
      * @since 1.0.0
-     * @category state
+     * @category Open state
      */
     readonly open: boolean;
 }
@@ -45,7 +45,7 @@ export interface State {
  * ## Ownership and lifetime
  * Configuration is inert.
  * @since 1.0.0
- * @category state
+ * @category Open state
  */
 export interface InitialState {
     /** Stable tooltip id.
@@ -55,7 +55,7 @@ export interface InitialState {
      * ## Ownership and lifetime
      * Plain data retains no resources.
      * @since 1.0.0
-     * @category relationships
+     * @category Identity and relationships
      */
     readonly id: string;
     /** Initial visibility, defaulting to false.
@@ -65,7 +65,7 @@ export interface InitialState {
      * ## Ownership and lifetime
      * Plain data retains no resources.
      * @since 1.0.0
-     * @category state
+     * @category Open state
      */
     readonly open?: boolean;
 }
@@ -76,7 +76,7 @@ export interface InitialState {
  * ## Ownership and lifetime
  * The immutable schema acquires no resources.
  * @since 1.0.0
- * @category schemas
+ * @category Open state
  */
 export declare const StateSchema: Schema.Struct<{
     readonly id: Schema.String;
@@ -98,7 +98,7 @@ export declare const StateSchema: Schema.Struct<{
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Open state
  */
 export declare function makeState(initial: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly id: string;
@@ -121,7 +121,7 @@ export declare function makeState(initial: InitialState): Effect.Effect<RefSubje
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category Open state
  */
 export declare function setOpen<E, R>(state: RefSubject.RefSubject<State, E, R>, open: boolean): Effect.Effect<State, E, R>;
 /** Options for a tooltip anchor host.
@@ -133,7 +133,7 @@ export declare function setOpen<E, R>(state: RefSubject.RefSubject<State, E, R>,
  * ## Ownership and lifetime
  * Options are inert; rendering owns listeners/timers by Scope.
  * @since 1.0.0
- * @category models
+ * @category Pointer and focus anchors
  */
 export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
     /** Hydrated state shared with tooltip content.
@@ -143,7 +143,7 @@ export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
      * ## Ownership and lifetime
      * The anchor borrows state; its original Scope owns it.
      * @since 1.0.0
-     * @category state
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /** Anchor content.
@@ -154,7 +154,7 @@ export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
      * ## Ownership and lifetime
      * Dynamic content follows the anchor Scope.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /** Delay in milliseconds before opening.
@@ -165,7 +165,7 @@ export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
      * Delayed Effects run inside the component interaction lifetime; newer
      * schedules invalidate older versions.
      * @since 1.0.0
-     * @category timing
+     * @category Interaction delays
      */
     readonly showDelay?: number;
     /** Delay in milliseconds before closing.
@@ -175,7 +175,7 @@ export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
      * ## Ownership and lifetime
      * Newer schedules invalidate older delayed updates.
      * @since 1.0.0
-     * @category timing
+     * @category Interaction delays
      */
     readonly hideDelay?: number;
 }
@@ -214,7 +214,7 @@ type AnchorInternalProps<Options extends AnchorOptions> = ReturnType<ReturnType<
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Pointer and focus anchors
  */
 export declare function Anchor<const Options extends AnchorOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, AnchorInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /** Options for native tooltip popover content.
@@ -224,7 +224,7 @@ export declare function Anchor<const Options extends AnchorOptions, const Host e
  * ## Ownership and lifetime
  * Options are inert; rendering owns listeners/ref observation by Scope.
  * @since 1.0.0
- * @category models
+ * @category Native content host
  */
 export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
     /** Hydrated state supplying content id and visibility.
@@ -234,7 +234,7 @@ export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
      * ## Ownership and lifetime
      * Content borrows state; its original Scope owns it.
      * @since 1.0.0
-     * @category state
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /** Non-interactive explanatory tooltip content.
@@ -244,7 +244,7 @@ export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
      * ## Ownership and lifetime
      * Dynamic content follows the content Scope.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
@@ -279,7 +279,7 @@ type ContentInternalProps<Options extends ContentOptions> = ReturnType<ReturnTyp
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Native content host
  */
 export declare function Content<const Options extends ContentOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ContentInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /** Canonical widget alias for `Content`.
@@ -289,7 +289,7 @@ export declare function Content<const Options extends ContentOptions, const Host
  * ## Ownership and lifetime
  * It has exactly the same Scope and popover ownership as `Content`.
  * @since 1.0.0
- * @category aliases
+ * @category Native content host
  */
 export declare const Tooltip: typeof Content;
 export {};

package/dist/Tooltip.js

@@ -11,7 +11,7 @@ import * as NativePopover from "./NativePopover.js";
  * ## Ownership and lifetime
  * The immutable schema acquires no resources.
  * @since 1.0.0
- * @category schemas
+ * @category Open state
  */
 export const StateSchema = Schema.Struct({ id: Schema.String, open: Schema.Boolean });
 /** Creates hydrated tooltip state.
@@ -30,7 +30,7 @@ export const StateSchema = Schema.Struct({ id: Schema.String, open: Schema.Boole
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Open state
  */
 export function makeState(initial) {
     return RefSubject.hydrate(StateSchema, { id: initial.id, open: initial.open ?? false });
@@ -52,7 +52,7 @@ export function makeState(initial) {
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category Open state
  */
 export function setOpen(state, open) {
     return RefSubject.update(state, (current) => ({ ...current, open }));
@@ -106,7 +106,7 @@ function anchorInternalProps(options) {
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Pointer and focus anchors
  */
 export function Anchor(options, host) {
     return Dom.renderHost()(options, host, anchorInternalProps(options), options.content, (props, content) => html `<span ...${props}>${content}</span>`);
@@ -153,7 +153,7 @@ function contentInternalProps(options) {
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Native content host
  */
 export function Content(options, host) {
     return Dom.renderHost()(options, host, contentInternalProps(options), options.content, (props, content) => {
@@ -167,6 +167,6 @@ export function Content(options, host) {
  * ## Ownership and lifetime
  * It has exactly the same Scope and popover ownership as `Content`.
  * @since 1.0.0
- * @category aliases
+ * @category Native content host
  */
 export const Tooltip = Content;