# XWUICardXGroup

The state container for a set of [XWUICardX](../XWUICardX/XWUICardX.md) cards.

A card can own its own hover: that is one element reacting to one pointer. Everything else about a *set* of cards is state no card can see.

| State | Why a card cannot own it |
|---|---|
| Which of N is active | A card cannot know it is the third of six |
| Which are selected | Selecting one may have to clear another |
| Where an arrow key goes | Requires knowing the neighbours and the ends |
| One tab stop, not N | Roving tabindex is a property of the set |
| Track sizing | The feature ratio is relative to the other columns |

Left to the cards, each of those becomes a page-level `forEach` that every consumer re-invents slightly differently.

| Prop | Values | Default | Decides |
|---|---|---|---|
| `flow` | `rail` `grid` | `rail` | One scrolling row, or a wrapping grid |
| `columns` | number | `4` | Column count for `grid` |
| `featureFirst` | boolean | `false` | Give card 0 a wider column |
| `featureUnits` | number | `3.22` | How many ordinary widths that column is worth |
| `selection` | `none` `single` `multi` | `none` | What a click does |
| `roving` | boolean | `true` | Arrow-key navigation, group is one tab stop |
| `wrap` | boolean | `true` | Arrows wrap at the ends |
| `card` | XWUICardX config | - | Applied to every card; per-card `conf` overrides it |

## Activation is not selection

**Activation** is where focus sits and moves with the arrow keys. **Selection** is what the user chose and only changes on click, Enter or Space. Conflating them means arrowing across a rail selects everything you pass.

Only selection paints by default. Activation is expressed through real focus, so the group never draws a second highlight competing with the card's own focus ring.

## The 3.22

`featureUnits` defaults to 3.22 because that is the ratio that makes a `43/20` tile exactly as **tall** as a `2/3` tile beside it: at a common height *h* they are 2.15*h* and 0.667*h* wide. A mixed rail therefore lands on one baseline with no fixed pixels. Change it to match whatever two aspects you pair.

## Programmable, not just interactive

`setActiveIndex()`, `toggleSelection()`, `getSelected()`, `setCards()` and `getCards()` mean the state is drivable from code, which is what makes gamepad input, deep links and "restore where they were" possible.

```api
```