@cube-dev/ui-kit 0.0.0-canary-1f0dd2c → 0.0.0-canary-1d27aa0

package/docs/components/fields/Checkbox.md

@@ -149,13 +149,11 @@ The `mods` property accepts the following modifiers you can override:
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels
-
    ```jsx
    <Checkbox>Enable two-factor authentication</Checkbox>
    ```
 
 2. **Don't**: Use unclear or ambiguous text
-
    ```jsx
    <Checkbox>Enable</Checkbox> {/* What gets enabled? */}
    ```

package/docs/components/fields/ColorInput.md

@@ -1,16 +1,26 @@
 # ColorInput
 
-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.
+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.
+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
+- 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.
+Reach for a `RadioGroup` or `Picker` of swatches instead when the choice is
+limited to a handful of approved colors.
 
 ## Component
 
@@ -33,11 +43,19 @@ Reach for a `RadioGroup` or `Picker` of swatches instead when the choice is limi
 - **`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.
+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.
+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.
 
-Rendered inside a color popover — as `ColorPicker` does at the top of its panel — the trigger is dropped automatically, since the popover it would open is the one already showing.
+Rendered inside a color popover — as `ColorPicker` does at the top of its panel
+— the trigger is dropped automatically, since the popover it would open is the
+one already showing.
 
 ### Base Properties
 
@@ -86,31 +104,40 @@ These properties allow direct style application without using the `styles` prop:
 
 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 |
+| 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.
+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 | Written in `format` from the first change on |
-| `derive` | Left exactly as typed | Normalized in the notation the text is written in |
-| `free` | Left exactly as typed | The text itself, verbatim |
+| Mode     | Text                                | Value                                                |
+| -------- | ----------------------------------- | ---------------------------------------------------- |
+| `forced` | Rewritten in `format` on blur/Enter | Written in `format` from the first change on          |
+| `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`.
+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`.
 
-**The value you pass in is left as you wrote it.** No mode reformats it on mount, including `forced` — doing so would mean calling `onChange` before the user has touched anything, which marks a form dirty for no reason. `forced` normalizes the text for display straight away, so the field can show `#7a4dbf` while the value is still the `rgb(122 77 191)` you supplied; from the first change onward the value is written in `format` too. Normalize before storing if the notation matters to you from the outset.
+**The value you pass in is left as you wrote it.** No mode reformats it on mount,
+including `forced` — doing so would mean calling `onChange` before the user has
+touched anything, which marks a form dirty for no reason. `forced` normalizes the
+text for display straight away, so the field can show `#7a4dbf` while the value
+is still the `rgb(122 77 191)` you supplied; from the first change onward the
+value is written in `format` too. Normalize before storing if the notation
+matters to you from the outset.
 
 ```jsx
 // A design-token form that must store OKLCH
@@ -124,15 +151,18 @@ In every mode an entry that is not a color is rejected: the previous valid color
 
 The popover edits one canonical color through three sets of axes:
 
-| Space | Axes | Good for |
-| --- | --- | --- |
+| 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 |
+| `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.
+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.
+`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
 
@@ -171,7 +201,9 @@ const [color, setColor] = useState('#7a4dbf');
 
 ### 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.
+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%)');
@@ -198,7 +230,8 @@ const [color, setColor] = useState('okhst(264 80% 60%)');
 - 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`)
