@solidrt/components 0.0.56 → 0.0.57

package/AGENTS.md

@@ -53,10 +53,13 @@ objects at that level - and the two compose freely in one tree.
   for one custom shape never means giving up `View`/`Text` elsewhere.
 - Focus navigation: `createFocusNav` moves real focus across `focusable`
   elements (Button is focusable by default; Pressable opt-in) - spatially on
-  arrows/dpad, sequentially on Tab/Shift+Tab (reading order, wrapping).
-  Attach its onKeyDown to the window; gamepad dpad/south wire automatically.
-  A focused press control activates on Enter/Space/remote-select via
-  createPress and draws Button's ring under `policy.focusRing` (true when a
+  `navigate`, sequentially on `cycle` (reading order, wrapping), activating
+  on `select`: three input-map actions (`uiActions`), never a device read.
+  Bare, it binds the standard set (`uiBindings`: arrows, Tab, Enter, Space,
+  remote center; dpad, left stick, south on every pad) on its own map,
+  `nav.input`; or pass `input`. Spread `nav.handlers` on the window. A
+  focused press control activates only through `select` (createPress reads
+  no key) and draws Button's ring under `policy.focusRing` (true when a
   keyboard OR gamepad/remote is present). An open Modal traps navigation
   inside itself automatically.
 
@@ -76,7 +79,7 @@ One bullet per module, generated from the first paragraph of its docs/ file.
 - `ScrollView` - A scrollable region; vertical by default, `horizontal` to flip. Both the wheel and dragging scroll the content: the drag activates after a small movement threshold along the scroll axis, also when it starts on a pressable (the press is cancelled and its feedback retracts), and keeps scrolling when the pointer leaves the box. Scrolling glides: the offset springs to each new target (250 ms, critically damped), so a wheel notch never jumps and a burst of notches reads as one motion; a dragging finger is tracked exactly, without the spring. No momentum/fling yet.
 - `Pressable` - A pressable box: `onPress` fires on a primary-button press released over the box; a drag out of the box (or a non-primary button) does not fire it, and a drag back in restores the pressed state. `children` and `style` may each be a function of the live `{ pressed, hovered, pending }` state, so the box restyles on press/hover without extra signals - read the state inside the prop or child expression, never eagerly into a local.
 - `Button` - A themed press target over `Pressable`: a padded, centered box with a label. A press shrinks it slightly on a quick spring and tints it with `overlayPressed`; hover tints with `overlayHover` (non-touch policies). `variant` picks the visual role - `primary` (accent fill, the default), `secondary`, `ghost` (no fill until hover), `danger` (destructive) - with fill, tints, and label color from the matching theme tokens; no variant draws a border. `size` (`sm`/`md`/`lg`) pins a minimum width so a row of buttons lines up (a longer label still expands past it); omitted, the button sizes to its content. A string or number child renders as the themed label; any other child renders as-is (an icon, a row, ...).
-- `createFocusNav` - Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. Two movement types over the same candidates: spatial (arrow keys, dpad) picks the nearest candidate in the pressed direction by on-screen boxes, and sequential (Tab / Shift+Tab) walks visual reading order - rows top to bottom, left to right - wrapping at the ends. Enter / remote center / gamepad south activates the focused control. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
+- `createFocusNav` - Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. It consumes three UI actions from an input map and reads no device: `navigate` (vec2) moves spatially, picking the nearest candidate in the pressed direction by on-screen boxes; `cycle` (axis) walks visual reading order - rows top to bottom, left to right - wrapping at the ends; `select` (button) activates the focused control; a held direction repeats. Created bare, the nav binds the standard set itself (`uiBindings`: arrows, Tab and Shift+Tab, Enter, Space and the remote center key on the keyboard; dpad, left stick and south on every pad) on a map of its own, reachable as `nav.input` for rebinding; given `input`, it consumes the app's map instead. Spread `nav.handlers` on the window. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
 - `Switch` - An on/off toggle: the track fills with `primary` when on and `surfaceAlt` when off (a fade), and the thumb springs across - the `knob` transition entry retimes that travel. Controlled via `value`/`onChange`, or uncontrolled via `defaultValue`. Built on `Pressable`, so `disabled` takes no pointer events. `style` overrides the track colors and radius.
 - `Checkbox` - A checkbox: filled with `primary` and a drawn checkmark when checked, an empty bordered box otherwise - the fill fades and the mark pops in and out. Controlled via `checked`/`onChange`, or uncontrolled via `defaultChecked`. The mark is the `theme.icons.check` slot when a theme sets one. `style` overrides the box colors, border, and radius.
 - `RadioGroup / Radio` - A single-selection pair: `RadioGroup` owns the selected value (controlled via `value`/`onChange`, or uncontrolled via `defaultValue`) and shares it with its `Radio` children; each `Radio` is a ring with an inner dot when selected - the ring color fades and the dot pops in and out. A string/number child of `Radio` renders as a themed label beside the ring; anything else as-is. `disabled` on the group disables every option, on a `Radio` just that one.

