@skdx/react 0.27.0 → 0.29.0

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

@@ -1,26 +1,26 @@
 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. */
+/** @internal Shared state distributed from {@link ColorPicker} to its parts via context. */
 export interface ColorPickerContextValue {
-    /** The canonical colour. HSB, so hue survives a trip to black — see `utils/color.md`. */
+    /** @internal The canonical colour, stored as HSB so hue survives a trip to black. */
     color: HsbColor;
-    /** The colour serialised in the current `format`; what `value`/`onValueChange` speak. */
+    /** @internal The colour serialised in the current `format`. */
     value: string;
     format: ColorFormat;
     alpha: boolean;
     step: number;
     disabled: boolean;
     readOnly: boolean;
-    /** `!disabled && !readOnly` — the single condition every part gates input on. */
+    /** @internal `!disabled && !readOnly`. */
     interactive: boolean;
-    /** Human-readable description of a colour, used both as `aria-valuetext` and as the body of a live announcement. */
+    /** @internal Human-readable description of a colour, used as `aria-valuetext` and live-announcement text. */
     describe: (color: HsbColor) => string;
-    /** Applies a new colour. `announce` is for controls whose own role does not already speak the result — see `ColorPicker.md`. */
+    /** @internal Applies a new colour; `announce` is for controls whose own role doesn't already speak the result. */
     setColor: (next: HsbColor, options?: {
-        announce?: boolean;
+        announce?: boolean | undefined;
     }) => void;
-    /** Fires `onValueCommit` with the value as it currently stands. Called once at the end of a drag. */
+    /** @internal Fires `onValueCommit` with the value as it currently stands. */
     commit: () => void;
     setFormat: (format: ColorFormat) => void;
 }
@@ -29,124 +29,127 @@ export type ColorChannel = 'hex' | 'red' | 'green' | 'blue' | 'hue' | 'saturatio
 /** 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.
+     * Composed parts for full control over anatomy, replacing the derived area, tracks, input, and swatches.
+     * @default undefined — the picker derives its anatomy.
+     */
+    children?: React.ReactNode | undefined;
+    /**
+     * Current colour for controlled usage, in any {@link parseColor} notation. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own colour internally.
      */
-    value?: string;
+    value?: string | undefined;
     /**
      * 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;
+    defaultValue?: string | undefined;
     /**
-     * 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`.
+     * Fires with the new string on every change: arrow keys, drag frames, swatch clicks, and format switches.
      * @default undefined — no-op if omitted.
      */
-    onValueCommit?: (value: string) => void;
+    onValueChange?: ((value: string) => void) | undefined;
     /**
-     * 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.
+     * Fires once with the final string when a pointer drag ends; keyboard and click changes don't fire it.
      * @default undefined — no-op if omitted.
      */
-    onValueChangeEnd?: (value: string) => void;
+    onValueCommit?: ((value: string) => void) | undefined;
     /**
-     * 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.
+     * Notation `value` is written in, for controlled usage. Pair with `onFormatChange`.
      * @default undefined — uncontrolled, tracks its own format internally.
      */
-    format?: ColorFormat;
+    format?: ColorFormat | undefined;
     /**
      * The notation the picker starts in when it is left uncontrolled.
      * @default 'hex' — the notation people paste, type and recognise.
      */
-    defaultFormat?: ColorFormat;
+    defaultFormat?: ColorFormat | undefined;
     /**
-     * Fires with the new notation whenever it changes. `onValueChange` fires
-     * alongside it with the re-spelled string.
+     * Fires with the new notation whenever it changes, alongside `onValueChange` with the re-spelled string.
      * @default undefined — no-op if omitted.
      */
-    onFormatChange?: (format: ColorFormat) => void;
+    onFormatChange?: ((format: ColorFormat) => void) | undefined;
     /**
-     * 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.
+     * Whether the picker has an alpha channel; when `false`, `ColorPickerAlphaSlider` renders nothing.
      * @default true
      */
-    alpha?: boolean;
+    alpha?: boolean | undefined;
     /**
-     * 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.
+     * Keyboard increment in channel units: percent for saturation/brightness/alpha, degrees for hue.
      * @default 1 — every whole unit is reachable without a pointer.
      */