+- 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
@@ -220,20 +253,28 @@ const [color, setColor] = useState('okhst(264 80% 60%)');
    <ColorInput aria-label="" />
    ```
 
-3. **Do**: pick the `format` your backend stores, and leave `formatMode` at `forced` so the two can never disagree.
+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.
+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.
+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
+- 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
+- Editable numeric inputs next to each channel slider, for exact entry without
+  going through the text field
 
 ## Related Components
 

package/docs/components/fields/ColorPicker.md

@@ -1,8 +1,12 @@
 # ColorPicker
 
-A swatch button that opens the color popover. It is the same popover [ColorInput](./ColorInput.md) uses — three perceptual axes backed by [Glaze](https://github.com/tenphi/glaze) — without the text field in front of it.
+A swatch button that opens the color popover. It is the same popover
+[ColorInput](./ColorInput.md) uses — three perceptual axes backed
+by [Glaze](https://github.com/tenphi/glaze) — without the text field in front of
+it.
 
-Reach for it when a color is **chosen but never typed**. Reach for `ColorInput` when someone needs to paste `#7a4dbf` from a brand guide.
+Reach for it when a color is **chosen but never typed**. Reach for `ColorInput`
+when someone needs to paste `#7a4dbf` from a brand guide.
 
 ## When to Use
 
@@ -10,7 +14,8 @@ Reach for it when a color is **chosen but never typed**. Reach for `ColorInput`
 - A chart legend, a tag color, a cell in a dense table
 - Anywhere the exact notation is an implementation detail the user never sees
 
-Use [ColorInput](./ColorInput.md) instead when the color has to be readable and pasteable as text.
+Use [ColorInput](./ColorInput.md) instead when the color has to be
+readable and pasteable as text.
 
 ## Component
 
@@ -36,7 +41,10 @@ Use [ColorInput](./ColorInput.md) instead when the color has to be readable and
 - **`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 trigger
 
-There is no `formatMode`: with no text to reconcile, `format` alone decides how the value is written. Everything else about the color model — the notations it reads, the gamut handling, the three spaces — is identical to `ColorInput` and documented there.
+There is no `formatMode`: with no text to reconcile, `format` alone decides how
+the value is written. Everything else about the color model — the notations it
+reads, the gamut handling, the three spaces — is identical to `ColorInput` and
+documented there.
 
 ### Base Properties
 
@@ -72,25 +80,30 @@ These properties allow direct style application without using the `styles` prop:
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier      | Type      | Description              |
-| ------------- | --------- | ------------------------ |
-| `placeholder` | `boolean` | No color is selected yet |
+| Modifier      | Type      | Description                          |
+| ------------- | --------- | ------------------------------------ |
+| `placeholder` | `boolean` | No color is selected yet             |
 
 The swatch carries its own `empty` modifier while there is no color to show.
 
 ### The value as text
 
-The popover carries a `ColorInput` above the preview, so the exact color can be read, copied, pasted and normalized in place rather than only dialed in. It has no trigger of its own — a disclosure inside the thing it discloses would be meaningless — and clearing it clears the picker.
+The popover carries a `ColorInput` above the preview, so the exact color can be
+read, copied, pasted and normalized in place rather than only dialed in. It has
+no trigger of its own — a disclosure inside the thing it discloses would be
+meaningless — and clearing it clears the picker.
 
 ### A palette under the editor
 
-Pass `swatches` and a [ColorSwatchGroup](./ColorSwatchGroup.md) appears below the channels, so a common color is one press away.
+Pass `swatches` and a [ColorSwatchGroup](./ColorSwatchGroup.md)
+appears below the channels, so a common color is one press away.
 
 ```jsx
 <ColorPicker label="Brand color" swatches={palette} swatchColumns={4} />
 ```
 
-That group never offers its own custom-color escape hatch, since the escape hatch is a `ColorPicker` and would nest popovers without end.
+That group never offers its own custom-color escape hatch, since the escape
+hatch is a `ColorPicker` and would nest popovers without end.
 
 ## Examples
 
@@ -110,7 +123,8 @@ Drop the label for a compact button — a toolbar, or a cell in a table.
 </ColorPicker>
 ```
 
-Give it an `aria-label` when you do: with no visible text, that is the only thing naming the control.
+Give it an `aria-label` when you do: with no visible text, that is the only
+thing naming the control.
 
 ### A label of your own
 
@@ -147,10 +161,12 @@ Give it an `aria-label` when you do: with no visible text, that is the only thin
 
 ### Screen Reader Support
 
