@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/keys/index.js

@@ -0,0 +1,199 @@
+/** Keys `nextIndex` may handle for `options`, as a `data-rk` value (loader holds them while a chunk loads). */
+export function navigationKeys(options = {}) {
+    const { orientation = "vertical", homeEnd = true, pageSize = 0 } = options;
+    const keys = [];
+    if (orientation !== "horizontal")
+        keys.push("ArrowDown", "ArrowUp");
+    if (orientation !== "vertical")
+        keys.push("ArrowLeft", "ArrowRight");
+    if (homeEnd)
+        keys.push("Home", "End");
+    if (pageSize)
+        keys.push("PageUp", "PageDown");
+    return keys.join(" ");
+}
+/**
+ * Index the key moves to from `from` (-1: nothing focused yet) among `count` items, or `null` when
+ * the key is not a navigation key for these options (let it through). Returns `from` when the key is
+ * handled but nothing moves (at the edge without wrap).
+ */
+export function nextIndex(count, from, key, options = {}) {
+    const { orientation = "vertical", wrap = false, homeEnd = true, pageSize = 0, dir = "ltr", isDisabled } = options;
+    const enabled = (i) => !isDisabled?.(i);
+    const step = (start, delta, loop) => {
+        for (let i = start + delta, n = 0; n < count; i += delta, n++) {
+            if (i < 0 || i >= count) {
+                if (!loop)
+                    return from;
+                i = i < 0 ? count - 1 : 0;
+            }
+            if (enabled(i))
+                return i;
+        }
+        return from;
+    };
+    const first = () => step(-1, 1, false);
+    const last = () => step(count, -1, false);
+    const vertical = orientation !== "horizontal", horizontal = orientation !== "vertical";
+    const forward = vertical && key === "ArrowDown" ? 1 : horizontal && key === (dir === "rtl" ? "ArrowLeft" : "ArrowRight") ? 1 : 0;
+    const backward = vertical && key === "ArrowUp" ? 1 : horizontal && key === (dir === "rtl" ? "ArrowRight" : "ArrowLeft") ? 1 : 0;
+    if (count === 0)
+        return forward || backward || (homeEnd && (key === "Home" || key === "End")) ? from : null;
+    if (forward)
+        return from < 0 ? first() : step(from, 1, wrap);
+    if (backward)
+        return from < 0 ? last() : step(from, -1, wrap);
+    if (homeEnd && key === "Home")
+        return first();
+    if (homeEnd && key === "End")
+        return last();
+    if (pageSize && (key === "PageDown" || key === "PageUp")) {
+        const delta = key === "PageDown" ? 1 : -1;
+        let target = Math.min(count - 1, Math.max(0, (from < 0 ? 0 : from) + delta * pageSize));
+        // Land on the nearest enabled item in the direction of travel, else back towards `from`.
+        while (target >= 0 && target < count && !enabled(target))
+            target += delta;
+        if (target < 0 || target >= count)
+            return delta > 0 ? last() : first();
+        return target;
+    }
+    return null;
+}
+// Typeahead: per-owner buffer + timestamp (transient, never serialized).
+const buffers = new WeakMap();
+let collator;
+const TIMEOUT = 750;
+/**
+ * Typeahead (APG): printable `key` extends the owner's buffer (reset after 750 ms); returns the index
+ * of the next item after `from` whose text starts with the buffer (base sensitivity: case and accents
+ * ignored, `Intl.Collator`), or -1. Repeating one character cycles through items starting with it.
+ * `owner` is any object identifying the widget (its state object).
+ */
+export function typeahead(owner, texts, from, key, now = Date.now(), isDisabled) {
+    if (key.length !== 1 || (key === " " && !buffers.get(owner)?.text))
+        return -1;
+    const previous = buffers.get(owner);
+    const text = (previous && now - previous.at < TIMEOUT ? previous.text : "") + key;
+    buffers.set(owner, { text, at: now });
+    collator ??= new Intl.Collator(undefined, { usage: "search", sensitivity: "base" });
+    const cmp = collator;
+    // Same character repeated: cycle through matches of that single character.
+    const search = text.length > 1 && [...text].every((c) => c === text[0]) ? text[0] : text;
+    const starts = (value) => value.length >= search.length && cmp.compare(value.slice(0, search.length), search) === 0;
+    const begin = search.length === 1 ? from + 1 : Math.max(from, 0);
+    for (let n = 0; n < texts.length; n++) {
+        const i = (begin + n) % texts.length;
+        if (!isDisabled?.(i) && starts(texts[i].trim()))
+            return i;
+    }
+    return -1;
+}
+/** Test hook: forget an owner's typeahead buffer. */
+export function _resetTypeahead(owner) {
+    buffers.delete(owner);
+}
+const MODIFIER_NAMES = new Set(["shift", "alt", "control", "meta", "mod"]);
+const CANONICAL_MODIFIER_ORDER = ["Alt", "Control", "Meta", "Shift"];
+const KEY_ALIASES = {
+    space: " ",
+    esc: "escape",
+    del: "delete",
+    ins: "insert",
+    left: "arrowleft",
+    right: "arrowright",
+    up: "arrowup",
+    down: "arrowdown",
+    pageup: "pageup",
+    pagedown: "pagedown",
+};
+const appleShortcuts = () => typeof navigator !== "undefined" &&
+    /^Mac/i.test(navigator.userAgentData?.platform || navigator.platform);
+/** Canonical modifier tokens of a binding (`Mod` → Meta on Mac, Control elsewhere). */
+export function modifierSetFromParsed(parsed) {
+    const set = new Set();
+    if (parsed.alt)
+        set.add("Alt");
+    if (parsed.shift)
+        set.add("Shift");
+    if (parsed.ctrl)
+        set.add("Control");
+    if (parsed.meta)
+        set.add("Meta");
+    if (parsed.mod)
+        set.add(appleShortcuts() ? "Meta" : "Control");
+    return set;
+}
+/** Modifier tokens of a keydown event. */
+export function modifierSetFromEvent(e) {
+    const set = new Set();
+    if (e.altKey)
+        set.add("Alt");
+    if (e.ctrlKey)
+        set.add("Control");
+    if (e.metaKey)
+        set.add("Meta");
+    if (e.shiftKey)
+        set.add("Shift");
+    return set;
+}
+const sortedModifierTokens = (set) => CANONICAL_MODIFIER_ORDER.filter((name) => set.has(name));
+/** Parse `"Mod+Shift+z"`, `"Ctrl+Alt+Enter"`, `"Escape"` (modifiers case-insensitive, any order). */
+export function parseKeyboardShortcut(spec) {
+    const parts = spec.split("+").reduce((prev, part) => {
+        const lower = part.toLowerCase();
+        if (MODIFIER_NAMES.has(lower)) {
+            if (lower === "shift")
+                prev.shift = true;
+            else if (lower === "alt")
+                prev.alt = true;
+            else if (lower === "control")
+                prev.ctrl = true;
+            else if (lower === "meta")
+                prev.meta = true;
+            else if (lower === "mod")
+                prev.mod = true;
+        }
+        else
+            prev.key = part;
+        return prev;
+    }, { shift: false, alt: false, ctrl: false, meta: false, mod: false, key: "" });
+    if (parts.key === "")
+        throw new Error(`Invalid keyboard shortcut: "${spec}". Must include exactly one non-modifier key (e.g. "a", "Enter", "ArrowDown"). Combine any of Shift, Alt, Ctrl, Meta, and Mod.`);
+    return parts;
+}
+const canonicalKeyFromSpecKey = (specKey) => {
+    const k = specKey.toLowerCase();
+    return KEY_ALIASES[k] ?? k;
+};
+/** Canonical form of a binding: modifiers sorted (Alt, Control, Meta, Shift), then the key. */
+export function canonicalKeyboardShortcut(parsed) {
+    const mods = sortedModifierTokens(modifierSetFromParsed(parsed));
+    const key = canonicalKeyFromSpecKey(parsed.key);
+    return mods.length > 0 ? `${mods.join("+")}+${key}` : key;
+}
+/** Canonical form of a keydown event. */
+export function keyboardEventToCanonicalShortcut(e) {
+    const mods = sortedModifierTokens(modifierSetFromEvent(e));
+    return (mods.length > 0 ? `${mods.join("+")}+` : "") + e.key.toLowerCase();
+}
+/**
+ * A keydown handler running the action of the exact modifier + key match (later duplicate bindings
+ * win). Handled: preventDefault + stop; unhandled keys `continuePropagation()` when available.
+ */
+export function createKeyboardShortcutHandler(bindings) {
+    const map = new Map();
+    for (const [spec, action] of Object.entries(bindings))
+        map.set(canonicalKeyboardShortcut(parseKeyboardShortcut(spec)), action);
+    return (e) => {
+        const action = map.get(keyboardEventToCanonicalShortcut(e));
+        let result = action?.(e);
+        if (result === undefined && action !== undefined)
+            result = { shouldContinuePropagation: false, shouldPreventDefault: true };
+        else if (typeof result === "boolean")
+            result = { shouldContinuePropagation: !result, shouldPreventDefault: result };
+        if (result?.shouldPreventDefault)
+            e.preventDefault();
+        if (!action || result?.shouldContinuePropagation)
+            e.continuePropagation?.();
+    };
+}