-    step?: number;
+    step?: number | undefined;
     /**
-     * Blocks pointer and keyboard interaction across every part, and takes the
-     * focusable parts out of the tab order.
+     * Blocks pointer and keyboard interaction and takes every focusable part out of the tab order.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
-     * 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.
+     * Displays the colour but blocks changes, while every part stays focusable and in the tab order.
      * @default false
      */
-    readOnly?: boolean;
+    readOnly?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerInput}. Ignored when `children` is given.
+     * @default true
+     */
+    showInput?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerSwatchGroup}. Ignored when `children`
+     * is given or `swatches` is empty.
+     * @default true
+     */
+    showSwatches?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerEyeDropper} trigger.
+     * Ignored when `children` is given.
+     * @default true
+     */
+    showEyeDropper?: boolean | undefined;
+    /**
+     * Preset colours the derived anatomy renders as {@link ColorPickerSwatch}
+     * parts, one per entry. Ignored when `children` is given or `showSwatches` is `false`.
+     * @default [] — no swatches rendered.
+     */
+    swatches?: string[] | undefined;
+    /**
+     * Stretches the control across its container width, mirrored as a bare `data-full-width`.
+     * @default undefined — the control sizes to its content.
+     */
+    fullWidth?: boolean | undefined;
+    /**
+     * Size rung the skin scales the picker by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
 /** 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.
- */
+/** Props for the {@link ColorPickerAreaThumb}, the handle on the 2D surface. No `asChild`: it renders two `role="slider"` axes as its own children. */
 export interface ColorPickerAreaThumbProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /**
-     * Accessible name of the horizontal axis, which is a `role="slider"` of its own.
+     * Accessible name of the horizontal saturation slider.
      * @default 'Saturation'
      */
-    saturationLabel?: string;
+    saturationLabel?: string | undefined;
     /**
-     * Accessible name of the vertical axis, which is a second `role="slider"`.
+     * Accessible name of the vertical brightness slider.
      * @default 'Brightness'
      */