-- The trigger announces as a button, named by the field label, `aria-label`, or its own text
+- The trigger announces as a button, named by the field label, `aria-label`, or
+  its own text
 - The popover announces as a dialog named "Color picker"
 - Each channel slider sits in a group named after its axis
-- The swatch is decorative; the color is announced as the trigger's text unless you replace it
+- The swatch is decorative; the color is announced as the trigger's text unless
+  you replace it
 
 ### ARIA Properties
 
@@ -165,22 +181,28 @@ Give it an `aria-label` when you do: with no visible text, that is the only thin
    <ColorPicker aria-label="Series color">{null}</ColorPicker>
    ```
 
-2. **Don't**: leave a swatch-only picker unnamed — the swatch says nothing to a screen reader
+2. **Don't**: leave a swatch-only picker unnamed — the swatch says nothing to a
+   screen reader
 
    ```jsx
    <ColorPicker>{null}</ColorPicker>
    ```
 
-3. **Do**: reach for `ColorInput` the moment someone might want to paste a hex value; a picker alone makes that impossible.
+3. **Do**: reach for `ColorInput` the moment someone might want to paste a hex
+   value; a picker alone makes that impossible.
 
 ## Integration with Forms
 
-This component supports all [Field properties](../../FieldProperties.md) when used within a Form. The field value is the color string.
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string.
 
 ## Suggested Improvements
 
 - A row of recent or preset swatches inside the popover
-- An eyedropper that samples a pixel from the page, where [`EyeDropper`](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is available
+- An eyedropper that samples a pixel from the page, where
+  [`EyeDropper`](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is
+  available
 - Clearing the color back to `null` from the trigger
 
 ## Related Components

package/docs/components/fields/ColorSwatch.md

@@ -1,8 +1,13 @@
 # ColorSwatch
 
-A square of color. It is the smallest piece of the color family — [ColorPicker](./ColorPicker.md), [ColorInput](./ColorInput.md) and [ColorSwatchGroup](./ColorSwatchGroup.md) all draw one, and it is exported so a legend, a list row or a table cell can draw the same one.
+A square of color. It is the smallest piece of the color family —
+[ColorPicker](./ColorPicker.md),
+[ColorInput](./ColorInput.md) and
+[ColorSwatchGroup](./ColorSwatchGroup.md) all draw one, and it is
+exported so a legend, a list row or a table cell can draw the same one.
 
-It is decorative on its own: it carries no text and no accessible name. Pair it with the value written out, or put it in a control that names it.
+It is decorative on its own: it carries no text and no accessible name. Pair it
+with the value written out, or put it in a control that names it.
 
 ## When to Use
 
@@ -27,7 +32,8 @@ Supports [Base properties](../../BaseProperties.md)
 
 #### styles
 
-Customizes the swatch itself. `width` and `height` set here win over both the `size` prop and the automatic sizing.
+Customizes the swatch itself. `width` and `height` set here win over both the
+`size` prop and the automatic sizing.
 
 ### Style Properties
 
@@ -42,9 +48,9 @@ These properties allow direct style application without using the `styles` prop:
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier | Type | Description |
-| --- | --- | --- |
-| `empty` | `boolean` | No color to show — drawn as the conventional diagonal stroke |
+| Modifier | Type      | Description                                                    |
+| -------- | --------- | -------------------------------------------------------------- |
+| `empty`  | `boolean` | No color to show — drawn as the conventional diagonal stroke     |
 
 ## Sizes
 
@@ -54,11 +60,21 @@ The `mods` property accepts the following modifiers you can override:
 
 ### Sizing inside a control
 
-Leave `size` off and the swatch sizes itself to whatever it sits in. `Item`, `Button` and the text inputs publish their own height as the `$size` custom property, and the swatch reads it and lands `8px` inside — `20px` in a `small` control, `24px` in a `medium` one, `28px` in a `large` one. Nothing has to be passed between the two, so a control that changes size takes its swatch with it.
+Leave `size` off and the swatch sizes itself to whatever it sits in. `Item`,
+`Button` and the text inputs publish their own height as the `$size` custom
+property, and the swatch reads it and lands `8px` inside — `20px` in a `small`
+control, `24px` in a `medium` one, `28px` in a `large` one. Nothing has to be
+passed between the two, so a control that changes size takes its swatch with it.
 
-Outside a control there is nothing to read, and the swatch falls back to `medium`.
+Outside a control there is nothing to read, and the swatch falls back to
+`medium`.
 
-`ColorInput` and `ColorPicker` deliberately do **not** use this. Their swatch is a fixed `20px` badge at every field size — it reads as a value the field is showing rather than as part of the control, and a text input hangs its prefix off the border with no padding of its own, so a tracking swatch in a large field would sit against the edge. Automatic fitting is for a swatch you place yourself, in a `Button` or an `Item`, where the host has the padding that makes it work.
+`ColorInput` and `ColorPicker` deliberately do **not** use this. Their swatch is a
+fixed `20px` badge at every field size — it reads as a value the field is showing
+rather than as part of the control, and a text input hangs its prefix off the border
+with no padding of its own, so a tracking swatch in a large field would sit against
+the edge. Automatic fitting is for a swatch you place yourself, in a `Button` or an
+`Item`, where the host has the padding that makes it work.
 
 ## Examples
 
@@ -80,7 +96,8 @@ Outside a control there is nothing to read, and the swatch falls back to `medium
 
 ### With the value spelled out
 
