@typed/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/Link.d.ts

@@ -1,36 +1,71 @@
-import * as Effect from "effect/Effect";
 import type { Scope } from "effect/Scope";
-import type { Stream } from "effect/Stream";
-import { type Fx } from "@typed/fx/Fx";
-import { EventHandler, type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
-type EventHandlerProperty = `on${string}`;
-type AnchorEventHandlers = {
-    readonly [K in keyof HTMLAnchorElement as K extends EventHandlerProperty ? K : never]?: Effect.Effect<unknown, any, any> | EventHandler.EventHandler<Event, any, any>;
-};
-type AnchorRef = {
-    readonly ref?: (element: HTMLAnchorElement) => void | Effect.Effect<unknown, any, any> | Stream<unknown, any, any> | Fx<unknown, any, any>;
-};
-type IfEquals<X, Y, Output> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? Output : never;
-type WritableKeys<T> = {
-    [P in keyof T]-?: IfEquals<{
-        [Q in P]: T[P];
-    }, {
-        -readonly [Q in P]: T[P];
-    }, P>;
-}[keyof T];
-type AnchorProperties = {
-    readonly [K in WritableKeys<HTMLAnchorElement> as K extends EventHandlerProperty | "ref" ? never : K]?: Renderable<HTMLAnchorElement[K], any, any>;
-};
-export interface LinkOptions extends AnchorEventHandlers, AnchorRef, AnchorProperties {
+import * as Fx from "@typed/fx/Fx";
+import { type NavigationError, Navigation } from "@typed/navigation";
+import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * Native anchor options plus Typed navigation behavior.
+ *
+ * @remarks
+ * `href` and content remain renderable, while `replace` selects history policy.
+ * Ordinary anchor options—including target, download, rel, and user click
+ * handlers—stay available through the DOM host model.
+ * @since 1.0.0
+ * @category Component options
+ */
+export type LinkOptions = Dom.HostOptions<HTMLAnchorElement> & {
     readonly href: Renderable<string, any, any>;
     readonly content: Renderable<string | number | boolean | null | undefined | void | RenderEvent, any, any>;
     readonly replace?: boolean;
-}
+};
+type LinkError<Options extends object> = Renderable.ErrorFromObject<Options> | NavigationError;
+type LinkServices<Options extends object> = Renderable.ServicesFromObject<Options> | Navigation | Scope | RenderTemplate;
 /**
- * Renders an `<a href="...">` that intercepts same-origin, same-document clicks
- * and navigates via `Navigation.navigate` instead of full page load. Requires
- * `Navigation` and `RenderTemplate` in the Effect context (e.g. `BrowserRouter`).
+ * Renders a native anchor with safe, eligible same-origin SPA navigation.
+ *
+ * Modified clicks, downloads, external URLs, non-HTTP(S) destinations, and
+ * non-self targets retain browser behavior. Unsafe executable schemes are
+ * rendered as `about:blank` and their clicks are canceled. A user click handler
+ * runs first through DOM host event chaining; `preventDefault()` prevents the
+ * internal navigation decision.
+ *
+ * @remarks
+ * `Link` keeps the anchor as the integration boundary: native opening, copying,
+ * status previews, modifier keys, downloads, and external navigation continue
+ * to work. Only an unmodified primary click to same-origin HTTP(S) is handed to
+ * Typed's Effect-native `Navigation` service.
+ *
+ * Calling `Link` starts no work. Running the returned Fx subscribes to dynamic
+ * href/content and installs a real, non-passive DOM click listener in its
+ * Effect Scope. Scope finalization removes only those resources. Navigation
+ * failures and required services remain visible in the Fx type. A custom host
+ * must preserve the sanitized href, chained click handler, content, and native
+ * anchor behavior.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { Link } from "@typed/ui/Link";
+ *
+ * export const AccountLinks = html`<nav aria-label="Account">
+ *     ${Link({ href: "/account/profile", content: "Edit profile" })}
+ *     ${Link({
+ *       href: "/account/security",
+ *       content: "Security settings",
+ *       replace: false,
+ *     })}
+ *     ${Link({
+ *       href: "https://www.w3.org/WAI/",
+ *       content: "Accessibility resources (opens in a new tab)",
+ *       props: { target: "_blank", rel: "noopener" },
+ *     })}
+ *   </nav>`;
+ * ```
+ * @since 1.0.0
+ * @category Native controls
  */
-export declare function Link<const Opts extends LinkOptions>(options: Opts): Fx<RenderEvent, Renderable.ErrorFromObject<Opts>, Renderable.ServicesFromObject<Opts> | Scope | RenderTemplate>;
+export declare function Link<const Options extends object>(options: Options, ..._: Options extends LinkOptions ? [] : ["Link options must satisfy LinkOptions"]): Fx.Fx<RenderEvent, LinkError<Options>, LinkServices<Options>>;
+export declare function Link<const Options extends object, const Host extends HostResult>(options: Options, host: Dom.HostOverride<Dom.HostProps<HTMLAnchorElement>, Renderable.Any, Host>, ..._: Options extends LinkOptions ? [] : ["Link options must satisfy LinkOptions"]): Fx.Fx<RenderEvent, LinkError<Options> | Fx.Error<Host>, LinkServices<Options> | Fx.Services<Host>>;
 export {};
 //# sourceMappingURL=Link.d.ts.map

package/dist/Link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Link.d.ts","sourceRoot":"","sources":["../src/Link.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,EAAO,MAAM,cAAc,CAAC;AAG5C,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,KAAK,oBAAoB,GAAG,KAAK,MAAM,EAAE,CAAC;AAE1C,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,CAAC,IAAI,MAAM,iBAAiB,IAAI,CAAC,SAAS,oBAAoB,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAClF,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAChC,YAAY,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC;CAC/C,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,GAAG,CAAC,EAAE,CACb,OAAO,EAAE,iBAAiB,KACvB,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CAClG,CAAC;AAEF,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,IACxB,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvF,KAAK,YAAY,CAAC,CAAC,IAAI;KACpB,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KAAE,EAAE;QAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KAAE,EAAE,CAAC,CAAC;CAChF,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,KAAK,gBAAgB,GAAG;IACtB,QAAQ,EAAE,CAAC,IAAI,YAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,oBAAoB,GAAG,KAAK,GACpF,KAAK,GACL,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC;CACpD,CAAC;AAEF,MAAM,WAAW,WAAY,SAAQ,mBAAmB,EAAE,SAAS,EAAE,gBAAgB;IACnF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,UAAU,CAC1B,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,EACjE,GAAG,EACH,GAAG,CACJ,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAyBD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,SAAS,WAAW,EACjD,OAAO,EAAE,IAAI,GACZ,EAAE,CACH,WAAW,EACX,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,EAChC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,cAAc,CAC7D,CAqBA"}
+{"version":3,"file":"Link.d.ts","sourceRoot":"","sources":["../src/Link.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,KAAK,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,GAAG;IAC7D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,UAAU,CAC1B,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,EACjE,GAAG,EACH,GAAG,CACJ,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,KAAK,SAAS,CAAC,OAAO,SAAS,MAAM,IAAI,UAAU,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,eAAe,CAAC;AAE/F,KAAK,YAAY,CAAC,OAAO,SAAS,MAAM,IACpC,UAAU,CAAC,kBAAkB,CAAC,OAAO,CAAC,GACtC,UAAU,GACV,KAAK,GACL,cAAc,CAAC;AAsDnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EAC/C,OAAO,EAAE,OAAO,EAChB,GAAG,CAAC,EAAE,OAAO,SAAS,WAAW,GAAG,EAAE,GAAG,CAAC,uCAAuC,CAAC,GACjF,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AACjE,wBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,EAC9E,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAC9E,GAAG,CAAC,EAAE,OAAO,SAAS,WAAW,GAAG,EAAE,GAAG,CAAC,uCAAuC,CAAC,GACjF,EAAE,CAAC,EAAE,CACN,WAAW,EACX,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EACnC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAC1C,CAAC"}

package/dist/Link.js

@@ -1,45 +1,92 @@
+/**
+ * Native anchors with selective same-origin Navigation interception.
+ * Modified clicks, external links, downloads, and non-self targets retain native behavior.
+ *
+ * Read the [Link guide](/explore/ui-link) for a complete example.
+ *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/link/).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
 import * as Effect from "effect/Effect";
-import { gen } from "@typed/fx/Fx";
-import { RefSubject } from "@typed/fx/RefSubject";
-import { getUrl, Navigation } from "@typed/navigation";
+import * as Stream from "effect/Stream";
+import * as Fx from "@typed/fx/Fx";
+import { Navigation } from "@typed/navigation";
 import { EventHandler, html, } from "@typed/template";
-function makeLinkClickHandler(replace$) {
-    return EventHandler.make((ev) => Effect.gen(function* () {
-        const href = ev.currentTarget.href;
-        if (ev.ctrlKey || ev.metaKey || ev.shiftKey)
+import * as Dom from "./Dom.js";
+function makeLinkClickHandler(replace) {
+    // Classification and native cancellation must run during event dispatch;
+    // only the resulting router navigation is lazy.
+    return EventHandler.make((event) => {
+        const anchor = Dom.currentTarget(event);
+        const href = anchor.href;
+        if (event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.altKey ||
+            event.ctrlKey ||
+            event.shiftKey)
+            return;
+        const target = anchor.target;
+        if (target && target !== "_self")
             return;
-        const t = ev.currentTarget.target;
-        if (t && t !== "_self")
+        if (anchor.hasAttribute("download"))
             return;
-        const nav = yield* Navigation;
-        const target = getUrl(nav.origin, href);
-        if (target.origin !== nav.origin)
+        if (!isSafeLinkHref(href)) {
+            event.preventDefault();
             return;
-        ev.preventDefault();
-        const replace = yield* replace$;
-        yield* nav.navigate(href, { history: replace ? "replace" : "push" });
-    }));
+        }
+        const destination = new URL(href);
+        if (destination.protocol !== "http:" && destination.protocol !== "https:")
+            return;
+        if (destination.origin !== anchor.ownerDocument.defaultView?.location.origin)
+            return;
+        event.preventDefault();
+        return Effect.flatMap(Navigation, (navigation) => navigation.navigate(href, { history: replace ? "replace" : "push" }));
+    }, { passive: false });
 }
-/**
- * Renders an `<a href="...">` that intercepts same-origin, same-document clicks
- * and navigates via `Navigation.navigate` instead of full page load. Requires
- * `Navigation` and `RenderTemplate` in the Effect context (e.g. `BrowserRouter`).
- */
-export function Link(options) {
-    return gen(function* () {
-        const { replace = false, onclick, content: children, ...rest } = options;
-        const replace$ = yield* RefSubject.make(replace);
-        const navigationHandler = makeLinkClickHandler(replace$);
-        const userHandler = onclick ? EventHandler.fromEffectOrEventHandler(onclick) : undefined;
-        const clickHandler = userHandler
-            ? EventHandler.make(Effect.fn(function* (ev) {
-                yield* userHandler.handler(ev);
-                if (ev.defaultPrevented)
-                    return;
-                yield* navigationHandler.handler(ev);
-            }), { ...userHandler.options, preventDefault: true })
-            : navigationHandler;
-        const props = { ...rest, onclick: clickHandler };
-        return html `<a ...${props}>${children}</a>`;
+function internalProps(options) {
+    return () => ({
+        href: sanitizeLinkHref(options.href),
+        onclick: makeLinkClickHandler(options.replace ?? false),
     });
 }
+// Keep the implementation erased: constraining it to LinkOptions widens the
+// Renderable `any` slots and loses the exact error/service inference above.
+export function Link(options, host, ..._) {
+    const render = Dom.renderHost();
+    return render(options, host, internalProps(options), options.content, (props, content) => html `<a ...${props}>${content}</a>`);
+}
+function sanitizeLinkHref(href) {
+    if (Fx.isFx(href))
+        return Fx.map(href, neutralizeExecutableHref);
+    if (Stream.isStream(href)) {
+        return Stream.map(href, neutralizeExecutableHref);
+    }
+    if (Effect.isEffect(href))
+        return Effect.map(href, neutralizeExecutableHref);
+    if (Array.isArray(href)) {
+        return href.map((value) => sanitizeLinkHref(value));
+    }
+    return (typeof href === "string" ? neutralizeExecutableHref(href) : href);
+}
+function neutralizeExecutableHref(href) {
+    return isSafeLinkHref(href) ? href : "about:blank";
+}
+function isSafeLinkHref(href) {
+    try {
+        switch (new URL(href, "http://localhost").protocol) {
+            case "http:":
+            case "https:":
+            case "mailto:":
+            case "tel:":
+                return true;
+            default:
+                return false;
+        }
+    }
+    catch {
+        return false;
+    }
+}

package/dist/Listbox.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Listbox separates active and selected values, registers options in a Collection, and combines
+ * vertical keyboard movement with buffered typeahead. It supports roving focus by default and uses
+ * real focus, keydown, and click events.
+ *
+ * @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.
+ *
+ * Learn the interaction in the [Listbox guide](/explore/ui-listbox).
+ *
+ * @since 1.0.0
+ * @category modules
+ * @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";
+/**
+ * The committed single value and the option currently owning keyboard focus.
+ * Normal option focus and movement update both values; the DOM ID and saved value may differ.
+ *
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+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 Current value
+     */
+    readonly value: string | null;
+}
+/**
+ * Initial Listbox values. value and activeId default to null, loop defaults to true, and roving
+ * focus is used.
+ *
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+export interface InitialState {
+    /**
+     * Current semantic value selected or edited by the widget.
+     * @since 1.0.0
+     * @category Current value
+     */
+    readonly value?: string | null;
+    /**
+     * 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 Listbox state.
+ *
+ * @remarks
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Listbox from "@typed/ui/Listbox";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Listbox.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+export declare const StateSchema: Schema.Struct<{
+    readonly value: Schema.NullOr<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 Listbox state. value and activeId default to null, loop defaults to true, and
+ * roving focus is used.
+ *
+ * @remarks
+ * 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 Listbox from "@typed/ui/Listbox";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Listbox.makeState({});
+ *     const collection = yield* Listbox.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+export declare function makeState(initial?: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
+    readonly value: string | null;
+    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 Listbox items.
+ *
+ * @remarks
+ * 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 Listbox from "@typed/ui/Listbox";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Listbox.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Option registration
+ */
+export declare const makeCollection: (initial?: Collection.State<string, Element>) => Effect.Effect<RefSubject.RefSubject<Collection.State<string, Element>, never, never>, never, Scope.Scope>;
+/**
+ * Sets both activeId and selected value in one update.
+ *
+ * @remarks
+ * The operation exposes Listbox's transition directly so callers can compose it in Effect programs
+ * and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+export declare function select<E, R>(state: RefSubject.RefSubject<State, E, R>, id: string, value: string): Effect.Effect<State, E, R>;
+/**
+ * Moves through the registered options, synchronizes value when the target has one, then focuses
+ * and scrolls the active option.
+ *
+ * @remarks
+ * The operation exposes Listbox's transition directly so callers can compose it in Effect programs
+ * and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Selection and focus
+ */
+export declare function move(state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>, collection: RefSubject.RefSubject<Collection.State<string>>, direction: Composite.Move): Effect.Effect<State, Schema.SchemaError>;
+/**
+ * Inputs accepted by Listbox.Root in addition to the shared DOM host options.
+ *
+ * @since 1.0.0
+ * @category Listbox surface
+ */
+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 rootProps<const Options extends RootOptions>(options: Options): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly role: "listbox";
+    readonly "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    readonly "aria-activedescendant": RefSubject.Computed<string | undefined, Schema.SchemaError, never>;
+    readonly tabindex: RefSubject.Computed<-1 | 0, Schema.SchemaError, never>;
+    readonly onfocus: Effect.Effect<void, Schema.SchemaError, never> | undefined;
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, Schema.SchemaError, never> | undefined;
+    readonly ref: RefSubject.HydratedRefSubject<State, Schema.SchemaError, never, never>;
+};
+type RootProps<Options extends RootOptions> = ReturnType<ReturnType<typeof rootProps<Options>>>;
+/**
+ * Renders the listbox root, initializes selection on focus, and handles vertical movement and
+ * typeahead in DOM order.
+ *
+ * @remarks
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Listbox surface
+ */
+export declare function Root<const Options extends RootOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RootProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Inputs accepted by Listbox.Option in addition to the shared DOM host options.
+ *
+ * @since 1.0.0
+ * @category Selectable options
+ */
+export interface OptionOptions 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>>;
+    /**
+     * 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 Current value
+     */
+    readonly value: string;
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Search text used by typeahead independently of rendered markup.
+     * @since 1.0.0
+     * @category Text matching
+     */
+    readonly textValue?: 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 optionProps<const Options extends OptionOptions>(options: Options): () => {
+    readonly id: string;
+    readonly role: "option";
+    readonly "aria-selected": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly "aria-disabled": boolean;
+    readonly tabindex: RefSubject.Computed<-1 | 0, Schema.SchemaError, never>;
+    readonly onclick: Effect.Effect<void, never, never> | Effect.Effect<State, Schema.SchemaError, never>;
+    readonly onfocus: Effect.Effect<void, never, never> | Effect.Effect<State, Schema.SchemaError, never>;
+    readonly ref: ((element: Element & HTMLDivElement & RefSubject.HydrationElement) => Effect.Effect<void, any, any>) | undefined;
+};
+type OptionProps<Options extends OptionOptions> = ReturnType<ReturnType<typeof optionProps<Options>>>;
+/**
+ * Renders and optionally registers an option; focus or click selects it unless disabled.
+ *
+ * @remarks
+ * 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.
+ *
+ * @since 1.0.0
+ * @category Selectable options
+ */
+export declare function Option<const Options extends OptionOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, OptionProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+export {};
+//# sourceMappingURL=Listbox.d.ts.map

package/dist/Listbox.d.ts.map

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