package/label/behaviour.d.ts

@@ -0,0 +1,54 @@
+export interface LabelAriaProps {
+    /** Id of the labelled element (generated when omitted). */
+    id?: string;
+    /** Whether a visible label is rendered (RA `label`: any truthy content). */
+    label?: unknown;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** @default "label" */
+    labelElementType?: string;
+}
+export interface LabelAria {
+    labelProps: {
+        id?: string;
+        for?: string;
+    };
+    fieldProps: {
+        id: string;
+        "aria-label"?: string;
+        "aria-labelledby"?: string;
+    };
+}
+/** RA `useLabels` (`labelsProps`): merge aria-label and aria-labelledby (both → labelledby includes the element itself). */
+export declare function labelsProps(id: string | undefined, label: string | undefined, labelledBy: string | undefined, defaultLabel?: string): {
+    id: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+/** RA `useLabel`. With an explicit `id`, the part ids derive from it (`<id>-label`; byte-stable HTML). */
+export declare function labelProps(props: LabelAriaProps): LabelAria;
+export interface FieldAriaProps extends LabelAriaProps {
+    /** Whether a description renders (RA `description`). */
+    description?: unknown;
+    /** Whether an error message may render (RA `errorMessage`; validation errors count too). */
+    errorMessage?: unknown;
+    "aria-describedby"?: string;
+}
+export interface FieldIds extends LabelAria {
+    /** Id of the description element (undefined: no description). */
+    descriptionId: string | undefined;
+    /** Id of the error message element (always reserved: validation errors can appear later). */
+    errorMessageId: string;
+    /** Extra `aria-describedby` ids from the props. */
+    extraDescribedBy: string | undefined;
+}
+/** RA `useField`: label + description + error message ids. */
+export declare function fieldProps(props: FieldAriaProps): FieldIds;
+/** `aria-describedby` of the field: description, error message (while `invalid`), then the extra ids. */
+export declare function describedBy(ids: FieldIds, invalid: boolean): string | undefined;
+/** @deprecated migration shim — remove when no importer (use `labelProps`). */
+export declare const labelAria: typeof labelProps;
+/** @deprecated migration shim — remove when no importer (use `fieldProps`). */
+export declare const fieldAria: typeof fieldProps;
+/** @deprecated migration shim — remove when no importer (use `labelsProps`). */
+export declare const labelsAttrs: typeof labelsProps;

package/label/behaviour.js

@@ -0,0 +1,60 @@
+// Ported from react-aria `useLabel`, `useField`, `useLabels` (packages/react-aria/src/label/useLabel.ts,
+// src/label/useField.ts, src/utils/useLabels.ts), Apache-2.0, © Adobe.
+// Rivet: names per cdk convention: `useLabel` → `labelProps`, `useField` → `fieldProps`, `useLabels` → `labelsProps`
+// (old `labelAria` / `fieldAria` / `labelsAttrs` = deprecated migration shims).
+// Rivet: ids are created once on the server (`createId`); the description / error ids are part of
+// `aria-describedby` only while that part renders (RA `useSlotId`): description when given, error
+// message while the field is invalid (`describedBy(ids, invalid)` is read by a binding).
+import { createId } from "@rivetjs/cdk/id";
+import { DEV, devWhere } from "#dev";
+/** RA `useLabels` (`labelsProps`): merge aria-label and aria-labelledby (both → labelledby includes the element itself). */
+export function labelsProps(id, label, labelledBy, defaultLabel) {
+    const own = id ?? createId();
+    if (labelledBy && label)
+        labelledBy = [...new Set([own, ...labelledBy.trim().split(/\s+/)])].join(" ");
+    else if (labelledBy)
+        labelledBy = labelledBy.trim().split(/\s+/).join(" ");
+    if (!label && !labelledBy && defaultLabel)
+        label = defaultLabel;
+    return { id: own, "aria-label": label, "aria-labelledby": labelledBy };
+}
+/** RA `useLabel`. With an explicit `id`, the part ids derive from it (`<id>-label`; byte-stable HTML). */
+export function labelProps(props) {
+    const id = props.id ?? createId();
+    let labelledBy = props["aria-labelledby"];
+    const ariaLabel = props["aria-label"];
+    let attrs = {};
+    if (props.label) {
+        const labelId = props.id ? props.id + "-label" : createId();
+        labelledBy = labelledBy ? `${labelId} ${labelledBy}` : labelId;
+        attrs = { id: labelId, for: (props.labelElementType ?? "label") === "label" ? id : undefined };
+    }
+    else if (DEV && !labelledBy && !ariaLabel && isDev()) {
+        console.warn("[rivet:cdk] labelProps: If you do not provide a visible label, you must specify an aria-label or aria-labelledby attribute for accessibility" +
+            devWhere());
+    }
+    return { labelProps: attrs, fieldProps: labelsProps(id, ariaLabel, labelledBy) };
+}
+const isDev = () => typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+/** RA `useField`: label + description + error message ids. */
+export function fieldProps(props) {
+    const label = labelProps(props);
+    return {
+        ...label,
+        descriptionId: props.description != null && props.description !== false ? (props.id ? props.id + "-description" : createId()) : undefined,
+        errorMessageId: props.id ? props.id + "-error" : createId(),
+        extraDescribedBy: props["aria-describedby"],
+    };
+}
+/** `aria-describedby` of the field: description, error message (while `invalid`), then the extra ids. */
+export function describedBy(ids, invalid) {
+    // A live `aria-describedby` (accessor, live props) is read here, inside the caller's binding.
+    const extra = ids.extraDescribedBy;
+    return [ids.descriptionId, invalid ? ids.errorMessageId : undefined, typeof extra === "function" ? extra() : extra].filter(Boolean).join(" ") || undefined;
+}
+/** @deprecated migration shim — remove when no importer (use `labelProps`). */
+export const labelAria = labelProps;
+/** @deprecated migration shim — remove when no importer (use `fieldProps`). */
+export const fieldAria = fieldProps;
+/** @deprecated migration shim — remove when no importer (use `labelsProps`). */
+export const labelsAttrs = labelsProps;

package/label/index.d.ts

@@ -0,0 +1,35 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import type { ValidationResult } from "../state/form-validation.js";
+import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type ContextValue, type HTMLProps, type RefValue, type SlotProps, type StyleObject } from "../slots/index.jsx";
+export { fieldProps, labelProps, labelsProps, fieldAria, labelAria, labelsAttrs, describedBy, type FieldIds, type FieldAriaProps, type LabelAria, type LabelAriaProps, } from "./behaviour.js";
+export { Text, TextContext, type TextProps } from "../text/index.jsx";
+export interface LabelProps extends HTMLProps<"label">, SlotProps, DOMRenderProps<"label", undefined> {
+    /** @default "rv-Label" */
+    class?: string;
+    style?: StyleObject;
+    /** @default "label" */
+    elementType?: string;
+    ref?: RefValue<HTMLLabelElement>;
+    /** Content; a function (not lazy JSX) is reactive content, rendered in a binding (e.g. a context-provided `children: () => title`). */
+    children?: Content | (() => Content);
+}
+export declare const LabelContext: import("@rivetjs/reactivity").Context<ContextValue<LabelProps, HTMLLabelElement>>;
+export declare function Label(props: LabelProps): unknown;
+export interface FieldErrorProps extends Omit<GlobalDOMAttributes<HTMLSpanElement>, "hidden"> {
+    id?: string;
+    /** Validation of the field (read by bindings). */
+    validation: () => ValidationResult;
+    /** Whether the error part shows (default: `validation().isInvalid`); hidden otherwise. */
+    hasError?: () => boolean;
+    /** Message: static content, a function of the validation, or (default) the validation errors joined by a space. */
+    errorMessage?: Content | ((validation: ValidationResult) => Content);
+    /** @default "rv-FieldError" */
+    class?: string;
+}
+/**
+ * RAC `FieldError`: error message of a field, `hidden` while there is nothing to show (RAC renders
+ * nothing; Rivet keeps the node so the id relation and bindings stay in place).
+ */
+export declare function FieldError(props: FieldErrorProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/label/index.jsx

@@ -0,0 +1,85 @@
+// Ported from react-aria-components `Label`, `FieldError` (packages/react-aria-components/src/Label.tsx,
+// FieldError.tsx), Apache-2.0, © Adobe. `Text` lives in `../text/` (re-exported here).
+// Rivet: `Label` merges its props with `LabelContext` (`contextProps`): fields provide
+// `{ id, for, elementType }` from `fieldAria` (`<TextField><Label>…</Label><Input/></TextField>`).
+// `label` / `span` are compiled branches, other `elementType`s render through `Dynamic`.
+// `render` (RAC DOMRenderProps): given, the attributes object goes to `render(attrs, undefined)`; the default path is the compiled element. Deviations: not a hideable collection component; `FieldError` (until it moves to
+// `../form/field-error.tsx`) keeps its node with `hidden` while there is no error.
+import { createContext, untrack } from "@rivetjs/reactivity";
+import { Dynamic } from "@rivetjs/runtime/dom";
+import { renderSlot } from "@rivetjs/runtime/slot";
+import { globalDOMProps } from "@rivetjs/cdk/dom-props";
+import { slotChildren } from "../utils/render.js";
+import { resumableContext, contextProps, markSlotRendered, slottedContext, } from "../slots/index.jsx";
+import { isHiddenPart } from "../collections/hidden.js";
+import { slotProbing } from "#server";
+import { hasLive } from "../utils/live.jsx";
+import { liveElement } from "../utils/live-element.jsx";
+export { fieldProps, labelProps, labelsProps, fieldAria, labelAria, labelsAttrs, describedBy, } from "./behaviour.js";
+export { Text, TextContext } from "../text/index.jsx";
+export const LabelContext = resumableContext(createContext({}, { id: "rv-label" }));
+export function Label(props) {
+    // RAC createHideableComponent: nothing in the collection build pass (its context providers are absent).
+    if (slotProbing || isHiddenPart())
+        return null;
+    const [merged, ref] = contextProps(props, props.ref, LabelContext);
+    // Server: an owner's `createSlot` (rendering after this Label) sees the label (RAC useSlot's ref callback).
+    if (typeof document === "undefined")
+        markSlotRendered(slottedContext(LabelContext, props.slot)?.ref);
+    // Live props (P5): class / style / children live (one `Dynamic` element); `elementType` read once.
+    if (hasLive(merged)) {
+        const live = untrack(() => (merged.render ? null : (merged.elementType ?? "label")));
+        if (live)
+            return untrack(() => liveElement(merged, ref, live, "rv-Label"));
+    }
+    const { elementType = "label", children, class: className, style, slot, render, ...labelProps } = merged;
+    const cls = className ?? "rv-Label";
+    const s = slot ?? undefined;
+    const r = ref;
+    if (render)
+        return render({
+            ...labelProps,
+            style: (typeof style === "function" ? style() : style),
+            slot: s,
+            ref: r,
+            class: cls,
+            children: slotChildren(children),
+        }, undefined);
+    if (elementType === "label")
+        return (<label {...labelProps} style={(typeof style === "function" ? style() : style)} slot={s} ref={r} class={cls}>
+        {renderSlot(children)}
+      </label>);
+    if (elementType === "span")
+        return (<span {...labelProps} style={(typeof style === "function" ? style() : style)} slot={s} ref={r} class={cls}>
+        {renderSlot(children)}
+      </span>);
+    return (<Dynamic component={elementType} {...labelProps} style={(typeof style === "function" ? style() : style)} slot={s} ref={r} class={cls}>
+      {renderSlot(children)}
+    </Dynamic>);
+}
+/** `hidden` is FieldError's own (shown only while there is an error); `style` is bound explicitly (element spread rejects `style`). */
+const FIELD_ERROR_OWNED = ["hidden", "style"];
+/**
+ * RAC `FieldError`: error message of a field, `hidden` while there is nothing to show (RAC renders
+ * nothing; Rivet keeps the node so the id relation and bindings stay in place).
+ */
+export function FieldError(props) {
+    const { errorMessage, validation } = props;
+    const shown = props.hasError ?? (() => validation().isInvalid);
+    // Read props before the JSX: the spread element resumes as one binding (see Button).
+    const dom = globalDOMProps(props, FIELD_ERROR_OWNED);
+    const id = props.id;
+    const className = props.class ?? "rv-FieldError";
+    const style = props.style;
+    if (typeof errorMessage === "function")
+        return (<span {...dom} style={style} id={id} class={className} data-slot="errorMessage" hidden={shown() ? undefined : true}>
+        {errorMessage(validation())}
+      </span>);
+    if (errorMessage != null)
+        return (<span {...dom} style={style} id={id} class={className} data-slot="errorMessage" hidden={shown() ? undefined : true}>
+        {errorMessage}
+      </span>);
+    return (<span {...dom} style={style} id={id} class={className} data-slot="errorMessage" hidden={shown() ? undefined : true}>
+      {validation().validationErrors.join(" ")}
+    </span>);
+}

package/landmark/index.d.ts

@@ -0,0 +1,10 @@
+import { type AriaLandmarkProps, type LandmarkProps, type LandmarkRef } from "./manager.js";
+export { UNSTABLE_createLandmarkController, type AriaLandmarkProps, type AriaLandmarkRole, type LandmarkAria, type LandmarkController, type LandmarkControllerOptions, type LandmarkProps, } from "./manager.js";
+/**
+ * Provides landmark navigation in an application. Call this with a role and label to register a
+ * landmark navigable with F6 (RA `useLandmark`; returns the `landmarkProps` bag).
+ *
+ * @param props - Props for the landmark.
+ * @param ref - Ref to the landmark (`ref()`).
+ */
+export declare function landmarkProps(props: AriaLandmarkProps, ref: LandmarkRef): LandmarkProps;

package/landmark/index.jsx

@@ -0,0 +1,35 @@
+// Ported from react-aria (packages/react-aria/src/landmark/useLandmark.ts: useLandmark), Apache-2.0, © Adobe.
+// Rivet:
+// - `useLandmark(props, ref)` → `landmarkProps(props, ref)`: returns RA's `landmarkProps` bag (`tabIndex`
+//   is a signal accessor); `ref` is a `ref()` (`Ref<T>`, read as `ref()` where RA reads `ref.current`).
+//   Registration (RA: layout effect) is a resumable `clientEffect` with `when: "idle"`: a server-rendered
+//   landmark registers once the page is idle; one rendered in the browser registers right after mounting.
+//   `aria-label` may be an accessor (re-registers on change, as RA re-runs its effect on a new label).
+// - The manager (document access) lives in `./manager.ts`, a plain module the server compile leaves alone.
+import { signal } from "@rivetjs/reactivity";
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { registerLandmark } from "./manager.js";
+export { UNSTABLE_createLandmarkController, } from "./manager.js";
+/**
+ * Provides landmark navigation in an application. Call this with a role and label to register a
+ * landmark navigable with F6 (RA `useLandmark`; returns the `landmarkProps` bag).
+ *
+ * @param props - Props for the landmark.
+ * @param ref - Ref to the landmark (`ref()`).
+ */
+export function landmarkProps(props, ref) {
+    const { role, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, focus } = props;
+    const isLandmarkFocused = signal(false);
+    clientEffect(() => {
+        const label = (typeof ariaLabel === "function" ? ariaLabel() : ariaLabel) || ariaLabelledby;
+        if (!ref())
+            return;
+        return registerLandmark(ref, role, label, focus, isLandmarkFocused);
+    }, { when: "idle" });
+    return {
+        role,
+        tabIndex: () => (isLandmarkFocused() ? -1 : undefined),
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledby,
+    };
+}

package/landmark/manager.d.ts

@@ -0,0 +1,50 @@
+type FocusableElement = HTMLElement | SVGElement;
+export type LandmarkRef = () => FocusableElement | null | undefined;
+export type AriaLandmarkRole = "main" | "region" | "search" | "navigation" | "form" | "banner" | "contentinfo" | "complementary";
+export interface AriaLandmarkProps {
+    role: AriaLandmarkRole;
+    /** Rivet: a string or an accessor. */
+    "aria-label"?: string | (() => string | undefined);
+    "aria-labelledby"?: string;
+    focus?: (direction: "forward" | "backward") => void;
+}
+export interface LandmarkProps {
+    role: AriaLandmarkRole;
+    tabIndex: () => number | undefined;
+    "aria-label"?: string | (() => string | undefined);
+    "aria-labelledby"?: string;
+}
+/** Return of `landmarkProps` (RA `LandmarkAria.landmarkProps`). */
+export interface LandmarkAria {
+    landmarkProps: LandmarkProps;
+}
+export interface LandmarkControllerOptions {
+    /**
+     * The element from which to start navigating.
+     * @default document.activeElement
+     */
+    from?: FocusableElement;
+}
+/** A LandmarkController allows programmatic navigation of landmarks. */
+export interface LandmarkController {
+    /** Moves focus to the next landmark. */
+    focusNext(opts?: LandmarkControllerOptions): boolean;
+    /** Moves focus to the previous landmark. */
+    focusPrevious(opts?: LandmarkControllerOptions): boolean;
+    /** Moves focus to the main landmark. */
+    focusMain(): boolean;
+    /** Moves focus either forward or backward in the landmark sequence. */
+    navigate(direction: "forward" | "backward", opts?: LandmarkControllerOptions): boolean;
+    /**
+     * Disposes the landmark controller. When no landmarks are registered, and no
+     * controllers are active, the landmark keyboard listeners are removed from the page.
+     */
+    dispose(): void;
+}
+/** Creates a LandmarkController, which allows programmatic navigation of landmarks. */
+export declare function UNSTABLE_createLandmarkController(): LandmarkController;
+/** @internal Register a landmark with the current manager (and its replacements); returns the cleanup. */
+export declare function registerLandmark(ref: LandmarkRef, role: AriaLandmarkRole, label: string | undefined, focus: ((direction: "forward" | "backward") => void) | undefined, isLandmarkFocused: {
+    set(value: boolean): unknown;
+}): () => void;
+export {};