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

package/dist/RadioGroup.js

@@ -0,0 +1,291 @@
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, html, } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Composite from "./Composite.js";
+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";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(RadioGroup.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    value: Schema.String,
+    activeId: Schema.NullOr(Schema.String),
+    orientation: Schema.Literals(["vertical"]),
+    loop: Schema.Boolean,
+    rtl: Schema.Boolean,
+    virtualFocus: Schema.Boolean,
+});
+/**
+ * Creates hydrated RadioGroup state. The caller supplies value; activeId defaults to that value
+ * and loop defaults true.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* RadioGroup.makeState({ value: "email" });
+ *     const collection = yield* RadioGroup.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial) {
+    return RefSubject.hydrate(StateSchema, {
+        value: initial.value,
+        activeId: initial.activeId ?? null,
+        orientation: "vertical",
+        loop: initial.loop ?? true,
+        rtl: false,
+        virtualFocus: false,
+    });
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* RadioGroup.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Sets selected value and activeId to the same registered radio 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.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function setValue(state, value, activeId) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        value,
+        activeId: activeId ?? current.activeId,
+    }));
+}
+function move(state, collection, direction) {
+    return Effect.gen(function* () {
+        const current = yield* state;
+        const items = yield* collection;
+        const activeId = current.activeId ?? items.find((item) => item.value === current.value)?.id ?? null;
+        const nextId = Composite.moveActiveId(items, { ...current, activeId }, direction);
+        const item = nextId === null ? undefined : items.find((item) => item.id === nextId);
+        if (item?.value === undefined)
+            return current;
+        const next = yield* setValue(state, item.value, item.id);
+        yield* Composite.focusActive({ state, collection });
+        return next;
+    });
+}
+function rootInternalProps(options) {
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn(function* (event) {
+            const direction = Composite.keyMove(event, { orientation: "vertical" });
+            if (direction === undefined)
+                return;
+            event.preventDefault();
+            yield* move(options.state, options.collection, direction);
+        }));
+    return ({ property }) => ({
+        role: "radiogroup",
+        "aria-label": property("label", undefined),
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the radiogroup and maps Arrow keys to selection and focus movement.
+ *
+ * @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/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.
+ * @since 1.0.0
+ * @category components
+ */
+export function Root(options, host) {
+    return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function itemInternalProps(options) {
+    const checked = RefSubject.map(options.state, (state) => state.value === options.value);
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.value,
+            textValue: options.value,
+            disabled: options.disabled,
+        });
+    return () => ({
+        id: options.id,
+        type: "radio",
+        role: "radio",
+        name: options.name,
+        value: options.value,
+        "?disabled": options.disabled ?? false,
+        "aria-checked": checked,
+        "aria-disabled": options.disabled ?? false,
+        "?checked": checked,
+        ".checked": checked,
+        onchange: options.disabled === true
+            ? Effect.void
+            : setValue(options.state, options.value, options.id),
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers a native radio input synchronized with selected value.
+ *
+ * @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.
+ * @since 1.0.0
+ * @category components
+ */
+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.
+ *
+ * @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.
+ * @since 1.0.0
+ * @category components
+ */
+export const RadioGroup = Root;

package/dist/Role.d.ts

@@ -0,0 +1,64 @@
+import type * as Scope from "effect/Scope";
+import type { Fx } from "@typed/fx/Fx";
+import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * Options for assigning explicit ARIA semantics to a generic host.
+ * @remarks
+ * ## Why
+ * This primitive keeps role selection visible when no dedicated component
+ * matches the required semantic.
+ * ## Ownership and lifetime
+ * The model acquires no resources; dynamic values follow the rendered Scope.
+ * @since 1.0.0
+ * @category models
+ */
+export interface RoleOptions extends Dom.HostOptions<HTMLDivElement> {
+    /** Content rendered inside the semantic host.
+     * @remarks
+     * ## Why
+     * Native content remains available to the accessibility tree.
+     * ## Ownership and lifetime
+     * Dynamic content follows the component Scope.
+     * @since 1.0.0
+     * @category content
+     */
+    readonly content: Renderable.Any;
+    /** The explicit ARIA role.
+     * @remarks
+     * ## Why
+     * Callers must choose semantics appropriate to their interaction model.
+     * ## Ownership and lifetime
+     * The reflected value retains no resources.
+     * @since 1.0.0
+     * @category accessibility
+     */
+    readonly role: Renderable.Any<string | null | undefined>;
+}
+declare function internalProps<const Options extends RoleOptions>({ property, }: Dom.InternalPropsHelpers<Options>): {
+    role: Exclude<Dom.Property<Options, "role">, Dom.Nullish> | undefined;
+};
+type RoleInternalProps<Options extends RoleOptions> = ReturnType<typeof internalProps<Options>>;
+/**
+ * Renders a generic element with caller-selected ARIA semantics.
+ * @remarks
+ * ## Why
+ * It provides cooperative host composition without pretending every ARIA role
+ * has identical keyboard behavior; the caller remains responsible for the
+ * chosen role's complete accessibility contract.
+ * ## Ownership and lifetime
+ * Running the returned Fx owns dynamic attributes and content until its Effect
+ * Scope closes. A custom host must preserve the supplied role.
+ * @example
+ * ```ts
+ * import { Role } from "@typed/ui/Role"
+ *
+ * const status = Role({ role: "status", content: "Ready" })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+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 {};
+//# sourceMappingURL=Role.d.ts.map

package/dist/Role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Role.d.ts","sourceRoot":"","sources":["../src/Role.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;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAY,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IAClE;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC1D;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAAE,EACxD,QAAQ,GACT,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IACzB,IAAI;EACd;AAED,KAAK,iBAAiB,CAAC,OAAO,SAAS,WAAW,IAAI,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAEhG;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC3F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,EACxD,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,CAcA"}

package/dist/Role.js

@@ -0,0 +1,27 @@
+import { html } from "@typed/template";
+import * as Dom from "./Dom.js";
+function internalProps({ property, }) {
+    return { role: property("role", undefined) };
+}
+/**
+ * Renders a generic element with caller-selected ARIA semantics.
+ * @remarks
+ * ## Why
+ * It provides cooperative host composition without pretending every ARIA role
+ * has identical keyboard behavior; the caller remains responsible for the
+ * chosen role's complete accessibility contract.
+ * ## Ownership and lifetime
+ * Running the returned Fx owns dynamic attributes and content until its Effect
+ * Scope closes. A custom host must preserve the supplied role.
+ * @example
+ * ```ts
+ * import { Role } from "@typed/ui/Role"
+ *
+ * const status = Role({ role: "status", content: "Ready" })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Role(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}