package/README.md

@@ -382,30 +382,43 @@ An `onPress` returning a promise makes the button an async action: while it is u
 <Button onPress={async () => { await save() }}>Save</Button>
 ```
 
-A focused Button (see `createFocusNav`) draws a ring in the theme `ring` color under the `focusRing` policy (text-colored by default so it stays visible on primary-filled buttons) and activates on Enter, Space, or a remote's center key. `focusable` (default true) opts out of focus-navigation candidacy; disabled buttons are never candidates.
+A focused Button (see `createFocusNav`) draws a ring in the theme `ring` color under the `focusRing` policy (text-colored by default so it stays visible on primary-filled buttons) and activates on the navigation's `select` action (Enter, Space, a remote's center key or a pad's south button under the standard bindings). `focusable` (default true) opts out of focus-navigation candidacy; disabled buttons are never candidates.
 
 API: `Button`, `ButtonProps`, `ButtonVariant` - typed and commented in [src/button.tsx](./src/button.tsx).
 
 ### createFocusNav
 
-Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. Two movement types over the same candidates: spatial (arrow keys, dpad) picks the nearest candidate in the pressed direction by on-screen boxes, and sequential (Tab / Shift+Tab) walks visual reading order - rows top to bottom, left to right - wrapping at the ends. Enter / remote center / gamepad south activates the focused control. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
+Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. It consumes three UI actions from an input map and reads no device: `navigate` (vec2) moves spatially, picking the nearest candidate in the pressed direction by on-screen boxes; `cycle` (axis) walks visual reading order - rows top to bottom, left to right - wrapping at the ends; `select` (button) activates the focused control; a held direction repeats. Created bare, the nav binds the standard set itself (`uiBindings`: arrows, Tab and Shift+Tab, Enter, Space and the remote center key on the keyboard; dpad, left stick and south on every pad) on a map of its own, reachable as `nav.input` for rebinding; given `input`, it consumes the app's map instead. Spread `nav.handlers` on the window. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
 
 ```jsx
 import { createFocusNav } from "@solidrt/components"
 
 function App() {
   let nav = createFocusNav()
-  return <window onKeyDown={nav.onKeyDown}>...</window>
+  return <Window {...nav.handlers}>...</Window>
 }
 ```
 
-Attaching `nav.onKeyDown` on the window is what keeps it cooperative: key events bubble from the focused node, so a focused TextInput keeps its arrow keys and navigation only sees what nothing else consumed. Gamepad dpad/south are wired automatically.
+Spreading the map's handlers on the window is what keeps it cooperative: key events bubble from the focused node, so a focused TextInput keeps its caret keys (and a typed Space) and navigation only sees what nothing else consumed. Pads need no handler; their sources poll.
+
+Rebind on the nav's own map, or bring a map that also holds the app's actions:
+
+```jsx
+let nav = createFocusNav()
+nav.input.bind("select", gamepad().button("east"))
+
+let input = createInputMap({ ...uiActions, pause: "button" })
+input.bind(uiBindings({ keyboard, gamepad: gamepad() }))
+input.bind("pause", keyboard.key("Escape"), gamepad().button("start"))
+let nav = createFocusNav({ input })
+return <Window {...input.handlers}>...</Window>
+```
 
 When the focused control disappears (an action replacing it, a screen change), focus lands on the nearest candidate to where it sat as soon as the successor is laid out - the ring follows a Disconnect button into the Connect button that replaces it. A deliberate blur (tapping outside, dismissing the keyboard) stays blurred; the next press resumes at the nearest candidate.
 
 An open `Modal` traps navigation inside itself with no extra wiring (topmost wins when stacked); pass `scope: () => nodeOrNull` to trap into some other subtree instead. `move`/`tab`/`activate` are exposed for custom triggers.
 
-API: `createFocusNav`, `FocusNavOptions` - typed and commented in [src/focus-nav.ts](./src/focus-nav.ts).
+API: `createFocusNav`, `uiActions`, `uiBindings`, `FocusNavOptions`, `UiActions`, `UiDevices` - typed and commented in [src/focus-nav.ts](./src/focus-nav.ts).
 
 ### Switch
 

package/docs/button.md

@@ -18,4 +18,4 @@ An `onPress` returning a promise makes the button an async action: while it is u
 <Button onPress={async () => { await save() }}>Save</Button>
 ```
 
