# Form Guide

> A team's last results as W, D, and L on tinted squares, oldest first, with a peek that lists the scores, latest first.

- Name: `form-guide`
- Status: beta
- Categories: sport, display
- File: the install writes `form-guide.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/hover-card`. The install adds them.
- Gallery: https://arbokui.com/components/form-guide
- Registry item: https://arbokui.com/r/form-guide.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/form-guide
   ```

## Use it for

- A team's recent results in a table row, a fixture card, or a team header.
- Pass results oldest first. The latest sits on the right.
- Add score, opponent, away, and date to each result, and the guide opens a peek that lists them, latest first.
- In a table or list, mark each row with data-peek-row. The peek then opens beside the row, so the rows above and below stay in reach.
- Use size='sm' in dense tables.

## Avoid it for

- A full results list. Use a table, with the date, the opponent, and the score in columns.
- Anything that is not a win, a draw, or a loss. Use Badge.

## Props

- `results`: `{ result: "W" | "D" | "L"; score?: string; opponent?: string; away?: boolean; date?: string }[]`. Required. The last results, oldest first. A win is green, a loss red, a draw ink, and the letter always says it. An empty list shows a dash.
- `size`: `"sm" | "md" | "lg"`. Default `"md"`. Squares of 18, 22, or 28px at the default density.
- `aria-label`: `string`. Default `"Form"`. What screen readers hear before the results.
- `className`: `string`. Extra classes for the row of squares. Later classes win.

## Accessibility

- Screen readers hear 'Form, oldest to latest: won, won, lost'. The letters say the result, so color is never the only signal.
- With no details it is role="img" with that name, and no tab stop.
- With details it is a HoverCard trigger: a focusable role="button" with that name and aria-haspopup="dialog".
- Focus opens the peek at once, a short rest of the pointer opens it, and so does a tap. Enter or Space moves focus into it, and Esc closes it and puts focus back.
- ↑ and ↓ step to the peek above or below, as on every peek, and only one peek shows at a time.
- The peek is a dialog named 'Last 5, latest first', which it also shows as its title. It lists each result as a line of text.
- The squares use the tones' soft colors, which the theme holds to 4.5:1 with their letters.

## Examples

### Results only

```tsx
<FormGuide results={[{ result: "W" }, { result: "W" }, { result: "L" }, { result: "D" }, { result: "W" }]} />
```

### With a peek

```tsx
<FormGuide
  results={[
    { result: "L", score: "12–19", opponent: "Bears", away: true, date: "Sat 12 Sep" },
    { result: "W", score: "31–10", opponent: "Hawks", date: "Sat 19 Sep" },
    { result: "W", score: "24–17", opponent: "Lions", date: "Sat 26 Sep" },
  ]}
/>
```