# rowNavigation

> Keyboard row navigation for a list or table: `j`/`k` and the arrows move one roving focus stop through the rows, Enter or `o` opens a row, `x` toggles its selection checkbox, Space can ask for a peek, and `/` jumps to the page's search field.

```ts
import { rowNavigation } from "@sdxc/ui/app";
```

Walks a list's rows from the keyboard, registering its keys in the page's shortcut registry
under the host's layer, so a list inside a sheet answers above the page's. Rows receive a
2px focus ring drawn inside their edge, so a scrolling container never clips it.

## Signature

```ts
rowNavigation(options?: RowNavigation.Options): MixinDescriptor<HTMLElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `RowNavigation.Options` | Which rows to walk, what opens one, and the copy each key lists under. |

## Examples

```tsx
<ul mix={[rowNavigation({ search: "q", labels: { group: "List", next: "Next", previous: "Previous" } })]}>…</ul>
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/app` too.

### RowPeekEvent

Dispatched, bubbling, on the focused row when Space asks to peek at it, so a page opens the
row's detail beside the list while focus stays on the row.

#### Signature

```ts
new RowPeekEvent(row: HTMLElement)
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `row` | `readonly HTMLElement` | The row asked about. |

### ROW_NAVIGATION_ROW_SELECTOR

Rows the mixin walks when its options name none: marked rows, table body rows, list items.

#### Signature

```ts
const ROW_NAVIGATION_ROW_SELECTOR = "[data-row], tbody > tr, :scope > li"
```

### ROW_NAVIGATION_PRIMARY_SELECTOR

The control opening a row: one marked `data-row-primary`, else its first link.

#### Signature

```ts
const ROW_NAVIGATION_PRIMARY_SELECTOR = "[data-row-primary], a[href]"
```

### ROW_NAVIGATION_ATTRIBUTE

Attribute every row the mixin has indexed carries, which its focus ring is drawn on.

#### Signature

```ts
const ROW_NAVIGATION_ATTRIBUTE = "data-row-navigation"
```

### ROW_PEEK_EVENT

Event a row dispatches when Space asks to peek at it.

#### Signature

```ts
const ROW_PEEK_EVENT = "ui:row-peek" as const
```

### RowNavigation.Labels

The copy each key lists under in the help sheet; an omitted label keeps that key unlisted.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `group?` | `string` | The help-sheet heading the keys list under. |
| `next?` | `string` |  |
| `previous?` | `string` |  |
| `open?` | `string` |  |
| `toggle?` | `string` |  |
| `peek?` | `string` |  |
| `search?` | `string` |  |
| `selected?` | `string` | Announced when `x` checks the row's checkbox. |
| `deselected?` | `string` | Announced when `x` clears the row's checkbox. |

### RowNavigation.Options

Options for rowNavigation.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `rows?` | `string` | Rows to walk, matched inside the host. @default ROW_NAVIGATION_ROW_SELECTOR |
| `within?` | `string` | The nearest ancestor matching this selector becomes the host whose rows are walked, for a mixin carried by a marker element inside the list rather than the list itself. |
| `primary?` | `string` | The control Enter and `o` press inside a row. @default ROW_NAVIGATION_PRIMARY_SELECTOR |
| `search?` | `string` | The `id` of the search field `/` focuses; omitted, `/` stays unbound. |
| `peek?` | `boolean` | Binds Space to dispatch RowPeekEvent on the focused row. @default false |
| `labels?` | `Labels` |  |
| `announcer?` | `Announcer` | Says what `x` did, for a reader who cannot see the checkbox change. |