-A focused Button (see `createFocusNav`) draws a ring in the theme `ring` color under the `focusRing` policy (text-colored by default so it stays visible on primary-filled buttons) and activates on Enter, Space, or a remote's center key. `focusable` (default true) opts out of focus-navigation candidacy; disabled buttons are never candidates.
+A focused Button (see `createFocusNav`) draws a ring in the theme `ring` color under the `focusRing` policy (text-colored by default so it stays visible on primary-filled buttons) and activates on the navigation's `select` action (Enter, Space, a remote's center key or a pad's south button under the standard bindings). `focusable` (default true) opts out of focus-navigation candidacy; disabled buttons are never candidates.

package/docs/focus-nav.md

@@ -1,17 +1,30 @@
 # createFocusNav
 
-Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. Two movement types over the same candidates: spatial (arrow keys, dpad) picks the nearest candidate in the pressed direction by on-screen boxes, and sequential (Tab / Shift+Tab) walks visual reading order - rows top to bottom, left to right - wrapping at the ends. Enter / remote center / gamepad south activates the focused control. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
+Focus navigation for pointer-free control (TV remote, keyboard, gamepad), moving real focus across the elements declaring `focusable`. It consumes three UI actions from an input map and reads no device: `navigate` (vec2) moves spatially, picking the nearest candidate in the pressed direction by on-screen boxes; `cycle` (axis) walks visual reading order - rows top to bottom, left to right - wrapping at the ends; `select` (button) activates the focused control; a held direction repeats. Created bare, the nav binds the standard set itself (`uiBindings`: arrows, Tab and Shift+Tab, Enter, Space and the remote center key on the keyboard; dpad, left stick and south on every pad) on a map of its own, reachable as `nav.input` for rebinding; given `input`, it consumes the app's map instead. Spread `nav.handlers` on the window. Nothing is focused until the first navigation press; pointer input works unchanged throughout. Every interactive control (Button, Item, TextInput, RichTextEditor, Checkbox, Radio, Switch, Select and its options, SegmentedControl segments, Slider) is a candidate unless disabled, and draws the theme's `ring` color at `borderWidth.focus` while focused under the `focusRing` policy; the Slider steps its value with the arrow keys.
 
 ```jsx
 import { createFocusNav } from "@solidrt/components"
 
 function App() {
   let nav = createFocusNav()
-  return <window onKeyDown={nav.onKeyDown}>...</window>
+  return <Window {...nav.handlers}>...</Window>
 }
 ```
 
-Attaching `nav.onKeyDown` on the window is what keeps it cooperative: key events bubble from the focused node, so a focused TextInput keeps its arrow keys and navigation only sees what nothing else consumed. Gamepad dpad/south are wired automatically.
+Spreading the map's handlers on the window is what keeps it cooperative: key events bubble from the focused node, so a focused TextInput keeps its caret keys (and a typed Space) and navigation only sees what nothing else consumed. Pads need no handler; their sources poll.
+
+Rebind on the nav's own map, or bring a map that also holds the app's actions:
+
+```jsx
+let nav = createFocusNav()
+nav.input.bind("select", gamepad().button("east"))
+
+let input = createInputMap({ ...uiActions, pause: "button" })
+input.bind(uiBindings({ keyboard, gamepad: gamepad() }))
+input.bind("pause", keyboard.key("Escape"), gamepad().button("start"))
+let nav = createFocusNav({ input })
+return <Window {...input.handlers}>...</Window>
+```
 
 When the focused control disappears (an action replacing it, a screen change), focus lands on the nearest candidate to where it sat as soon as the successor is laid out - the ring follows a Disconnect button into the Connect button that replaces it. A deliberate blur (tapping outside, dismissing the keyboard) stays blurred; the next press resumes at the nearest candidate.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/components",
