@skdx/react 0.26.0

package/dist/color-picker/ColorPickerHueSlider.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import type { ColorPickerHueSliderProps } from './types.js';
+/**
+ * The hue track: a linear `role="slider"` over 0–360°, independent of the
+ * saturation and brightness the 2D area holds.
+ *
+ * **It has ends and does not wrap.** Hue is circular, but a linear control
+ * reporting `aria-valuemin={0}`/`aria-valuemax={360}` that teleported from one
+ * end to the other would be lying to assistive tech — so the track stops at
+ * the last hue on the step grid below 360, since 360° *is* 0° and folding
+ * would throw the thumb back to the left edge mid-drag. Reach for
+ * `AngleSlider` when you want a hue control that genuinely wraps.
+ *
+ * Pointer geometry is physical — left-to-right when horizontal,
+ * bottom-to-top when vertical, matching `Slider` — while the arrow **keys**
+ * mirror under `dir="rtl"`. The gradient is yours, and so is its direction.
+ *
+ * ```css
+ * .my-hue {
+ *   background: linear-gradient(
+ *     to right,
+ *     #f00 0%, #ff0 17%, #0f0 33%, #0ff 50%, #00f 67%, #f0f 83%, #f00 100%
+ *   );
+ * }
+ * .my-hue-thumb {
+ *   position: absolute;
+ *   inset-inline-start: var(--skdx-color-picker-hue-position);
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerHueSlider className="my-hue">
+ *   <ColorPickerHueSliderThumb className="my-hue-thumb" />
+ * </ColorPickerHueSlider>
+ * ```
+ */
+export declare const ColorPickerHueSlider: React.ForwardRefExoticComponent<Omit<ColorPickerHueSliderProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/color-picker/ColorPickerHueSliderThumb.d.cts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { ColorPickerHueSliderThumbProps } from './types.cjs';
+/**
+ * The handle on a {@link ColorPickerHueSlider}. Purely visual: `aria-hidden`
+ * and out of the tab order, because the track itself carries the
+ * `role="slider"` semantics and takes the tab stop — a second focusable
+ * element here would announce the same value twice.
+ *
+ * It ships **no positioning**. The root publishes
+ * `--skdx-color-picker-hue-position` as a percentage, so one CSS rule places it
+ * and nothing recomputes an offset per frame:
+ *
+ * ```css
+ * .my-hue-thumb {
+ *   position: absolute;
+ *   inset-inline-start: var(--skdx-color-picker-hue-position);
+ * }
+ * ```
+ *
+ * `data-dragging` lives on the **track**, not here — one attribute, and the
+ * descendant selector `[data-channel='hue'][data-dragging] .my-hue-thumb` costs
+ * nothing to write and nothing to plumb.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerHueSlider>
+ *   <ColorPickerHueSliderThumb className="my-hue-thumb" />
+ * </ColorPickerHueSlider>
+ * ```
+ */
+export declare const ColorPickerHueSliderThumb: React.ForwardRefExoticComponent<Omit<ColorPickerHueSliderThumbProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/color-picker/ColorPickerHueSliderThumb.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { ColorPickerHueSliderThumbProps } from './types.js';
+/**
+ * The handle on a {@link ColorPickerHueSlider}. Purely visual: `aria-hidden`
+ * and out of the tab order, because the track itself carries the
+ * `role="slider"` semantics and takes the tab stop — a second focusable
+ * element here would announce the same value twice.
+ *
+ * It ships **no positioning**. The root publishes
+ * `--skdx-color-picker-hue-position` as a percentage, so one CSS rule places it
+ * and nothing recomputes an offset per frame:
+ *
+ * ```css
+ * .my-hue-thumb {
+ *   position: absolute;
+ *   inset-inline-start: var(--skdx-color-picker-hue-position);
+ * }
+ * ```
+ *
+ * `data-dragging` lives on the **track**, not here — one attribute, and the
+ * descendant selector `[data-channel='hue'][data-dragging] .my-hue-thumb` costs
+ * nothing to write and nothing to plumb.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerHueSlider>
+ *   <ColorPickerHueSliderThumb className="my-hue-thumb" />
+ * </ColorPickerHueSlider>
+ * ```
+ */
+export declare const ColorPickerHueSliderThumb: React.ForwardRefExoticComponent<Omit<ColorPickerHueSliderThumbProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/color-picker/ColorPickerInput.d.cts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import type { ColorPickerInputProps } from './types.cjs';
+/**
+ * A text field over the colour. With no `channel` it carries the **whole
+ * value in the picker's current format** — the hex box people expect, which
+ * re-spells itself the moment the format changes. With a `channel` it edits
+ * one number: `red`, `hue`, `alpha`, and so on, which is how an RGB spinbox
+ * row is built without eight components.
+ *
+ * Editing is **draft-based**: keystrokes are held locally and only applied on
+ * `Enter` or blur, because `#ab` on the way to `#abcdef` is not a colour and
+ * committing per keystroke would repaint the picker to black halfway through
+ * every hex the user types. `Escape` abandons the draft, and an entry that
+ * does not parse reverts rather than clearing the colour.
+ *
+ * A commit **announces the resulting colour**. An input is not a slider: a
+ * screen reader echoes the characters typed, which says nothing about the
+ * colour they produced. See `ColorPicker.md` for where that line is drawn.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerInput aria-label="Hex value" />
+ *
+ * <ColorPickerInput channel="red" />
+ * <ColorPickerInput channel="green" />
+ * <ColorPickerInput channel="blue" />
+ * <ColorPickerInput channel="alpha" />
+ * ```
+ */
+export declare const ColorPickerInput: React.ForwardRefExoticComponent<Omit<ColorPickerInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/color-picker/ColorPickerInput.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import type { ColorPickerInputProps } from './types.js';
+/**
+ * A text field over the colour. With no `channel` it carries the **whole
+ * value in the picker's current format** — the hex box people expect, which
+ * re-spells itself the moment the format changes. With a `channel` it edits
+ * one number: `red`, `hue`, `alpha`, and so on, which is how an RGB spinbox
+ * row is built without eight components.
+ *
+ * Editing is **draft-based**: keystrokes are held locally and only applied on
+ * `Enter` or blur, because `#ab` on the way to `#abcdef` is not a colour and
+ * committing per keystroke would repaint the picker to black halfway through
+ * every hex the user types. `Escape` abandons the draft, and an entry that
+ * does not parse reverts rather than clearing the colour.
+ *
+ * A commit **announces the resulting colour**. An input is not a slider: a
+ * screen reader echoes the characters typed, which says nothing about the
+ * colour they produced. See `ColorPicker.md` for where that line is drawn.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerInput aria-label="Hex value" />
+ *
+ * <ColorPickerInput channel="red" />
+ * <ColorPickerInput channel="green" />
+ * <ColorPickerInput channel="blue" />
+ * <ColorPickerInput channel="alpha" />
+ * ```
+ */
+export declare const ColorPickerInput: React.ForwardRefExoticComponent<Omit<ColorPickerInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/color-picker/ColorPickerSwatch.d.cts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import type { ColorPickerSwatchProps } from './types.cjs';
+/**
+ * One preset colour inside a {@link ColorPickerSwatchGroup}. Renders a
+ * `role="radio"` `<button>` whose `aria-checked` is true when the picker's
+ * current colour matches this swatch exactly — compared as hex, so
+ * `#f00`, `#ff0000` and `rgb(255, 0, 0)` are all recognised as the same preset.
+ *
+ * Clicking it **announces the resulting colour**. A swatch is a button, not a
+ * slider: nothing about pressing it tells a screen-reader user what colour
+ * they now have, so this is one of the few controls in the family that speaks
+ * for itself. See `ColorPicker.md` for where that line is drawn.
+ *
+ * A `value` that {@link parseColor} cannot read renders a **disabled** swatch
+ * rather than a button that silently does nothing — a preset list built from
+ * user data should fail visibly.
+ *
+ * It publishes `--skdx-color-picker-swatch-value` (always hex, always a real
+ * CSS colour) so the fill is one rule and never a second copy of the value in
+ * an inline `background`:
+ *
+ * ```css
+ * .my-swatch {
+ *   background: var(--skdx-color-picker-swatch-value);
+ * }
+ * .my-swatch[data-state='checked'] {
+ *   outline: 2px solid currentColor;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerSwatchGroup aria-label="Preset colours">
+ *   <ColorPickerSwatch value="#e11d48" className="my-swatch" />
+ *   <ColorPickerSwatch value="rgb(16 185 129 / 50%)" className="my-swatch" />
+ * </ColorPickerSwatchGroup>
+ * ```
+ */
+export declare const ColorPickerSwatch: React.ForwardRefExoticComponent<Omit<ColorPickerSwatchProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/color-picker/ColorPickerSwatch.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import type { ColorPickerSwatchProps } from './types.js';
+/**
+ * One preset colour inside a {@link ColorPickerSwatchGroup}. Renders a
+ * `role="radio"` `<button>` whose `aria-checked` is true when the picker's
+ * current colour matches this swatch exactly — compared as hex, so
+ * `#f00`, `#ff0000` and `rgb(255, 0, 0)` are all recognised as the same preset.
+ *
+ * Clicking it **announces the resulting colour**. A swatch is a button, not a
+ * slider: nothing about pressing it tells a screen-reader user what colour
+ * they now have, so this is one of the few controls in the family that speaks
+ * for itself. See `ColorPicker.md` for where that line is drawn.
+ *
+ * A `value` that {@link parseColor} cannot read renders a **disabled** swatch
+ * rather than a button that silently does nothing — a preset list built from
+ * user data should fail visibly.
+ *
+ * It publishes `--skdx-color-picker-swatch-value` (always hex, always a real
+ * CSS colour) so the fill is one rule and never a second copy of the value in
+ * an inline `background`:
+ *
+ * ```css
+ * .my-swatch {
+ *   background: var(--skdx-color-picker-swatch-value);
+ * }
+ * .my-swatch[data-state='checked'] {
+ *   outline: 2px solid currentColor;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerSwatchGroup aria-label="Preset colours">
+ *   <ColorPickerSwatch value="#e11d48" className="my-swatch" />
+ *   <ColorPickerSwatch value="rgb(16 185 129 / 50%)" className="my-swatch" />
+ * </ColorPickerSwatchGroup>
+ * ```
+ */
+export declare const ColorPickerSwatch: React.ForwardRefExoticComponent<Omit<ColorPickerSwatchProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/color-picker/ColorPickerSwatchGroup.d.cts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { ColorPickerSwatchGroupProps } from './types.cjs';
+/** @internal Swatches are found by attribute at interaction time — the same trade `useRovingFocus` makes everywhere, so a swatch added later needs no registration. */
+export declare const SWATCH_SELECTOR = "[data-skdx-color-picker-swatch]";
+/** @internal Which swatch currently holds the group's single tab stop. Not part of the public API. */
+export interface ColorPickerSwatchGroupContextValue {
+    activeValue: string | null;
+    setActiveValue: (value: string) => void;
+}
+export declare const ColorPickerSwatchGroupProvider: {
+    (props: ColorPickerSwatchGroupContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useColorPickerSwatchGroupContext: (consumerName: string) => ColorPickerSwatchGroupContextValue;
+/**
+ * Container for a set of preset {@link ColorPickerSwatch}es. Renders
+ * `role="radiogroup"` — picking one of N presets is exactly the radio pattern,
+ * and "none of them" is a legitimate radiogroup state, which matters because
+ * the picker's colour usually is *not* one of the presets.
+ *
+ * That brings a **single tab stop** for the whole set: arrow keys move between
+ * swatches, `Home`/`End` jump to the ends. All four arrows navigate, since
+ * swatches are normally laid out as a grid and forcing one axis would strand
+ * half of it. The tab stop follows the checked swatch, or the first one when
+ * none is checked.
+ *
+ * Give the group an accessible name (`aria-label` or `aria-labelledby`) — an
+ * unnamed radiogroup announces a bare count of options.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerSwatchGroup aria-label="Preset colours">
+ *   {['#e11d48', '#f59e0b', '#10b981', '#3b82f6'].map((preset) => (
+ *     <ColorPickerSwatch key={preset} value={preset} />
+ *   ))}
+ * </ColorPickerSwatchGroup>
+ * ```
+ */
+export declare const ColorPickerSwatchGroup: React.ForwardRefExoticComponent<Omit<ColorPickerSwatchGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/color-picker/ColorPickerSwatchGroup.d.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { ColorPickerSwatchGroupProps } from './types.js';
+/** @internal Swatches are found by attribute at interaction time — the same trade `useRovingFocus` makes everywhere, so a swatch added later needs no registration. */
+export declare const SWATCH_SELECTOR = "[data-skdx-color-picker-swatch]";
+/** @internal Which swatch currently holds the group's single tab stop. Not part of the public API. */
+export interface ColorPickerSwatchGroupContextValue {
+    activeValue: string | null;
+    setActiveValue: (value: string) => void;
+}
+export declare const ColorPickerSwatchGroupProvider: {
+    (props: ColorPickerSwatchGroupContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useColorPickerSwatchGroupContext: (consumerName: string) => ColorPickerSwatchGroupContextValue;
+/**
+ * Container for a set of preset {@link ColorPickerSwatch}es. Renders
+ * `role="radiogroup"` — picking one of N presets is exactly the radio pattern,
+ * and "none of them" is a legitimate radiogroup state, which matters because
+ * the picker's colour usually is *not* one of the presets.
+ *
+ * That brings a **single tab stop** for the whole set: arrow keys move between
+ * swatches, `Home`/`End` jump to the ends. All four arrows navigate, since
+ * swatches are normally laid out as a grid and forcing one axis would strand
+ * half of it. The tab stop follows the checked swatch, or the first one when
+ * none is checked.
+ *
+ * Give the group an accessible name (`aria-label` or `aria-labelledby`) — an
+ * unnamed radiogroup announces a bare count of options.
+ *
+ * @example
+ * ```tsx
+ * <ColorPickerSwatchGroup aria-label="Preset colours">
+ *   {['#e11d48', '#f59e0b', '#10b981', '#3b82f6'].map((preset) => (
+ *     <ColorPickerSwatch key={preset} value={preset} />
+ *   ))}
+ * </ColorPickerSwatchGroup>
+ * ```
+ */
+export declare const ColorPickerSwatchGroup: React.ForwardRefExoticComponent<Omit<ColorPickerSwatchGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/color-picker/index.d.cts

@@ -0,0 +1,13 @@
+export { ColorPicker } from './ColorPicker.cjs';
+export { ColorPickerArea } from './ColorPickerArea.cjs';
+export { ColorPickerAreaThumb } from './ColorPickerAreaThumb.cjs';
+export { ColorPickerHueSlider } from './ColorPickerHueSlider.cjs';
+export { ColorPickerHueSliderThumb } from './ColorPickerHueSliderThumb.cjs';
+export { ColorPickerAlphaSlider } from './ColorPickerAlphaSlider.cjs';
+export { ColorPickerAlphaSliderThumb } from './ColorPickerAlphaSliderThumb.cjs';
+export { ColorPickerSwatchGroup } from './ColorPickerSwatchGroup.cjs';
+export { ColorPickerSwatch } from './ColorPickerSwatch.cjs';
+export { ColorPickerInput } from './ColorPickerInput.cjs';
+export { ColorPickerFormatSelect } from './ColorPickerFormatSelect.cjs';
+export { ColorPickerEyeDropper } from './ColorPickerEyeDropper.cjs';
+export type { ColorChannel, ColorPickerProps, ColorPickerAreaProps, ColorPickerAreaThumbProps, ColorPickerHueSliderProps, ColorPickerHueSliderThumbProps, ColorPickerAlphaSliderProps, ColorPickerAlphaSliderThumbProps, ColorPickerSwatchGroupProps, ColorPickerSwatchProps, ColorPickerInputProps, ColorPickerFormatSelectProps, ColorPickerEyeDropperProps, } from './types.cjs';

package/dist/color-picker/index.d.ts

@@ -0,0 +1,13 @@
+export { ColorPicker } from './ColorPicker.js';
+export { ColorPickerArea } from './ColorPickerArea.js';
+export { ColorPickerAreaThumb } from './ColorPickerAreaThumb.js';
+export { ColorPickerHueSlider } from './ColorPickerHueSlider.js';
+export { ColorPickerHueSliderThumb } from './ColorPickerHueSliderThumb.js';
+export { ColorPickerAlphaSlider } from './ColorPickerAlphaSlider.js';
+export { ColorPickerAlphaSliderThumb } from './ColorPickerAlphaSliderThumb.js';
+export { ColorPickerSwatchGroup } from './ColorPickerSwatchGroup.js';
+export { ColorPickerSwatch } from './ColorPickerSwatch.js';
+export { ColorPickerInput } from './ColorPickerInput.js';
+export { ColorPickerFormatSelect } from './ColorPickerFormatSelect.js';
+export { ColorPickerEyeDropper } from './ColorPickerEyeDropper.js';
+export type { ColorChannel, ColorPickerProps, ColorPickerAreaProps, ColorPickerAreaThumbProps, ColorPickerHueSliderProps, ColorPickerHueSliderThumbProps, ColorPickerAlphaSliderProps, ColorPickerAlphaSliderThumbProps, ColorPickerSwatchGroupProps, ColorPickerSwatchProps, ColorPickerInputProps, ColorPickerFormatSelectProps, ColorPickerEyeDropperProps, } from './types.js';

package/dist/color-picker/types.d.cts

@@ -0,0 +1,211 @@
+import type * as React from 'react';
+import type { ColorFormat, HsbColor } from '../utils/color.cjs';
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** @internal Shared state distributed from {@link ColorPicker} to its parts via context. Not part of the public API. */
+export interface ColorPickerContextValue {
+    /** The canonical colour. HSB, so hue survives a trip to black — see `utils/color.md`. */
+    color: HsbColor;
+    /** The colour serialised in the current `format`; what `value`/`onValueChange` speak. */
+    value: string;
+    format: ColorFormat;
+    alpha: boolean;
+    step: number;
+    disabled: boolean;
+    readOnly: boolean;
+    /** `!disabled && !readOnly` — the single condition every part gates input on. */
+    interactive: boolean;
+    /** Human-readable description of a colour, used both as `aria-valuetext` and as the body of a live announcement. */
+    describe: (color: HsbColor) => string;
+    /** Applies a new colour. `announce` is for controls whose own role does not already speak the result — see `ColorPicker.md`. */
+    setColor: (next: HsbColor, options?: {
+        announce?: boolean;
+    }) => void;
+    /** Fires `onValueCommit` with the value as it currently stands. Called once at the end of a drag. */
+    commit: () => void;
+    setFormat: (format: ColorFormat) => void;
+}
+/** Which single channel a {@link ColorPickerInput} edits. */
+export type ColorChannel = 'hex' | 'red' | 'green' | 'blue' | 'hue' | 'saturation' | 'brightness' | 'lightness' | 'alpha';
+/** Props for the {@link ColorPicker} root. */
+export interface ColorPickerProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Current colour as a string in the active `format`, for controlled usage.
+     * Pair with `onValueChange`. Anything {@link parseColor} understands is
+     * accepted regardless of `format`; an unparseable string is ignored and the
+     * last good colour is kept, because a half-typed `#ab` should not blank the
+     * picker.
+     * @default undefined — uncontrolled, tracks its own colour internally.
+     */
+    value?: string;
+    /**
+     * Initial colour, for uncontrolled usage, seeding the first render.
+     * @default '#000000' — opaque black, the one colour every format agrees on.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new string on every change: each arrow key, each frame of a
+     * drag that moves the colour, each swatch click — and also on a `format`
+     * change, because the string genuinely changed even though the colour did not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Fires once with the final string when a pointer drag ends (release or
+     * cancel). This is the callback to hang an expensive effect on: a drag emits
+     * `onValueChange` per frame and this one exactly once, so a consumer can
+     * repaint continuously without also making a network call per frame.
+     *
+     * Keyboard and click changes do not fire it — each is already a discrete
+     * commit, reported by `onValueChange`.
+     * @default undefined — no-op if omitted.
+     */
+    onValueCommit?: (value: string) => void;
+    /**
+     * Previous name for `onValueCommit`, kept so 0.20 code keeps working.
+     * @deprecated Renamed to `onValueCommit` in 0.21. The contract, Vue and Web
+     * Components have always called this `value-commit`, and React's own
+     * `Slider`/`Editable` already spelled it `onValueCommit` — only
+     * `AngleSlider` and `ColorPicker` used `onValueChangeEnd`. Still honoured
+     * when `onValueCommit` is not supplied; it will be removed in 0.22.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChangeEnd?: (value: string) => void;
+    /**
+     * Notation `value` is written in, for controlled usage. Pair with
+     * `onFormatChange`. The colour itself is stored as HSB whatever this says;
+     * the format only decides how it is spelled on the way out.
+     * @default undefined — uncontrolled, tracks its own format internally.
+     */
+    format?: ColorFormat;
+    /**
+     * The notation the picker starts in when it is left uncontrolled.
+     * @default 'hex' — the notation people paste, type and recognise.
+     */
+    defaultFormat?: ColorFormat;
+    /**
+     * Fires with the new notation whenever it changes. `onValueChange` fires
+     * alongside it with the re-spelled string.
+     * @default undefined — no-op if omitted.
+     */
+    onFormatChange?: (format: ColorFormat) => void;
+    /**
+     * Whether the picker has an alpha channel. When `false`, `ColorPickerAlphaSlider`
+     * renders nothing and every emitted string is fully opaque — so a consumer
+     * that cannot handle transparency never receives an `rgba()` it must strip.
+     * @default true
+     */
+    alpha?: boolean;
+    /**
+     * Keyboard increment, in the units of whichever channel is being stepped:
+     * percentage points for saturation/brightness/alpha, degrees for hue. Shift
+     * multiplies it by ten, so a 1-unit picker still has a coarse gear.
+     * @default 1 — every whole unit is reachable without a pointer.
+     */
+    step?: number;
+    /**
+     * Blocks pointer and keyboard interaction across every part, and takes the
+     * focusable parts out of the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Displays the colour but blocks changes, while every part stays focusable
+     * and in the tab order — unlike `disabled`, a read-only picker can still be
+     * reached and read by a keyboard user.
+     * @default false
+     */
+    readOnly?: boolean;
+}
+/** Props for the {@link ColorPickerArea}, the 2D saturation/brightness surface. */
+export interface ColorPickerAreaProps extends PrimitivePropsWithRef<'div'> {
+}
+/**
+ * Props for the {@link ColorPickerAreaThumb}, the handle on the 2D surface.
+ *
+ * `asChild` is deliberately absent: the thumb renders the area's two
+ * `role="slider"` axes as its own children, and `Slot` merges onto exactly one
+ * element, so there is nothing here to slot onto.
+ */
+export interface ColorPickerAreaThumbProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
+    /**
+     * Accessible name of the horizontal axis, which is a `role="slider"` of its own.
+     * @default 'Saturation'
+     */
+    saturationLabel?: string;
+    /**
+     * Accessible name of the vertical axis, which is a second `role="slider"`.
+     * @default 'Brightness'
+     */
+    brightnessLabel?: string;
+}
+/** Props for the {@link ColorPickerHueSlider}, the 0–360° hue track. */
+export interface ColorPickerHueSliderProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Axis the track runs along, which decides whether pointer position is read
+     * from `clientX` or `clientY` and is published as `data-orientation`.
+     * Vertical tracks run bottom-to-top, matching `Slider`.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+}
+/** Props for the {@link ColorPickerHueSliderThumb}, the handle on the hue track. */
+export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for the {@link ColorPickerAlphaSlider}, the 0–100% opacity track. */
+export interface ColorPickerAlphaSliderProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Axis the track runs along, which decides whether pointer position is read
+     * from `clientX` or `clientY` and is published as `data-orientation`.
+     * Vertical tracks run bottom-to-top, matching `Slider`.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+}
+/** Props for the {@link ColorPickerAlphaSliderThumb}, the handle on the alpha track. */
+export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for the {@link ColorPickerSwatchGroup}, the container for preset swatches. */
+export interface ColorPickerSwatchGroupProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Whether arrow-key navigation wraps from the last swatch back to the first.
+     * @default true
+     */
+    loop?: boolean;
+}
+/** Props for a single {@link ColorPickerSwatch} preset. */
+export interface ColorPickerSwatchProps extends PrimitivePropsWithRef<'button'> {
+    /**
+     * The colour this swatch selects, in any notation {@link parseColor}
+     * understands. An unparseable value renders a disabled swatch rather than a
+     * button that silently does nothing when clicked.
+     */
+    value: string;
+}
+/** Props for a {@link ColorPickerInput} text field. */
+export interface ColorPickerInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+    /**
+     * Which single channel this input edits. Omit it and the input carries the
+     * whole colour as one string in the picker's current `format` — which is the
+     * hex box people expect, and which re-spells itself when the format changes.
+     * @default undefined — the whole colour, in the current format.
+     */
+    channel?: ColorChannel;
+}
+/** Props for the {@link ColorPickerFormatSelect}, a native `<select>` over the notations. */
+export interface ColorPickerFormatSelectProps extends Omit<React.ComponentPropsWithRef<'select'>, 'value' | 'defaultValue' | 'children'> {
+    /**
+     * Which notations to offer, in the order they should appear.
+     * @default ['hex', 'rgb', 'hsl', 'hsb'] — every format the picker can emit.
+     */
+    formats?: ColorFormat[];
+    /**
+     * Replaces the generated `<option>` list wholesale, for a consumer who wants
+     * their own labels or grouping. Their `value` attributes must still be
+     * {@link ColorFormat} strings.
+     * @default undefined — one `<option>` per entry in `formats`.
+     */
+    children?: React.ReactNode;
+}
+/** Props for the {@link ColorPickerEyeDropper} trigger. */
+export interface ColorPickerEyeDropperProps extends PrimitivePropsWithRef<'button'> {
+}