-    brightnessLabel?: string;
+    brightnessLabel?: string | undefined;
 }
 /** 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`.
+     * Accessible name for the hue slider control.
+     * @default 'Hue'
+     */
+    label?: string | undefined;
+    /**
+     * Axis the track runs along; vertical tracks run bottom-to-top.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
 }
 /** Props for the {@link ColorPickerHueSliderThumb}, the handle on the hue track. */
 export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'div'> {
@@ -154,12 +157,15 @@ export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'d
 /** 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`.
+     * Accessible name for the opacity slider control.
+     * @default 'Opacity'
+     */
+    label?: string | undefined;
+    /**
+     * Axis the track runs along; vertical tracks run bottom-to-top.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
 }
 /** Props for the {@link ColorPickerAlphaSliderThumb}, the handle on the alpha track. */
 export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<'div'> {
@@ -167,44 +173,41 @@ export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<
 /** 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.
+     * Whether arrow-key navigation wraps from the last swatch to the first.
      * @default true
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
 }
 /** 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.
+     * The colour this swatch selects. Unparseable values render disabled; valid
+     * colours are accepted in any {@link parseColor} notation.
      */
     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.
+     * Which single channel this input edits. Omit to carry the whole colour
+     * in the picker's current `format`; it re-spells itself on format changes.
      * @default undefined — the whole colour, in the current format.
      */
-    channel?: ColorChannel;
+    channel?: ColorChannel | undefined;
 }
 /** 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.
+     * Which notations to offer, in display order.
      * @default ['hex', 'rgb', 'hsl', 'hsb'] — every format the picker can emit.
      */
-    formats?: ColorFormat[];
+    formats?: ColorFormat[] | undefined;
     /**
-     * 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.
+     * Replaces the generated `<option>` list for custom labels or grouping.
+     * `value` attributes must still be {@link ColorFormat} strings.
      * @default undefined — one `<option>` per entry in `formats`.
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 }
 /** Props for the {@link ColorPickerEyeDropper} trigger. */
 export interface ColorPickerEyeDropperProps extends PrimitivePropsWithRef<'button'> {

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

@@ -1,26 +1,26 @@
 import type * as React from 'react';
 import type { ColorFormat, HsbColor } from '../utils/color.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
-/** @internal Shared state distributed from {@link ColorPicker} to its parts via context. Not part of the public API. */
+/** @internal Shared state distributed from {@link ColorPicker} to its parts via context. */
 export interface ColorPickerContextValue {
-    /** The canonical colour. HSB, so hue survives a trip to black — see `utils/color.md`. */
+    /** @internal The canonical colour, stored as HSB so hue survives a trip to black. */
     color: HsbColor;
-    /** The colour serialised in the current `format`; what `value`/`onValueChange` speak. */
+    /** @internal The colour serialised in the current `format`. */
     value: string;
     format: ColorFormat;
     alpha: boolean;
     step: number;
     disabled: boolean;
     readOnly: boolean;
-    /** `!disabled && !readOnly` — the single condition every part gates input on. */
+    /** @internal `!disabled && !readOnly`. */
     interactive: boolean;
-    /** Human-readable description of a colour, used both as `aria-valuetext` and as the body of a live announcement. */
+    /** @internal Human-readable description of a colour, used as `aria-valuetext` and live-announcement text. */
     describe: (color: HsbColor) => string;
-    /** Applies a new colour. `announce` is for controls whose own role does not already speak the result — see `ColorPicker.md`. */
+    /** @internal Applies a new colour; `announce` is for controls whose own role doesn't already speak the result. */
     setColor: (next: HsbColor, options?: {
-        announce?: boolean;
+        announce?: boolean | undefined;
     }) => void;
-    /** Fires `onValueCommit` with the value as it currently stands. Called once at the end of a drag. */
+    /** @internal Fires `onValueCommit` with the value as it currently stands. */
     commit: () => void;
     setFormat: (format: ColorFormat) => void;
 }
@@ -29,124 +29,127 @@ export type ColorChannel = 'hex' | 'red' | 'green' | 'blue' | 'hue' | 'saturatio
 /** 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.
+     * Composed parts for full control over anatomy, replacing the derived area, tracks, input, and swatches.
+     * @default undefined — the picker derives its anatomy.
+     */
+    children?: React.ReactNode | undefined;
+    /**
+     * Current colour for controlled usage, in any {@link parseColor} notation. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own colour internally.
      */
-    value?: string;
+    value?: string | undefined;
     /**
      * 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;
+    defaultValue?: string | undefined;
     /**
-     * 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`.
+     * Fires with the new string on every change: arrow keys, drag frames, swatch clicks, and format switches.
      * @default undefined — no-op if omitted.
      */
-    onValueCommit?: (value: string) => void;
+    onValueChange?: ((value: string) => void) | undefined;
     /**
-     * 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.
+     * Fires once with the final string when a pointer drag ends; keyboard and click changes don't fire it.
      * @default undefined — no-op if omitted.
      */
-    onValueChangeEnd?: (value: string) => void;
+    onValueCommit?: ((value: string) => void) | undefined;
     /**
-     * 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.
+     * Notation `value` is written in, for controlled usage. Pair with `onFormatChange`.
      * @default undefined — uncontrolled, tracks its own format internally.
      */
-    format?: ColorFormat;
+    format?: ColorFormat | undefined;
     /**
      * The notation the picker starts in when it is left uncontrolled.
      * @default 'hex' — the notation people paste, type and recognise.
      */
-    defaultFormat?: ColorFormat;
+    defaultFormat?: ColorFormat | undefined;
     /**
-     * Fires with the new notation whenever it changes. `onValueChange` fires
-     * alongside it with the re-spelled string.
+     * Fires with the new notation whenever it changes, alongside `onValueChange` with the re-spelled string.
      * @default undefined — no-op if omitted.
      */
-    onFormatChange?: (format: ColorFormat) => void;
+    onFormatChange?: ((format: ColorFormat) => void) | undefined;
     /**
-     * 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.
+     * Whether the picker has an alpha channel; when `false`, `ColorPickerAlphaSlider` renders nothing.
      * @default true
      */
-    alpha?: boolean;
+    alpha?: boolean | undefined;
     /**
-     * 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.
+     * Keyboard increment in channel units: percent for saturation/brightness/alpha, degrees for hue.
      * @default 1 — every whole unit is reachable without a pointer.
      */
-    step?: number;
+    step?: number | undefined;
     /**
-     * Blocks pointer and keyboard interaction across every part, and takes the
-     * focusable parts out of the tab order.
+     * Blocks pointer and keyboard interaction and takes every focusable part out of the tab order.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
-     * 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.
+     * Displays the colour but blocks changes, while every part stays focusable and in the tab order.
      * @default false
      */
-    readOnly?: boolean;
+    readOnly?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerInput}. Ignored when `children` is given.
+     * @default true
+     */
+    showInput?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerSwatchGroup}. Ignored when `children`
+     * is given or `swatches` is empty.
+     * @default true
+     */
+    showSwatches?: boolean | undefined;
+    /**
+     * Whether to render a {@link ColorPickerEyeDropper} trigger.
+     * Ignored when `children` is given.
+     * @default true
+     */
+    showEyeDropper?: boolean | undefined;
+    /**
+     * Preset colours the derived anatomy renders as {@link ColorPickerSwatch}
+     * parts, one per entry. Ignored when `children` is given or `showSwatches` is `false`.
+     * @default [] — no swatches rendered.
+     */
+    swatches?: string[] | undefined;
+    /**
+     * Stretches the control across its container width, mirrored as a bare `data-full-width`.
+     * @default undefined — the control sizes to its content.
+     */
+    fullWidth?: boolean | undefined;
+    /**
+     * Size rung the skin scales the picker by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
 /** 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.
- */
+/** Props for the {@link ColorPickerAreaThumb}, the handle on the 2D surface. No `asChild`: it renders two `role="slider"` axes as its own children. */
 export interface ColorPickerAreaThumbProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /**
-     * Accessible name of the horizontal axis, which is a `role="slider"` of its own.
+     * Accessible name of the horizontal saturation slider.
      * @default 'Saturation'
      */
