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

package/dist/Switch.d.ts

@@ -1,68 +1,43 @@
+/**
+ * A button-backed on/off setting with a stable accessible name.
+ * The internal click toggles boolean state; persistence and form serialization remain explicit.
+ *
+ * Read the [Switch guide](/explore/ui-switch) for a complete example.
+ *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { RefSubject } from "@typed/fx";
 import { type Renderable } from "@typed/template";
 import * as Dom from "./Dom.js";
 import type { HostResult } from "./Dom/Types.js";
-/** Current renderer-independent switch state.
- * @remarks
- * ## Why
- * The boolean can be tested and transformed without mounting a button.
- * ## Ownership and lifetime
- * Plain state retains no resources; its RefSubject owns updates by Scope.
- * @since 1.0.0
- * @category state
+/**
  */
 export interface State {
-    /** Whether the switch is on.
-     * @remarks
-     * ## Why
-     * This value drives the required `aria-checked` state.
-     * ## Ownership and lifetime
-     * Plain data acquires no resources.
-     * @since 1.0.0
-     * @category state
+    /**
      */
     readonly checked: boolean;
 }
-/** Optional initial switch state.
- * @remarks
- * ## Why
- * Omission provides a deterministic off state for SSR and clients.
- * ## Ownership and lifetime
- * Configuration is inert.
- * @since 1.0.0
- * @category state
+/**
  */
 export interface InitialState {
-    /** Initial on/off value, defaulting to false.
-     * @remarks
-     * ## Why
-     * The value seeds the serializable hydration contract.
-     * ## Ownership and lifetime
-     * It is copied into state and retains no resource.
-     * @since 1.0.0
-     * @category state
+    /**
      */
     readonly checked?: boolean;
 }
-/** Schema for switch hydration state.
- * @remarks
- * ## Why
- * Shared encoding keeps SSR and browser state compatible.
- * ## Ownership and lifetime
- * The immutable schema acquires no resources.
- * @since 1.0.0
- * @category schemas
+/**
  */
 export declare const StateSchema: Schema.Struct<{
     readonly checked: Schema.Boolean;
 }>;
