@typed/ui 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/RadioGroup.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Native radio selection with optional registered keyboard movement.
+ * Choice values, element IDs, and shared native names have distinct responsibilities.
+ *
+ * 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 Overview
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import * as Schema from "effect/Schema";
+import type { Fx } from "@typed/fx/Fx";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Composite from "./Composite.js";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * Selected choice plus the active element used for keyboard movement.
+ *
+ * @remarks
+ * value need not equal activeId. Orientation is vertical, virtualFocus is false, and the native
+ * inputs retain their own browser grouping by name.
+ * @since 1.0.0
+ * @category State models
+ */
+export interface State extends Omit<Composite.State, "orientation"> {
+    /**
+     * Axis used to interpret Arrow-key movement.
+     * @since 1.0.0
+     * @category Keyboard navigation
+     */
+    readonly orientation: "vertical";
+    /**
+     * Current semantic value selected or edited by the widget.
+     * @since 1.0.0
+     * @category Value state
+     */
+    readonly value: string;
+}
+/**
+ * Required selected value with optional initial active ID and wrap policy.
+ *
+ * @remarks
+ * activeId defaults to null; loop defaults to true. Supply an element ID only when the initial
+ * active choice is known.
+ * @since 1.0.0
+ * @category State models
+ */
+export interface InitialState {
+    /**
+     * Current semantic value selected or edited by the widget.
+     * @since 1.0.0
+     * @category Value state
+     */
+    readonly value: string;
+    /**
+     * Id currently active for keyboard navigation; null means no active item.
+     * @since 1.0.0
+     * @category Keyboard focus
+     */
+    readonly activeId?: string | null;
+    /**
+     * Whether movement wraps between the first and last enabled items.
+     * @since 1.0.0
+     * @category Keyboard navigation
+     */
+    readonly loop?: boolean;
+}
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate RadioGroup state.
+ *
+ * @remarks
+ * A public schema makes hydration and serialized state use the same runtime validation as direct
+ * construction.
+ *
+ * @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 Hydration schemas
+ */
+export declare const StateSchema: Schema.Struct<{
+    readonly value: Schema.String;
+    readonly activeId: Schema.NullOr<Schema.String>;
+    readonly orientation: Schema.Literals<readonly ["vertical"]>;
+    readonly loop: Schema.Boolean;
+    readonly rtl: Schema.Boolean;
+    readonly virtualFocus: Schema.Boolean;
+}>;
+/**
+ * Creates hydrated radio selection with a required value, null active ID, and looping enabled by
+ * default.
+ *
+ * @remarks
+ * 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
+ * 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 State construction
+ */
+export declare function makeState(initial: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
+    readonly value: string;
+    readonly activeId: string | null;
+    readonly orientation: "vertical";
+    readonly loop: boolean;
+    readonly rtl: boolean;
+    readonly virtualFocus: boolean;
+}, Schema.SchemaError, never, never>, never, Scope.Scope>;
+/**
+ * Creates a scoped Collection for RadioGroup items.
+ *
+ * @remarks
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * 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 State construction
+ */
+export declare const makeCollection: (initial?: Collection.State<string, Element>) => Effect.Effect<RefSubject.RefSubject<Collection.State<string, Element>, never, never>, never, Scope.Scope>;
+/**
+ * Sets the selected value and optionally the active element ID.
+ *
+ * @remarks
+ * 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 State transitions
+ */
+export declare function setValue<E, R>(state: RefSubject.RefSubject<State, E, R>, value: string, activeId?: string): Effect.Effect<State, E, R>;
+/**
+ * State, optional navigation collection, child content, and group name.
+ *
+ * @remarks
+ * Share the same collection with Item to enable registered keyboard movement. label names the
+ * group; each item still needs its own label.
+ * @since 1.0.0
+ * @category Component options
+ */
+export interface RootOptions extends Dom.HostOptions<HTMLDivElement> {
+    /**
+     * Renderer-independent RefSubject state consumed by this component or operation.
+     * @since 1.0.0
+     * @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 Item registration
+     */
+    readonly collection?: RefSubject.RefSubject<Collection.State<string>>;
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Accessible label rendered through aria-label.
+     * @since 1.0.0
+     * @category Accessible naming
+     */
+    readonly label?: Renderable.Any<string | null | undefined>;
+}
+declare function rootInternalProps<const Options extends RootOptions>(options: Options): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly role: "radiogroup";
+    readonly "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, Schema.SchemaError, never> | undefined;
+    readonly ref: RefSubject.HydratedRefSubject<State, Schema.SchemaError, never, never>;
+};
+type RootInternalProps<Options extends RootOptions> = ReturnType<ReturnType<typeof rootInternalProps<Options>>>;
+/**
+ * Renders a named radiogroup around native radio items.
+ *
+ * @remarks
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/template";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
+ *
+ * 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 Native controls
+ */
+export declare function Root<const Options extends RootOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RootInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * One native choice with stable element ID, application value, and native group name.
+ *
+ * @remarks
+ * Use the same state and name across one radio group, unique IDs across the document, and distinct
+ * values across choices. disabled is a boolean used by both rendering and registration.
+ * @since 1.0.0
+ * @category Component options
+ */
+export interface ItemOptions extends Dom.HostOptions<HTMLInputElement> {
+    /**
+     * Renderer-independent RefSubject state consumed by this component or operation.
+     * @since 1.0.0
+     * @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 Item registration
+     */
+    readonly collection?: RefSubject.RefSubject<Collection.State<string>>;
+    /**
+     * Stable id used for collection identity and ARIA relationships.
+     * @since 1.0.0
+     * @category Identity and relationships
+     */
+    readonly id: string;
+    /**
+     * Current semantic value selected or edited by the widget.
+     * @since 1.0.0
+     * @category Value state
+     */
+    readonly value: string;
+    /**
+     * Native radio-group form name shared by related input items.
+     * @since 1.0.0
+     * @category Native form data
+     */
+    readonly name?: string;
+    /**
+     * Flag used by collection movement and widget handlers to skip activation by default.
+     * @since 1.0.0
+     * @category Availability
+     */
+    readonly disabled?: boolean;
+}
+declare function itemInternalProps<const Options extends ItemOptions>(options: Options): () => {
+    readonly id: string;
+    readonly type: "radio";
+    readonly role: "radio";
+    readonly name: string | undefined;
+    readonly value: string;
+    readonly "?disabled": boolean;
+    readonly "aria-checked": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly "aria-disabled": boolean;
+    readonly "?checked": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly ".checked": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly onchange: Effect.Effect<void, never, never> | Effect.Effect<State, Schema.SchemaError, never>;
+    readonly ref: ((element: Element & HTMLInputElement & RefSubject.HydrationElement) => Effect.Effect<void, any, any>) | undefined;
+};
+type ItemInternalProps<Options extends ItemOptions> = ReturnType<ReturnType<typeof itemInternalProps<Options>>>;
+/**
+ * Renders one native radio input and optionally registers it for group navigation.
+ *
+ * @remarks
+ * 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 Native controls
+ */
+export declare function Item<const Options extends ItemOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ItemInternalProps<Options>>, "", Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Alias of Root.
+ *
+ * @remarks
+ * 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 Native controls
+ */
+export declare const RadioGroup: typeof Root;
+export {};
+//# sourceMappingURL=RadioGroup.d.ts.map