-    saturationLabel?: string;
+    saturationLabel?: string | undefined;
     /**
-     * Accessible name of the vertical axis, which is a second `role="slider"`.
+     * Accessible name of the vertical brightness slider.
      * @default 'Brightness'
      */
-    brightnessLabel?: string;
+    brightnessLabel?: string | undefined;
 }
 /** 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`.
+     * Accessible name for the hue slider control.
+     * @default 'Hue'
+     */
+    label?: string | undefined;
+    /**
+     * Axis the track runs along; vertical tracks run bottom-to-top.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
 }
 /** Props for the {@link ColorPickerHueSliderThumb}, the handle on the hue track. */
 export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'div'> {
@@ -154,12 +157,15 @@ export interface ColorPickerHueSliderThumbProps extends PrimitivePropsWithRef<'d
 /** 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`.
+     * Accessible name for the opacity slider control.
+     * @default 'Opacity'
+     */
+    label?: string | undefined;
+    /**
+     * Axis the track runs along; vertical tracks run bottom-to-top.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
 }
 /** Props for the {@link ColorPickerAlphaSliderThumb}, the handle on the alpha track. */
 export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<'div'> {
@@ -167,44 +173,41 @@ export interface ColorPickerAlphaSliderThumbProps extends PrimitivePropsWithRef<
 /** 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.
+     * Whether arrow-key navigation wraps from the last swatch to the first.
      * @default true
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
 }
 /** 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.
+     * The colour this swatch selects. Unparseable values render disabled; valid
+     * colours are accepted in any {@link parseColor} notation.
      */
     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.
+     * Which single channel this input edits. Omit to carry the whole colour
+     * in the picker's current `format`; it re-spells itself on format changes.
      * @default undefined — the whole colour, in the current format.
      */
-    channel?: ColorChannel;
+    channel?: ColorChannel | undefined;
 }
 /** 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.
+     * Which notations to offer, in display order.
      * @default ['hex', 'rgb', 'hsl', 'hsb'] — every format the picker can emit.
      */
-    formats?: ColorFormat[];
+    formats?: ColorFormat[] | undefined;
     /**
-     * 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.
+     * Replaces the generated `<option>` list for custom labels or grouping.
+     * `value` attributes must still be {@link ColorFormat} strings.
      * @default undefined — one `<option>` per entry in `formats`.
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 }
 /** Props for the {@link ColorPickerEyeDropper} trigger. */
 export interface ColorPickerEyeDropperProps extends PrimitivePropsWithRef<'button'> {