@cube-dev/ui-kit 0.154.1 → 0.156.0

package/dist/utils/react/nullableValue.d.ts

@@ -1,5 +1,5 @@
 
-import { Props } from "@tenphi/tasty";
+import { Props } from "../../props.js";
 
 //#region src/utils/react/nullableValue.d.ts
 type WithNullableValue<T extends Props> = Omit<T, 'value' | 'defaultValue'> & {

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props) {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v));

package/dist/utils/react/nullableValue.js.map

@@ -1 +1 @@
-{"version":3,"file":"nullableValue.js","names":[],"sources":["../../../src/utils/react/nullableValue.ts"],"sourcesContent":["import { Props } from '@tenphi/tasty';\n\nexport function castNullableStringValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'string', (v) =>\n    String(v),\n  );\n}\n\nexport function castNullableNumberValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'number', (v) =>\n    Number(v),\n  );\n}\n\nexport function castNullableArrayValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'object', (v) =>\n    Array.isArray(v) ? v : [],\n  );\n}\n\nexport function castNullableIsSelected<T>(props: T): T {\n  return castNullableField(\n    props,\n    ['isSelected', 'defaultSelected'],\n    'boolean',\n    (v) => !!v,\n  );\n}\n\nexport function castNullableSelectedKey<T>(props: T): T {\n  return castNullableField(props, ['selectedKey', 'defaultSelectedKey']);\n}\n\nexport function castNullableField<T>(\n  props: T,\n  keys: string[],\n  type?: string,\n  cast?: (k: any) => any,\n): T {\n  props = { ...props };\n\n  keys.forEach((key) => {\n    if (props[key] === null) {\n      props[key] = undefined;\n    }\n\n    if (type && cast && props[key] != null && typeof props[key] != type) {\n      props[key] = cast(props[key]);\n\n      console.warn(\n        'Wrong value type in',\n        props,\n        'in keys',\n        JSON.stringify(keys),\n      );\n    }\n  });\n\n  return props;\n}\n\nexport type WithNullableValue<T extends Props> = Omit<\n  T,\n  'value' | 'defaultValue'\n> & {\n  value?: T['value'] | any;\n  defaultValue?: T['defaultValue'] | any;\n};\n\nexport type WithNullableSelected<T extends Props> = Omit<\n  T,\n  'isSelected' | 'defaultSelected'\n> & {\n  isSelected?: T['isSelected'] | any;\n  defaultSelected?: T['defaultSelected'] | any;\n};\n\nexport type WithNullableSelectedKey<T extends Props> = Omit<\n  T,\n  'selectedKey' | 'defaultSelectedKey'\n> & {\n  selectedKey?: T['selectedKey'] | any;\n  defaultSelectedKey?: T['defaultSelectedKey'] | any;\n};\n"],"mappings":";;AAEA,SAAgB,wBAA2B,OAAa;AACtD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,OAAO,EAAE,CACV;;AAGH,SAAgB,wBAA2B,OAAa;AACtD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,OAAO,EAAE,CACV;;AAGH,SAAgB,uBAA0B,OAAa;AACrD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,MAAM,QAAQ,EAAE,GAAG,IAAI,EAAE,CAC1B;;AAGH,SAAgB,uBAA0B,OAAa;AACrD,QAAO,kBACL,OACA,CAAC,cAAc,kBAAkB,EACjC,YACC,MAAM,CAAC,CAAC,EACV;;AAOH,SAAgB,kBACd,OACA,MACA,MACA,MACG;AACH,SAAQ,EAAE,GAAG,OAAO;AAEpB,MAAK,SAAS,QAAQ;AACpB,MAAI,MAAM,SAAS,KACjB,OAAM,OAAO;AAGf,MAAI,QAAQ,QAAQ,MAAM,QAAQ,QAAQ,OAAO,MAAM,QAAQ,MAAM;AACnE,SAAM,OAAO,KAAK,MAAM,KAAK;AAE7B,WAAQ,KACN,uBACA,OACA,WACA,KAAK,UAAU,KAAK,CACrB;;GAEH;AAEF,QAAO"}
+{"version":3,"file":"nullableValue.js","names":[],"sources":["../../../src/utils/react/nullableValue.ts"],"sourcesContent":["import type { Props } from '../../props';\n\nexport function castNullableStringValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'string', (v) =>\n    String(v),\n  );\n}\n\nexport function castNullableNumberValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'number', (v) =>\n    Number(v),\n  );\n}\n\nexport function castNullableArrayValue<T>(props: T): T {\n  return castNullableField(props, ['value', 'defaultValue'], 'object', (v) =>\n    Array.isArray(v) ? v : [],\n  );\n}\n\nexport function castNullableIsSelected<T>(props: T): T {\n  return castNullableField(\n    props,\n    ['isSelected', 'defaultSelected'],\n    'boolean',\n    (v) => !!v,\n  );\n}\n\nexport function castNullableSelectedKey<T>(props: T): T {\n  return castNullableField(props, ['selectedKey', 'defaultSelectedKey']);\n}\n\nexport function castNullableField<T>(\n  props: T,\n  keys: string[],\n  type?: string,\n  cast?: (k: any) => any,\n): T {\n  props = { ...props };\n\n  keys.forEach((key) => {\n    if (props[key] === null) {\n      props[key] = undefined;\n    }\n\n    if (type && cast && props[key] != null && typeof props[key] != type) {\n      props[key] = cast(props[key]);\n\n      console.warn(\n        'Wrong value type in',\n        props,\n        'in keys',\n        JSON.stringify(keys),\n      );\n    }\n  });\n\n  return props;\n}\n\nexport type WithNullableValue<T extends Props> = Omit<\n  T,\n  'value' | 'defaultValue'\n> & {\n  value?: T['value'] | any;\n  defaultValue?: T['defaultValue'] | any;\n};\n\nexport type WithNullableSelected<T extends Props> = Omit<\n  T,\n  'isSelected' | 'defaultSelected'\n> & {\n  isSelected?: T['isSelected'] | any;\n  defaultSelected?: T['defaultSelected'] | any;\n};\n\nexport type WithNullableSelectedKey<T extends Props> = Omit<\n  T,\n  'selectedKey' | 'defaultSelectedKey'\n> & {\n  selectedKey?: T['selectedKey'] | any;\n  defaultSelectedKey?: T['defaultSelectedKey'] | any;\n};\n"],"mappings":";;AAEA,SAAgB,wBAA2B,OAAa;AACtD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,OAAO,EAAE,CACV;;AAGH,SAAgB,wBAA2B,OAAa;AACtD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,OAAO,EAAE,CACV;;AAGH,SAAgB,uBAA0B,OAAa;AACrD,QAAO,kBAAkB,OAAO,CAAC,SAAS,eAAe,EAAE,WAAW,MACpE,MAAM,QAAQ,EAAE,GAAG,IAAI,EAAE,CAC1B;;AAGH,SAAgB,uBAA0B,OAAa;AACrD,QAAO,kBACL,OACA,CAAC,cAAc,kBAAkB,EACjC,YACC,MAAM,CAAC,CAAC,EACV;;AAOH,SAAgB,kBACd,OACA,MACA,MACA,MACG;AACH,SAAQ,EAAE,GAAG,OAAO;AAEpB,MAAK,SAAS,QAAQ;AACpB,MAAI,MAAM,SAAS,KACjB,OAAM,OAAO;AAGf,MAAI,QAAQ,QAAQ,MAAM,QAAQ,QAAQ,OAAO,MAAM,QAAQ,MAAM;AACnE,SAAM,OAAO,KAAK,MAAM,KAAK;AAE7B,WAAQ,KACN,uBACA,OACA,WACA,KAAK,UAAU,KAAK,CACrB;;GAEH;AAEF,QAAO"}

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useSyncExternalStore } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useEffect, useRef } from "react";
 
 //#region src/utils/react/useCombinedRefs.ts

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { useEffect } from "react";
 import { useFocusVisible } from "react-aria";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { useCallback, useContext, useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.154.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.156.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.154.1";
-const TASTY_VERSION = "2.11.2";
+const VERSION = "0.156.0";
+const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	const tastyVersion = TASTY_VERSION;

package/docs/components/content/Text.md

@@ -14,14 +14,13 @@ A flexible text component for inline or block text. Renders as `<span>` by defau
 - **`monospace`** `boolean` — Use monospace font
 - **`ellipsis`** `boolean` — Truncate overflow with ellipsis (sets `display: block`, `nowrap`, `overflow: hidden`)
 - **`nowrap`** `boolean` — Prevent text wrapping
-- **`block`** `boolean` — Display as block element
 - **`italic`** `string` — Font style (maps to `fontStyle`)
 - **`weight`** `string | number` — Font weight (maps to `fontWeight`)
 - **`transform`** `string` — Text transform (maps to `textTransform`)
 
 ### Style Defaults
 
-- `display` — `inline` (switches to `block` when `ellipsis` or `block`)
+- `display` — `inline` (switches to `block` when `ellipsis`). Pass `display="block"` to override.
 - `margin` — `0`
 - `padding` — `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