@cube-dev/ui-kit 0.155.0 → 0.156.0

package/docs/components/fields/ColorPicker.md

@@ -0,0 +1,271 @@
+# ColorPicker
+
+An input for a single color. It reads and writes color **text** — hex, `rgb()`,
+`hsl()`, `okhsl()`, `okhst()` and `oklch()` — shows the current color as a
+swatch, and opens a popover where the color can be dialed in on three
+perceptual axes.
+
+Every conversion goes through [Glaze](https://github.com/tenphi/glaze), so the
+canonical value the picker holds is OKHSL: bounded on every channel, and always
+inside the sRGB gamut. That is what makes an out-of-gamut state impossible and
+lets the same value be re-serialized into any of the supported notations without
+drift.
+
+## When to Use
+
+- Theme and branding forms — a seed color, an accent, a chart series color
+- Anywhere a color has to be typed *or* explored, rather than chosen from a
+  fixed palette
+- When the stored format matters (a design token file wants `oklch()`, a legacy
+  API wants hex) and the input has to guarantee it
+
+Reach for a `RadioGroup` or `Picker` of swatches instead when the choice is
+limited to a handful of approved colors.
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string | null` — The selected color (controlled)
+- **`defaultValue`** `string | null` — The selected color (uncontrolled)
+- **`onChange`** `(value: string | null) => void` — Fired with the color string, or `null` when the field is cleared
+- **`format`** `'hex' | 'rgb' | 'hsl' | 'okhsl' | 'okhst' | 'oklch'` (default: `hex`) — Notation the value is written in, and the one `forced` mode displays
+- **`formatMode`** `'forced' | 'derive' | 'free'` (default: `forced`) — How strictly the input text is tied to `format`
+- **`defaultSpace`** `'hst' | 'lch' | 'rgb'` (default: `hst`) — Color concept the popover opens with
+- **`placeholder`** `string` (default: `Pick a color`) — Text shown while the field is empty
+- **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — Input size
+- **`isOpen`** `boolean` — Whether the popover is open (controlled)
+- **`defaultOpen`** `boolean` (default: `false`) — Whether the popover is open initially
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the popover may flip to the other side of the input
+- **`onFocus`** `(event: FocusEvent) => void` — Fired when the text input receives focus
+- **`onBlur`** `(event: FocusEvent) => void` — Fired when the text input loses focus
+
+Named CSS colors (`red`, `rebeccapurple`) are **not** accepted — they are not a
+color space, and Glaze does not resolve them either. Alpha is parsed but
+dropped: the value is always opaque.
+
+Focusing the field selects the whole value, so a pasted color replaces it
+outright. The string is the unit of editing here: a single channel is tuned with
+the sliders rather than by hand-editing one number inside `oklch(…)`. Clicking a
+field that already has focus positions the caret as usual, so the text stays
+editable by hand.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the input wrapper — the element that owns the border, fill and size.
+
+**Sub-elements:**
+
+- `Prefix` — the container holding the color swatch
+- `Suffix` — the container holding the validation state, then the popover trigger
+- `InputIcon` — the swatch slot
+- `State` — the validation / loading indicator
+
+#### inputStyles
+
+Customizes the `<input>` element itself.
+
+#### triggerStyles
+
+Customizes the popover trigger button.
+
+#### swatchStyles
+
+Customizes the color swatch shown inside the input.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+- **Color:** `color`, `fill`, `fade`, `image`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier   | Type      | Description                                       |
+| ---------- | --------- | ------------------------------------------------- |
+| `focused`  | `boolean` | The text input has focus                          |
+| `hovered`  | `boolean` | The pointer is over the input                     |
+| `disabled` | `boolean` | The picker is disabled                            |
+| `valid`    | `boolean` | The field is in the valid state                   |
+| `invalid`  | `boolean` | The field is in the invalid state                 |
+| `prefix`   | `boolean` | A prefix (the swatch) is rendered                 |
+| `suffix`   | `boolean` | A suffix (the trigger) is rendered                |
+
+The swatch carries its own `empty` modifier while there is no color to show.
+
+## Format modes
+
+The three modes differ in how much freedom the *text* gets. The value is always
+a real color in every one of them.
+
+| Mode     | Text                                | Value                                                |
+| -------- | ----------------------------------- | ---------------------------------------------------- |
+| `forced` | Rewritten in `format` on blur/Enter | Always written in `format`                           |
+| `derive` | Left exactly as typed               | Normalized in the notation the text is written in    |
+| `free`   | Left exactly as typed               | The text itself, verbatim                            |
+
+In every mode an entry that is not a color is rejected: the previous valid color
+stays the value while it is being typed, and the text snaps back to it on blur.
+Emptying the field is not an error — it commits `null`.
+
+```jsx
+// A design-token form that must store OKLCH
+<ColorPicker label="Accent" format="oklch" onChange={setAccent} />
+
+// A CSS editor: keep whatever the author wrote, but guarantee it parses
+<ColorPicker label="Color" formatMode="free" onChange={setCss} />
+```
+
+## Color spaces
+
+The popover edits one canonical color through three sets of axes:
+
+| Space | Axes                          | Good for                                              |
+| ----- | ----------------------------- | ----------------------------------------------------- |
+| `hst` | Hue, Saturation, Tone (OKHST) | Building ramps — equal tone steps read as equal steps |
+| `lch` | Lightness, Chroma, Hue (OKLCH)| Matching a value from a design-token file             |
+| `rgb` | Red, Green, Blue              | Matching a value from a legacy palette or a screenshot|
+
+Each of these opens on its own space; the switcher inside the popover moves
+between them at any time.
+
+`H` means the same angle in HST and LCH, so the hue strip is identical in both.
+The chroma slider is bounded by the sRGB gamut at the current lightness and hue,
+which is why its range changes as `L` moves.
+
+## Examples
+
+### Basic usage
+
+```jsx
+<ColorPicker label="Brand color" defaultValue="#7a4dbf" />
+```
+
+### Controlled
+
+```jsx
+const [color, setColor] = useState('#7a4dbf');
+
+<ColorPicker label="Brand color" value={color} onChange={setColor} />;
+```
+
+### Inside a form
+
+```jsx
+<Form onSubmit={onSubmit}>
+  <ColorPicker
+    name="accent"
+    label="Accent color"
+    format="oklch"
+    rules={[{ required: true, message: 'Pick an accent color' }]}
+  />
+</Form>
+```
+
+### Opening on a specific space
+
+```jsx
+<ColorPicker label="Series color" defaultSpace="rgb" defaultValue="#26fcb2" />
+```
+
+### Using the value as a style
+
+Because the emitted value is a plain color string, it can go straight into a
+tasty style — including the `okhsl()` and `okhst()` notations, which tasty
+parses natively.
+
+```jsx
+const [color, setColor] = useState('okhst(264 80% 60%)');
+
+<>
+  <ColorPicker label="Fill" format="okhst" value={color} onChange={setColor} />
+  <Block fill={color} height="10x" radius="1r" />
+</>;
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — moves focus to the text input, then to the popover trigger
+- `Enter` — commits and normalizes the typed color without leaving the field
+- `Space` / `Enter` on the trigger — opens the popover
+- `Escape` — closes the popover
+- `Left` / `Right`, `Home` / `End` on a channel slider — moves that channel
+- `Left` / `Right` on the space switcher — moves between HST, LCH and RGB
+
+### Screen Reader Support
+
+- The text input announces as a textbox with the field's label
+- The trigger announces as "Open the color picker"
+- The popover announces as a dialog named "Color picker"
+- Each channel slider sits in a group named after its axis (`Hue`,
+  `Saturation`, `Tone`, `Lightness`, `Chroma`, `Red`, `Green`, `Blue`)
+- The swatch is decorative and is not announced — the text carries the value
+
+### ARIA Properties
+
+- `aria-label` — names the field when there is no visible label
+- `aria-describedby` — wired to the field description by the form system
+
+## Best Practices
+
+1. **Do**: name the field, so the text input is announced meaningfully
+
+   ```jsx
+   <ColorPicker label="Brand color" />
+   ```
+
+2. **Don't**: rely on the swatch alone to convey the value
+
+   ```jsx
+   <ColorPicker aria-label="" />
+   ```
+
+3. **Do**: pick the `format` your backend stores, and leave `formatMode` at
+   `forced` so the two can never disagree.
+
+4. **Don't**: use `free` mode when the value is later parsed by something
+   stricter than a browser — the text is passed through as written.
+
+## Integration with Forms
+
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string, and clearing the input
+stores `null`, which makes `required` rules behave as expected.
+
+## Suggested Improvements
+
+- An eyedropper that samples a pixel from the page, where
+  [`EyeDropper`](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is
+  available
+- Optional alpha support, which the canonical value currently drops
+- A row of recent or preset swatches inside the popover
+- Editable numeric inputs next to each channel slider, for exact entry without
+  going through the text field
+
+## Related Components
+
+- [HueSlider](./HueSlider.md) — just the hue axis, when only a hue is needed
+- [Slider](./Slider.md) — the primitive each channel is built from
+- [TextInput](./TextInput.md) — the input chrome this component reuses

package/docs/components/layout/Board.md

@@ -32,6 +32,16 @@ clipped by an ancestor's `overflow: hidden`.
   widget is placed exactly where you drop it and its neighbours are never pushed
   or swapped; without `allowOverlap` a drop onto an occupied cell is blocked, and
   with `allowOverlap` widgets may stack for a fully free canvas.
+- **Selection** — off by default. Pressing a widget selects it and arms a drag
+  of the selection: selecting and grabbing are one gesture, so move the pointer
+  and it drags, stay still and it was just a selection. <kbd>Shift</kbd> (or
+  <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>) toggles a widget's membership. Keys are layout
+  item ids, scoped to a single board, and always reported in layout order.
+- **Selection is focus-like** — it tracks what the user is working with, and
+  touching anything else moves it on: pressing another widget makes *that* the
+  selection, pressing a control inside a widget drops it, and so does focus
+  leaving the board. With `'multiple'`, pressing an already-selected widget
+  keeps the selection so a drag moves the whole block.
 
 ## Properties
 
@@ -58,6 +68,13 @@ clipped by an ancestor's `overflow: hidden`.
 - **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Can be overridden per widget.
 - **`showGridLines`** `boolean | 'drag'` (default: `false`) — Show grid lines behind the widgets. `true` always, `'drag'` only while a widget is being dragged or resized. A nested board that does not set this inherits an enabled ancestor's grid lines, showing its own while a drag is in progress.
 - **`isAligned`** `boolean` (default: `false`) — Align a nested board with its ancestor `Board`'s layout. Only takes effect when the board is nested inside another `Board`'s widget. When set, every cell matches the parent's cell size exactly: the board inherits the parent's column pitch (deriving its own column count from its measured width so cells stay parent-sized as the container is resized) and uses the parent's row height verbatim. It never shrinks rows to fit — pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height. `cols`/`rowHeight` then act as fallbacks used only until the parent metrics resolve.
+- **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — Whether widgets can be selected, and how many at a time. `'multiple'` also enables the marquee and rigid group movement.
+- **`selectedKeys`** `string[]` — Controlled selection. Keys are layout item ids (`LayoutItem.i`).
+- **`defaultSelectedKeys`** `string[]` — Initial selection for uncontrolled usage.
+- **`onSelectionChange`** `(keys: string[]) => void` — Called when the selection changes. Keys are deduped and returned in the board's layout order, never in click order.
+- **`selectionCancel`** `string` (default: `BOARD_SELECTION_CANCEL`) — CSS selector marking interactive descendants. A press on one never selects and never starts a drag, so the control keeps its own click *and* its native focus; it also drops the selection, since interacting with a widget's content means the user has moved on. On a selectable board this doubles as the drag guard, so form controls stay usable without also configuring `dragCancel`. The default covers native form controls, links, and the common ARIA widget roles, plus `[data-no-select]` as an escape hatch. Pass `''` to disable the guard. Can be overridden per widget.
+- **`allowMarqueeSelection`** `boolean` (default: `selectionMode === 'multiple'`) — Draw a rubber-band selection when a drag starts on empty board space. A press on a widget selects and drags instead, so the lasso owns empty canvas only. Hold <kbd>Shift</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> to add to the existing selection rather than replacing it.
+- **`onWidgetsDelete`** `(keys: string[]) => void` — Called when <kbd>Delete</kbd>/<kbd>Backspace</kbd> is pressed with a non-empty selection and focus is not in an editable field. **Board never mutates the layout itself** — removing the widgets is yours to do, which is what lets you make it undoable. Board only handles these keys when this handler is set.
 - **`constraints`** `LayoutConstraint[]` — Grid/item layout constraints.
 - **`width`** `number` — Explicit width (disables measurement; useful for SSR/tests).
 - **`widgetProps`** `Partial<Board.Widget props>` — Default props applied to every widget this board hosts (per-widget `Board.Widget` props override these). Use it to add a card border to every widget (`widgetProps={{ isCard: true }}`) or set shared `styles`/sizing defaults without repeating them on each widget.
@@ -82,6 +99,16 @@ clipped by an ancestor's `overflow: hidden`.
 - **`isAutoHeight`** `boolean` (default: `false`) — Grow this widget's height in its board to fit its content (only ever increases, never shrinks). Pair it with a nested `Board isAligned` so the container expands until the inner board's rows fit at the parent's row height. It also pins the widget's resize floor: you cannot drag the widget shorter than the height its content currently needs.
 - **`dragCancel`** `string` — Override the board's `dragCancel` selector for this widget.
 - **`dragHandle`** `string` — Override the board's `dragHandle` selector for this widget.
+- **`isSelectable`** `boolean` — Disable selection for this widget while the board's `selectionMode` is on.
+- **`selectionCancel`** `string` — Override the board's `selectionCancel` selector for this widget.
+- **`aria-label`** `string` — Accessible name for the widget. Falls back to `qa`, then the layout item id — both developer-facing, so set this whenever the widget is user-visible. Also what the selection announcement reads out.
+
+A widget clips its content to its grid cell, card or not — otherwise a nested
+board with more rows than currently fit, or a mid-drag reflow, would paint over
+its neighbours. The cost is that a descendant's `outline` is cropped at the edge
+(an outline is clipped by an *ancestor's* overflow, not its own), so a widget
+whose content must paint outside — a control drawing its own active ring — sets
+`overflow="visible"`, or draws the ring inset with a negative `outlineOffset`.
 
 ### Board.Provider
 
@@ -119,6 +146,48 @@ container's measured width, mirroring react-grid-layout's `Responsive` +
 A breakpoint with no layout is synthesized from the nearest available one,
 corrected into bounds and compacted for the target column count.
 
+### Modifiers
+
+Every widget host exposes these as `data-*` attributes, and any style map passed
+through `widgetProps.styles` or a per-widget `styles` resolves against them.
+
+- **`selected`** — the widget is in the board's selection.
+- **`card`** — the widget draws a card border (`isCard`).
+- **`draggable`** — the widget can be dragged and no drag is in flight.
+- **`drag`** — the widget is being dragged.
+- **`floating`** — this is the clone floating in the drag overlay.
+- **`resizing`** — the widget is being resized.
+- **`static`** — the layout item is `static`.
+- **`hovered`**, **`focus-visible`** — pointer and keyboard-focus states.
+- **`settled`** — the board has painted its widgets once, so position changes animate.
+
+Selection is an *edge* treatment — a `#primary-border` border plus a `#primary`
+ring — because it reads as a focus-like state rather than a fill. `outline` stays
+reserved for the real focus ring, which is what keeps the two legible together:
+they use different tokens and the focus outline sits one border-width further
+out. To restyle it, override the same keys:
+
+```jsx
+<Board
+  selectionMode="multiple"
+  widgetProps={{
+    styles: {
+      border: { '': true, selected: '#note-border' },
+      shadow: { '': false, selected: '0 0 0 1bw #note' },
+    },
+  }}
+/>
+```
+
+### Data attributes
+
+Supported hooks for tests, E2E, and building your own selection overlay:
+
+- **`data-board-id`** on the board element — the board's `id`.
+- **`data-board-widget-host`** on every widget host — presence only, "this is a widget host".
+- **`data-board-widget-id`** on every widget host — which widget.
+- **`data-selected`** on a selected host.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).
@@ -221,14 +290,76 @@ mounted so the tab a widget is dragged out of (and the board owning the in-fligh
 drag) is not unmounted mid-gesture. Spring-loading works with mouse and pen;
 touch drags capture the pointer, so they do not trigger it.
 
+### Selection
+
+Click to select, Shift/Cmd/Ctrl-click to add or remove, and drag from empty board
+Press a widget to select it, <kbd>Shift</kbd>-press to add or remove one, and
+drag from empty board space to lasso. Because the press both selects and arms the
+drag, grabbing a widget you have not selected simply makes it the selection and
+moves it; grabbing one that *is* selected moves the whole block rigidly — keeping
+its shape horizontally, clamping against the grid edge as a unit rather than
+collapsing, and committing once.
+
+A group reflows exactly like a single widget: it is compacted by the same rules,
+so on a `vertical` board it can no more be parked in empty space than one widget
+can, and the widgets around it close the gap in the same frame. Under
+`compact="free"` (or `null`) nothing compacts, so the block stays precisely where
+it was dropped.
+
+### Interactive content keeps its clicks
+
+### Controlled selection and deleting widgets
+
+### Restyling the selection
+
 ## Accessibility
 
-- Widgets are focusable when draggable. Press <kbd>Tab</kbd> to focus a widget,
-  then use the arrow keys to move it one cell at a time. Arrow keys only move
-  the widget when the widget host itself is focused — not when focus is inside
-  a nested control (e.g. an <kbd>input</kbd> or <kbd>textarea</kbd>).
-- Dragging, resizing, and keyboard movement are all handled by React Aria's
-  `useMove`, which normalizes mouse, touch, and keyboard interactions.
+### Keyboard Navigation
+
+| Key | Action |
+| --- | --- |
+| <kbd>Tab</kbd> | Move focus to the next widget. |
+| <kbd>Arrow</kbd> keys | Move the focused widget one cell. With a selection, moves the whole selection. |
+| <kbd>Space</kbd> | Toggle the focused widget's selection (`selectionMode` only). |
+| <kbd>Shift</kbd> / <kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + press | Add or remove a widget from the selection. |
+| <kbd>Escape</kbd> | Clear the selection. |
+| <kbd>Delete</kbd> / <kbd>Backspace</kbd> | Request deletion of the selection via `onWidgetsDelete`. |
+
+Arrow keys and <kbd>Space</kbd> only act when the widget host **itself** is
+focused, never when focus is inside a nested control, so an `input`,
+`textarea`, or `button` inside a widget keeps every key it needs. Board's own
+keys are handled on the board element rather than on `document`, and are only
+consumed when they actually do something — an <kbd>Escape</kbd> with nothing
+selected still reaches an ancestor Dialog, and <kbd>Backspace</kbd> stays
+available for text editing and browser-back.
+
+Every draggable or selectable widget is its own tab stop. Roving tabindex would
+be an improvement on a large board, but arrow keys are already claimed for
+movement, so it needs a navigation key set of its own — see below.
+
+### Screen Reader Support
+
+Each widget host is a `group` with an accessible name, taken from
+`aria-label`, then `qa`, then the layout item id — set `aria-label` on any
+user-visible widget, since the other two are developer-facing. Draggable widgets
+carry a localized `aria-roledescription`, and selectable ones advertise
+`aria-keyshortcuts="Space"`.
+
+Selection state is conveyed two ways: a selected widget is described as
+"Selected" via `aria-describedby`, and every selection change is announced
+through a polite live region owned by the board ("Revenue selected", "3 widgets
+selected", "Selection cleared"). A marquee announces once, on release — not once
+per pointer frame.
+
+### ARIA Properties
+
+Board deliberately does **not** use a collection role. `aria-selected` is only
+valid on `option`, `gridcell`, `row`, `treeitem` and friends, and every one of
+those requires presentational children — but a Board widget hosts arbitrary
+interactive content (nested boards, tabs, inputs), and a `grid`'s keyboard model
+would fight `useMove`'s arrow keys. Rather than ship ARIA that lies about the
+structure, selection is exposed through the name, description, and live region
+described above. Set `aria-label` on your widgets and this reads correctly.
 
 ## Not yet supported
 
@@ -240,6 +371,23 @@ touch drags capture the pointer, so they do not trigger it.
   placeholder, and new `onDrop`/`droppingItem` props). Add widgets
   programmatically (render a new `Board.Widget` and add its layout item), or drag
   between boards with `Board.Provider`.
+- **Cross-board group transfer** — a group drag never leaves its source board.
+  Cross-board transfer is single-item throughout (`WidgetTransferInfo`, the
+  carried preview, the free-slot fallback), and landing a group on a board with a
+  different column count has no obvious right answer. Degrading to a
+  single-widget transfer would silently split a selection the user made, so the
+  gesture is confined instead. Drag widgets across one at a time.
+- **Collection ARIA semantics** — `role="grid"`/`option`, `aria-selected` and
+  `aria-multiselectable`, for the reason above.
+- **Roving tabindex** — needs a widget-navigation key set that does not collide
+  with `useMove`'s arrow keys.
+- **<kbd>Cmd/Ctrl</kbd>+<kbd>A</kbd>** — select all.
+- **Cross-board marquee and cross-board selection** — selection is per board; a
+  `Board.Provider` shares drag, not selection.
+- **Windows High Contrast Mode** — no component in the kit styles for
+  `forced-colors` yet. The selected state uses a tint, a border *and* an extra
+  ring, so it does not rely on hue alone, but a full forced-colors pass is a
+  system-wide change.
 
 ## Attribution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.155.0",
+  "version": "0.156.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {