# useSelection

The ONE selection model: single/multi over an ordered id list, keyboard focus cursor, shift-range, auto-prune. Selection is staging, never execution.

Install: `npx candlelight-ds add use-selection`

Category: hook · Grammar: G1

## Use when

Any list where rows can be armed or checked.

## Don't use when

A single persistent 'active' object owned by a store (the live thing) — that is the running store's state, not list selection.

## States

- selected → bg-fill-selected
- focused cursor → inset hairline ring
- neither → hover ramp on transparent rest

## Keyboard

- `↑↓ / shift-click / ⌘A` — wire focusDelta, selectRange, toggleAll through the surface map

## Acceptance tests

- Selection prunes automatically when the list changes (filter, sort, strike) without breaking set identity.
- The styling contract is decided once, here — rows read it, never restyle it.

## Files

- hooks/useSelection.ts

npm dependencies: none

Rendered twin: https://candlelight-docs.vercel.app/components/use-selection · Full spec: https://candlelight-docs.vercel.app/spec.md