-  "version": "0.0.56",
+  "version": "0.0.57",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -21,6 +21,6 @@
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.6",
-    "@solidrt/core": "0.0.56"
+    "@solidrt/core": "0.0.57"
   }
 }

package/src/editor-field.tsx

@@ -269,6 +269,10 @@ export function EditorField(props: EditorFieldProps) {
       activateField()
     } else if (e.key === "Escape") {
       if (node) setFocus(null)
+    } else if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && textInputActive()) {
+      // A printable key is this field's text (it arrives as a text-input
+      // event); consumed here so a typed Space never reaches the window as
+      // the focus navigation's select.
     } else {
       consumed = false
     }

package/src/focus-nav.ts

@@ -1,37 +1,132 @@
 import {
   createEffect,
+  createInputMap,
   createSignal,
-  gamepads,
+  gamepad,
   getBoundingBoxViewport,
   getFocusables,
   focusedNode,
   getNodePath,
+  keyboard,
+  onCleanup,
   onLayout,
   setFocus,
+  untrack,
 } from "@solidrt/core"
-import type { KeyEvent } from "@solidrt/core"
+import type { Binding, GamepadDevice, InputMap, KeyboardDevice, Vec2 } from "@solidrt/core"
 
 // Focus navigation: the pointer-free control path, so a TV remote, a
 // keyboard, or a gamepad can drive an app. Two movement types over the same
 // candidates, both steering real focus (setFocus) across the elements
 // declaring `focusable`:
 //
-// - Spatial (arrows, dpad): judged by on-screen boxes at press time - the
+// - Spatial (`navigate`): judged by on-screen boxes at press time - the
 //   nearest candidate with progress in the pressed direction wins, so
 //   registration order never matters.
-// - Sequential (Tab / Shift+Tab): visual reading order - rows top to bottom,
-//   left to right within a row, wrapping at the ends. Derived from the same
+// - Sequential (`cycle`): visual reading order - rows top to bottom, left
+//   to right within a row, wrapping at the ends. Derived from the same
 //   boxes rather than registration order, which reordering mounts (a <For>
 //   shuffle) silently scrambles.
 //
-// Activation is split by source: Enter / the remote center key bubble to the
-// focused node itself (createPress consumes them there), while a controller's
-// south button goes through the action registry below. Purely additive to
+// The nav reads no device (ARCHITECTURE.md: controls through an
+// abstraction, never direct event handling). It consumes the three UI
+// actions of an input map - `navigate` (vec2), `cycle` (axis), `select`
+// (button) - the way Flutter's focus widgets consume intents and Godot's
+// controls the ui_* actions. A component library must work with nothing
+// wired, as those two do, so a nav created bare binds the standard set
+// itself (uiBindings over the keyboard and every pad) on a map of its own,
+// reachable as `nav.input` for rebinding; given `input`, it consumes the
+// app's map, which may hold the app's other actions too. Either way the
+// app spreads the map's handlers on the window: keys arrive there only when
+// no focused component consumed them, so a focused TextInput keeps its
+// caret keys and the Slider its arrows.
+//
+// A held direction repeats on the nav's own timing over the action's rate
+// (a first step on the edge, the next after NAV_REPEAT_DELAY, then every
+// NAV_REPEAT_INTERVAL), so pads and remotes walk the way keyboards used to
+// through key repeat. Activation is one path: the `select` press runs the
+// focused node's action from the registry below, for Enter, Space, the
+// remote's center key and the pad's south button alike. Purely additive to
 // pointer input: nothing is focused until the first navigation press, and
 // pointer presses work unchanged throughout.
 
 type Direction = "up" | "down" | "left" | "right"
 
