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

package/dist/Alert.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Assertive live-region content without focus movement or an announcement queue.
+ * Use urgent text updates deliberately; routine feedback usually belongs in a status region.
+ *
+ * Read the [Alert guide](/explore/ui-alert) for a complete example.
+ *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/alert/).
+ * @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";
@@ -7,36 +18,16 @@ import type { HostResult } from "./Dom/Types.js";
  * Options for the assertive alert live region.
  *
  * @remarks
- * ## Why
- *
  * Alerts announce important, time-sensitive output without moving focus or
  * requiring a modal interaction.
- *
- * ## Ownership and lifetime
- *
- * The options are inert. Rendering owns only the alert host and subscriptions
- * for renderable option values; the running Effect Scope removes them.
- *
  * @since 1.0.0
- * @category models
+ * @category Component options
  */
 export interface AlertOptions extends Dom.HostOptions<HTMLDivElement> {
     /**
      * Content announced by the `role="alert"` live region.
-     *
-     * @remarks
-     * ## Why
-     *
-     * Keeping the announcement renderable lets applications publish Effect- or
-     * Fx-backed status while retaining the platform accessibility tree.
-     *
-     * ## Ownership and lifetime
-     *
-     * The value acquires no resources itself. Rendering subscribes to dynamic
-     * content for the lifetime of the alert's Scope.
-     *
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
@@ -45,33 +36,36 @@ declare function internalProps(): {
 };
 type AlertInternalProps = ReturnType<typeof internalProps>;
 /**
- * Renders a non-modal, assertive live region.
- *
- * For an interrupting confirmation, use `Dialog.Content` with
- * `role="alertdialog"`; an alert must not take focus or require dismissal.
+ * Renders an assertive alert region without moving focus.
  *
  * @remarks
- * ## Why
- *
- * `Alert` supplies the native ARIA live-region contract while leaving content,
- * host choice, and Effect requirements composable. It does not synthesize an
- * event or introduce an application-owned announcement queue.
- *
- * ## Ownership and lifetime
- *
- * Calling `Alert` starts no work. Running the returned Fx owns the rendered
- * host, dynamic values, and listeners in its Effect Scope; finalization removes
- * only those resources. A custom host must preserve the supplied `role`.
+ * Keep the region mounted and change its text when an urgent event occurs. Initial page content
+ * or repeated identical messages may not announce as expected. This primitive does not queue
+ * announcements, schedule dismissal, or provide an acknowledgement dialog. Prefer a status
+ * region for routine updates.
  *
  * @example
  * ```ts
- * import { Alert } from "@typed/ui/Alert"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Alert } from "@typed/ui/Alert";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
  *
- * const saved = Alert({ content: "Changes saved" })
+ * export const AlertPreview = component(function* () {
+ *   const message = yield* RefSubject.make("");
+ *   return html`<section>
+ *     <p>Preview the message shown when an upload fails.</p>
+ *     ${Button({
+ *       content: "Preview upload failure",
+ *       onclick: RefSubject.set(message, "Upload failed. Your file is still available; try again."),
+ *     })}
+ *     ${Alert({ content: message, props: { class: "upload-alert" } })}
+ *   </section>`;
+ * });
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 export declare function Alert<const Options extends AlertOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, AlertInternalProps>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 export {};

package/dist/Alert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Alert.d.ts","sourceRoot":"","sources":["../src/Alert.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;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IACnE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED,iBAAS,aAAa;aACX,IAAI,EAAE,OAAO;EACvB;AACD,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAChD,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":"Alert.d.ts","sourceRoot":"","sources":["../src/Alert.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;CAClC;AAED,iBAAS,aAAa;aACX,IAAI,EAAE,OAAO;EACvB;AACD,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAChD,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/Alert.js

@@ -4,33 +4,36 @@ function internalProps() {
     return { role: "alert" };
 }
 /**
- * Renders a non-modal, assertive live region.
- *
- * For an interrupting confirmation, use `Dialog.Content` with
- * `role="alertdialog"`; an alert must not take focus or require dismissal.
+ * Renders an assertive alert region without moving focus.
  *
  * @remarks
- * ## Why
- *
- * `Alert` supplies the native ARIA live-region contract while leaving content,
- * host choice, and Effect requirements composable. It does not synthesize an
- * event or introduce an application-owned announcement queue.
- *
- * ## Ownership and lifetime
- *
- * Calling `Alert` starts no work. Running the returned Fx owns the rendered
- * host, dynamic values, and listeners in its Effect Scope; finalization removes
- * only those resources. A custom host must preserve the supplied `role`.
+ * Keep the region mounted and change its text when an urgent event occurs. Initial page content
+ * or repeated identical messages may not announce as expected. This primitive does not queue
+ * announcements, schedule dismissal, or provide an acknowledgement dialog. Prefer a status
+ * region for routine updates.
  *
  * @example
  * ```ts
- * import { Alert } from "@typed/ui/Alert"
- *
- * const saved = Alert({ content: "Changes saved" })
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Alert } from "@typed/ui/Alert";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
+ *
+ * export const AlertPreview = component(function* () {
+ *   const message = yield* RefSubject.make("");
+ *   return html`<section>
+ *     <p>Preview the message shown when an upload fails.</p>
+ *     ${Button({
+ *       content: "Preview upload failure",
+ *       onclick: RefSubject.set(message, "Upload failed. Your file is still available; try again."),
+ *     })}
+ *     ${Alert({ content: message, props: { class: "upload-alert" } })}
+ *   </section>`;
+ * });
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 export function Alert(options, host) {
     return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);

package/dist/Button.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Native command activation and explicit button/submit/reset behavior.
+ * The control has no internal click action; return application Effects from its handler.
+ *
+ * Read the [Button guide](/explore/ui-button) for a complete example.
+ *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+ * @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";
@@ -7,103 +18,44 @@ import type { HostResult } from "./Dom/Types.js";
  * Native button submission behavior.
  *
  * @remarks
- * ## Why
- *
  * The union exposes the exact HTML button types and defaults components to the
  * non-submitting `button` behavior.
- *
- * ## Ownership and lifetime
- *
- * This is a pure type and acquires no resources.
- *
  * @since 1.0.0
- * @category models
+ * @category State models
  */
 export type ButtonType = "button" | "submit" | "reset";
 /**
  * Renderable state and host options for a native button.
  *
  * @remarks
- * ## Why
- *
  * The model keeps native button semantics while allowing content, disabled
  * state, and handlers to come from any Typed renderable source.
- *
- * ## Ownership and lifetime
- *
- * The options are inert. The rendered component's Scope owns dynamic option
- * subscriptions and listener cleanup.
- *
  * @since 1.0.0
- * @category models
+ * @category Component options
  */
 export interface ButtonOptions extends Dom.HostOptions<HTMLButtonElement> {
     /**
      * The button's visible and accessible content.
-     *
-     * @remarks
-     * ## Why
-     *
-     * Native content supplies the accessible name unless the host explicitly
-     * provides another naming mechanism.
-     *
-     * ## Ownership and lifetime
-     *
-     * Dynamic content is subscribed to only while the component Scope is open.
-     *
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /**
      * The native `type` attribute; defaults to `"button"`.
-     *
-     * @remarks
-     * ## Why
-     *
-     * An explicit non-submitting default prevents a reusable button from
-     * accidentally submitting an enclosing form.
-     *
-     * ## Ownership and lifetime
-     *
-     * The value is reflected by the renderer and retains no resources.
-     *
      * @since 1.0.0
-     * @category attributes
+     * @category Native attributes
      */
     readonly type?: Renderable.Any<ButtonType | null | undefined>;
     /**
      * Whether the native control is disabled.
-     *
-     * @remarks
-     * ## Why
-     *
-     * Using the native disabled state removes the button from interaction and
-     * form submission according to browser semantics.
-     *
-     * ## Ownership and lifetime
-     *
-     * Dynamic values are observed for the component Scope and then released.
-     *
      * @since 1.0.0
-     * @category attributes
+     * @category Availability
      */
     readonly disabled?: Renderable.Any<boolean | null | undefined>;
     /**
      * A real DOM click handler supplied by the consumer.
-     *
-     * @remarks
-     * ## Why
-     *
-     * `Button` has no internal activation handler. The supplied handler receives
-     * the real DOM click event; browser default actions remain native.
-     *
-     * ## Ownership and lifetime
-     *
-     * Rendering installs the listener and the component Scope removes it.
-     *
      * @since 1.0.0
-     * @category events
+     * @category Event handlers
      */
     readonly onclick?: Dom.EventHandlerInput<Dom.EventOf<HTMLButtonElement["onclick"]>>;
 }
@@ -116,28 +68,32 @@ type ButtonInternalProps<Options extends ButtonOptions> = ReturnType<typeof inte
  * Renders a semantic native button with cooperative host customization.
  *
  * @remarks
- * ## Why
- *
  * `Button` retains browser keyboard, form, focus, and accessibility behavior.
  * Its internal props only establish the default type and disabled state. Any
  * `onclick` behavior belongs entirely to the consumer and receives a real DOM
  * event; there is no component-internal click action to chain or cancel.
  *
- * ## Ownership and lifetime
- *
- * Calling the factory is inert. Running its Fx owns the host's dynamic parts
- * and listeners in an Effect Scope. A custom host must apply the supplied props
- * and content so disabled and button-type semantics are not lost.
- *
  * @example
  * ```ts
- * import { Button } from "@typed/ui/Button"
- *
- * const submit = Button({ type: "submit", content: "Save" })
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
+ *
+ * export const PreviewCounter = component(function* () {
+ *   const previews = yield* RefSubject.make(0);
+ *   return html`<section>
+ *     ${Button({
+ *       content: "Recalculate preview",
+ *       props: { class: "preview-action" },
+ *       onclick: RefSubject.update(previews, (count) => count + 1),
+ *     })}
+ *     <p role="status">Preview calculations: ${previews}</p>
+ *   </section>`;
+ * });
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare function Button<const Options extends ButtonOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ButtonInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 export {};

package/dist/Button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../src/Button.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;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAc,SAAQ,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC;IACvE;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC9D;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC/D;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACrF;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,EAC1D,QAAQ,GACT,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IAEhC,IAAI;IACJ,WAAW;EAEd;AAED,KAAK,mBAAmB,CAAC,OAAO,SAAS,aAAa,IAAI,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC/F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,EAC1D,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":"Button.d.ts","sourceRoot":"","sources":["../src/Button.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,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAc,SAAQ,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC;IACvE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACrF;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,EAC1D,QAAQ,GACT,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IAEhC,IAAI;IACJ,WAAW;EAEd;AAED,KAAK,mBAAmB,CAAC,OAAO,SAAS,aAAa,IAAI,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC/F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,EAC1D,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/Button.js

@@ -10,28 +10,32 @@ function internalProps({ property, }) {
  * Renders a semantic native button with cooperative host customization.
  *
  * @remarks
- * ## Why
- *
  * `Button` retains browser keyboard, form, focus, and accessibility behavior.
  * Its internal props only establish the default type and disabled state. Any
  * `onclick` behavior belongs entirely to the consumer and receives a real DOM
  * event; there is no component-internal click action to chain or cancel.
  *
- * ## Ownership and lifetime
- *
- * Calling the factory is inert. Running its Fx owns the host's dynamic parts
- * and listeners in an Effect Scope. A custom host must apply the supplied props
- * and content so disabled and button-type semantics are not lost.
- *
  * @example
  * ```ts
- * import { Button } from "@typed/ui/Button"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/ui/Component";
  *
- * const submit = Button({ type: "submit", content: "Save" })
+ * export const PreviewCounter = component(function* () {
+ *   const previews = yield* RefSubject.make(0);
+ *   return html`<section>
+ *     ${Button({
+ *       content: "Recalculate preview",
+ *       props: { class: "preview-action" },
+ *       onclick: RefSubject.update(previews, (count) => count + 1),
+ *     })}
+ *     <p role="status">Preview calculations: ${previews}</p>
+ *   </section>`;
+ * });
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Button(options, host) {
     return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<button ...${props}>${content}</button>`);