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

package/dist/Grid.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Grid is a virtual-focus ARIA grid. The root retains DOM focus while the active cell id is
+ * exposed through aria-activedescendant; CellPosition supplies row and column coordinates for
+ * two-dimensional movement.
+ *
+ * @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 [Grid guide](/explore/ui-grid).
+ *
+ * @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 Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * The cell ID exposed by the root through `aria-activedescendant`.
+ * Native focus stays on the root; selected cells and editing state are not stored here.
+ *
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export interface State {
+    /**
+     * Id currently active for keyboard navigation; null means no active item.
+     * @since 1.0.0
+     * @category Keyboard focus
+     */
+    readonly activeId: string | null;
+}
+/**
+ * Initial Grid values. activeId defaults to null.
+ *
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export interface InitialState {
+    /**
+     * Id currently active for keyboard navigation; null means no active item.
+     * @since 1.0.0
+     * @category Keyboard focus
+     */
+    readonly activeId?: string | null;
+}
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Grid state.
+ *
+ * @remarks
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Grid.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export declare const StateSchema: Schema.Struct<{
+    readonly activeId: Schema.NullOr<Schema.String>;
+}>;
+/**
+ * Creates hydrated Grid state. activeId defaults to null.
+ *
+ * @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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Grid.makeState({});
+ *     const collection = yield* Grid.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export declare function makeState(initial?: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
+    readonly activeId: string | null;
+}, Schema.SchemaError, never, never>, never, Scope.Scope>;
+/**
+ * Logical coordinates stored with each registered Grid cell.
+ *
+ * @remarks
+ * The public model lets custom composites reuse Grid's deterministic policy without copying an
+ * internal shape.
+ *
+ * @since 1.0.0
+ * @category Cell registration
+ */
+export interface CellPosition {
+    /**
+     * Stable logical row identity used by vertical grid movement.
+     * @since 1.0.0
+     * @category Row identity
+     */
+    readonly rowId: string;
+    /**
+     * Caller-supplied column index used for movement and emitted unchanged as aria-colindex; ARIA
+     * indexes are one-based.
+     * @since 1.0.0
+     * @category Cell position
+     */
+    readonly columnIndex: number;
+}
+/**
+ * Creates a scoped Collection for Grid 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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Grid.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Cell registration
+ */
+export declare const makeCollection: (initial?: Collection.State<CellPosition, Element>) => Effect.Effect<RefSubject.RefSubject<Collection.State<CellPosition, Element>, never, never>, never, Scope.Scope>;
+/**
+ * Sets activeId, including null to clear virtual focus.
+ *
+ * @remarks
+ * The operation exposes Grid's transition directly so callers can compose it in Effect programs
+ * and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export declare function activate<E, R>(state: RefSubject.RefSubject<State, E, R>, activeId: string | null): Effect.Effect<State, E, R>;
+/**
+ * Inputs accepted by Grid.Root in addition to the shared DOM host options.
+ *
+ * @since 1.0.0
+ * @category Grid 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<CellPosition>>;
+    /**
+     * Accessible label rendered through aria-label.
+     * @since 1.0.0
+     * @category Accessible naming
+     */
+    readonly label: Renderable.Any<string | null | undefined>;
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Whether aria-multiselectable is announced on the grid.
+     * @since 1.0.0
+     * @category Selection state
+     */
+    readonly multiselectable?: Renderable.Any<boolean | null | undefined>;
+}
+declare function rootInternalProps<const Options extends RootOptions>(options: Options): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly role: "grid";
+    readonly tabindex: 0;
+    readonly "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    readonly "aria-activedescendant": RefSubject.Computed<string | undefined, Schema.SchemaError, never>;
+    readonly "aria-multiselectable": false | Exclude<Dom.Property<Options, "multiselectable">, Dom.Nullish>;
+    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 RootInternalProps<Options extends RootOptions> = ReturnType<ReturnType<typeof rootInternalProps<Options>>>;
+/**
+ * Renders the focus-owning grid root and initializes the active cell from DOM order on first
+ * focus.
+ *
+ * @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 Grid surface
+ */
+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>;
+/**
+ * Inputs accepted by Grid.Row in addition to the shared DOM host options.
+ *
+ * @since 1.0.0
+ * @category Rows
+ */
+export interface RowOptions extends Dom.HostOptions<HTMLDivElement> {
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Optional one-based aria-rowindex value supplied by the caller.
+     * @since 1.0.0
+     * @category Cell position
+     */
+    readonly rowIndex?: Renderable.Any<number | null | undefined>;
+}
+declare function rowInternalProps<const Options extends RowOptions>({ property, }: Dom.InternalPropsHelpers<Options>): {
+    readonly role: "row";
+    readonly "aria-rowindex": Exclude<Dom.Property<Options, "rowIndex">, Dom.Nullish> | undefined;
+};
+type RowInternalProps<Options extends RowOptions> = ReturnType<typeof rowInternalProps<Options>>;
+/**
+ * Renders an ARIA row and forwards an optional one-based aria-rowindex.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const view = Grid.Row({ rowIndex: 1, content: "Cells" });
+ * ```
+ * @since 1.0.0
+ * @category Rows
+ */
+export declare function Row<const Options extends RowOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, RowInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Inputs accepted by Grid.Cell in addition to the shared DOM host options.
+ *
+ * @since 1.0.0
+ * @category Cells and headers
+ */
+export interface CellOptions 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<CellPosition>>;
+    /**
+     * Stable id used for collection identity and ARIA relationships.
+     * @since 1.0.0
+     * @category Identity and relationships
+     */
+    readonly id: string;
+    /**
+     * Stable logical row identity used by vertical grid movement.
+     * @since 1.0.0
+     * @category Row identity
+     */
+    readonly rowId: string;
+    /**
+     * Caller-supplied column index used for movement and emitted unchanged as aria-colindex; ARIA
+     * indexes are one-based.
+     * @since 1.0.0
+     * @category Cell position
+     */
+    readonly columnIndex: number;
+    /**
+     * Optional one-based aria-rowindex value supplied by the caller.
+     * @since 1.0.0
+     * @category Cell position
+     */
+    readonly rowIndex?: number;
+    /**
+     * Optional selected state exposed through aria-selected.
+     * @since 1.0.0
+     * @category Selection state
+     */
+    readonly selected?: Renderable.Any<boolean | null | undefined>;
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+}
+declare function cellInternalProps<const Options extends CellOptions>(options: Options, role: "gridcell" | "columnheader" | "rowheader"): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly id: string;
+    readonly role: "columnheader" | "gridcell" | "rowheader";
+    readonly "aria-colindex": number;
+    readonly "aria-rowindex": Exclude<Dom.Property<Options, "rowIndex">, Dom.Nullish> | undefined;
+    readonly "aria-selected": Exclude<Dom.Property<Options, "selected">, Dom.Nullish> | undefined;
+    readonly "?data-active": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly ref: ((element: Element) => Effect.Effect<void, never, Scope.Scope>) | undefined;
+};
+type CellInternalProps<Options extends CellOptions> = ReturnType<ReturnType<typeof cellInternalProps<Options>>>;
+/**
+ * Renders and optionally registers a gridcell with row and column coordinates.
+ *
+ * @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 Cells and headers
+ */
+export declare function Cell<const Options extends CellOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, CellInternalProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
+/**
+ * Renders the Cell contract with the columnheader role.
+ *
+ * @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 Cells and headers
+ */
+export declare function ColumnHeader<const Options extends CellOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, CellInternalProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
+/**
+ * Renders the Cell contract with the rowheader role.
+ *
+ * @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 Cells and headers
+ */
+export declare function RowHeader<const Options extends CellOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, CellInternalProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
+/**
+ * Maps grid keys to a cell id: horizontal movement stays in-row, vertical movement stays
+ * in-column, and Ctrl+Home/End reaches grid endpoints.
+ *
+ * @remarks
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const nextId = Grid.moveActiveId([{ id: "a", value: { rowId: "r1", columnIndex: 1 } }], "a", { key: "ArrowRight", ctrlKey: false });
+ * ```
+ * @since 1.0.0
+ * @category Spatial navigation
+ */
+export declare function moveActiveId(items: readonly Collection.Item<CellPosition>[], activeId: string | null, event: Pick<KeyboardEvent, "key" | "ctrlKey">): string | undefined;
+export {};
+//# sourceMappingURL=Grid.d.ts.map