-The swatch has no accessible name of its own, so the text beside it is what a screen reader announces.
+The swatch has no accessible name of its own, so the text beside it is what a
+screen reader announces.
 
 ```jsx
 <Space gap="1x" placeItems="center start">
@@ -103,7 +120,9 @@ The swatch has no accessible name of its own, so the text beside it is what a sc
 
 ## Accessibility
 
-`ColorSwatch` renders a plain `div` with no role and no name — a color on its own is not information a screen reader can use, and an announced hex is rarely what the user wants to hear.
+`ColorSwatch` renders a plain `div` with no role and no name — a color on its
+own is not information a screen reader can use, and an announced hex is rarely
+what the user wants to hear.
 
 - **Do** put the value, or the name of the thing the color belongs to, next to it
 - **Do** rely on the surrounding control's `aria-label` when the swatch is its icon

package/docs/components/fields/ColorSwatchGroup.md

@@ -1,8 +1,13 @@
 # ColorSwatchGroup
 
-A grid of color swatches, one of which can be selected. It is the palette half of choosing a color, where [ColorPicker](./ColorPicker.md) is the freeform half — and the two compose: pass `swatches` to a `ColorPicker` and the palette appears under the editor.
+A grid of color swatches, one of which can be selected. It is the palette half
+of choosing a color, where [ColorPicker](./ColorPicker.md) is the
+freeform half — and the two compose: pass `swatches` to a `ColorPicker` and the
+palette appears under the editor.
 
-Under the hood it is a radio group, so one tab stop and arrow keys move between swatches. The API is shaped after `Picker` rather than `RadioGroup`: colors go in as data, not as children.
+Under the hood it is a radio group, so one tab stop and arrow keys move between
+swatches. The API is shaped after `Picker` rather than `RadioGroup`: colors go in
+as data, not as children.
 
 ## When to Use
 
@@ -53,33 +58,41 @@ These properties allow direct style application without using the `styles` prop:
 
 ### Style Props on the group
 
-`ColorSwatchGroup` and `ColorPicker` both take the outer and block style props, so `radius`, `border`, `padding` and `shadow` work directly on them.
+`ColorSwatchGroup` and `ColorPicker` both take the outer and block style props,
+so `radius`, `border`, `padding` and `shadow` work directly on them.
 
 ### Modifiers
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier   | Type      | Description                      |
-| ---------- | --------- | -------------------------------- |
-| `selected` | `boolean` | The swatch is the selected color |
-| `empty`    | `boolean` | The swatch has no color to show  |
-| `disabled` | `boolean` | The group is disabled            |
+| Modifier   | Type      | Description                        |
+| ---------- | --------- | ---------------------------------- |
+| `selected` | `boolean` | The swatch is the selected color   |
+| `empty`    | `boolean` | The swatch has no color to show    |
+| `disabled` | `boolean` | The group is disabled              |
 
 ## ColorSwatch
 
-The square itself is exported, for the times you need to show a color without a control around it — a legend, a table cell, a summary line. It takes direct style props, so its shape and size are yours:
+The square itself is exported, for the times you need to show a color without a
+control around it — a legend, a table cell, a summary line. It takes direct
+style props, so its shape and size are yours:
 
 ```jsx
 <ColorSwatch color="#7a4dbf" radius="round" width="4x" height="4x" />
 ```
 
-It is decorative on its own: pair it with the value as text, or with something that names it.
+It is decorative on its own: pair it with the value as text, or with something
+that names it.
 
 ## Swatches must be unique
 
-Equivalent colors are collapsed into one swatch, because two entries for the same color make selection ambiguous — there would be no way to say which one is selected. Matching is done on the canonical hex, so `#ff0000`, `rgb(255 0 0)` and `hsl(0 100% 50%)` are one swatch, not three.
+Equivalent colors are collapsed into one swatch, because two entries for the
+same color make selection ambiguous — there would be no way to say which one is
+selected. Matching is done on the canonical hex, so `#ff0000`, `rgb(255 0 0)`
+and `hsl(0 100% 50%)` are one swatch, not three.
 