+// A held direction walks: the first step on the edge, the next after this
+// many ms, then one every NAV_REPEAT_INTERVAL ms while it holds.
+const NAV_REPEAT_DELAY = 400
+const NAV_REPEAT_INTERVAL = 100
+// Deflection along the dominant axis of `navigate` (a stick) or on `cycle`
+// below which the action reads as no direction; dpad and arrows read 1.
+const NAV_THRESHOLD = 0.5
+
+/** The UI actions the focus navigation consumes: `navigate` (vec2, the
+ * direction to move focus in the screen convention, x right and y down),
+ * `cycle` (axis: +1 steps to the next candidate in reading order, -1 to
+ * the previous) and `select` (button: activate the focused control). An
+ * app's own map declares them by spreading this object. */
+export const uiActions = { navigate: "vec2", cycle: "axis", select: "button" } as const
+export type UiActions = typeof uiActions
+
+export type UiDevices = { keyboard?: KeyboardDevice; gamepad?: GamepadDevice }
+
+/**
+ * The standard UI bindings: the arrows on `navigate`, Tab and Shift+Tab
+ * on `cycle`, Enter, Space and the remote's center key (code "Select") on
+ * `select` for the keyboard; the dpad and the left stick on `navigate` and
+ * the south button on `select` for a pad. What a bare createFocusNav
+ * binds; an app with its own map applies it with `input.bind(...)`.
+ */
+export function uiBindings(devices: UiDevices): Binding[] {
+  let out: Binding[] = []
+  let kb = devices.keyboard
+  if (kb) {
+    out.push(
+      { action: "navigate", source: kb.arrows },
+      { action: "cycle", source: kb.axis("Shift+Tab", "Tab") },
+      { action: "select", source: kb.key("Enter") },
+      { action: "select", source: kb.key("Space") },
+      { action: "select", source: kb.key("Select") },
+    )
+  }
+  let pad = devices.gamepad
+  if (pad) {
+    out.push({ action: "navigate", source: pad.dpad }, { action: "navigate", source: pad.leftStick }, { action: "select", source: pad.button("south") })
+  }
+  return out
+}
+
+// Steps on a held value: once on the edge, again after NAV_REPEAT_DELAY,
+// then every NAV_REPEAT_INTERVAL until it reads null or changes (a change
+// restarts the delay). Runs under the calling scope: the effect and the
+// timer die with it.
+function repeating<T>(read: () => T | null, step: (value: T) => void): void {
+  let current: T | null = null
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let stop = () => {
+    if (timer == null) return
+    clearTimeout(timer)
+    timer = null
+  }
+  let later = (value: T, delay: number) => {
+    timer = setTimeout(() => {
+      step(value)
+      later(value, NAV_REPEAT_INTERVAL)
+    }, delay)
+  }
+  // The step reads focus and the candidates for itself, a snapshot, not a
+  // dependency: untracked so the strict-mode read diagnostic stays quiet.
+  createEffect(read, (value) => {
+    if (value === current) return
+    current = value
+    stop()
+    if (value === null) return
+    untrack(() => step(value))
+    later(value, NAV_REPEAT_DELAY)
+  })
+  onCleanup(stop)
+}
+
 // What "select" means per focusable node, registered by createPress's ref.
 // Only the controller path consults it - key activation reaches the focused
 // node by bubbling and never comes through here. Package-internal.