package/dist/RadioGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RadioGroup.d.ts","sourceRoot":"","sources":["../src/RadioGroup.ts"],"names":[],"mappings":"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"}

package/dist/RadioGroup.js

@@ -0,0 +1,241 @@
+/**
+ * Native radio selection with optional registered keyboard movement.
+ * Choice values, element IDs, and shared native names have distinct responsibilities.
+ *
+ * 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 Overview
+ * @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
+ * A public schema makes hydration and serialized state use the same runtime validation as direct
+ * construction.
+ *
+ * @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 Hydration 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 radio selection with a required value, null active ID, and looping enabled by
+ * default.
+ *
+ * @remarks
+ * 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
+ * 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 State construction
+ */
+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
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * 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 State construction
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Sets the selected value and optionally the active element ID.
+ *
+ * @remarks
+ * 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 State transitions
+ */
+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 a named radiogroup around native radio items.
+ *
+ * @remarks
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/template";
+ * import * as RadioGroup from "@typed/ui/RadioGroup";
+ *
+ * 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 Native controls
+ */
+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 one native radio input and optionally registers it for group navigation.
+ *
+ * @remarks
+ * 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 Native controls
+ */
+export function Item(options, host) {
+    return Dom.renderHost()(options, host, itemInternalProps(options), "", (props) => html `<input ...${props} />`);
+}
+/**
+ * Alias of Root.
+ *
+ * @remarks
+ * 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 Native controls
+ */
+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 Semantic hosts
+ */
+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 Rendered 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 Semantic roles
+     */
+    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 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 {};
+//# 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 Semantic hosts
+ */
+export function Role(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}