-The same matching decides which swatch a value selects, so `value` need not be written in the same notation as the swatch it refers to.
+The same matching decides which swatch a value selects, so `value` need not be
+written in the same notation as the swatch it refers to.
 
 ## Examples
 
@@ -96,7 +109,10 @@ The same matching decides which swatch a value selects, so `value` need not be w
 
 ### Wrapping onto rows
 
-By default the swatches wrap to fill whatever width they are given: a single row where there is room, more rows where there is not. `columns` pins them to a fixed grid instead, sized to the swatches rather than stretched across the container.
+By default the swatches wrap to fill whatever width they are given: a single row
+where there is room, more rows where there is not. `columns` pins them to a
+fixed grid instead, sized to the swatches rather than stretched across the
+container.
 
 ```jsx
 <ColorSwatchGroup colors={palette} columns={4} />
@@ -104,7 +120,8 @@ By default the swatches wrap to fill whatever width they are given: a single row
 
 ### Naming the swatches
 
-A swatch announces its color by default, which is rarely the most useful thing to hear. Give the colors names when they have them.
+A swatch announces its color by default, which is rarely the most useful thing
+to hear. Give the colors names when they have them.
 
 ```jsx
 <ColorSwatchGroup
@@ -121,7 +138,8 @@ A swatch announces its color by default, which is rarely the most useful thing t
 <ColorSwatchGroup colors={palette} allowCustom />
 ```
 
-The trailing picker shows the current color whenever that color is not one of the swatches, so a custom choice stays visible.
+The trailing picker shows the current color whenever that color is not one of
+the swatches, so a custom choice stays visible.
 
 ### Inside a ColorPicker
 
@@ -129,7 +147,10 @@ The trailing picker shows the current color whenever that color is not one of th
 <ColorPicker label="Brand color" swatches={palette} swatchColumns={4} />
 ```
 
-`allowCustom` is ignored there, and deliberately so: the escape hatch is itself a `ColorPicker`, so offering it inside one would nest popovers without end. The group reads a context the popover provides, which means the recursion cannot be written even by hand.
+`allowCustom` is ignored there, and deliberately so: the escape hatch is itself
+a `ColorPicker`, so offering it inside one would nest popovers without end. The
+group reads a context the popover provides, which means the recursion cannot be
+written even by hand.
 
 ## Accessibility
 
