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

package/dist/Menu.d.ts

@@ -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 [Menu guide](/explore/ui-menu).
+ *
  * @since 1.0.0
  * @category modules
  * @packageDocumentation
@@ -23,43 +25,29 @@ import * as Composite from "./Composite.js";
 import * as Dom from "./Dom.js";
 import type { HostResult } from "./Dom/Types.js";
 /**
- * Complete renderer-independent state for Menu.
- *
- * @remarks
- * ## Why
- *
- * Applications can inspect, update, and test Menu behavior without mounting or coupling the state
- * to a renderer.
+ * Popup identity, visibility, and active command focus.
+ * Checked preferences and command results belong to the application, not this state.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { State } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Inside the linked program,
- * `const snapshot: State = yield* state` exposes popup identity, open state, and active-item focus.
  * @since 1.0.0
- * @category models
+ * @category Popup state
  */
 export interface State extends Omit<Composite.State, "orientation"> {
     /**
      * Axis used to interpret Arrow-key movement.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly orientation: "vertical";
     /**
      * Stable id used for collection identity and ARIA relationships.
      * @since 1.0.0
-     * @category models
+     * @category Identity and relationships
      */
     readonly id: string;
     /**
      * Whether the associated native popover is open.
      * @since 1.0.0
-     * @category models
+     * @category Popup visibility
      */
     readonly open: boolean;
 }
@@ -67,47 +55,32 @@ export interface State extends Omit<Composite.State, "orientation"> {
  * Initial Menu values. The caller supplies id; open defaults false, activeId null, loop true, and
  * orientation vertical.
  *
- * @remarks
- * ## Why
- *
- * Making initialization explicit documents hydration-sensitive defaults and lets servers and
- * clients construct matching state.
- *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { InitialState } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). Construct a closed menu with
- * `const initial: InitialState = { id: "file-menu", open: false }; const state = yield* Menu.makeState(initial)`.
  * @since 1.0.0