@@ -56,6 +151,15 @@ export function pushNavScope(node: { id: number }): () => void {
 }
 
 export interface FocusNavOptions {
+  /**
+   * The input map to consume the UI actions from: it must declare
+   * `navigate`, `cycle` and `select` with the kinds of `uiActions`, and the
+   * app binds it (uiBindings or its own) and spreads its handlers on the
+   * window. Without one the nav makes its own map bound to the standard set
+   * over the keyboard and every pad, which `nav.input` exposes for
+   * rebinding.
+   */
+  input?: InputMap<any>
   /**
    * Restricts reachable candidates to this node's subtree while it returns
    * one, overriding the default (the topmost open Modal, which traps
@@ -71,16 +175,23 @@ type Placed = { id: number; x: number; y: number }
 
 /**
  * Creates focus navigation over the `focusable` elements: spatial movement on
- * arrows/dpad, sequential on Tab/Shift+Tab. Attach the returned onKeyDown to
- * the window - keys arrive there only when no focused component consumed
- * them, so a focused TextInput keeps its caret keys:
+ * `navigate`, sequential on `cycle`, activation on `select`, consumed from an
+ * input map (see FocusNavOptions.input). Spread the map's handlers on the
+ * window - keys arrive there only when no focused component consumed them,
+ * so a focused TextInput keeps its caret keys:
  *
  *   let nav = createFocusNav()
- *   <window onKeyDown={nav.onKeyDown}>...
+ *   <window {...nav.handlers}>...
  *
- * Gamepad dpad/south edges are wired automatically (call it inside a
- * component/root scope). move/tab/activate are exposed for custom triggers.
+ * Call it inside a component/root scope: its effects and repeat timers live
+ * there. move/tab/activate are the verbs, for custom triggers.
  */
+let defaultMap = (): InputMap<UiActions> => {
+  let map = createInputMap(uiActions)
+  map.bind(uiBindings({ keyboard, gamepad: gamepad() }))
+  return map
+}
+
 export function createFocusNav(options?: FocusNavOptions) {
   let currentScope = () => options?.scope?.() ?? scopeStack()[scopeStack().length - 1]
 
@@ -157,9 +268,9 @@ export function createFocusNav(options?: FocusNavOptions) {
   }
 
   // Sequential step in reading order, wrapping at the ends. With no
-  // reachable focus it resumes near the last position; lacking one, Tab
-  // enters at the first element and Shift+Tab at the last (the step "wraps
-  // into" the set from either side).
+  // reachable focus it resumes near the last position; lacking one, a
+  // forward step enters at the first element and a backward one at the
+  // last (the step "wraps into" the set from either side).
   let tab = (delta: 1 | -1) => {
     let placed = reachable()
     if (placed.length === 0) return
@@ -173,9 +284,9 @@ export function createFocusNav(options?: FocusNavOptions) {
     focusCandidate(row[(i + delta + row.length) % row.length]!)
   }
 
-  // Controller select, and Enter reaching the window (nothing focused, or the
-  // focused node did not consume it): with no reachable focus the press lands
-  // focus instead of acting.
+  // The `select` press (Enter, the remote's center key, the pad's south
+  // button, whatever the app bound): runs the focused node's registered
+  // action; with no reachable focus the press lands focus instead of acting.
   let activate = () => {
     let placed = reachable()
     if (placed.length === 0) return
@@ -188,18 +299,6 @@ export function createFocusNav(options?: FocusNavOptions) {
     navActions.get(hit.id)?.()
   }
 
-  // Keyboard and TV remote. Arrows and Tab use key repeat (holding walks
-  // through candidates); activation ignores it. The remote center key's `key`
-  // is "Unidentified", so it is matched by code.
-  let onKeyDown = (e: KeyEvent) => {
-    if (e.key === "ArrowUp") move("up")
-    else if (e.key === "ArrowDown") move("down")
-    else if (e.key === "ArrowLeft") move("left")
-    else if (e.key === "ArrowRight") move("right")
-    else if (e.key === "Tab") tab(e.shiftKey ? -1 : 1)
-    else if ((e.key === "Enter" || e.code === "Select") && !e.repeat) activate()
-  }
-
   // The focused control vanishing (replaced by its own action, a screen
   // change) clears focus; hand it to the nearest successor so the ring
   // never disappears mid-navigation. Only when the node actually died: a
@@ -243,26 +342,26 @@ export function createFocusNav(options?: FocusNavOptions) {
     },
   )
 
-  // Gamepads: edge-detect the dpad and south button on the union of all pads'
-  // pressed buttons. The sticky replay on the first read seeds the baseline
-  // (a button already held at creation fires its edge once).
-  let prevButtons = new Set<string>()
-  createEffect(
-    () => gamepads(),
-    (pads) => {
-      let now = new Set<string>()
-      for (let pad of pads) for (let b of pad?.buttons ?? []) now.add(b)
-      for (let b of now) {
-        if (prevButtons.has(b)) continue
-        if (b === "dpadUp") move("up")
-        else if (b === "dpadDown") move("down")
-        else if (b === "dpadLeft") move("left")
-        else if (b === "dpadRight") move("right")
-        else if (b === "south") activate()
-      }
-      prevButtons = now
-    },
-  )
+  // The map: the app's, checked for the UI actions, or the platform default.
+  let input: InputMap<any> = options?.input ?? defaultMap()
+  for (let [name, kind] of Object.entries(uiActions)) {
+    if (input.actions[name] !== kind) throw new Error(`createFocusNav: the input map needs a ${kind} action "${name}" (declare it with uiActions)`)
+  }
+  // The direction an action reads now, or null: the dominant axis of
+  // `navigate` past the threshold, the sign of `cycle`.
+  let direction = (): Direction | null => {
+    let [x, y] = input.value("navigate") as Vec2
+    if (Math.max(Math.abs(x), Math.abs(y)) < NAV_THRESHOLD) return null
+    if (Math.abs(x) > Math.abs(y)) return x > 0 ? "right" : "left"
+    return y > 0 ? "down" : "up"
+  }
+  let cycleStep = (): 1 | -1 | null => {
+    let v = input.value("cycle") as number
+    return v >= NAV_THRESHOLD ? 1 : v <= -NAV_THRESHOLD ? -1 : null
+  }
+  repeating(direction, move)
+  repeating(cycleStep, tab)
+  onCleanup(input.onPress("select", activate))
 
-  return { onKeyDown, move, tab, activate }
+  return { input, handlers: input.handlers, move, tab, activate }
 }

package/src/index.ts

@@ -9,7 +9,7 @@ export { createDocumentBuffer, plainDocument, ATOM, type Document, type Document
 export { ScrollView, type ScrollViewProps } from "./scroll-view"
 export { Pressable, type PressableProps, type PressState } from "./pressable"
 export { Button, type ButtonProps, type ButtonVariant } from "./button"
-export { createFocusNav, type FocusNavOptions } from "./focus-nav"
+export { createFocusNav, uiActions, uiBindings, type FocusNavOptions, type UiActions, type UiDevices } from "./focus-nav"
 export { Switch, type SwitchProps } from "./switch"
 export { Checkbox, type CheckboxProps } from "./checkbox"
 export { RadioGroup, Radio, type RadioGroupProps, type RadioProps } from "./radio"

package/src/press.ts

@@ -45,12 +45,12 @@ export interface PressOptions {
 // changes live. The host view must attach `ref` for retention bounds; without
 // it every position counts as inside (the up always fires).
 //
-// Keyboard/remote activation: when the host node holds focus (spatial nav or
-// setFocus), Enter, Space, or the remote center key fires onPress and stops
-// propagating; `focused` mirrors the node's focus for styling (a ring). The
-// ref also registers onPress as the node's nav action, the path a
-// controller's south button activates through (see focus-nav.ts). Key
-// activation shows no pressed state - the focus ring is the feedback.
+// Keyboard/remote/controller activation reads no key here: the ref registers
+// onPress as the node's nav action, and the focus navigation's `select`
+// action (Enter, Space, the remote center key, the pad's south button, or
+// whatever the app bound) runs it while the node holds focus (see
+// focus-nav.ts). `focused` mirrors the node's focus for styling (a ring).
+// Key activation shows no pressed state - the focus ring is the feedback.
 // The arena and the movement recognizers (createPan, createTransform) live in
 // core; press stays here because it couples to this package's focus-nav
 // (registerNavAction) and nothing outside components needs it yet
@@ -187,11 +187,6 @@ export function createPress(options: PressOptions) {
       options.onPointerLeave?.(e)
     },
     onKeyDown: (e: KeyEvent) => {
-      // The remote center key's `key` is "Unidentified"; match its code.
-      if ((e.key === "Enter" || e.key === " " || e.code === "Select") && !e.repeat && !options.disabled) {
-        e.stopPropagation()
-        activate()
-      }
       options.onKeyDown?.(e)
     },
     onFocus: () => {