@@ -163,11 +184,14 @@ The trailing picker shows the current color whenever that color is not one of th
    <ColorSwatchGroup colors={['#ff0000', 'rgb(255 0 0)']} />
    ```
 
-3. **Do**: reach for `allowCustom` only where a color outside the palette is genuinely acceptable. A fixed set is the point of this component.
+3. **Do**: reach for `allowCustom` only where a color outside the palette is
+   genuinely acceptable. A fixed set is the point of this component.
 
 ## Integration with Forms
 
-This component supports all [Field properties](../../FieldProperties.md) when used within a Form. The field value is the color string.
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string.
 
 ## Suggested Improvements
 

package/docs/components/fields/ComboBox.md

@@ -66,7 +66,6 @@ A combobox component that combines a text input with a dropdown list, allowing u
 **clearOnBlur** - When `true`, clears both the selection and input when the input loses focus. When `false` (default), the input reverts to showing the current selection. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
 
 **popoverTrigger** - Controls how the popover opens:
-
 - `manual` - Only opens via trigger button or arrow keys
 - `input` (default) - Opens when user types + manual triggers
 - `focus` - Opens on input focus + typing + manual triggers
@@ -88,7 +87,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element of the ComboBox (the input container).
 
 **Sub-elements:**
-
 - `Prefix` - Container for prefix content and icons
 - `Suffix` - Container for suffix content, validation icons, and action buttons
 - `InputIcon` - Container for the left icon
@@ -547,7 +545,6 @@ const [selectedKey, setSelectedKey] = useState(null);
 ## Best Practices
 
 1. **Do**: Provide clear labels and placeholders
-
    ```jsx
    <ComboBox
      label="Country"
@@ -558,7 +555,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 2. **Do**: Use sections to group related options
-
    ```jsx
    <ComboBox label="Contact">
      <ComboBox.Section title="Recent">
@@ -571,7 +567,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 3. **Do**: Enable `allowsCustomValue` when user input flexibility is needed
-
    ```jsx
    <ComboBox
      allowsCustomValue
@@ -583,7 +578,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 4. **Don't**: Use ComboBox for a small fixed set of options
-
    ```jsx
    {/* Use Select instead for simple dropdowns */}
    <ComboBox label="Yes or No">
@@ -593,7 +587,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 5. **Don't**: Disable filtering on large lists
-
    ```jsx
    {/* Defeats the purpose of ComboBox's search capability */}
    <ComboBox filter={false} label="Countries">
@@ -602,7 +595,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 6. **Accessibility**: Always provide meaningful labels and descriptions
-
    ```jsx
    <ComboBox
      label="Product Category"
@@ -614,7 +606,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 7. **Performance**: Use `items` prop with render function for dynamic lists
-
    ```jsx
    <ComboBox items={largeDataset}>
      {(item) => <ComboBox.Item key={item.id}>{item.name}</ComboBox.Item>}
@@ -622,7 +613,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 8. **Smart Behavior**: The ComboBox automatically shows all items when opening the popover after filtering yields no results
-
    ```jsx
    {/* User types "xyz" (no match), then clicks trigger - shows all items */}
    <ComboBox label="Search">
@@ -632,7 +622,6 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 9. **Selected Item Sorting**: Use `items` prop for automatic selected-item-first sorting
-
    ```jsx
    {/* With items prop, selected item appears first by default */}
    <ComboBox items={options} defaultSelectedKey="option5">
@@ -641,11 +630,10 @@ const [selectedKey, setSelectedKey] = useState(null);
    ```
 
 10. **Independent Control**: Control input and selection separately when needed
-
     ```jsx
     const [inputValue, setInputValue] = useState('');
     const [selectedKey, setSelectedKey] = useState(null);
-
+    
     <ComboBox
       inputValue={inputValue}
       selectedKey={selectedKey}