prime-ui-kit 0.14.0 → 0.16.0

package/dist/components/code-block/CodeBlock.d.ts

@@ -3,14 +3,20 @@ import type { Variant } from "../../internal/states";
 export type CodeBlockColorScheme = "light" | "dark";
 /** `soft` — filled panel with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host. */
 export type CodeBlockVariant = Extract<Variant, "soft" | "ghost">;
-export type CodeBlockProps = Omit<React.HTMLAttributes<HTMLPreElement>, "children" | "dangerouslySetInnerHTML"> & {
-    /** TS/TSX source; highlighted with `highlightTsxHtml`. */
+export type CodeBlockProps = Omit<React.HTMLAttributes<HTMLPreElement>, "children"> & {
+    /**
+     * TS / TSX source; trailing whitespace is trimmed, then highlighted.
+     */
     code: string;
-    /** Forces a theme for the block. Omit to follow the surrounding theme. */
+    /**
+     * Fixes the theme for this block only (`data-theme`). Omit to follow the page theme.
+     */
     colorScheme?: CodeBlockColorScheme;
-    /** Default `soft`. */
+    /**
+     * `soft` — a filled panel (one ladder step off its host) with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host.
+     */
     variant?: CodeBlockVariant;
     ref?: React.Ref<HTMLPreElement>;
 };
 /** A static, highlighted TS/TSX snippet in `<pre><code>`. */
-export declare function CodeBlock({ code, colorScheme, variant, className, tabIndex, ...rest }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
+export declare function CodeBlock({ code, colorScheme, variant, className, tabIndex, ref, ...rest }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/color-field/ColorField.d.ts

@@ -1,36 +1,75 @@
+import * as React from "react";
 import { type ColorPickerLabels } from "../color-picker/ColorPicker";
-import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
+import { type FieldFocusRingProps, type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
 import type { ControlSize } from "../../internal/states";
-import { type ColorPreset } from "../../internal/swatch";
-export type ColorFieldLabels = ColorPickerLabels & {
+import type { ColorPreset } from "../../internal/swatch";
+/** The picker strings the field's panel shows: the sliders and the channel strip. */
+type PanelLabelKey = "eyeDropper" | "hex" | "hue" | "saturation" | "lightness" | "alpha" | "red" | "green" | "blue";
+export type ColorFieldLabels = Pick<ColorPickerLabels, PanelLabelKey> & {
     /** Muted marker after the label when `optional`. */
     optional: string;
+    /** Read after the field name of a `required` field (its trigger is a button). */
+    required: string;
     /** Accessible name of the preset swatches in the panel (`presets`). */
     presets: string;
 };
-export type ColorFieldProps = FieldRootDomProps & FieldFrameProps & {
-    /** Controlled color: a CSS color string (hex, `rgb()`, `hsl()`). */
+export declare const COLOR_FIELD_LABELS: ColorFieldLabels;
+export type ColorFieldProps = FieldRootDomProps & FieldFrameProps & FieldFocusRingProps & {
+    /**
+     * Controlled color: a CSS color string (hex, `rgb()`, `hsl()`).
+     */
     value?: string;
+    /**
+     * Initial color when uncontrolled.
+     */
     defaultValue?: string;
-    /** Called with the new color as hex: `#RRGGBB`, or `#RRGGBBAA` when `alpha` lowers the opacity. */
+    /**
+     * Called with the new color as hex: `#RRGGBB`, or `#RRGGBBAA` when `alpha` lowers the opacity. A controlled field that does not take the value keeps its color.
+     */
     onValueChange?: (value: string) => void;
-    /** Ready colors under the channels: `{ value, label }`, picked in one click. */
+    /**
+     * Ready colors under the channels (`{ value, label }`), picked in one click; none by default.
+     */
     presets?: readonly ColorPreset[];
-    /** Adds the opacity slider; the value then carries alpha. */
+    /**
+     * Adds the opacity slider; the value then carries alpha.
+     */
     alpha?: boolean;
-    /** Field tier; the panel uses the same tier. */
+    /**
+     * Field tier (height 28 · 32 · 36 · 40 · 48); the panel uses the same tier. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Disables the field: it shows the color and does not open.
+     */
     disabled?: boolean;
-    /** Danger ring and `aria-invalid`; a non-empty `error` implies it. */
+    /**
+     * Danger ring and `aria-invalid` without a message. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** Form field name: a hidden input submits the hex value. */
+    /**
+     * Form field name: a hidden input submits the hex value.
+     */
     name?: string;
-    /** Id of the field button; generated when omitted. */
+    /**
+     * Id of the field button; hint id is `<id>-hint`, error id is `<id>-error`.
+     */
     id?: string;
-    /** Accessible name when there is no `label`; the current value is appended. */
+    /**
+     * Accessible name without a visible `label`; the current hex is appended.
+     */
     "aria-label"?: string;
+    /**
+     * Names the field button by an outside element.
+     */
     "aria-labelledby"?: string;
+    /**
+     * Merged before the hint/error ids.
+     */
     "aria-describedby"?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<ColorFieldLabels>;
 };
 /**
@@ -38,7 +77,8 @@ export type ColorFieldProps = FieldRootDomProps & FieldFrameProps & {
  * the ColorPicker panel (area, hue, optional opacity, channels with the eyedropper, presets) in a
  * Popover.
  */
-export declare function ColorField({ value: valueProp, defaultValue, onValueChange, presets, alpha, size, disabled: disabledProp, invalid: invalidProp, focusRing, name, id, label, required, optional, hint, error, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, labels: labelsProp, ...rest }: ColorFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ColorField({ value: valueProp, defaultValue, onValueChange, presets, alpha, size: sizeProp, disabled: disabledProp, invalid: invalidProp, focusRing, name, id, label, required, optional, hint, error, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, labels: labelsProp, ...rest }: ColorFieldProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export declare namespace ColorField {
     var displayName: string;
 }
+export {};

package/dist/components/color-picker/ColorPicker.d.ts

@@ -1,8 +1,8 @@
 import * as React from "react";
 import { type ColorAreaProps as AriaColorAreaProps, type ColorSliderProps as AriaColorSliderProps, type ColorThumbProps as AriaColorThumbProps, type SliderTrackProps as AriaSliderTrackProps, type Color, parseColor } from "react-aria-components";
 import { Button } from "../button/Button";
-import { type ColorSwatchesProps } from "../color-swatches/ColorSwatches";
-import type { FieldRootDomProps } from "../../internal/FieldFrame";
+import { type ColorSwatchesColorProps } from "../color-swatches/ColorSwatches";
+import type { FieldFocusRingProps, FieldRootDomProps } from "../../internal/FieldFrame";
 import type { ControlSize } from "../../internal/states";
 export type { Color as ColorPickerColorValue } from "react-aria-components";
 export type ColorValueFormat = "hsl" | "rgb" | "hex";
@@ -33,49 +33,73 @@ export type ColorPickerLabels = {
 };
 export declare const COLOR_PICKER_LABELS: ColorPickerLabels;
 export type ColorPickerRootProps = {
-    /** Controlled color: a CSS color string or a `Color` from `parseColor`. */
+    /**
+     * Controlled color: a CSS color string or a `Color` from `parseColor`.
+     */
     value?: string | Color;
+    /**
+     * Initial color when uncontrolled.
+     */
     defaultValue?: string | Color;
+    /**
+     * Called with the new `Color` (`color.toString("hex")` for a string).
+     */
     onValueChange?: (color: Color) => void;
-    /** Initial value format of `FormatSelect` and `ChannelStrip`. */
+    /**
+     * Controlled value format of `FormatSelect` and `ChannelStrip`.
+     */
+    format?: ColorValueFormat;
+    /**
+     * Initial value format, uncontrolled.
+     */
     defaultFormat?: ColorValueFormat;
+    /**
+     * Called with the format picked in `FormatSelect`.
+     */
+    onFormatChange?: (format: ColorValueFormat) => void;
+    /**
+     * Tier of the fields inside (`HexInput`, `FormatSelect`); without it the tier of its host (a panel, a popover), else `m`.
+     */
+    size?: ControlSize;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<ColorPickerLabels>;
+    /**
+     * The parts.
+     */
     children: React.ReactNode;
 };
-export type ColorPickerHexInputProps = FieldRootDomProps & {
-    /** Tier. Default: the tier of the surrounding control (a panel, a popover), else `m`. */
-    size?: ControlSize;
+export type ColorPickerHexInputProps = FieldRootDomProps & FieldFocusRingProps & {
+    /**
+     * Field label; defaults to `labels.hex`.
+     */
     label?: React.ReactNode;
+    /**
+     * Help text under the field. Hidden while `error` is shown.
+     */
     hint?: React.ReactNode;
-    /** Error message in the hint slot; implies `invalid`. */
-    error?: React.ReactNode;
     /**
-     * Draws the focus ring on the focused field (default). `false` sets `data-focus-ring="false"` and
-     * hides only the visual ring — focus, keyboard and ARIA are unchanged, the error ring still shows.
-     * Turn it off only where focus is otherwise obvious; WCAG 2.4.7.
+     * Error message in the hint slot; marks the field invalid.
      */
-    focusRing?: boolean;
+    error?: React.ReactNode;
 };
 export { parseColor };
+/** Hex text of a color: `#rrggbb`, or `#rrggbbaa` when it is not opaque. */
+export declare function toHexText(color: Color): string;
+/** The color of a CSS color text (hex, `rgb()`, `hsl()`), or `null` for text it cannot read. */
+export declare function parseHex(text: string): Color | null;
 type DivProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
     ref?: React.Ref<HTMLDivElement>;
 };
 export type ColorPickerFormatSelectProps = DivProps;
 declare function FormatSelect({ className, ...rest }: ColorPickerFormatSelectProps): import("react/jsx-runtime").JSX.Element;
-export type ColorPickerChannelStripProps = DivProps & {
-    /**
-     * Draws the focus ring on the focused field (default). `false` sets `data-focus-ring="false"` and
-     * hides only the visual ring — focus, keyboard and ARIA are unchanged, the error ring still shows.
-     * Turn it off only where focus is otherwise obvious; WCAG 2.4.7.
-     */
-    focusRing?: boolean;
-};
+export type ColorPickerChannelStripProps = DivProps & FieldFocusRingProps;
 /** Channel row: eyedropper on the left, then the cells of the current format. */
 declare function ChannelStrip({ className, focusRing, ...rest }: ColorPickerChannelStripProps): import("react/jsx-runtime").JSX.Element;
 export type ColorPickerPanelProps = React.HTMLAttributes<HTMLDivElement> & {
     /**
-     * `none` (default) — layout only, for use inside Popover / Card that already provide a surface.
-     * `raised` — standalone floating panel: raised background, panel radius/padding, overlay shadow.
+     * `none` — layout only (inside a Popover or Card). `raised` — a standalone floating panel: raised background, panel radius and padding, overlay shadow.
      */
     surface?: "none" | "raised";
     ref?: React.Ref<HTMLDivElement>;
@@ -85,16 +109,22 @@ declare function Panel({ surface, className, children, ...rest }: ColorPickerPan
 declare namespace Panel {
     var displayName: string;
 }
-declare function ColorPickerRoot({ value, defaultValue, onValueChange, defaultFormat, labels: labelsProp, children, }: ColorPickerRootProps): import("react/jsx-runtime").JSX.Element;
+declare function ColorPickerRoot({ value, defaultValue, onValueChange, format: formatProp, defaultFormat, onFormatChange, size: sizeProp, labels: labelsProp, children, }: ColorPickerRootProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace ColorPickerRoot {
     var displayName: string;
 }
 export type ColorPickerSliderProps = Omit<AriaColorSliderProps, "isDisabled"> & {
+    /**
+     * Shows the color but takes no input (grayscale).
+     */
     disabled?: boolean;
     ref?: React.Ref<HTMLDivElement>;
 };
 declare function Slider({ className, disabled, ...props }: ColorPickerSliderProps): import("react/jsx-runtime").JSX.Element;
 export type ColorPickerAreaProps = Omit<AriaColorAreaProps, "isDisabled"> & {
+    /**
+     * Shows the color but takes no input (grayscale).
+     */
     disabled?: boolean;
     ref?: React.Ref<HTMLDivElement>;
 };
@@ -106,9 +136,9 @@ export type ColorPickerThumbProps = AriaColorThumbProps & {
 };
 declare function Area({ className, disabled, ...props }: ColorPickerAreaProps): import("react/jsx-runtime").JSX.Element;
 declare function SliderTrack({ className, style, ...props }: ColorPickerSliderTrackProps): import("react/jsx-runtime").JSX.Element;
+/** The draggable thumb of `ColorPicker.Area` and of a `ColorPicker.SliderTrack`. */
 declare function Thumb({ className, ...props }: ColorPickerThumbProps): import("react/jsx-runtime").JSX.Element;
-declare function AreaThumb({ className, ...props }: ColorPickerThumbProps): import("react/jsx-runtime").JSX.Element;
-export type ColorPickerSwatchesProps = Omit<ColorSwatchesProps, "value" | "defaultValue" | "onValueChange" | "allowEmpty" | "name">;
+export type ColorPickerSwatchesProps = Omit<ColorSwatchesColorProps, "mode" | "palette" | "value" | "defaultValue" | "onValueChange" | "allowEmpty" | "name">;
 /**
  * Preset swatches bound to the picker color: picking one sets the color, editing the color
  * elsewhere moves the selection. The kit `ColorSwatches`, so presets carry names.
@@ -118,16 +148,21 @@ declare namespace Swatches {
     var displayName: string;
 }
 export type ColorPickerSliderMetaProps = DivProps & {
-    /** The channel name. */
+    /**
+     * Visible label of the slider.
+     */
     label: React.ReactNode;
 };
-/** Slider heading: the label and the current channel value. */
+/**
+ * Slider heading: the label and the current channel value. The value is an `<output>` of its own:
+ * React Aria's `SliderOutput` inside a color slider points `for` at an id no input carries.
+ */
 declare function SliderMeta({ label, className, ...rest }: ColorPickerSliderMetaProps): import("react/jsx-runtime").JSX.Element;
 declare function HexInput({ label, hint, error, focusRing, ...rest }: ColorPickerHexInputProps): import("react/jsx-runtime").JSX.Element;
 declare namespace HexInput {
     var displayName: string;
 }
-export type ColorPickerEyeDropperButtonProps = Omit<React.ComponentPropsWithoutRef<typeof Button.Root>, "variant" | "tone" | "size" | "aria-label"> & {
+export type ColorPickerEyeDropperButtonProps = Omit<React.ComponentPropsWithoutRef<typeof Button.Root>, "variant" | "tone" | "size" | "aria-label" | "shape" | "asChild"> & {
     ref?: React.Ref<HTMLButtonElement>;
 };
 /**
@@ -154,7 +189,6 @@ export declare const ColorPicker: {
     ChannelStrip: typeof ChannelStrip;
     HexInput: typeof HexInput;
     Area: typeof Area;
-    AreaThumb: typeof AreaThumb;
     Slider: typeof Slider;
     SliderMeta: typeof SliderMeta;
     SliderTrack: typeof SliderTrack;

package/dist/components/color-picker/ColorPresets.d.ts

@@ -11,29 +11,74 @@ export type ColorPresetsLabels = {
     /** The "no color" swatch (`allowEmpty`) and the trigger name for an empty value. */
     empty: string;
 };
+export declare const COLOR_PRESETS_LABELS: ColorPresetsLabels;
 export type ColorPresetsRootProps = {
-    /** Controlled color; `null` — no color. */
+    /**
+     * Controlled color; `null` — no color.
+     */
     value?: string | null;
+    /**
+     * Initial color when uncontrolled.
+     */
     defaultValue?: string | null;
+    /**
+     * Called with the preset `value` or `null`.
+     */
     onValueChange?: (value: string | null) => void;
+    /**
+     * Controlled open state of the panel.
+     */
     open?: boolean;
+    /**
+     * Initial open state.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called when the panel opens or closes.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** Swatches in panel order. Default: `COLOR_PRESETS` (16). */
+    /**
+     * Escape closes the panel and returns focus to the trigger.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * A press outside the panel and its trigger closes it; focus follows the pointer.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Swatches in panel order.
+     */
     presets?: readonly ColorPreset[];
-    /** Grid columns. Default: one row for up to 8 presets (+ "no color"), else 8; 16 → 8 × 2. */
+    /**
+     * Grid columns; default one row for up to 8 presets (+ «no color»), else 8.
+     */
     columns?: number;
-    /** Tier of the trigger, swatches and panel. Default: the host tier, else `m`. */
+    /**
+     * Tier of the trigger, the swatches and the panel. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
+    /**
+     * The trigger is disabled and does not open the panel. A disabled `Fieldset` around it sets it too.
+     */
     disabled?: boolean;
-    /** Adds the "no color" swatch after the presets (value `null`); hue rows stay aligned. */
+    /**
+     * Adds the «no color» swatch after the presets (value `null`).
+     */
     allowEmpty?: boolean;
-    /** Close the panel after a pick (focus returns to the trigger). Default `true`. */
+    /**
+     * Close the panel after a pick (focus returns to the trigger).
+     */
     closeOnSelect?: boolean;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<ColorPresetsLabels>;
+    /**
+     * `ColorPresets.Trigger` and `ColorPresets.Content`.
+     */
     children: React.ReactNode;
 };
-declare function ColorPresetsRoot({ value: valueProp, defaultValue, onValueChange, open: openProp, defaultOpen, onOpenChange, presets, columns: columnsProp, size: sizeProp, disabled: disabledProp, allowEmpty, closeOnSelect, labels: labelsProp, children, }: ColorPresetsRootProps): import("react/jsx-runtime").JSX.Element;
+declare function ColorPresetsRoot({ value: valueProp, defaultValue, onValueChange, open: openProp, defaultOpen, onOpenChange, closeOnEscape, closeOnOutsideClick, presets, columns: columnsProp, size: sizeProp, disabled: disabledProp, allowEmpty, closeOnSelect, labels: labelsProp, children, }: ColorPresetsRootProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace ColorPresetsRoot {
     var displayName: string;
 }
@@ -41,21 +86,23 @@ export type ColorPresetsSwatchProps = Omit<React.HTMLAttributes<HTMLSpanElement>
     ref?: React.Ref<HTMLSpanElement>;
 };
 /**
- * The current color as a small square for a custom trigger (e.g. inside `Button.Root`). Sized from
- * the host's `--prime-icon-size`; `aria-hidden` — the trigger carries the name.
+ * The current color as a small square for a custom trigger (e.g. inside `Button.Root`), at the
+ * host's icon size; `aria-hidden` — the trigger carries the name.
  */
 declare function Swatch(props: ColorPresetsSwatchProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Swatch {
     var displayName: string;
 }
 export type ColorPresetsTriggerProps = {
-    /** One element that opens the panel: `ColorPresets.SwatchButton`, or e.g. `Button.Root` with `ColorPresets.Swatch`. */
+    /**
+     * One element: `ColorPresets.SwatchButton`, or e.g. `Button.Root` with `ColorPresets.Swatch`.
+     */
     children: React.ReactElement;
 };
 /**
  * A slot: clones its one child into the panel's trigger. Name «<labels.trigger>: <color name>»,
- * `disabled` from the root, ArrowDown / ArrowUp open the panel; the child's own `aria-label`,
- * `disabled` and handlers win (Slot merge rules).
+ * `disabled` from the root, ArrowDown / ArrowUp open the panel (the Popover's `openOnArrow`); the
+ * child's own `aria-label`, `disabled` and handlers win (Slot merge rules).
  */
 declare function Trigger({ children }: ColorPresetsTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Trigger {
@@ -70,9 +117,17 @@ declare namespace SwatchButton {
     var displayName: string;
 }
 export type ColorPresetsContentProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "role"> & {
-    /** Visible heading above the grid; also the list's accessible name (else `labels.list`). */
+    /**
+     * Heading above the grid; also the list's accessible name (else `labels.list`).
+     */
     label?: React.ReactNode;
+    /**
+     * Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it.
+     */
     align?: PositionAlign;
+    /**
+     * Side of the trigger.
+     */
     side?: PositionSide;
     /** The floating panel. */
     ref?: React.Ref<HTMLDivElement>;

package/dist/components/color-swatches/ColorSwatches.d.ts

@@ -1,5 +1,5 @@
 import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
-import type { ControlSize } from "../../internal/states";
+import type { ControlSize, PaletteColor } from "../../internal/states";
 import { type ColorPreset } from "../../internal/swatch";
 export type ColorSwatchesLabels = {
     /** Accessible name of the group when there is no visible `label` and no `aria-label`. */
@@ -8,38 +8,110 @@ export type ColorSwatchesLabels = {
     empty: string;
     /** Muted marker after the label for `optional`. */
     optional: string;
+    /** Names of the palette hues (`mode="palette"`): each swatch's accessible name. */
+    colorNames: Record<PaletteColor, string>;
 };
-export type ColorSwatchesProps = FieldRootDomProps & Omit<FieldFrameProps, "focusRing"> & {
-    /** Controlled color; `null` — no color. */
-    value?: string | null;
-    defaultValue?: string | null;
-    onValueChange?: (value: string | null) => void;
-    /** Swatches in order. Default: `COLOR_PRESETS` (16). */
-    presets?: readonly ColorPreset[];
+export declare const COLOR_SWATCHES_LABELS: ColorSwatchesLabels;
+type ColorSwatchesBaseProps = FieldRootDomProps & FieldFrameProps & {
     /**
-     * Tier: swatch = control height − 8 (20 · 24 · 28 · 32 · 40), gap = tier gap. Default: the
-     * tier of the surrounding control, else `m`.
+     * Tier of the swatches (height 20 · 24 · 28 · 32 · 40); the label and hint keep the host tier. Without it the swatches take the host tier too.
      */
     size?: ControlSize;
+    /**
+     * Disables every swatch (grey, half transparent).
+     */
     disabled?: boolean;
+    /**
+     * Danger inner edge on every swatch and `aria-invalid`. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** Adds the "no color" swatch after the presets (value `null`). */
+    /**
+     * Adds the «no color» checkerboard swatch after the presets (value `null`).
+     */
     allowEmpty?: boolean;
-    /** Form field name: a hidden input submits the selected color (empty string for no color). */
+    /**
+     * Form field name: a hidden input submits the selected color (empty string for no color).
+     */
     name?: string;
+    /**
+     * Id of the radiogroup; hint id is `<id>-hint`, error id is `<id>-error`.
+     */
     id?: string;
+    /**
+     * Accessible name when there is no visible `label` (else `labels.group`).
+     */
     "aria-label"?: string;
+    /**
+     * Names the group by an outside element.
+     */
     "aria-labelledby"?: string;
+    /**
+     * Merged before the hint/error ids.
+     */
     "aria-describedby"?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<ColorSwatchesLabels>;
 };
-/**
- * Columns of a grid of `count` swatches in `width`: as many tier-sized swatches as fit, then spread
- * evenly over the rows that needs (16 in a row of 14 → two rows of 8, not 14 + 2).
- */
-export declare function balancedColumns(count: number, width: number, cell: number, gap: number): number;
+/** Any CSS color from a preset list (the default mode). */
+export type ColorSwatchesColorProps = ColorSwatchesBaseProps & {
+    /**
+     * `color` — any CSS color from `presets`; `palette` — a kit palette hue (`PaletteColor`) from `palette`, drawn from its solid step in both themes.
+     */
+    mode?: "color";
+    /**
+     * Controlled color (a hue with `palette`); `null` — no color.
+     */
+    value?: string | null;
+    /**
+     * Initial color when uncontrolled.
+     */
+    defaultValue?: string | null;
+    /**
+     * Called with the preset `value` (as written in `presets`), the hue with `palette`, or `null`.
+     */
+    onValueChange?: (value: string | null) => void;
+    /**
+     * `color` mode: swatches in order, `{ value, label }`; the label is the swatch's accessible name and tooltip.
+     */
+    presets?: readonly ColorPreset[];
+    /**
+     * `palette` mode: the hues in order; each is named by `labels.colorNames`.
+     */
+    palette?: never;
+};
+/** A kit palette hue: the value is its name, the swatches its solid step in both themes. */
+type ColorSwatchesPaletteProps = ColorSwatchesBaseProps & {
+    /**
+     * `color` — any CSS color from `presets`; `palette` — a kit palette hue (`PaletteColor`) from `palette`, drawn from its solid step in both themes.
+     */
+    mode: "palette";
+    /**
+     * Controlled color (a hue with `palette`); `null` — no color.
+     */
+    value?: PaletteColor | null;
+    /**
+     * Initial color when uncontrolled.
+     */
+    defaultValue?: PaletteColor | null;
+    /**
+     * Called with the preset `value` (as written in `presets`), the hue with `palette`, or `null`.
+     */
+    onValueChange?: (value: PaletteColor | null) => void;
+    /**
+     * `color` mode: swatches in order, `{ value, label }`; the label is the swatch's accessible name and tooltip.
+     */
+    presets?: never;
+    /**
+     * `palette` mode: the hues in order; each is named by `labels.colorNames`.
+     */
+    palette?: readonly PaletteColor[];
+};
+export type ColorSwatchesProps = ColorSwatchesColorProps | ColorSwatchesPaletteProps;
 /**
  * Inline color choice: a wrapping grid of swatches, one selected (`role="radiogroup"`).
  * Fits forms and dialogs where opening a palette popover would be one step too many.
  */
-export declare function ColorSwatches({ value: valueProp, defaultValue, onValueChange, presets, size: sizeProp, disabled: disabledProp, invalid, allowEmpty, name, id, className, label, required, optional, hint, error, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, labels: labelsProp, ...rest }: ColorSwatchesProps): import("react/jsx-runtime").JSX.Element;
+export declare function ColorSwatches(props: ColorSwatchesProps): import("react/jsx-runtime").JSX.Element;
+export {};