- * @category models
+ * @category Popup state
  */
 export interface InitialState {
     /**
      * Stable id used for collection identity and ARIA relationships.
      * @since 1.0.0
-     * @category models
+     * @category Identity and relationships
      */
     readonly id: string;
     /**
      * Whether the associated native popover is open.
      * @since 1.0.0
-     * @category models
+     * @category Popup visibility
      */
     readonly open?: boolean;
     /**
      * Id currently active for keyboard navigation; null means no active item.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard focus
      */
     readonly activeId?: string | null;
     /**
      * Whether movement wraps between the first and last enabled items.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly loop?: boolean;
 }
@@ -115,15 +88,6 @@ export interface InitialState {
  * Effect Schema used by makeState to encode, decode, and hydrate Menu 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";
@@ -132,7 +96,7 @@ export interface InitialState {
  * const decodeState = Schema.decodeUnknownEffect(Menu.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Popup state
  */
 export declare const StateSchema: Schema.Struct<{
     readonly id: Schema.String;
@@ -148,12 +112,6 @@ export declare const StateSchema: Schema.Struct<{
  * true, and orientation vertical.
  *
  * @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.
@@ -172,7 +130,7 @@ export declare const StateSchema: Schema.Struct<{
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Popup state
  */
 export declare function makeState(initial: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly id: string;
@@ -187,12 +145,6 @@ export declare function makeState(initial: InitialState): Effect.Effect<RefSubje
  * Creates a scoped Collection for Menu 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.
  *
@@ -209,65 +161,41 @@ export declare function makeState(initial: InitialState): Effect.Effect<RefSubje
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Command registration
  */
 export declare const makeCollection: (initial?: Collection.State<string, Element>) => Effect.Effect<RefSubject.RefSubject<Collection.State<string, Element>, never, never>, never, Scope.Scope>;
 /**
  * Updates only the menu's explicit open state.
  *
  * @remarks
- * ## Why
- *
  * The operation exposes Menu'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 { setOpen } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Inside the linked Effect program invoke
- * `yield* setOpen(state, true)`, then read state to observe `open: true` without changing focus or
- * menu identity.
  * @since 1.0.0
- * @category combinators
+ * @category Popup state
  */
 export declare function setOpen<E, R>(state: RefSubject.RefSubject<State, E, R>, open: boolean): Effect.Effect<State, E, R>;
 /**
  * Inputs accepted by Menu.Trigger in addition to the shared DOM host options.
  *
  * @remarks
- * ## Why
- *
  * Separator orientation is an accessibility announcement only, so it remains independent from the
  * orientation used by menu keyboard navigation.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { TriggerOptions } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). A native popover trigger accepts
- * `const options: TriggerOptions = { state, content: "File" }`.
  * @since 1.0.0
- * @category models
+ * @category Opening a menu
  */
 export interface TriggerOptions extends Dom.HostOptions<HTMLButtonElement> {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /**
      * Renderable child content for the component host.
      * @since 1.0.0
-     * @category models
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
@@ -285,99 +213,64 @@ type TriggerProps<Options extends TriggerOptions> = ReturnType<ReturnType<typeof
  * Renders a native button targeting menu popover content and opens the menu on ArrowDown.
  *
  * @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 { Trigger } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Trigger({ state, content: "File" })`; render that Fx before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Opening a menu
  */
 export declare function Trigger<const Options extends TriggerOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, TriggerProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Consumer-facing alias of the canonical Menu 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 { Button } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Button({ state, content: "File" })`; render that Fx before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Opening a menu
  */
 export declare const Button: typeof Trigger;
 /**
  * Inputs accepted by Menu.Content in addition to the shared DOM host options.
  *
  * @remarks
- * ## Why
- *
  * The model makes popup content, optional collection navigation, and optional parent-menu linkage
  * explicit while retaining the shared custom-host boundary.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { ContentOptions } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). Enable menu movement with
- * `const options: ContentOptions = { state, collection, label: "File", content: "Commands" }`.
  * @since 1.0.0
- * @category models
+ * @category Menu surface
  */
 export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /**
      * Item registry used for collection-driven keyboard behavior and mounted ordering.
      * @since 1.0.0
-     * @category models
+     * @category Item registration
      */
     readonly collection?: RefSubject.RefSubject<Collection.State<string>>;
     /**
      * Parent-menu state and collection used for nested directional navigation and focus return.
      * @since 1.0.0
-     * @category models
+     * @category Nested menus
      */
     readonly parent?: ParentMenu;
     /**
      * 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>;
 }
@@ -385,40 +278,29 @@ export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
  * Public Menu.ParentMenu behavioral model.
  *
  * @remarks
- * ## Why
- *
  * The public model lets custom composites reuse Menu's deterministic policy without copying an
  * internal shape.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { ParentMenu } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). Nested menus carry their parent
- * navigation pair explicitly: `const parent: ParentMenu = { state, collection }`.
  * @since 1.0.0
- * @category models
+ * @category Nested menus
  */
 export interface ParentMenu {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /**
      * Item registry used for collection-driven keyboard behavior and mounted ordering.
      * @since 1.0.0
-     * @category models
+     * @category Item registration
      */
     readonly collection: RefSubject.RefSubject<Collection.State<string>>;
     /**
      * Id of the trigger that owns this menu and receives focus when the menu closes.
      * @since 1.0.0
-     * @category models
+     * @category Nested menus
      */
     readonly triggerId: string;
 }
@@ -437,119 +319,82 @@ type ContentProps<Options extends ContentOptions> = ReturnType<ReturnType<typeof
  * traversal.
  *
  * @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 { Content } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Content({ state, label: "File", content: "Commands" })`; render that Fx before the
- * same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Menu surface
  */
 export declare function Content<const Options extends ContentOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ContentProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Consumer-facing alias of the canonical Menu 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 { Menu } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Menu({ state, label: "File", content: "Commands" })`; render that Fx before the same
- * Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Menu surface
  */
 export declare const Menu: typeof Content;
 /**
  * Inputs accepted by Menu.Item in addition to the shared DOM host options.
  *
  * @remarks
- * ## Why
- *
  * The model makes item identity, content, optional registration metadata, and state ownership
  * explicit before the item is rendered.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { ItemOptions } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). A menu command is
- * `const options: ItemOptions = { state, collection, id: "save", content: "Save" }`.
  * @since 1.0.0
- * @category models
+ * @category Commands
  */
 export interface ItemOptions extends Dom.HostOptions<HTMLDivElement> {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /**
      * Item registry used for collection-driven keyboard behavior and mounted ordering.
      * @since 1.0.0
-     * @category models
+     * @category Item registration
      */
     readonly collection?: RefSubject.RefSubject<Collection.State<string>>;
     /**
      * Stable id used for collection identity and ARIA relationships.
      * @since 1.0.0
-     * @category models
+     * @category Identity and relationships
      */
     readonly id: string;
     /**
      * Renderable child content for the component host.
      * @since 1.0.0
-     * @category models
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /**
      * Search text used by typeahead independently of rendered markup.
      * @since 1.0.0
-     * @category models
+     * @category Text matching
      */
     readonly textValue?: string;
     /**
      * Flag used by collection movement and widget handlers to skip activation by default.
      * @since 1.0.0
-     * @category models
+     * @category Availability
      */
     readonly disabled?: boolean;
     /**
      * ARIA role emitted by the item variant.
      * @since 1.0.0
-     * @category models
+     * @category Command semantics
      */
     readonly role?: "menuitem" | "menuitemcheckbox" | "menuitemradio";
     /**
      * Checked state exposed by checkbox and radio menu-item variants.
      * @since 1.0.0
-     * @category models
+     * @category Checked state
      */
     readonly checked?: Renderable.Any<boolean | null | undefined>;
 }
@@ -572,90 +417,61 @@ type ItemProps<Options extends ItemOptions> = ReturnType<ReturnType<typeof itemP
  * activate.
  *
  * @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/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Item({ state, id: "save", content: "Save" })`; render that Fx before the same Scope
- * closes.
  * @since 1.0.0
- * @category components
+ * @category Commands
  */
 export declare function Item<const Options extends ItemOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ItemProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Inputs accepted by Menu.SubmenuTrigger 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 { SubmenuTriggerOptions } from "@typed/ui/Menu";` Extend the
- * [Menu.makeState runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). After
- * `const submenu = yield* Menu.makeState({ id: "share-menu" })`, use
- * `const options: SubmenuTriggerOptions<State> = { state, submenu, collection, id: "share", content: "Share" }`.
  * @since 1.0.0
- * @category models
+ * @category Nested menus
  */
 export interface SubmenuTriggerOptions<ParentState extends Composite.State> extends Dom.HostOptions<HTMLButtonElement> {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<ParentState, Schema.SchemaError>;
     /**
      * Whether the item participates as a submenu entry.
      * @since 1.0.0
-     * @category models
+     * @category Nested menus
      */
     readonly submenu: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
     /**
      * Item registry used for collection-driven keyboard behavior and mounted ordering.
      * @since 1.0.0
-     * @category models
+     * @category Item registration
      */
     readonly collection?: RefSubject.RefSubject<Collection.State<string>>;
     /**
      * Stable id used for collection identity and ARIA relationships.
      * @since 1.0.0
-     * @category models
+     * @category Identity and relationships
      */
     readonly id: string;
     /**
      * Renderable child content for the component host.
      * @since 1.0.0
-     * @category models
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /**
      * Search text used by typeahead independently of rendered markup.
      * @since 1.0.0
-     * @category models
+     * @category Text matching
      */
     readonly textValue?: string;
     /**
      * Flag used by collection movement and widget handlers to skip activation by default.
      * @since 1.0.0
-     * @category models
+     * @category Availability
      */
     readonly disabled?: boolean;
 }
@@ -680,26 +496,12 @@ type SubmenuTriggerProps<ParentState extends Composite.State, Options extends Su
  * 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 { SubmenuTrigger } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final
- * snapshot read after `const submenu = yield* Menu.makeState({ id: "share-menu" })` with
- * `SubmenuTrigger({ state, submenu, collection, id: "share", content: "Share" })`; render that Fx
- * before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Nested menus
  */
 export declare function SubmenuTrigger<ParentState extends Composite.State, const Options extends SubmenuTriggerOptions<NoInfer<ParentState>>, const Host extends HostResult = never>(options: Options & {
     readonly state: RefSubject.HydratedRefSubject<ParentState, Schema.SchemaError>;
@@ -707,30 +509,14 @@ export declare function SubmenuTrigger<ParentState extends Composite.State, cons
 /**
  * Inputs accepted by Menu.CheckboxItem 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 { CheckboxItemOptions } from "@typed/ui/Menu";` Extend the
- * [Menu.makeState runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). A checked command
- * is
- * `const options: CheckboxItemOptions = { state, collection, id: "autosave", checked: true, content: "Autosave" }`.
  * @since 1.0.0
- * @category models
+ * @category Checked commands
  */
 export interface CheckboxItemOptions extends Omit<ItemOptions, "role" | "checked"> {
     /**
      * Checked state exposed by checkbox and radio menu-item variants.
      * @since 1.0.0
-     * @category models
+     * @category Checked state
      */
     readonly checked: Renderable.Any<boolean | null | undefined>;
 }
@@ -741,53 +527,25 @@ type CheckboxItemWithRole<Options extends CheckboxItemOptions> = Options & {
  * Renders Item with menuitemcheckbox semantics and caller-supplied checked 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 { CheckboxItem } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `CheckboxItem({ state, id: "autosave", checked: true, content: "Autosave" })`; render
- * that Fx before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Checked commands
  */
 export declare function CheckboxItem<const Options extends CheckboxItemOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<CheckboxItemWithRole<Options>, ItemProps<CheckboxItemWithRole<Options>>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Inputs accepted by Menu.RadioItem 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 { RadioItemOptions } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). A radio command is
- * `const options: RadioItemOptions = { state, collection, id: "compact", checked: false, content: "Compact" }`.
  * @since 1.0.0
- * @category models
+ * @category Checked commands
  */
 export interface RadioItemOptions extends Omit<ItemOptions, "role" | "checked"> {
     /**
      * Checked state exposed by checkbox and radio menu-item variants.
      * @since 1.0.0
-     * @category models
+     * @category Checked state
      */
     readonly checked: Renderable.Any<boolean | null | undefined>;
 }
@@ -798,59 +556,31 @@ type RadioItemWithRole<Options extends RadioItemOptions> = Options & {
  * Renders Item with menuitemradio semantics and caller-supplied checked 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 { RadioItem } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `RadioItem({ state, id: "compact", checked: false, content: "Compact" })`; render that
- * Fx before the same Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Checked commands
  */
 export declare function RadioItem<const Options extends RadioItemOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<RadioItemWithRole<Options>, ItemProps<RadioItemWithRole<Options>>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Inputs accepted by Menu.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/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). A labeled command group accepts
- * `const options: GroupOptions = { label: "View", content: "Choices" }`.
  * @since 1.0.0
- * @category models
+ * @category Command grouping
  */
 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>;
 }
@@ -863,13 +593,6 @@ type GroupProps<Options extends GroupOptions> = ReturnType<ReturnType<typeof gro
  * Renders a labelled ARIA group inside menu content.
  *
  * @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.
@@ -881,60 +604,35 @@ type GroupProps<Options extends GroupOptions> = ReturnType<ReturnType<typeof gro
  * const view = Menu.Group({ label: "View", content: "Choices" });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Command grouping
  */
 export declare function Group<const Options extends GroupOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, GroupProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 /**
  * Consumer-facing alias of the canonical Menu 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 { Dismiss } from "@typed/ui/Menu";` Extend the [Menu.makeState runnable
- * setup](/reference/%40typed%2Fui%2FMenu%23makeState). Replace the linked program's final snapshot
- * read with `Dismiss({ state, id: "close", content: "Close" })`; render that Fx before the same
- * Scope closes.
  * @since 1.0.0
- * @category components
+ * @category Commands
  */
 export declare const Dismiss: typeof Item;
 /**
  * Inputs accepted by Menu.Separator in addition to the shared DOM host options.
  *
  * @remarks
- * ## Why
- *
  * The model adds separator orientation to the shared host options. Orientation is consumed only
  * by the separator's `aria-orientation` attribute; it does not change menu navigation.
  *
- * ## Ownership and lifetime
- *
- * This declaration is data or schema metadata and acquires no resources.
- *
- * ## Example
- *
- * Import with `import type { SeparatorOptions } from "@typed/ui/Menu";` Extend the [Menu.makeState
- * runnable setup](/reference/%40typed%2Fui%2FMenu%23makeState). Choose only its announced axis:
- * `const options: SeparatorOptions = { orientation: "vertical" }`; this does not alter Arrow-key
- * behavior.
  * @since 1.0.0
- * @category models
+ * @category Command grouping
  */
 export interface SeparatorOptions extends Dom.HostOptions<HTMLHRElement> {
     /**
      * Value forwarded only to the separator's aria-orientation attribute.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly orientation?: "horizontal" | "vertical";
 }
@@ -947,13 +645,6 @@ type SeparatorProps<Options extends SeparatorOptions> = ReturnType<ReturnType<ty
  * Renders a separator with explicit horizontal or vertical orientation.
  *
  * @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.
@@ -965,7 +656,7 @@ type SeparatorProps<Options extends SeparatorOptions> = ReturnType<ReturnType<ty
  * const view = Menu.Separator({ orientation: "horizontal" });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Command grouping
  */
 export declare function Separator<const Options extends SeparatorOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, SeparatorProps<Options>>, "", Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 export {};