# `lr-swatch-picker` - **Import** `import '@aceshooting/lyra-ui/components/lr-swatch-picker.js';` (stable tag alias; registers the tag) - **Class** `LyraSwatchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.class.js` - **Family** `components/forms/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** none - **Themeable via** 4 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-swatch-picker` A single-select picker over a small, fixed set of color swatches with the WAI-ARIA APG `radiogroup` contract built in: `role="radiogroup"`/`role="radio"`, roving tabindex, automatic activation (click or arrow-key move both select immediately, like a native radio group), cyclic Arrow/Home/End navigation. First-party invention (no Web Awesome equivalent). Distinct from `lr-color-picker`, which is a freeform picker over the whole colour space — this picks exactly one of N designer-chosen named colors, the shape apps otherwise hand-roll as a row of round accent-color buttons. Its `items` are the _only_ choices; a `lr-color-picker`'s `swatches` are a shortcut list alongside a grid, a hue ramp and a text field that can still express any colour. Arrow/Home/End navigation starts from the swatch that actually received the keyboard event, even when a controlled `value` write changed the selected or remembered roving item first. Own `disabled` changes take effect immediately for host `click()` and `focus()`, including calls in the same task as the property assignment. Blocked activation leaves value and `lr-change` untouched; blocked focus preserves outside focus and emits no native focus inside the picker. **Properties:** - `items: readonly SwatchPickerItem[] = []` (attribute: false) — `SwatchPickerItem { readonly value: string; readonly color: string; readonly label: string; readonly icon?: unknown; readonly gemstone?: GemstoneKey }`; a valid CSS `color` is used as the swatch fill, while invalid values, declaration-breaking input, and `url()` are ignored (and are never interpolated into a gemstone SVG). `label` is each swatch's accessible name and `title`. `icon` is an optional custom shape rendered _instead of_ the plain filled circle. Its rendered subtree stays visible but is inert and hidden from assistive technology, so the swatch button remains the sole action. `gemstone` selects the canonical faceted glyph when `mode="gemstone"`. An explicit `icon` wins over `gemstone`. Assignments are bounded and copied into a frozen owned snapshot; mutate a new array/item and reassign it to update the palette. - `value: string | null = null` — the currently selected option's `value` (controlled); `null` leaves nothing selected while keeping the first swatch tabbable. - `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — scales the swatch hit-area and fill diameter proportionally, hit-area floored at 24px; not pixel-matched to `lr-input`'s row-height scale) - `mode: 'swatch' | 'gemstone' = 'swatch'` (reflected) — `swatch` preserves the plain-circle default. `gemstone` renders the shared glyph for options carrying a `gemstone` key and enables the selected glow/shine defaults. That automatic glyph's checked-state halo/shine is the exact `gemstoneSelectedGlyphStyles` stylesheet the theme module also exports standalone (see `theme/gemstones.js` below), so a glyph rendered elsewhere on the page — e.g. a header trigger showing the current selection — can match this picker exactly by consuming the same export. An explicit `icon` on a `gemstone`-mode item is a consumer shape, not that shared glyph, and keeps this picker's own generic selected-icon glow instead (see `--lr-swatch-picker-gemstone-*` below). - `accessibleLabel: string = ''` (attribute `aria-label`) — accessible name copied to the internal `role="radiogroup"`; attribute presence wins, including an explicitly empty name. - The 9.x compatibility aliases were removed in 10.0.0: `options` is `items`, the exported `SwatchOption` type is `SwatchPickerItem`, and the former invisible `label` IDL is `accessibleLabel`/`aria-label`. The canonical sibling radiogroup vocabulary is now the only spelling. - `disabled: boolean = false` (reflected) — locks the whole picker. Every swatch renders as a real `disabled` ``; } } ``` **Known gotchas:** - arrow-key navigation cycles (past the last swatch wraps to the first, and vice versa) rather than clamping, and self-selects on move — arrow-navigating to a swatch immediately updates `value` and fires `lr-change`, there's no separate commit step. - live `items` changes preserve a focused swatch by item-object identity across reorders. Removing the focused option moves focus and the roving tab stop to the nearest surviving swatch (the next item at that position, or the previous item when the final option was removed) without changing the controlled `value` or emitting `lr-change`. - under RTL (nearest `dir="rtl"` ancestor) `ArrowLeft`/`ArrowRight` swap which direction they move. - each swatch's fill comes from its option's `color`, applied through a per-swatch custom property set inline on `[part='swatch']` and read by `[part='swatch-fill']`, so a consumer's `::part(swatch-fill)` `background-color` rule can still override it. - style the selected state through `--lr-swatch-picker-selected-color`/`-selected-blur`/ `-shine-duration`, not through `::part(swatch)[aria-checked='true']` from outside: the CSS Shadow Parts spec only allows a fixed set of pseudo-classes after `::part()`, not arbitrary attribute selectors, so that combinator can silently fail to match depending on the engine. - the semantic `radiogroup` lives inside shadow DOM. Set `accessibleLabel` or a host `aria-label`; the component deliberately forwards the resulting name to that internal role. - the automatic gemstone glyph's checked-state halo/shine is themed through `--lr-gemstone-selected-color`/`-blur`/`-shine-duration`, not through `--lr-swatch-picker-selected-*`/`-gemstone-*` — those style a plain color-fill swatch or a consumer-supplied `icon` override instead, even while `mode="gemstone"`. **Additional API surface:** - `--lr-swatch-picker-gap` — Gap between swatches. Default: `var(--lr-space-xs)`. - `--lr-swatch-picker-wrap` — `flex-wrap` on the swatch row. Default: `wrap`, reproducing the previously hardcoded wrapping row exactly. Set `nowrap` to confine every swatch to a single row — the case this exists for is a picker inside a fixed-width popover, where a second row changes the panel's height and moves the popover under its trigger. A custom property rather than an attribute, so it inherits through wrappers like the gap and hit-size hooks beside it; tuning the gap and hit size small enough to avoid wrapping is a guess that breaks at the next swatch added. ---