-/** Creates hydrated switch state independent of rendering.
+/**
+ * Creates hydrated switch state independent of rendering.
  * @remarks
- * ## Why
  * Domain code and tests can own the state while any renderer consumes it.
- * ## Ownership and lifetime
  * The caller's Effect Scope owns the returned RefSubject.
  * @example
  * ```ts
@@ -74,17 +49,13 @@ export declare const StateSchema: Schema.Struct<{
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export declare function makeState(initial?: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly checked: boolean;
 }, Schema.SchemaError, never, never>, never, import("effect/Scope").Scope>;
-/** Sets the switch on/off state.
- * @remarks
- * ## Why
- * Explicit transitions keep state logic outside the renderer.
- * ## Ownership and lifetime
- * The Effect reuses the subject's lifetime and acquires no resource.
+/**
+ * Sets the switch to the requested checked state.
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -96,15 +67,11 @@ export declare function makeState(initial?: InitialState): Effect.Effect<RefSubj
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function setChecked<E, R>(state: RefSubject.RefSubject<State, E, R>, checked: boolean): Effect.Effect<State, E, R>;
-/** Atomically inverts the switch state.
- * @remarks
- * ## Why
- * A RefSubject update prevents stale read-then-write transitions.
- * ## Ownership and lifetime
- * The Effect acquires no resource and uses the existing state Scope.
+/**
+ * Toggles the switch between checked and unchecked.
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -116,38 +83,22 @@ export declare function setChecked<E, R>(state: RefSubject.RefSubject<State, E,
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function toggle<E, R>(state: RefSubject.RefSubject<State, E, R>): Effect.Effect<State, E, R>;
-/** Options for an ARIA switch rendered as a native button.
- * @remarks
- * ## Why
- * Button behavior supplies focus and keyboard activation while ARIA exposes
- * the binary switch semantic.
- * ## Ownership and lifetime
- * Options are inert; rendering owns subscriptions and listeners by Scope.
- * @since 1.0.0
- * @category models
+/**
  */
 export interface SwitchOptions extends Dom.HostOptions<HTMLButtonElement> {
-    /** Hydrated state synchronized with `aria-checked`.
-     * @remarks
-     * ## Why
-     * One source controls SSR, render output, and activation updates.
-     * ## Ownership and lifetime
-     * The component borrows the state; its originating Scope owns it.
+    /**
+     * Hydrated state synchronized with `aria-checked`.
      * @since 1.0.0
-     * @category state
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
-    /** Visible content and accessible name.
-     * @remarks
-     * ## Why
-     * A switch requires an accessible name, normally supplied by its content.
-     * ## Ownership and lifetime
-     * Dynamic content follows the component Scope.
+    /**
+     * Visible content and accessible name.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
 }
@@ -160,27 +111,37 @@ declare function internalProps<const Options extends SwitchOptions>(options: Opt
     readonly ref: RefSubject.HydratedRefSubject<State, Schema.SchemaError, never, never>;
 };
 type SwitchInternalProps<Options extends SwitchOptions> = ReturnType<ReturnType<typeof internalProps<Options>>>;
-/** Renders a button-backed ARIA switch.
+/**
+ * Renders a button-backed ARIA switch.
  * @remarks
- * ## Why
  * The component combines native button activation with a renderer-independent
  * boolean state and real DOM click events.
- * ## Ownership and lifetime
  * Running the Fx owns listener/state subscriptions in its Effect Scope. A
  * custom host must preserve button type, role, `aria-checked`, click handler,
  * and the single hydration ref owner.
  * @example
  * ```ts
- * import { Effect } from "effect"
- * import * as Switch from "@typed/ui/Switch"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/ui/Component";
+ * import * as Switch from "@typed/ui/Switch";
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Switch.makeState()
- *   return Switch.Switch({ state, content: "Notifications" })
- * })
+ * export const PreviewSetting = component(function* () {
+ *   const state = yield* Switch.makeState({ checked: true });
+ *   const status = RefSubject.map(state, ({ checked }) => checked ? "On" : "Off");
+ *   return html`<section>
+ *     ${Switch.Switch({
+ *       state,
+ *       content: "Show live preview",
+ *       props: { class: "preview-switch", "aria-describedby": "preview-setting-help" },
+ *     })}
+ *     <span aria-hidden="true">${status}</span>
+ *     <p id="preview-setting-help">Updates the preview while you edit.</p>
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export declare function Switch<const Options extends SwitchOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, SwitchInternalProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 export {};

package/dist/Switch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../src/Switch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;EAA6C,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,YAAiB;;2EAEnD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EACzC,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAE5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EACzB,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,GACxC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAE5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC;IACvE;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACzE;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,OAAO,EAAE,OAAO,kBACpD,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;aAEnD,IAAI,EAAE,QAAQ;aACd,IAAI,EAAE,QAAQ;aACd,cAAc;aACd,WAAW;aACX,OAAO;aACP,GAAG;EAER;AACD,KAAK,mBAAmB,CAAC,OAAO,SAAS,aAAa,IAAI,UAAU,CAClE,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;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,0DAWF"}
+{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../src/Switch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;GACG;AACH,MAAM,WAAW,KAAK;IACpB;OACG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;GACG;AACH,MAAM,WAAW,YAAY;IAC3B;OACG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;GACG;AACH,eAAO,MAAM,WAAW;;EAA6C,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,YAAiB;;2EAEnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EACzC,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAE5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EACzB,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,GACxC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAE5B;AAED;GACG;AACH,MAAM,WAAW,aAAc,SAAQ,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC;IACvE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACzE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,OAAO,EAAE,OAAO,kBACpD,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;aAEnD,IAAI,EAAE,QAAQ;aACd,IAAI,EAAE,QAAQ;aACd,cAAc;aACd,WAAW;aACX,OAAO;aACP,GAAG;EAER;AACD,KAAK,mBAAmB,CAAC,OAAO,SAAS,aAAa,IAAI,UAAU,CAClE,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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,0DAWF"}

package/dist/Switch.js

@@ -2,21 +2,13 @@ import * as Schema from "effect/Schema";
 import { RefSubject } from "@typed/fx";
 import { html } from "@typed/template";
 import * as Dom from "./Dom.js";
-/** Schema for switch hydration state.
- * @remarks
- * ## Why
- * Shared encoding keeps SSR and browser state compatible.
- * ## Ownership and lifetime
- * The immutable schema acquires no resources.
- * @since 1.0.0
- * @category schemas
+/**
  */
 export const StateSchema = Schema.Struct({ checked: Schema.Boolean });
-/** Creates hydrated switch state independent of rendering.
+/**
+ * Creates hydrated switch state independent of rendering.
  * @remarks
- * ## Why
  * Domain code and tests can own the state while any renderer consumes it.
- * ## Ownership and lifetime
  * The caller's Effect Scope owns the returned RefSubject.
  * @example
  * ```ts
@@ -28,17 +20,13 @@ export const StateSchema = Schema.Struct({ checked: Schema.Boolean });
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export function makeState(initial = {}) {
     return RefSubject.hydrate(StateSchema, { checked: initial.checked ?? false });
 }
-/** Sets the switch on/off state.
- * @remarks
- * ## Why
- * Explicit transitions keep state logic outside the renderer.
- * ## Ownership and lifetime
- * The Effect reuses the subject's lifetime and acquires no resource.
+/**
+ * Sets the switch to the requested checked state.
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -50,17 +38,13 @@ export function makeState(initial = {}) {
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function setChecked(state, checked) {
     return RefSubject.update(state, (current) => ({ ...current, checked }));
 }
-/** Atomically inverts the switch state.
- * @remarks
- * ## Why
- * A RefSubject update prevents stale read-then-write transitions.
- * ## Ownership and lifetime
- * The Effect acquires no resource and uses the existing state Scope.
+/**
+ * Toggles the switch between checked and unchecked.
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -72,7 +56,7 @@ export function setChecked(state, checked) {
  * })
  * ```
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function toggle(state) {
     return RefSubject.update(state, (current) => ({ ...current, checked: !current.checked }));
@@ -87,27 +71,37 @@ function internalProps(options) {
         ref: options.state,
     });
 }
-/** Renders a button-backed ARIA switch.
+/**
+ * Renders a button-backed ARIA switch.
  * @remarks
- * ## Why
  * The component combines native button activation with a renderer-independent
  * boolean state and real DOM click events.
- * ## Ownership and lifetime
  * Running the Fx owns listener/state subscriptions in its Effect Scope. A
  * custom host must preserve button type, role, `aria-checked`, click handler,
  * and the single hydration ref owner.
  * @example
  * ```ts
- * import { Effect } from "effect"
- * import * as Switch from "@typed/ui/Switch"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/ui/Component";
+ * import * as Switch from "@typed/ui/Switch";
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Switch.makeState()
- *   return Switch.Switch({ state, content: "Notifications" })
- * })
+ * export const PreviewSetting = component(function* () {
+ *   const state = yield* Switch.makeState({ checked: true });
+ *   const status = RefSubject.map(state, ({ checked }) => checked ? "On" : "Off");
+ *   return html`<section>
+ *     ${Switch.Switch({
+ *       state,
+ *       content: "Show live preview",
+ *       props: { class: "preview-switch", "aria-describedby": "preview-setting-help" },
+ *     })}
+ *     <span aria-hidden="true">${status}</span>
+ *     <p id="preview-setting-help">Updates the preview while you edit.</p>
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Switch(options, host) {
     return Dom.renderHost()(options, host, internalProps(options), options.content, (props, content) => {