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

package/dist/RadioGroup.js

@@ -1,15 +1,12 @@
 /**
- * RadioGroup keeps a selected value and active id in explicit state. Arrow movement skips disabled
- * registered items, updates selection, and moves focus; each item renders a real radio input with
- * ARIA state.
+ * Native radio selection with optional registered keyboard movement.
+ * Choice values, element IDs, and shared native names have distinct responsibilities.
  *
- * @remarks
- * The module keeps policy, state transitions, and DOM rendering separable so applications can use
- * the state and pure operations without mounting UI, or supply custom hosts without replacing native
- * events and browser-owned focus.
+ * Read the [RadioGroup guide](/explore/ui-radio-group) for a complete example.
  *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
  * @since 1.0.0
- * @category modules
+ * @category Overview
  * @packageDocumentation
  */
 import * as Effect from "effect/Effect";
@@ -23,15 +20,9 @@ import * as Dom from "./Dom.js";
  * Effect Schema used by makeState to encode, decode, and hydrate RadioGroup 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 +31,7 @@ import * as Dom from "./Dom.js";
  * const decodeState = Schema.decodeUnknownEffect(RadioGroup.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Hydration schemas
  */
 export const StateSchema = Schema.Struct({
     value: Schema.String,
@@ -51,19 +42,13 @@ export const StateSchema = Schema.Struct({
     virtualFocus: Schema.Boolean,
 });
 /**
- * Creates hydrated RadioGroup state. The caller supplies value; activeId defaults to that value
- * and loop defaults true.
+ * Creates hydrated radio selection with a required value, null active ID, and looping enabled by
+ * default.
  *
  * @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.
+ * The selected value and element ID are separate. The first keyboard movement can resolve the
+ * selected value against the mounted collection. Creation requires Scope; renderers borrow the
+ * returned subject.
  *
  * @example
  * ```ts
@@ -79,7 +64,7 @@ export const StateSchema = Schema.Struct({
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export function makeState(initial) {
     return RefSubject.hydrate(StateSchema, {
@@ -95,12 +80,8 @@ export function makeState(initial) {
  * Creates a scoped Collection for RadioGroup 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.
  *
@@ -117,31 +98,17 @@ export function makeState(initial) {
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export const makeCollection = Collection.makeState;
 /**
- * Sets selected value and activeId to the same registered radio id.
+ * Sets the selected value and optionally the active element ID.
  *
  * @remarks
- * ## Why
- *
- * The operation exposes RadioGroup'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 { setValue } from "@typed/ui/RadioGroup";` Extend the [RadioGroup.makeState
- * runnable setup](/reference/%40typed%2Fui%2FRadioGroup%23makeState). Inside the linked Effect
- * program invoke `yield* setValue(state, "phone", "phone")`, then read state to observe the checked
- * value and active roving-focus id update together.
+ * Omitting activeId preserves the previous active ID. This state update does not look up an
+ * item, move DOM focus, or verify that the value belongs to the group.
  * @since 1.0.0
- * @category combinators
+ * @category State transitions
  */
 export function setValue(state, value, activeId) {
     return RefSubject.update(state, (current) => ({
@@ -182,28 +149,40 @@ function rootInternalProps(options) {
     });
 }
 /**
- * Renders the radiogroup and maps Arrow keys to selection and focus movement.
+ * Renders a named radiogroup around native radio items.
  *
  * @remarks
- * ## Why
- *
- * The component applies the family behavior while leaving callers free to supply a custom host
- * through the shared DOM boundary.
+ * Pass the same state to every item and the same native name to items in one group. With a
+ * collection, the root handles vertical arrow movement and Home/End, skips disabled
+ * registrations, updates selection, and moves real focus. Without a collection, native input
+ * behavior remains the keyboard 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
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/ui/Component";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
  *
- * Import with `import { Root } from "@typed/ui/RadioGroup";` Extend the [RadioGroup.makeState
- * runnable setup](/reference/%40typed%2Fui%2FRadioGroup%23makeState). Replace the linked program's
- * final snapshot read with `Root({ state, label: "Contact method", content: "Choices" })`; render
- * that Fx before the same Scope closes.
+ * export const DeliveryChoice = component(function* () {
+ *   const state = yield* RadioGroup.makeState({ value: "standard" });
+ *   const collection = yield* RadioGroup.makeCollection();
+ *   return RadioGroup.Root({
+ *     state,
+ *     collection,
+ *     label: "Delivery speed",
+ *     content: html`
+ *       <label>${RadioGroup.Item({
+ *         state, collection, id: "delivery-standard", name: "delivery", value: "standard",
+ *       })} Standard delivery</label>
+ *       <label>${RadioGroup.Item({
+ *         state, collection, id: "delivery-express", name: "delivery", value: "express",
+ *       })} Express delivery</label>
+ *     `,
+ *   });
+ * });
+ * ```
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Root(options, host) {
     return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
@@ -238,54 +217,25 @@ function itemInternalProps(options) {
     });
 }
 /**
- * Renders and optionally registers a native radio input synchronized with selected value.
+ * Renders one native radio input and optionally registers it for group navigation.
  *
  * @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/RadioGroup";` Extend the [RadioGroup.makeState
- * runnable setup](/reference/%40typed%2Fui%2FRadioGroup%23makeState). Replace the linked program's
- * final snapshot read with `Item({ state, id: "email", value: "email", name: "contact" })`; render
- * that Fx before the same Scope closes.
+ * id identifies the element; value identifies the choice; name establishes the native browser
+ * group. A native change updates the selected value and active ID. Supply a wrapping label or an
+ * external label linked to id. Registration ends with the rendered Scope.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Item(options, host) {
     return Dom.renderHost()(options, host, itemInternalProps(options), "", (props) => html `<input ...${props} />`);
 }
 /**
- * Consumer-facing alias of the canonical RadioGroup component with identical behavior and
- * lifetime.
+ * Alias of Root.
  *
  * @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 { RadioGroup } from "@typed/ui/RadioGroup";` Extend the [RadioGroup.makeState
- * runnable setup](/reference/%40typed%2Fui%2FRadioGroup%23makeState). Replace the linked program's
- * final snapshot read with `RadioGroup({ state, label: "Contact method", content: "Choices" })`;
- * render that Fx before the same Scope closes.
+ * The alias exposes the same native-input grouping and optional collection behavior; it introduces
+ * no additional state or focus policy.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const RadioGroup = Root;

package/dist/Role.d.ts

@@ -12,7 +12,7 @@ import type { HostResult } from "./Dom/Types.js";
  * ## Ownership and lifetime
  * The model acquires no resources; dynamic values follow the rendered Scope.
  * @since 1.0.0
- * @category models
+ * @category Semantic hosts
  */
 export interface RoleOptions extends Dom.HostOptions<HTMLDivElement> {
     /** Content rendered inside the semantic host.
@@ -22,7 +22,7 @@ export interface RoleOptions extends Dom.HostOptions<HTMLDivElement> {
      * ## Ownership and lifetime
      * Dynamic content follows the component Scope.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content: Renderable.Any;
     /** The explicit ARIA role.
@@ -32,7 +32,7 @@ export interface RoleOptions extends Dom.HostOptions<HTMLDivElement> {
      * ## Ownership and lifetime
      * The reflected value retains no resources.
      * @since 1.0.0
-     * @category accessibility
+     * @category Semantic roles
      */
     readonly role: Renderable.Any<string | null | undefined>;
 }
@@ -57,7 +57,7 @@ type RoleInternalProps<Options extends RoleOptions> = ReturnType<typeof internal
  * const status = Role({ role: "status", content: "Ready" })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Semantic hosts
  */
 export declare function Role<const Options extends RoleOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RoleInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
 export {};

package/dist/Role.js

@@ -20,7 +20,7 @@ function internalProps({ property, }) {
  * const status = Role({ role: "status", content: "Ready" })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Semantic hosts
  */
 export function Role(options, host) {
     return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);