useSelection

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

npx candlelight-ds add use-selection

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-selectedfocused cursor → inset hairline ringneither → hover ramp on transparent rest

Keyboard

• ↑↓ / shift-click / ⌘Awire focusDelta, selectRange, toggleAll through the surface map

Acceptance

• 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.

Raw twin: /components/use-selection.md·Registry item: /r/use-selection.json