package/dist/Grid.d.ts.map

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

package/dist/Grid.js

@@ -0,0 +1,284 @@
+/**
+ * Grid is a virtual-focus ARIA grid. The root retains DOM focus while the active cell id is
+ * exposed through aria-activedescendant; CellPosition supplies row and column coordinates for
+ * two-dimensional movement.
+ *
+ * @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 [Grid guide](/explore/ui-grid).
+ *
+ * @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 Dom from "./Dom.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Grid state.
+ *
+ * @remarks
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Grid.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export const StateSchema = Schema.Struct({ activeId: Schema.NullOr(Schema.String) });
+/**
+ * Creates hydrated Grid state. activeId defaults to null.
+ *
+ * @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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Grid.makeState({});
+ *     const collection = yield* Grid.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export function makeState(initial = {}) {
+    return RefSubject.hydrate(StateSchema, { activeId: initial.activeId ?? null });
+}
+/**
+ * Creates a scoped Collection for Grid 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 Grid from "@typed/ui/Grid";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Grid.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Cell registration
+ */
+export const makeCollection = Collection.makeState;
+/**
+ * Sets activeId, including null to clear virtual focus.
+ *
+ * @remarks
+ * The operation exposes Grid's transition directly so callers can compose it in Effect programs
+ * and native event handlers.
+ *
+ * @since 1.0.0
+ * @category Cell focus
+ */
+export function activate(state, activeId) {
+    return RefSubject.update(state, (current) => ({ ...current, activeId }));
+}
+function rootInternalProps(options) {
+    const onfocus = options.collection === undefined
+        ? undefined
+        : Effect.gen(function* () {
+            if ((yield* options.state).activeId !== null)
+                return;
+            const first = Collection.byDomOrder(yield* options.collection)[0];
+            if (first !== undefined)
+                yield* activate(options.state, first.id);
+        });
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn((event) => onKeyDown(options.state, options.collection, event)));
+    return ({ property }) => ({
+        role: "grid",
+        tabindex: 0,
+        "aria-label": property("label", undefined),
+        "aria-activedescendant": RefSubject.map(options.state, (state) => state.activeId ?? undefined),
+        "aria-multiselectable": property("multiselectable", false),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the focus-owning grid root and initializes the active cell from DOM order on first
+ * focus.
+ *
+ * @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 Grid surface
+ */
+export function Root(options, host) {
+    return Dom.renderHost()(options, host, rootInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+function rowInternalProps({ property, }) {
+    return { role: "row", "aria-rowindex": property("rowIndex", undefined) };
+}
+/**
+ * Renders an ARIA row and forwards an optional one-based aria-rowindex.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const view = Grid.Row({ rowIndex: 1, content: "Cells" });
+ * ```
+ * @since 1.0.0
+ * @category Rows
+ */
+export function Row(options, host) {
+    return Dom.renderHost()(options, host, rowInternalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function cellInternalProps(options, role) {
+    const active = RefSubject.map(options.state, (state) => state.activeId === options.id);
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: { rowId: options.rowId, columnIndex: options.columnIndex },
+            textValue: options.id,
+        });
+    return ({ property }) => ({
+        id: options.id,
+        role,
+        "aria-colindex": options.columnIndex,
+        "aria-rowindex": property("rowIndex", undefined),
+        "aria-selected": property("selected", undefined),
+        "?data-active": active,
+        ref: register,
+    });
+}
+function cell(options, host, role) {
+    return Dom.renderHost()(options, host, cellInternalProps(options, role), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+/**
+ * Renders and optionally registers a gridcell with row and column coordinates.
+ *
+ * @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 Cells and headers
+ */
+export function Cell(options, host) {
+    return cell(options, host, "gridcell");
+}
+/**
+ * Renders the Cell contract with the columnheader role.
+ *
+ * @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 Cells and headers
+ */
+export function ColumnHeader(options, host) {
+    return cell(options, host, "columnheader");
+}
+/**
+ * Renders the Cell contract with the rowheader role.
+ *
+ * @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 Cells and headers
+ */
+export function RowHeader(options, host) {
+    return cell(options, host, "rowheader");
+}
+function onKeyDown(state, collection, event) {
+    return Effect.gen(function* () {
+        const items = Collection.byDomOrder(yield* collection);
+        const next = moveActiveId(items, (yield* state).activeId, event);
+        if (next === undefined)
+            return yield* state;
+        event.preventDefault();
+        return yield* activate(state, next);
+    });
+}
+/**
+ * Maps grid keys to a cell id: horizontal movement stays in-row, vertical movement stays
+ * in-column, and Ctrl+Home/End reaches grid endpoints.
+ *
+ * @remarks
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Grid from "@typed/ui/Grid";
+ *
+ * const nextId = Grid.moveActiveId([{ id: "a", value: { rowId: "r1", columnIndex: 1 } }], "a", { key: "ArrowRight", ctrlKey: false });
+ * ```
+ * @since 1.0.0
+ * @category Spatial navigation
+ */
+export function moveActiveId(items, activeId, event) {
+    if (items.length === 0)
+        return undefined;
+    if (event.ctrlKey && event.key === "Home")
+        return items[0]?.id;
+    if (event.ctrlKey && event.key === "End")
+        return items.at(-1)?.id;
+    const active = activeId === null ? undefined : items.find((item) => item.id === activeId);
+    if (active === undefined || active.value === undefined)
+        return event.key === "Home" ? items[0]?.id : undefined;
+    const row = items.filter((item) => item.value?.rowId === active.value.rowId);
+    if (event.key === "ArrowLeft")
+        return row.at(Math.max(0, row.indexOf(active) - 1))?.id;
+    if (event.key === "ArrowRight")
+        return row.at(Math.min(row.length - 1, row.indexOf(active) + 1))?.id;
+    if (event.key === "Home")
+        return row[0]?.id;
+    if (event.key === "End")
+        return row.at(-1)?.id;
+    if (event.key !== "ArrowUp" && event.key !== "ArrowDown")
+        return undefined;
+    const column = items.filter((item) => item.value?.columnIndex === active.value.columnIndex);
+    return column.at(column.indexOf(active) + (event.key === "ArrowUp" ? -1 : 1))?.id ?? active.id;
+}