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

package/dist/Composite.d.ts

@@ -9,7 +9,7 @@
  * events and browser-owned focus.
  *
  * @since 1.0.0
- * @category modules
+ * @category Architecture overview
  * @packageDocumentation
  */
 import * as Effect from "effect/Effect";
@@ -35,7 +35,7 @@ import * as Collection from "./Collection.js";
  * [Composite.makeState runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Choose an
  * axis policy explicitly: `const orientation: Orientation = "horizontal"`.
  * @since 1.0.0
- * @category models
+ * @category Directional movement
  */
 export type Orientation = "horizontal" | "vertical" | "both";
 /**
@@ -57,7 +57,7 @@ export type Orientation = "horizontal" | "vertical" | "both";
  * runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). Choose a supported movement
  * operation explicitly: `const direction: Move = "next"`.
  * @since 1.0.0
- * @category models
+ * @category Directional movement
  */
 export type Move = "next" | "previous" | "first" | "last";
 /**
@@ -80,37 +80,37 @@ export type Move = "next" | "previous" | "first" | "last";
  * `const snapshot: State = yield* state` exposes focus, orientation, looping, RTL, and
  * virtual-focus policy.
  * @since 1.0.0
- * @category models
+ * @category Active item state
  */
 export interface State {
     /**
      * Id currently active for keyboard navigation; null means no active item.
      * @since 1.0.0
-     * @category models
+     * @category Active item state
      */
     readonly activeId: string | null;
     /**
      * Axis used to interpret Arrow-key movement.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly orientation: Orientation;
     /**
      * Whether movement wraps between the first and last enabled items.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly loop: boolean;
     /**
      * Whether horizontal Arrow-key meaning is reversed for right-to-left layout.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly rtl: boolean;
     /**
      * Whether DOM focus remains on the root and activeId is exposed via aria-activedescendant.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard focus
      */
     readonly virtualFocus: boolean;
 }
@@ -135,37 +135,37 @@ export interface State {
  * policy explicitly with
  * `const initial: InitialState = { activeId: null, orientation: "vertical", loop: false, rtl: false, virtualFocus: true }; const state = yield* Composite.makeState(initial)`.
  * @since 1.0.0
- * @category models
+ * @category Active item state
  */
 export interface InitialState {
     /**
      * Id currently active for keyboard navigation; null means no active item.
      * @since 1.0.0
-     * @category models
+     * @category Active item state
      */
     readonly activeId?: string | null;
     /**
      * Axis used to interpret Arrow-key movement.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly orientation?: Orientation;
     /**
      * Whether movement wraps between the first and last enabled items.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly loop?: boolean;
     /**
      * Whether horizontal Arrow-key meaning is reversed for right-to-left layout.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly rtl?: boolean;
     /**
      * Whether DOM focus remains on the root and activeId is exposed via aria-activedescendant.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard focus
      */
     readonly virtualFocus?: boolean;
 }
@@ -189,25 +189,25 @@ export interface InitialState {
  * the only three inputs with
  * `const options: MoveOptions<string, State> = { state, collection, includeDisabled: false }`.
  * @since 1.0.0
- * @category models
+ * @category Directional movement
  */
 export interface MoveOptions<Value = unknown, CompositeState extends State = State, E = never, R = never, E2 = never, R2 = never, Element extends object = globalThis.Element> {
     /**
      * Renderer-independent RefSubject state consumed by this component or operation.
      * @since 1.0.0
-     * @category models
+     * @category State connection
      */
     readonly state: RefSubject.RefSubject<CompositeState, E, R>;
     /**
      * Item registry used for collection-driven keyboard behavior and mounted ordering.
      * @since 1.0.0
-     * @category models
+     * @category Item registration
      */
     readonly collection: RefSubject.RefSubject<Collection.State<Value, Element>, E2, R2>;
     /**
      * Whether movement may land on disabled collection items.
      * @since 1.0.0
-     * @category models
+     * @category Availability
      */
     readonly includeDisabled?: boolean;
 }
@@ -230,19 +230,19 @@ export interface MoveOptions<Value = unknown, CompositeState extends State = Sta
  * [Composite.makeState runnable setup](/reference/%40typed%2Fui%2FComposite%23makeState). A
  * compatible focus state is observable directly: `const active: ActiveIdState = yield* state`.
  * @since 1.0.0
- * @category models
+ * @category Active item state
  */
 export interface ActiveIdState {
     /**
      * Id currently active for keyboard navigation; null means no active item.
      * @since 1.0.0
-     * @category models
+     * @category Active item state
      */
     readonly activeId: string | null;
     /**
      * Whether movement wraps between the first and last enabled items.
      * @since 1.0.0
-     * @category models
+     * @category Directional movement
      */
     readonly loop: boolean;
 }
@@ -266,37 +266,37 @@ export interface ActiveIdState {
  * keyboard adapters need only the modeled surface:
  * `const event: KeyboardEventLike = { key: "ArrowDown", preventDefault() {} }`.
  * @since 1.0.0
- * @category models
+ * @category Keyboard navigation
  */
 export interface KeyboardEventLike {
     /**
      * Native KeyboardEvent key value to interpret.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly key: string;
     /**
      * Whether Alt modified the key event.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly altKey?: boolean;
     /**
      * Whether Control modified the key event.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly ctrlKey?: boolean;
     /**
      * Whether Meta modified the key event.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     readonly metaKey?: boolean;
     /**
      * Optional native-event callback invoked only for an internally handled key.
      * @since 1.0.0
-     * @category models
+     * @category Keyboard navigation
      */
     preventDefault?: () => void;
 }
@@ -320,19 +320,19 @@ export interface KeyboardEventLike {
  * the exact typed query and timestamp with
  * `const buffer: TypeaheadBuffer = { value: "Ty", updatedAt: 100 }`.
  * @since 1.0.0
- * @category models
+ * @category Typeahead
  */
 export interface TypeaheadBuffer {
     /**
      * Buffered typeahead key sequence, preserving the supplied key case.
      * @since 1.0.0
-     * @category models
+     * @category Typeahead
      */
     readonly value: string;
     /**
      * Timestamp of the last typeahead key, used to decide whether to append or restart.
      * @since 1.0.0
-     * @category models
+     * @category Typeahead
      */
     readonly updatedAt: number;
 }
@@ -357,7 +357,7 @@ export interface TypeaheadBuffer {
  * const decodeState = Schema.decodeUnknownEffect(Composite.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Active item state
  */
 export declare const StateSchema: Schema.Struct<{
     readonly activeId: Schema.NullOr<Schema.String>;
@@ -396,7 +396,7 @@ export declare const StateSchema: Schema.Struct<{
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Active item state
  */
 export declare function makeState(initial?: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly activeId: string | null;
@@ -427,7 +427,7 @@ export declare function makeState(initial?: InitialState): Effect.Effect<RefSubj
  * program invoke `yield* move({ state, collection }, "next")`, then read state to observe the next
  * enabled registered id selected under the current loop policy.
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export declare function move<Value, CompositeState extends State, E, R, E2, R2, Element extends object>(options: MoveOptions<Value, CompositeState, E, R, E2, R2, Element>, direction: Move): Effect.Effect<CompositeState, E | E2, R | R2>;
 /**
@@ -451,7 +451,7 @@ export declare function move<Value, CompositeState extends State, E, R, E2, R2,
  * program read `const value = yield* tabIndex(state, "item-2")`; it is `0` only while that item
  * owns roving focus and is `-1` under virtual focus.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export declare function tabIndex<CompositeState extends State, E, R>(state: RefSubject.RefSubject<CompositeState, E, R>, id: string): RefSubject.Computed<0 | -1, E, R>;
 /**
@@ -475,7 +475,7 @@ export declare function tabIndex<CompositeState extends State, E, R>(state: RefS
  * the linked Effect program read `const id = yield* activeDescendant(state)`; it is the active id
  * only under virtual focus and otherwise `undefined`.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export declare function activeDescendant<CompositeState extends State, E, R>(state: RefSubject.RefSubject<CompositeState, E, R>): RefSubject.Computed<string | undefined, E, R>;
 /**
@@ -499,7 +499,7 @@ export declare function activeDescendant<CompositeState extends State, E, R>(sta
  * program read `const value = yield* rootTabIndex(state)`; it is `0` while the root owns focus and
  * `-1` after a roving-focus item becomes active.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export declare function rootTabIndex<CompositeState extends State, E, R>(state: RefSubject.RefSubject<CompositeState, E, R>): RefSubject.Computed<0 | -1, E, R>;
 /**
@@ -523,7 +523,7 @@ export declare function rootTabIndex<CompositeState extends State, E, R>(state:
  * const direction = Composite.keyMove({ key: "ArrowLeft" }, { orientation: "horizontal", rtl: true });
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard navigation
  */
 export declare function keyMove(event: Pick<KeyboardEventLike, "key">, options: {
     readonly orientation?: Orientation;
@@ -550,7 +550,7 @@ export declare function keyMove(event: Pick<KeyboardEventLike, "key">, options:
  * program run `yield* moveByKey({ key: "ArrowDown" }, { state, collection })`, then read state to
  * observe the active id selected by the current orientation and RTL policy.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard navigation
  */
 export declare function moveByKey<Value, CompositeState extends State, E, R, E2, R2, Element extends object>(event: KeyboardEventLike, options: MoveOptions<Value, CompositeState, E, R, E2, R2, Element>): Effect.Effect<boolean, E | E2, R | R2>;
 /**
@@ -575,7 +575,7 @@ export declare function moveByKey<Value, CompositeState extends State, E, R, E2,
  * program run `yield* moveAndFocus({ state, collection }, "next")`; the returned state names the
  * next id and its registered element receives native focus.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export declare function moveAndFocus<Value, CompositeState extends State, E, R, E2, R2, Element extends object>(options: MoveOptions<Value, CompositeState, E, R, E2, R2, Element>, direction: Move): Effect.Effect<CompositeState, E | E2, R | R2>;
 /**
@@ -599,7 +599,7 @@ export declare function moveAndFocus<Value, CompositeState extends State, E, R,
  * program run `yield* focusActive({ state, collection })`; the active registered element receives
  * native focus, with no state transition when no matching element exists.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export declare function focusActive<Value, CompositeState extends State, E, R, E2, R2, Element extends object>(options: MoveOptions<Value, CompositeState, E, R, E2, R2, Element>): Effect.Effect<void, E | E2, R | R2>;
 /**
@@ -623,7 +623,7 @@ export declare function focusActive<Value, CompositeState extends State, E, R, E
  * const focused = Composite.focusElement(document.querySelector("button") ?? undefined);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export declare function focusElement(element: object | undefined): Effect.Effect<void>;
 /**
@@ -647,7 +647,7 @@ export declare function focusElement(element: object | undefined): Effect.Effect
  * program run `yield* scrollActive({ state, collection })`; the active registered element receives
  * `scrollIntoView({ block: "nearest", inline: "nearest" })` when that method is available.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export declare function scrollActive<Value, CompositeState extends State, E, R, E2, R2, Element extends object>(options: MoveOptions<Value, CompositeState, E, R, E2, R2, Element>): Effect.Effect<void, E | E2, R | R2>;
 /**
@@ -671,7 +671,7 @@ export declare function scrollActive<Value, CompositeState extends State, E, R,
  * const id = Composite.typeahead([{ id: "alpha", textValue: "Alpha" }], "al");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export declare function typeahead<Item extends Collection.Item<unknown, object>>(items: readonly Item[], search: string, text?: (item: Item) => string, includeDisabled?: boolean): string | null;
 /**
@@ -695,7 +695,7 @@ export declare function typeahead<Item extends Collection.Item<unknown, object>>
  * const id = Composite.typeaheadFrom([{ id: "alpha", textValue: "Alpha" }], "al", null);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export declare function typeaheadFrom<Item extends Collection.Item<unknown, object>>(items: readonly Item[], search: string, activeId: string | null, text?: (item: Item) => string, includeDisabled?: boolean): string | null;
 /**
@@ -720,7 +720,7 @@ export declare function typeaheadFrom<Item extends Collection.Item<unknown, obje
  * const key = Composite.typeaheadKey({ key: "A" });
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export declare function typeaheadKey(event: KeyboardEventLike): string | null;
 /**
@@ -744,7 +744,7 @@ export declare function typeaheadKey(event: KeyboardEventLike): string | null;
  * const buffer = Composite.updateTypeaheadBuffer({ value: "a", updatedAt: 100 }, "b", 200);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export declare function updateTypeaheadBuffer(buffer: TypeaheadBuffer, key: string, now: number, timeout?: number): TypeaheadBuffer;
 /**
@@ -768,7 +768,7 @@ export declare function updateTypeaheadBuffer(buffer: TypeaheadBuffer, key: stri
  * const items = Composite.orderedEnabledItems([{ id: "a" }, { id: "b", disabled: true }]);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export declare function orderedEnabledItems<Item extends Collection.Item<unknown, object>>(items: readonly Item[]): readonly Item[];
 /**
@@ -793,7 +793,7 @@ export declare function orderedEnabledItems<Item extends Collection.Item<unknown
  * const id = Composite.moveActiveId([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export declare function moveActiveId<Item extends Collection.Item<unknown, object>>(items: readonly Item[], state: ActiveIdState, direction: Move, includeDisabled?: boolean): string | null;
 /**
@@ -817,7 +817,7 @@ export declare function moveActiveId<Item extends Collection.Item<unknown, objec
  * const item = Composite.moveActiveItem([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export declare function moveActiveItem<Item extends Collection.Item<unknown, object>>(items: readonly Item[], state: ActiveIdState, direction: Move, includeDisabled?: boolean): Item | undefined;
 //# sourceMappingURL=Composite.d.ts.map

package/dist/Composite.js

@@ -9,7 +9,7 @@
  * events and browser-owned focus.
  *
  * @since 1.0.0
- * @category modules
+ * @category Architecture overview
  * @packageDocumentation
  */
 import * as Effect from "effect/Effect";
@@ -37,7 +37,7 @@ import * as Collection from "./Collection.js";
  * const decodeState = Schema.decodeUnknownEffect(Composite.StateSchema);
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Active item state
  */
 export const StateSchema = Schema.Struct({
     activeId: Schema.NullOr(Schema.String),
@@ -76,7 +76,7 @@ export const StateSchema = Schema.Struct({
  * );
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Active item state
  */
 export function makeState(initial = {}) {
     return RefSubject.hydrate(StateSchema, {
@@ -109,7 +109,7 @@ export function makeState(initial = {}) {
  * program invoke `yield* move({ state, collection }, "next")`, then read state to observe the next
  * enabled registered id selected under the current loop policy.
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export function move(options, direction) {
     return Effect.gen(function* () {
@@ -139,7 +139,7 @@ export function move(options, direction) {
  * program read `const value = yield* tabIndex(state, "item-2")`; it is `0` only while that item
  * owns roving focus and is `-1` under virtual focus.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export function tabIndex(state, id) {
     return RefSubject.map(state, (current) => current.virtualFocus ? -1 : current.activeId === id ? 0 : -1);
@@ -165,7 +165,7 @@ export function tabIndex(state, id) {
  * the linked Effect program read `const id = yield* activeDescendant(state)`; it is the active id
  * only under virtual focus and otherwise `undefined`.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export function activeDescendant(state) {
     return RefSubject.map(state, (current) => current.virtualFocus && current.activeId ? current.activeId : undefined);
@@ -191,7 +191,7 @@ export function activeDescendant(state) {
  * program read `const value = yield* rootTabIndex(state)`; it is `0` while the root owns focus and
  * `-1` after a roving-focus item becomes active.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard focus
  */
 export function rootTabIndex(state) {
     return RefSubject.map(state, (current) => current.virtualFocus || current.activeId === null ? 0 : -1);
@@ -217,7 +217,7 @@ export function rootTabIndex(state) {
  * const direction = Composite.keyMove({ key: "ArrowLeft" }, { orientation: "horizontal", rtl: true });
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard navigation
  */
 export function keyMove(event, options) {
     if (event.key === "Home")
@@ -257,7 +257,7 @@ export function keyMove(event, options) {
  * program run `yield* moveByKey({ key: "ArrowDown" }, { state, collection })`, then read state to
  * observe the active id selected by the current orientation and RTL policy.
  * @since 1.0.0
- * @category combinators
+ * @category Keyboard navigation
  */
 export function moveByKey(event, options) {
     return Effect.gen(function* () {
@@ -291,7 +291,7 @@ export function moveByKey(event, options) {
  * program run `yield* moveAndFocus({ state, collection }, "next")`; the returned state names the
  * next id and its registered element receives native focus.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export function moveAndFocus(options, direction) {
     return Effect.tap(move(options, direction), Effect.andThen(focusActive(options), scrollActive(options)));
@@ -317,7 +317,7 @@ export function moveAndFocus(options, direction) {
  * program run `yield* focusActive({ state, collection })`; the active registered element receives
  * native focus, with no state transition when no matching element exists.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export function focusActive(options) {
     return Effect.gen(function* () {
@@ -349,7 +349,7 @@ export function focusActive(options) {
  * const focused = Composite.focusElement(document.querySelector("button") ?? undefined);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export function focusElement(element) {
     return Effect.sync(() => {
@@ -379,7 +379,7 @@ export function focusElement(element) {
  * program run `yield* scrollActive({ state, collection })`; the active registered element receives
  * `scrollIntoView({ block: "nearest", inline: "nearest" })` when that method is available.
  * @since 1.0.0
- * @category combinators
+ * @category DOM focus and scrolling
  */
 export function scrollActive(options) {
     return Effect.gen(function* () {
@@ -414,7 +414,7 @@ export function scrollActive(options) {
  * const id = Composite.typeahead([{ id: "alpha", textValue: "Alpha" }], "al");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export function typeahead(items, search, text = (item) => item.textValue ?? item.id, includeDisabled = false) {
     return typeaheadFrom(items, search, null, text, includeDisabled);
@@ -440,7 +440,7 @@ export function typeahead(items, search, text = (item) => item.textValue ?? item
  * const id = Composite.typeaheadFrom([{ id: "alpha", textValue: "Alpha" }], "al", null);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export function typeaheadFrom(items, search, activeId, text = (item) => item.textValue ?? item.id, includeDisabled = false) {
     const query = search.trim().toLocaleLowerCase();
@@ -474,7 +474,7 @@ export function typeaheadFrom(items, search, activeId, text = (item) => item.tex
  * const key = Composite.typeaheadKey({ key: "A" });
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export function typeaheadKey(event) {
     if (event.altKey || event.ctrlKey || event.metaKey)
@@ -502,7 +502,7 @@ export function typeaheadKey(event) {
  * const buffer = Composite.updateTypeaheadBuffer({ value: "a", updatedAt: 100 }, "b", 200);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Typeahead
  */
 export function updateTypeaheadBuffer(buffer, key, now, timeout = 500) {
     return {
@@ -531,7 +531,7 @@ export function updateTypeaheadBuffer(buffer, key, now, timeout = 500) {
  * const items = Composite.orderedEnabledItems([{ id: "a" }, { id: "b", disabled: true }]);
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export function orderedEnabledItems(items) {
     return Collection.enabledItems(Collection.byDomOrder(items));
@@ -558,7 +558,7 @@ export function orderedEnabledItems(items) {
  * const id = Composite.moveActiveId([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export function moveActiveId(items, state, direction, includeDisabled = false) {
     return moveActiveItem(items, state, direction, includeDisabled)?.id ?? null;
@@ -584,7 +584,7 @@ export function moveActiveId(items, state, direction, includeDisabled = false) {
  * const item = Composite.moveActiveItem([{ id: "a" }, { id: "b" }], { activeId: "a", loop: true }, "next");
  * ```
  * @since 1.0.0
- * @category combinators
+ * @category Directional movement
  */
 export function moveActiveItem(items, state, direction, includeDisabled = false) {
     const enabled = orderedItems(items, includeDisabled);