# List

A cross-platform list container with optional section titles and interactive rows. Rows support hover, press, and basic keyboard activation.

## Installation

```bash
npm install @xsolla/xui-list
```

## Imports

```tsx
import { List } from "@xsolla/xui-list";
```

## Quick start

```tsx
import * as React from "react";
import { List } from "@xsolla/xui-list";

export default function QuickStart() {
  return (
    <List>
      <List.Row>Item 1</List.Row>
      <List.Row>Item 2</List.Row>
      <List.Row>Item 3</List.Row>
    </List>
  );
}
```

## API Reference

### `<List>`

Container. Extends `BoxProps`; layout/style props are forwarded to the underlying `Box`.

| Prop       | Type        | Default | Description                                                                                                   |
| ---------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `testID`   | `string`    | —       | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
| `children` | `ReactNode` | -       | Rows and section titles.                                                                                      |

### `<List.Row>`

| Prop        | Type         | Default | Description                                                     |
| ----------- | ------------ | ------- | --------------------------------------------------------------- |
| `children`  | `ReactNode`  | -       | Row content.                                                    |
| `hoverable` | `boolean`    | `false` | Render hover and press background even without a press handler. |
| `onClick`   | `() => void` | -       | Web click handler. Takes precedence when both are set.          |
| `onPress`   | `() => void` | -       | Cross-platform press handler.                                   |

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

When a press handler or `hoverable` is set, the row is focusable (`tabIndex={0}`) and activates on `Enter` or `Space`.

### `<List.Title>`

Section heading rendered above a group of rows.

| Prop       | Type        | Default | Description |
| ---------- | ----------- | ------- | ----------- |
| `children` | `ReactNode` | -       | Title text. |

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

## Examples

### Sectioned list

```tsx
import * as React from "react";
import { List } from "@xsolla/xui-list";

export default function Sectioned() {
  return (
    <List>
      <List.Title>Fruits</List.Title>
      <List.Row>Apple</List.Row>
      <List.Row>Banana</List.Row>
      <List.Title>Vegetables</List.Title>
      <List.Row>Carrot</List.Row>
      <List.Row>Broccoli</List.Row>
    </List>
  );
}
```

### Interactive rows

```tsx
import * as React from "react";
import { List } from "@xsolla/xui-list";

export default function Interactive() {
  return (
    <List>
      <List.Row onPress={() => console.log("1")}>Activate row 1</List.Row>
      <List.Row onPress={() => console.log("2")}>Activate row 2</List.Row>
      <List.Row hoverable>Hoverable but inert</List.Row>
    </List>
  );
}
```

### Settings menu (with Cell)

```tsx
import * as React from "react";
import { List } from "@xsolla/xui-list";
import { Cell } from "@xsolla/xui-cell";
import { ChevronRight } from "@xsolla/xui-icons-base";

export default function SettingsMenu() {
  return (
    <List>
      <List.Title>Account</List.Title>
      <List.Row onPress={() => {}}>
        <Cell>
          <Cell.Text title="Profile" />
          <Cell.Slot>
            <ChevronRight size={16} />
          </Cell.Slot>
        </Cell>
      </List.Row>
      <List.Row onPress={() => {}}>
        <Cell>
          <Cell.Text title="Security" />
          <Cell.Slot>
            <ChevronRight size={16} />
          </Cell.Slot>
        </Cell>
      </List.Row>
    </List>
  );
}
```

## Keyboard

| Key     | Action                                                |
| ------- | ----------------------------------------------------- |
| `Enter` | Activate the focused row when a press handler is set. |
| `Space` | Activate the focused row when a press handler is set. |

## Accessibility

- Interactive rows are focusable via `tabIndex={0}` and respond to `Enter`/`Space`.
- The current implementation passes `role: "list"` / `role: "listitem"` inside the `style` object, where it has no effect on either web or native (`role` is not a valid CSS property and native ignores it). Treat `List` as visually-only and add semantic markup yourself if list semantics are required (e.g. wrap children in a `<ul>` / `<li>` outside the package) and provide an accessible label on the container.
- Decorative icons inside rows should be marked `aria-hidden`.