@discourse/types 2026.8.0-fb9247e0 → 2026.9.0-c0ef3a11

package/declarations/app/ui-kit/modifiers/d-roving-focus/types.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Which of the practice page's two focus-management strategies the group uses:
+ * a roving tabindex that moves DOM focus, or `aria-activedescendant` on a controller that keeps
+ * it. Named for the strategies rather than for selection, which the page is emphatic is a
+ * different concept.
+ */
+export type DRovingFocusStrategy = "roving-tabindex" | "active-descendant";
+/**
+ * Whether an `aria-disabled` item is a cursor target. Named for the two behaviours rather than
+ * spelled as a boolean, because the call site should say which one it wants.
+ */
+export type DRovingFocusDisabledItems = "skip" | "focusable";
+export type Orientation = "grid" | "horizontal" | "vertical";
+/**
+ * Controls for moving the cursor to a live item in the roving-focus group.
+ *
+ * The `focus*` members return whether they landed on an item — `false` when the group is
+ * currently empty (e.g. a re-render dropped every item), when the index fails the member's own
+ * numeric predicate, or, for
+ * {@link DRovingFocusApi.focusLogicalIndex}, when the target row is not mounted — so the caller
+ * can fall back. The two stepping members are the exception: they report a three-valued
+ * {@link DRovingFocusStepResult}, because "already at the end" and "nothing to step through" want
+ * different fallbacks. {@link DRovingFocusApi.reannounceActive} moves nothing and carries its own
+ * return contract.
+ */
+export interface DRovingFocusApi {
+    /** Moves the cursor to the first navigable item. */
+    focusFirst(): boolean;
+    /** Moves the cursor to the last navigable item. */
+    focusLast(): boolean;
+    /**
+     * Moves the cursor to a position among the navigable items, clamping an out-of-range index to
+     * the first or last one (and still reporting `true`). A non-integer index reports `false`.
+     */
+    focusIndex(index: number): boolean;
+    /**
+     * Move the cursor to the item whose `data-logical-index` — or, failing that, `data-index` — is
+     * the given ABSOLUTE logical index. This is the addressing a windowed list needs, where the
+     * mounted items are a slice of a much larger set and their NodeList position is not their true
+     * index. The stamp is compared numerically, so a zero-padded value still matches. Returns
+     * `false` when that logical index is not currently mounted (the caller must scroll it into view
+     * first). When no item carries either attribute (a non-windowed group) the index is treated as
+     * positional — but bounds-checked rather than clamped, so an out-of-range index reports `false`
+     * and moves nothing, unlike {@link DRovingFocusApi.focusIndex}.
+     */
+    focusLogicalIndex(index: number): boolean;
+    /**
+     * Active mode only — makes assistive tech read the active item again without moving the
+     * cursor, by dropping `aria-activedescendant` and restoring it a tick later. Re-asserting
+     * the same value is a no-op, so a change is the only thing that can be observed.
+     *
+     * For when the item itself is unchanged but what it says about its context is not: a row
+     * whose `aria-setsize` moved from 2 to 1 under a stationary cursor reports a different
+     * position in a different set, and nothing re-reads it. Returns `false` when there is no
+     * cursor to re-read.
+     */
+    reannounceActive(): boolean;
+    /**
+     * Steps the cursor one item forward, as the corresponding arrow key would. `axis` picks which
+     * axis to travel in a grid; omitted, it follows the group's own orientation.
+     *
+     * Unlike the keyboard path this suppresses the EDGE callback — `onBoundary` announces that a
+     * *reader* pushed against a boundary, which a programmatic call has not done.
+     * `onActiveChange` still fires on a real move, because the cursor really did move.
+     */
+    focusNext(axis?: DRovingFocusAxis): DRovingFocusStepResult;
+    /** The backward counterpart of {@link DRovingFocusApi.focusNext}, with the same contract. */
+    focusPrevious(axis?: DRovingFocusAxis): DRovingFocusStepResult;
+    /** The items the cursor may legally land on, in DOM order. */
+    items(): HTMLElement[];
+    /** The item the cursor currently sits on, or `null` when there is no cursor. */
+    currentItem(): HTMLElement | null;
+    /**
+     * The position of `item` within {@link DRovingFocusApi.items}, or `-1` when it is not a member.
+     *
+     * Deliberately resolved against that list rather than by re-querying the DOM: raw selector
+     * order counts items the cursor can never land on, so an index derived that way addresses a
+     * different item than the one it names as soon as a single hidden or disabled match sits
+     * earlier in the container.
+     */
+    indexOf(item: HTMLElement): number;
+    /**
+     * Moves the cursor onto a specific element, returning `false` (and moving nothing) when it is
+     * not one of {@link DRovingFocusApi.items}. Addressing by element rather than by index is what
+     * lets a caller hold a reference across a re-render without recomputing positions.
+     */
+    focusElement(item: HTMLElement): boolean;
+    /**
+     * Active mode only — drops the cursor entirely, so nothing is highlighted and
+     * `aria-activedescendant` points at nothing until the next move seeds a new one.
+     *
+     * There is deliberately no focus-mode counterpart. There the cursor IS DOM focus, and the
+     * cursor is resolved from `document.activeElement` first, so a clear that does not blur would
+     * clear nothing — while one that did blur would strand focus on `<body>`, which is worse than
+     * the state it set out to fix.
+     *
+     * @returns Whether there was a cursor to drop.
+     */
+    clear(): boolean;
+}
+/**
+ * A single navigation axis. `"grid"` is absent by construction: it names a space that allows
+ * both axes, not a direction a step can travel.
+ */
+export type DRovingFocusAxis = Exclude<Orientation, "grid">;
+/**
+ * Where the cursor goes when no surviving one can be kept. Each value names its own fallback:
+ * `"selected-or-first"` prefers a marked item and settles for the first, `"selected-or-none"`
+ * prefers a marked item and settles for nothing.
+ */
+export type DRovingFocusEntry = "none" | "first" | "selected-or-first" | "selected-or-none";
+/**
+ * The outcome of an API-driven step: `"moved"` when the cursor advanced, `"edge"` when a cursor
+ * exists but is already against a boundary, and `"unavailable"` when the group has no items at
+ * all. Three-valued so a caller can tell "the run ended here" from "there is no run here" and
+ * fall back accordingly.
+ */
+export type DRovingFocusStepResult = "moved" | "edge" | "unavailable";
+export interface DRovingFocusArgs {
+    /**
+     * Which focus-management strategy the group uses. Default `"roving-tabindex"`.
+     *
+     * Shape dictated by: Managing Focus in Composites, which names these two strategies.
+     */
+    focusStrategy?: DRovingFocusStrategy;
+    /**
+     * Navigation axes; `"grid"` (default) allows both, `"horizontal"`/`"vertical"` one. Ignored
+     * under `focusStrategy="active-descendant"`, which is single-axis by construction: it leaves the
+     * horizontal arrows to its controller's caret, so the vertical axis is always the live one
+     * there whatever this says.
+     */
+    orientation?: Orientation;
+    /** CSS selector matching the navigable items within the container. */
+    itemSelector: string;
+    /**
+     * Called when an item is activated: Enter or Space in `"roving-tabindex"` mode, Enter only in `"active-descendant"`
+     * mode, where Space belongs to the controller's caret. Only fires when the key landed on the
+     * item itself, so a control nested inside an item keeps its own activation.
+     *
+     * See {@link DRovingFocusArgs.onActiveChange} for choosing between wiring selection to this and
+     * wiring it to the cursor.
+     */
+    onActivate?: (item: HTMLElement, event: KeyboardEvent) => void;
+    /**
+     * Called whenever the cursor is placed on an item, or with `null` (and no `meta`) when the
+     * highlight is cleared. `meta.pointer` is `true` when a pointer press placed it, which a
+     * consumer can use to move the cursor without revealing it. Fires even when the cursor is
+     * re-placed on the item it already held.
+     *
+     * Driven by actual cursor movement, so in `"roving-tabindex"` mode it reports arrow keys, pointer
+     * presses and the API — not the tab stop being seeded or re-seeded, which moves no cursor —
+     * and the `null` clear is an active-mode signal only.
+     *
+     * With {@link DRovingFocusArgs.onActivate} this pair is the practice page's
+     * selection-follows-focus switch, which is why both exist rather than one. Wire selection here
+     * to have it follow the cursor, or to `onActivate` to make the reader commit deliberately. The
+     * page's "Deciding When to Make Selection Automatically Follow Focus" is the guidance on which
+     * to choose, and a radio group and a listbox land on opposite answers.
+     */
+    onActiveChange?: (item: HTMLElement | null, meta?: {
+        pointer: boolean;
+    }) => void;
+    /**
+     * Called when an arrow key would move the cursor past an end of the GROUP, with `wrap` false
+     * and a cursor already present; wrapping suppresses it. Deliberately reports the boundary
+     * rather than prescribing a response: handing off to a neighbouring control and fetching more
+     * rows are both legitimate, and which one applies is the consumer's business.
+     *
+     * `direction` is LOGICAL — `"forward"` means past the last item in DOM order, whichever arrow
+     * key produced it. In a right-to-left group the forward horizontal key is ArrowLeft, so a
+     * consumer handing off to a neighbouring control must resolve the physical side itself.
+     *
+     * `axis` names the axis travelled, and the two are not symmetric. `"horizontal"` requires
+     * `"horizontal"` or `"grid"` orientation and never fires under `focusStrategy="active-descendant"`, which
+     * leaves the horizontal arrows to its controller's caret. `"vertical"` requires `"vertical"`
+     * or `"grid"` in `"roving-tabindex"` mode, but fires in `"active-descendant"` mode whatever `orientation` says,
+     * because there the vertical axis is always the live one. A consumer that means "leave the
+     * widget" must therefore branch on `axis` rather than treat every boundary alike.
+     *
+     * Under a multi-column grid a ROW edge is not a group edge, so an interior row never fires
+     * this — otherwise a consumer would be dragged away mid-traversal.
+     */
+    onBoundary?: (direction: "forward" | "backward", axis: DRovingFocusAxis) => void;
+    /**
+     * The size of the logical index space addressed by `data-logical-index` or `data-index`,
+     * including disabled rows. Setting it is what makes PageUp/PageDown page: without it those keys
+     * are left alone entirely so a scrollable container pages natively, Home and End address the
+     * mounted items positionally, and {@link DRovingFocusArgs.onJump} is never called.
+     */
+    logicalCount?: number;
+    /**
+     * Called when a logical jump target is outside the currently-mounted item window, so the
+     * consumer can mount and focus that row. Without it an off-window jump cannot be serviced, so
+     * the key is left un-prevented rather than becoming a dead key.
+     */
+    onJump?: (target: number, direction: "forward" | "backward") => void;
+    /**
+     * Registers stable controls for moving the cursor, and receives `null` on teardown or when
+     * superseded by a different callback. Compared by identity, so pass a stable reference — an
+     * inline arrow re-registers on every render, and would take a `null` each time first.
+     */
+    onRegisterApi?: (api: DRovingFocusApi | null) => void;
+    /** Whether navigation wraps at the ends (default `false` = clamp). */
+    wrap?: boolean;
+    /**
+     * Focus mode: whether one item is reachable with Tab (default `true`).
+     *
+     * Shape dictated by: Navigation Between Components, the single-tab-stop contract.
+     */
+    tabStop?: boolean;
+    /**
+     * Focus mode: whether removing the item that holds focus moves the cursor to the item that
+     * took its place, rather than letting focus fall to `body` (default `true`).
+     *
+     * Only fires when focus was genuinely lost, so a reader who moved focus elsewhere before the
+     * removal keeps it. When the group empties entirely nothing happens: where focus should go
+     * with no items left is the consumer's decision.
+     *
+     * **Depends on the modifier being told the items changed.** Reconciliation runs from
+     * `modify()`, which re-runs only when a named argument does, so a group whose items come from
+     * state this cannot observe must pass {@link DRovingFocusArgs.itemsKey}. Without it there is
+     * no failure to see: focus simply falls to `body` as though this were off. Defaulting to
+     * `true` does not make it independent of that contract.
+     *
+     * Turn it off to place focus yourself, e.g. onto a control outside the group.
+     */
+    restoreLostFocus?: boolean;
+    /**
+     * Class toggled on the active item in `"active-descendant"` mode.
+     *
+     * Shape dictated by: Discernible and Predictable Focus, where the indicator must stay visible.
+     */
+    activeClass?: string | null;
+    /**
+     * A reactive key (e.g. the filter string) that re-reconciles the cursor when it changes. The
+     * modifier only re-runs when a named arg does, so a group whose items change from state the
+     * modifier cannot see needs this to keep its cursor and tab stop correct.
+     */
+    itemsKey?: unknown;
+    /**
+     * A reactive key identifying the *question* the items answer. Reconciling normally keeps the
+     * cursor on the active item whenever it survives the change, which is right when rows are
+     * appended or revised but wrong when the list becomes a different result set: a row that
+     * happens to match both queries would hold the cursor deep in the new list. Change this and
+     * the cursor stops tracking the survivor: in `"active-descendant"` mode it re-seeds per
+     * {@link DRovingFocusArgs.entryFocus}; in `"roving-tabindex"` mode the tab stop is picked afresh rather
+     * than left on a surviving row.
+     *
+     * Key it on the query the *rendered* items answer, not the one being typed — a list that
+     * keeps its old rows visible during an async reload would otherwise re-seed against them.
+     */
+    resetKey?: unknown;
+    /**
+     * Active mode: the element that keeps DOM focus, as an `HTMLElement` or a document-wide
+     * selector. Its editability changes the key contract — a text input keeps Home/End for its
+     * caret, while a non-editable controller (a select-only combobox) hands them to the listbox.
+     * `null` is a legitimate transient while the controller has yet to render.
+     *
+     * A selector is resolved when the arguments change, not continuously, so a controller that is
+     * destroyed and re-created under the same selector must be signalled — pass the element itself,
+     * or change another argument — or the listener stays on the detached node.
+     *
+     * Shape dictated by: Managing Focus in Composites Using aria-activedescendant.
+     */
+    controllerElement?: HTMLElement | string | null;
+    /**
+     * Where the cursor goes when there is no surviving one to keep. Default
+     * `"selected-or-first"`.
+     *
+     * Each value names its own fallback, because the fallback is the whole distinction:
+     *
+     * - `"none"` — nothing becomes active.
+     * - `"first"` — the first navigable item, whatever is marked.
+     * - `"selected-or-first"` — the marked item, else the first.
+     * - `"selected-or-none"` — the marked item, else nothing.
+     *
+     * "Marked" means `aria-selected="true"`, `aria-checked="true"` or an `aria-current` token other
+     * than `"false"` or empty. The consumer owns those attributes; this only reads them.
+     *
+     * The two modes answer different questions with the same values. Under
+     * `focusStrategy="roving-tabindex"` this is the entry convention from the keyboard-interface practice:
+     * where focus lands when Tab moves into the composite. Toolbars and menubars enter on the
+     * first control (`"first"`), while listboxes, radio groups, tabs and trees enter on the
+     * selected one. Under `focusStrategy="active-descendant"` it is instead what is active when a popup
+     * opens, which the combobox pattern leaves to the author: a list that waits for the reader to
+     * type or arrow wants `"none"`, and one that should not pre-highlight an arbitrary row but
+     * should still restore a held value wants `"selected-or-none"`.
+     *
+     * A surviving cursor always outranks this. In focus mode an established tab stop is kept, and
+     * in active mode a still-present active item is kept, so this only decides the *first* entry
+     * and re-entry after a {@link DRovingFocusArgs.resetKey} change.
+     *
+     * In focus mode the two no-fallback values leave the group with no tab stop unless the author
+     * supplies one, which is a deliberate way to hand that choice back rather than an oversight.
+     *
+     * Shape dictated by: Navigation Inside Components, and its three entry conventions.
+     */
+    entryFocus?: DRovingFocusEntry;
+    /**
+     * Whether {@link DRovingFocusArgs.entryFocus}'s first-item fallback skips items the consumer
+     * has marked. Default `false`.
+     *
+     * The case it exists for is a multi-select whose Enter *toggles*: seeding the fallback onto an
+     * already-selected row arms the very first Enter to discard a value the reader never navigated
+     * to. Arrow keys still reach those rows, where removing them is deliberate.
+     *
+     * Constrains the fallback only, never a restored selection: the reader chose that row
+     * themselves and can see it is marked, so it is seeded even where activating it would remove
+     * it.
+     *
+     * **Scoped to a popup that seeds itself, and deliberately NOT the listbox convention.** The
+     * listbox pattern says the opposite for a multi-select group receiving focus — land on the
+     * first selected option, returning the reader to their own selection — and accepts that the
+     * next toggle key removes it, because they tabbed in on purpose and can see where the cursor
+     * is. This exists for the case that pattern does not cover: a combobox popup where the cursor
+     * is placed automatically, focus is still in the input, and Enter reads as "take this" rather
+     * than "toggle this", so an auto-seeded cursor on a held row silently drops a value the reader
+     * never navigated to. Reach for `entryFocus="selected-or-first"` in a listbox; reach for this
+     * in a popup.
+     */
+    fallbackSkipsMarked?: boolean;
+    /**
+     * Whether the cursor may rest on an item the consumer has marked `aria-disabled="true"`.
+     * Default `"skip"`, which is what a listbox or combobox wants.
+     *
+     * The practice page's section on the focusability of disabled controls draws a distinction
+     * this collapses by default: `disabled` is for state a reader can infer from context, while
+     * `aria-disabled` is for state that must stay discoverable, because moving focus to a control
+     * is how a screen reader user finds out it exists at all. Toolbars and menus are the patterns
+     * that need it.
+     *
+     * `"focusable"` widens where the cursor may LAND, and nothing else. A disabled item is still
+     * never activated, so {@link DRovingFocusArgs.onActivate} does not fire on one under either
+     * value. Reachable and operable are separate questions and only the first is opened here.
+     *
+     * Note the asymmetry with native `disabled`, which no value can override: the platform
+     * refuses focus to such a control outright, so targeting one would strand focus on `body`
+     * rather than move it. Only the ARIA spelling is affected.
+     *
+     * Shape dictated by: Focusability of disabled controls.
+     */
+    disabledItems?: DRovingFocusDisabledItems;
+    /**
+     * Called for an arrow press on the axis this group does NOT navigate, so the keys a
+     * single-axis composite leaves unused become available without every consumer re-deriving
+     * them. A `"vertical"` group reports the horizontal arrows and a `"horizontal"` group reports
+     * the vertical ones; a `"grid"` navigates both and so never reports either.
+     *
+     * Deliberately reports a direction rather than prescribing a response, exactly as
+     * {@link DRovingFocusArgs.onBoundary} does, because the meaning varies per pattern: expand
+     * and collapse for a tree, enter and exit a cell for a treegrid, open and close a submenu for
+     * a menubar. Those semantics are the consumer's; only the key handling is shared.
+     *
+     * `direction` is LOGICAL and already mirrored where the axis mirrors. In a right-to-left
+     * group the forward horizontal key is ArrowLeft, which is what a reader expects when the
+     * arrow pointing at a row's children is the one that opens them. The vertical axis does not
+     * mirror, so a horizontal group reports ArrowDown as `"forward"` whatever the direction.
+     *
+     * Return `true` when the press was acted on and the modifier will consume it. Return nothing
+     * to leave it un-prevented so it can bubble, which is what a leaf node or an
+     * already-collapsed row needs. Never fires while the cursor rests nowhere, since there would
+     * be no item to report it against.
+     */
+    onCrossAxis?: (direction: "forward" | "backward", item: HTMLElement, event: KeyboardEvent) => boolean | void;
+    /**
+     * Whether typing printable characters moves the cursor to the item whose accessible NAME
+     * starts with what was typed. Default `false`.
+     *
+     * The practice page specifies this identically for listbox, tree and menu, which is why it
+     * lives here rather than in each of them. Matching is on the accessible name — what assistive
+     * technology announces — rather than on text content, so an item labelled by `aria-label` or
+     * by a pseudo-element is reachable exactly as it is heard.
+     *
+     * Comparison folds case and diacritics, so `e` finds `Éclair`. Successive characters extend
+     * the query and narrow the match; the query lapses after a short pause, and Space extends it
+     * rather than activating while one is under way.
+     *
+     * Declined when the DOM holds only part of the set — {@link DRovingFocusArgs.logicalCount}
+     * exceeding the mounted count — because answering from those rows returns a nearer match
+     * while a truer one sits off-window, which is worse than not answering. A consumer that wants
+     * it there has to search its own data, which needs a callback this does not yet have.
+     *
+     * A logical count alone does not decline it: that argument also drives paging, and a
+     * fully-mounted list may set it for that alone. Note the completeness test relies on the
+     * consumer declaring the count honestly — a group that windows without saying so is searched
+     * as though it were whole, and nothing here can detect that. The same honesty applies in
+     * reverse: a selector-matched row that is not yet searchable — a placeholder awaiting its
+     * content — still counts as mounted, so keep placeholders out of `itemSelector` (or out of
+     * the count) while they are empty.
+     */
+    typeAhead?: boolean;
+}
+export interface DRovingFocusSignature {
+    Element: HTMLElement;
+    Args: {
+        Named: DRovingFocusArgs;
+        Positional: [];
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/declarations/app/ui-kit/modifiers/d-roving-focus/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/ui-kit/modifiers/d-roving-focus/types.ts"],"names":[],"mappings":"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"}

package/declarations/app/ui-kit/modifiers/d-roving-focus.d.ts

@@ -0,0 +1,105 @@
+import type Owner from "@ember/owner";
+import Modifier, { type ArgsFor } from "ember-modifier";
+import type { DRovingFocusArgs, DRovingFocusSignature } from "./d-roving-focus/types";
+export type { DRovingFocusApi, DRovingFocusAxis, DRovingFocusDisabledItems, DRovingFocusEntry, DRovingFocusStepResult, DRovingFocusStrategy, } from "./d-roving-focus/types";
+/**
+ * Keyboard navigation for a one-dimensional list or a two-dimensional grid of
+ * items, in DOM order.
+ *
+ * Its conformance target is the WAI-ARIA Authoring Practices' keyboard-interface practice,
+ * https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ — the sections implemented here
+ * are Discernible and Predictable Focus, Navigation Between Components, Navigation Inside
+ * Components, and the focusability of disabled controls. Focus VS Selection is split: the
+ * modifier owns the indicator, the consumer owns the chosen value.
+ *
+ * **Where the boundary falls.** Key BINDINGS come from the individual pattern pages, which that
+ * document delegates to, and pattern-specific SEMANTICS belong to consumers. So the modifier
+ * moves a cursor and reports what happened; what a step, an activation or a cross-axis press
+ * MEANS for a tree, a menubar or a treegrid is not its business. A behaviour earns a place here
+ * only if it means the same thing in every composite pattern.
+ *
+ * **What the practice page does not ask for.** Five arguments are deliberate extensions:
+ * `logicalCount`, `onJump` and `onRegisterApi` pair the cursor with a virtualised list, where the
+ * DOM holds a window rather than the whole set, and `itemsKey` and `resetKey` are reactivity
+ * plumbing. They are collected here so the conformance surface stays legible.
+ *
+ * It implements the two WAI-ARIA "single tab stop" patterns
+ * from one engine, chosen with `focusStrategy`:
+ *
+ * - `"roving-tabindex"` (the default) — exactly one item is reachable with Tab
+ *   (`tabindex="0"`) and the rest are set to `tabindex="-1"`; with `tabStop=false` every item is
+ *   set to `-1`. Arrow keys move real DOM focus between items and update tabindex along with it.
+ *   Use this when the active item should itself hold focus (a tile grid, a toolbar).
+ * - `"active-descendant"` — DOM focus stays on a separate controller
+ *   element (typically a text input); arrow keys move a *virtual* highlight through
+ *   the items by pointing the controller's `aria-activedescendant` at the active
+ *   item and toggling `activeClass` on it. Use this for a combobox where the user
+ *   must keep typing while navigating results.
+ *
+ * The single-tab-stop invariant holds as long as the modifier is told when the items change:
+ * it only re-runs when a named argument does, so a group whose rows come from state it cannot
+ * see must pass `itemsKey`.
+ *
+ * Navigation is always DOM order, which is a CONSTRAINT ON CONSUMERS rather than an
+ * implementation detail: the practice page stresses keeping the navigation order aligned with
+ * reading order, and CSS can reorder a grid visually (`order`, `grid-auto-flow: dense`, an
+ * explicit line placement) without moving anything in the DOM. Where those disagree the cursor
+ * follows the DOM and the reader sees it jump. Order the markup the way it should be read.
+ *
+ * Row and column arithmetic uses the items that occupy a layout
+ * position — a disabled or `visibility: hidden` row still fills its cell, so counting only the
+ * navigable ones would land a vertical step a column adrift. The column count is derived from
+ * the resolved `grid-template-columns` at keydown time, never from element geometry
+ * (`offsetTop`/`offsetLeft`), so a responsive grid that reflows is handled without
+ * re-configuration. Only a CSS grid publishes a track list, so a group laid out some other
+ * two-dimensional way (wrapping flex, multi-column) navigates on one axis, and says so in
+ * development.
+ *
+ * The modifier is deliberately role-agnostic: the consumer supplies the container
+ * and item roles (`role="listbox"`/`"grid"` + `role="option"`, and, for active mode,
+ * `role="combobox"` + `aria-controls` on the controller). The modifier owns only the
+ * keyboard cursor — `tabindex` (focus mode) or `aria-activedescendant` + `activeClass`
+ * plus an `id` minted onto any highlighted item that lacks one (active mode). It never touches
+ * `aria-selected`, which expresses a *chosen value* (a separate concept the consumer owns).
+ *
+ * @example A toolbar whose buttons are navigated with the left and right arrows.
+ * ```gjs
+ * <div role="toolbar" {{dRovingFocus orientation="horizontal" itemSelector="[role=button]"}}>
+ *   <button role="button">Bold</button>
+ *   <button role="button">Italic</button>
+ * </div>
+ * ```
+ *
+ * @example A combobox whose input keeps focus while the arrows move a virtual highlight.
+ * ```gjs
+ * <input id="q" role="combobox" aria-controls="results" />
+ * <div
+ *   id="results"
+ *   role="listbox"
+ *   {{dRovingFocus
+ *     focusStrategy="active-descendant"
+ *     controllerElement="#q"
+ *     itemSelector="[role=option]"
+ *     activeClass="--active"
+ *     itemsKey=this.query
+ *     onActivate=this.choose
+ *   }}
+ * >
+ *   {{#each this.results key="id" as |result|}}
+ *     <div role="option" id={{result.id}}>{{result.label}}</div>
+ *   {{/each}}
+ * </div>
+ * ```
+ */
+export default class DRovingFocusModifier extends Modifier<DRovingFocusSignature> {
+    #private;
+    constructor(owner: Owner, args: ArgsFor<DRovingFocusSignature>);
+    /**
+     * Reads the named args, (re)binds the keydown listener to the right element, and
+     * seeds the cursor. Re-runs whenever a tracked arg changes — passing
+     * `itemsKey=this.query` is how a filtering consumer asks the modifier to
+     * re-reconcile the cursor against a freshly-rendered item set.
+     */
+    modify(element: HTMLElement, _positional: [], named: DRovingFocusArgs): void;
+}
+//# sourceMappingURL=d-roving-focus.d.ts.map

package/declarations/app/ui-kit/modifiers/d-roving-focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d-roving-focus.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/ui-kit/modifiers/d-roving-focus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,QAAQ,EAAE,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAYxD,OAAO,KAAK,EAEV,gBAAgB,EAChB,qBAAqB,EAEtB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAM,CAAC,OAAO,OAAO,oBAAqB,SAAQ,QAAQ,CAAC,qBAAqB,CAAC;;gBA+KnE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAO9D;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;CA8T7E"}

package/declarations/app/ui-kit/modifiers/d-swipe.d.ts

@@ -79,6 +79,7 @@ interface DSwipeSignature {
  * with the current state of the swipe, including its direction, orientation, and delta values.
  *
  * @example
+ * ```hbs
  * <div {{swipe
  *        onDidStartSwipe=this.onDidStartSwipe
  *        onDidSwipe=this.onDidSwipe
@@ -88,6 +89,13 @@ interface DSwipeSignature {
  * >
  *   Swipe here
  * </div>
+ * ```
+ *
+ * Guide to choosing between the gesture primitives:
+ * `docs/developer-guides/docs/03-code-internals/30-drag-and-gesture-primitives.md`
+ *
+ * @see The `dPointerDrag` modifier for a value that tracks the pointer continuously. This
+ *   reports a discrete directional flick, not a continuous transform.
  */
 export default class DSwipeModifier extends Modifier<DSwipeSignature> {
     #private;

package/declarations/app/ui-kit/modifiers/d-swipe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"d-swipe.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/ui-kit/modifiers/d-swipe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,QAAQ,EAAE,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIxD,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,aAAa,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAExC,uCAAuC;IACvC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEjC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAElB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IAEf,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IAEf,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;IAEf,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAE5C,6CAA6C;IAC7C,OAAO,EAAE,WAAW,CAAC;IAErB,uDAAuD;IACvD,OAAO,EAAE,MAAM,OAAO,CAAC;IAEvB,yDAAyD;IACzD,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB,yDAAyD;IACzD,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,EAAE,KAAK,CAAC;CACtB;AAED,UAAU,eAAe;IACvB,uDAAuD;IACvD,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE;QACJ,KAAK,EAAE;YACL;;;;eAIG;YACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;YAE5D,oEAAoE;YACpE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;YAEzC,oCAAoC;YACpC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;YAE5C,oEAAoE;YACpE,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;YAEvD,oFAAoF;YACpF,OAAO,CAAC,EAAE,OAAO,CAAC;YAElB,0FAA0F;YAC1F,QAAQ,CAAC,EAAE,OAAO,CAAC;SACpB,CAAC;QACF,UAAU,EAAE,EAAE,CAAC;KAChB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,QAAQ,CAAC,eAAe,CAAC;;IAClD,IAAI,EAAE,IAAI,CAAC;gBAYhB,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC;IAKxD;;;;;;OAMG;IACH,MAAM,CACJ,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,EAAE,EACf,EACE,eAAe,EACf,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,OAAO,EACP,QAAQ,GACT,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;IAwBrC;;;;OAIG;IAEH,eAAe,CAAC,KAAK,EAAE,KAAK;IAgB5B;;OAEG;IAEH,aAAa,CAAC,KAAK,EAAE,KAAK;IAM1B;;OAEG;IAEH,UAAU,CAAC,KAAK,EAAE,KAAK;IAKvB;;OAEG;IAEH,gBAAgB,CAAC,KAAK,EAAE,KAAK;IAM7B;;OAEG;IAEH,QAAQ,CAAC,KAAK,EAAE,KAAK;CAwBtB"}
+{"version":3,"file":"d-swipe.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/ui-kit/modifiers/d-swipe.ts"],"names":[],"mappings":"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"}