haze-ui 1.32.0 → 1.34.0

package/dist/types/components/Chart/Chart.d.ts

@@ -1,27 +1,54 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-import type { ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType } from './chart-elements';
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+import type { ReferenceAreaProps, ReferenceDotProps, ReferenceLineProps } from 'recharts';
+import type { ChartGaugeThreshold, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, ChartWaffleSeries } from './chart-elements.js';
+/**
+ * Semantic slot classes (AntD v6 `classNames` shape) for Chart: the
+ * `wrapper` slot lands on the fixed-height root `<div>`; `tooltip` and
+ * `legend` land on the recharts Tooltip/Legend wrappers (and the
+ * waffle chart's built-in legend row). Slots for parts a chart does
+ * not render are ignored — `gauge` has neither tooltip nor legend, and
+ * `tooltip`/`legend` need `showTooltip`/`showLegend` on.
+ */
+type ChartClassNames = {
+    /** The fixed-height root wrapper (`data-slot='chart'`). */
+    wrapper?: string;
+    /** The recharts tooltip wrapper — only rendered while `showTooltip`
+     *  is on (never by `gauge`/`waffle`). */
+    tooltip?: string;
+    /** The legend row — the container Chart renders around the default
+     *  recharts legend while `showLegend` is on (recharts v3's own
+     *  wrapper takes no consumer class), or the waffle chart's built-in
+     *  legend (always rendered). */
+    legend?: string;
+};
 type ChartProps<T> = {
-    /** Which recharts chart family to render. `pie` maps each datum to one
+    /** Which chart family to render. `pie` maps each datum to one
      * sector named by `xKey` and valued by each series `key`; `radar` maps
      * each datum to one spoke named by `xKey`; `scatter` plots the numeric
-     * `xKey` column against each series `key`. In the cartesian families
+     * `xKey` column against each series `key`; `gauge` reads a single
+     * `value` against `max` on a semicircle arc; `waffle` renders the
+     * series shares as a square CSS grid. In the cartesian families
      * the chart `type` picks the container and the default series shape —
      * override the shape per series via `ChartSeries.type`. */
     type: ChartType;
     /** One datum per point (pie: per sector; radar: per spoke); series
-     * values are read by `ChartSeries.key`. */
-    data: T[];
+     * values are read by `ChartSeries.key`. Omitted by `gauge` (driven by
+     * `value`) and `waffle` (driven by its inline `series` values). */
+    data?: T[];
     /** The series to plot — colors cycle through the semantic status tokens
      * when `color` is omitted. With `type='pie'` each series is one
      * concentric ring. In cartesian charts (line/area/bar) a per-series
      * `type` overrides that series' shape for composed charts (bars under a
      * line, a line over areas), and series sharing a `stackId` stack
-     * (Area/Bar shapes). Both are ignored by pie/radar/scatter. */
-    series: ChartSeries[];
+     * (Area/Bar shapes). Both are ignored by pie/radar/scatter. With
+     * `type='waffle'` each entry is one share of the grid: `name` feeds the
+     * legend, `value` is the square count, `color` any CSS color. Omitted
+     * by `gauge`, which reads a single `value` instead. */
+    series?: ChartSeries[] | ChartWaffleSeries[];
     /** Datum field driving the X axis — the cartesian categories, the pie
      * sector names, the radar spoke names, or the numeric scatter X
-     * column. */
-    xKey: keyof T & string;
+     * column. Ignored by `gauge` and `waffle`. */
+    xKey?: keyof T & string;
     /** Container height in px; the chart stretches to the full width. */
     height?: number;
     /** Pie only: inner radius in px (or a % string) — above 0 renders a
@@ -31,6 +58,36 @@ type ChartProps<T> = {
     /** Cartesian charts only: `vertical` swaps the axes for horizontal
      * bars/lines (ignored by `pie`). Default `'horizontal'`. */
     layout?: 'horizontal' | 'vertical';
+    /** Cartesian charts only (line/area/bar/scatter): recharts reference
+     * lines rendered under the series — one per entry, its props
+     * (x/y/segment, stroke, strokeDasharray, label, …) spread through
+     * verbatim. Ignored by pie/radar/gauge/waffle. */
+    referenceLines?: ReferenceLineProps[];
+    /** Cartesian charts only: recharts reference areas (band highlights),
+     * props spread through verbatim (x1/x2/y1/y2, fill, fillOpacity…).
+     * Ignored by pie/radar/gauge/waffle. */
+    referenceAreas?: ReferenceAreaProps[];
+    /** Cartesian charts only: recharts reference dots (point markers),
+     * props spread through verbatim (x/y, r, fill, label…). Ignored by
+     * pie/radar/gauge/waffle. */
+    referenceDots?: ReferenceDotProps[];
+    /** Gauge only: the reading plotted on the arc, clamped to [0, max]. */
+    value?: number;
+    /** Gauge only: the arc's full-scale value. Default `100`. */
+    max?: number;
+    /** Gauge only: colored arc segments — each threshold paints the band
+     * from the previous one (or 0) up to its `value` in its `color` at
+     * reduced opacity, and the value arc takes the color of the band it
+     * falls in (thresholds expected ascending; a value beyond the last
+     * bound falls back to the primary token). */
+    thresholds?: ChartGaugeThreshold[];
+    /** Gauge only: caption under the center readout (e.g. "of quota"). */
+    label?: ReactNode;
+    /** Gauge only: formats the center readout — default prints the raw
+     * number. */
+    valueFormat?: (v: number) => string;
+    /** Waffle only: squares per grid row. Default `10`. */
+    columns?: number;
     /** Replaces the default recharts tooltip. Receives the hovered label
      * (X value / sector name) plus one entry per series or sector. */
     renderTooltip?: (payload: ChartTooltipPayload<T>) => ReactNode;
@@ -41,14 +98,50 @@ type ChartProps<T> = {
     showGrid?: boolean;
     /** Renders a hover tooltip. Default `true`. */
     showTooltip?: boolean;
+    /** Renders the screen-reader fallback table alongside the graphic —
+     * a visually-hidden `<table>` mirroring the plotted data (caption names
+     * the chart type and series, headers the `xKey` plus one column per
+     * series label). Chart graphics expose nothing but their `aria-label`
+     * to assistive tech, so the table is the data channel; keep it on
+     * unless the surrounding page already tabulates the same data. Skipped
+     * while `loading` or the `empty` state is showing. Default `true`. */
+    fallbackTable?: boolean;
+    /** Loading state, replacing the chart (and the fallback table): `true`
+     * renders the default centered Spinner, any other node your own
+     * placeholder. Takes precedence over `empty`. */
+    loading?: ReactNode;
+    /** Empty state shown when `data` is an empty array: `true` (or omitted)
+     * renders the default Empty component, any other node your own
+     * placeholder; `false` opts out and renders the (blank) chart. The
+     * fallback table is skipped in this state. */
+    empty?: ReactNode;
+    /**
+     * Semantic slot classes (AntD v6 `classNames` shape): keyed by
+     * structural part (see {@link ChartClassNames}). Slot classes are
+     * appended at the end of each part's class list. Not passing it
+     * renders identical output.
+     */
+    classNames?: ChartClassNames;
+    /** Forwarded to the fixed-height root wrapper `<div>`
+     *  (`data-slot='chart'`). */
+    ref?: Ref<HTMLDivElement>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-/** Token-driven chart over recharts: line, area, bar, pie, radar or
- * scatter series rendered with haze semantic colors, axis/grid/tooltip/legend chrome
- * toggles, and the default-omittable `series`/`xKey` mapping. Cartesian
+/** Token-driven chart component: line, area, bar, pie, radar or
+ * scatter series rendered with haze semantic colors over recharts,
+ * axis/grid/tooltip/legend chrome toggles, recharts reference annotations
+ * (lines/areas/dots) on the cartesian families, and the
+ * default-omittable `series`/`xKey` mapping. `gauge` reads one `value`
+ * against `max` on a semicircle arc with threshold bands and a center
+ * readout; `waffle` renders series shares as a square CSS grid with a
+ * built-in legend (no recharts). Cartesian
  * charts double as composed charts — a per-series `type` mixes line/area/bar
  * shapes inside one chart, and `stackId` stacks the Area/Bar series sharing
- * an id. recharts is a haze-ui dependency — this module's helpers import it
- * statically, so under preserveModules only bundles that actually render
- * Chart include the dependency. */
-export default function Chart<T>({ type, data, series, xKey, height, innerRadius, layout, renderTooltip, showLegend, showGrid, showTooltip, className, style, ...rest }: ChartProps<T>): import("react").JSX.Element;
-export type { ChartProps, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, };
+ * an id. Accessibility: the graphic is a named `role='img'` (type + series,
+ * overridable via `aria-label`) with a screen-reader-only fallback table
+ * mirroring the data as its sibling; `loading`/`empty` states replace the
+ * plot (Spinner/Empty defaults, node overrides) without disturbing the
+ * fixed-height footprint. recharts is a haze-ui dependency — this module's
+ * helpers import it statically, so under preserveModules only bundles that
+ * actually render Chart include the dependency. */
+export default function Chart<T>({ type, data, series, xKey, height, innerRadius, layout, referenceLines, referenceAreas, referenceDots, value, max, thresholds, label, valueFormat, columns, renderTooltip, showLegend, showGrid, showTooltip, fallbackTable, loading, empty, classNames, 'aria-label': ariaLabel, className, style, ref, ...rest }: ChartProps<T>): import("react").JSX.Element;
+export type { ChartProps, ChartClassNames, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, ChartGaugeThreshold, ChartWaffleSeries, };

package/dist/types/components/Chart/chart-elements.d.ts

@@ -1,4 +1,5 @@
 import type { ReactElement, ReactNode } from 'react';
+import type { ReferenceAreaProps, ReferenceDotProps, ReferenceLineProps } from 'recharts';
 /** One plotted series: `key` picks the datum field to plot, `label` names
  * the series in the legend and tooltip (defaults to `key`), and `color`
  * opts out of the semantic token cycle. */
@@ -39,9 +40,31 @@ export type CartesianChartType = 'line' | 'area' | 'bar';
 export type SeriesChartType = CartesianChartType | 'radar' | 'scatter';
 /** Supported chart shapes — the cartesian families plus `pie` (each datum
  * is one sector named by the chart's `xKey`), `radar` (each datum is one
- * spoke named by `xKey`) and `scatter` (numeric `xKey` vs each series
- * `key`). */
-export type ChartType = CartesianChartType | 'radar' | 'scatter' | 'pie';
+ * spoke named by `xKey`), `scatter` (numeric `xKey` vs each series
+ * `key`), `gauge` (a semicircle RadialBar reading one `value` against
+ * `max`) and `waffle` (a CSS-native square grid, no recharts). */
+export type ChartType = CartesianChartType | 'radar' | 'scatter' | 'pie' | 'gauge' | 'waffle';
+/** Chart shapes dispatched through `chartElement`/`chartTree` — everything
+ * except `gauge` (which builds its own RadialBarChart tree via
+ * `gaugeTree`) and `waffle` (pure CSS via `waffleTree`). */
+export type RechartsChartType = Exclude<ChartType, 'gauge' | 'waffle'>;
+/** One colored band on a gauge arc: the band spans from the previous
+ * threshold (or 0) up to `value`, painted in `color`. */
+export type ChartGaugeThreshold = {
+    /** Upper bound of the band, in the same units as the gauge `value`. */
+    value: number;
+    /** The band's color — any CSS color string (tokens welcome). */
+    color: string;
+};
+/** One waffle series: `value` squares of the grid are painted in `color`
+ * (cycling the semantic tokens when omitted), `name` feeds the legend. */
+export type ChartWaffleSeries = {
+    name: string;
+    /** Square count for this series — one grid square per unit. */
+    value: number;
+    /** Any CSS color string (token reference or literal). */
+    color?: string;
+};
 /** One hovered entry as handed to Chart's `renderTooltip` slot. */
 export type ChartTooltipEntry<T = unknown> = {
     /** Series label (cartesian) or sector name (pie). */
@@ -112,15 +135,13 @@ export declare function pieElement(options: {
  * AreaChart, bar → BarChart, pie → PieChart, radar → RadarChart, scatter
  * → ScatterChart) plotting `data` with the given series children; cartesian
  * containers carry `layout`. */
-export declare function chartElement(type: ChartType, data: readonly unknown[], children: ReactNode, layout?: 'horizontal' | 'vertical'): ReactElement;
+export declare function chartElement(type: RechartsChartType, data: readonly unknown[], children: ReactNode, layout?: 'horizontal' | 'vertical'): ReactElement;
 /** Wraps a `renderTooltip` slot into a recharts Tooltip `content`
  * function, mapping recharts' payload items onto ChartTooltipEntry
  * (name falling back to the dataKey, missing colors to ''). */
 export declare function buildTooltipContent(render: (payload: ChartTooltipPayload) => ReactNode): (props: unknown) => ReactNode;
-/** The full token-styled chart tree Chart renders — kept beside the pure
- * helpers so the component module stays a single component export. */
 export declare function chartTree(options: {
-    type: ChartType;
+    type: RechartsChartType;
     data: readonly unknown[];
     xKey: string;
     showGrid: boolean;
@@ -130,4 +151,49 @@ export declare function chartTree(options: {
     layout?: 'horizontal' | 'vertical';
     innerRadius?: number | string;
     renderTooltip?: (payload: ChartTooltipPayload) => ReactNode;
+    referenceLines?: readonly ReferenceLineProps[];
+    referenceAreas?: readonly ReferenceAreaProps[];
+    referenceDots?: readonly ReferenceDotProps[];
+    /** Consumer class for the recharts Tooltip wrapper (the Chart
+     *  `classNames.tooltip` slot). */
+    tooltipClassName?: string;
+    /** Consumer class for the container around the default recharts
+     *  legend (the Chart `classNames.legend` slot). */
+    legendClassName?: string;
+}): ReactElement;
+/** The muted surface shared by the gauge's track arc and the waffle's
+ * remainder squares — the same muted background Progress uses for its
+ * track. */
+export declare const CHART_MUTED_COLOR = "var(--haze-color-bg-muted)";
+/** The semicircle gauge tree — a RadialBarChart whose PolarAngleAxis maps
+ * [0, max] onto the 180°–0° top half. RadialBar items share the chart's
+ * single datum but each reads its own `dataKey` field holding a
+ * `[from, to]` tuple that the angle axis maps onto an arc span — with one
+ * datum the radius band is never subdivided, so every arc paints the same
+ * ring: the muted track first, one reduced-opacity arc per threshold
+ * band, and the opaque value arc last (topmost). The center readout
+ * overlays the bowl's empty lower half. */
+export declare function gaugeTree(options: {
+    value: number;
+    max: number;
+    thresholds?: readonly ChartGaugeThreshold[];
+    formattedValue: string;
+    label?: ReactNode;
+}): ReactElement;
+/** The color of every grid square in draw order: one square per value unit
+ * (series colors cycle the semantic tokens when omitted), then muted
+ * remainder squares padding the grid up to a whole number of `columns`
+ * rows. Colored squares are truncated should rounding ever overshoot the
+ * row padding, keeping the grid at `ceil(total/columns) × columns`. */
+export declare function waffleCellColors(series: readonly ChartWaffleSeries[], columns?: number): string[];
+/** The CSS-native waffle tree — a square-grid alternative to the pie for
+ * part-to-whole shares, with one square per value unit, muted padding up
+ * to whole rows, and a built-in legend. No recharts involved, so the
+ * module stays out of gauge/waffle-only bundles' critical path. */
+export declare function waffleTree(options: {
+    series: readonly ChartWaffleSeries[];
+    columns?: number;
+    /** Consumer class for the built-in legend row (the Chart
+     *  `classNames.legend` slot). */
+    legendClassName?: string;
 }): ReactElement;

package/dist/types/components/Chart/index.d.ts

@@ -1,2 +1,2 @@
-export { default as Chart } from './Chart';
-export type { ChartProps, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, } from './Chart';
+export { default as Chart } from './Chart.js';
+export type { ChartProps, ChartClassNames, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, ChartGaugeThreshold, ChartWaffleSeries, } from './Chart.js';

package/dist/types/components/ChatContainer/index.d.ts

@@ -1,2 +1,2 @@
-export { default as ChatContainer } from './ChatContainer';
-export type { ChatContainerProps } from './ChatContainer';
+export { default as ChatContainer } from './ChatContainer.js';
+export type { ChatContainerProps } from './ChatContainer.js';

package/dist/types/components/ChatInput/index.d.ts

@@ -1,2 +1,2 @@
-export { default as ChatInput } from './ChatInput';
-export type { ChatInputProps } from './ChatInput';
+export { default as ChatInput } from './ChatInput.js';
+export type { ChatInputProps } from './ChatInput.js';

package/dist/types/components/ChatMessage/index.d.ts

@@ -1,2 +1,2 @@
-export { default as ChatMessage } from './ChatMessage';
-export type { ChatMessageProps, ChatMessageRole } from './ChatMessage';
+export { default as ChatMessage } from './ChatMessage.js';
+export type { ChatMessageProps, ChatMessageRole } from './ChatMessage.js';

package/dist/types/components/Checkbox/index.d.ts

@@ -1,4 +1,4 @@
-export { default as Checkbox } from './Checkbox';
-export type { CheckboxProps } from './Checkbox';
-export { default as CheckboxCore } from './CheckboxCore';
-export type { CheckboxCoreProps } from './CheckboxCore';
+export { default as Checkbox } from './Checkbox.js';
+export type { CheckboxProps } from './Checkbox.js';
+export { default as CheckboxCore } from './CheckboxCore.js';
+export type { CheckboxCoreProps } from './CheckboxCore.js';

package/dist/types/components/Chip/Chip.d.ts

@@ -1,11 +1,20 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
 type ChipProps = {
     variant?: 'solid' | 'outline';
-    color?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
+    /** Semantic status color. */
+    color?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
     icon?: ReactNode;
     onClose?: () => void;
+    /**
+     * Accessible label for the remove button. Inlined default keeps Chip
+     * hook-free (RSC-safe: no useStrings); locale-aware callers pass
+     * their own string.
+     */
+    removeLabel?: string;
     className?: string;
     children: ReactNode;
+    /** Forwarded to the root span (data-slot='chip'). */
+    ref?: Ref<HTMLSpanElement>;
 };
-export default function Chip({ variant, color, icon, onClose, className, children, }: ChipProps): import("react").JSX.Element;
+export default function Chip({ variant, color, icon, onClose, removeLabel, className, children, ref, }: ChipProps): import("react").JSX.Element;
 export type { ChipProps };

package/dist/types/components/Chip/chip-styles.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared Chip skin — the base, color and close-button classes the
+ * `Chip` component wears. Living in their own module keeps the
+ * component file free of style internals (react-refresh boundary) and
+ * lets the per-variant color maps ship as a public constant
+ * (`chipVariants`, the shadcn `buttonVariants` precedent) for
+ * consumers composing custom elements with the same skin; split-css
+ * groups the emitted CSS into `haze-ui/css/chip.css` with them.
+ */
+export declare const base: import("@linaria/core").LinariaClassName;
+export declare const solidColors: {
+    readonly default: import("@linaria/core").LinariaClassName;
+    readonly primary: import("@linaria/core").LinariaClassName;
+    readonly success: import("@linaria/core").LinariaClassName;
+    readonly warning: import("@linaria/core").LinariaClassName;
+    readonly danger: import("@linaria/core").LinariaClassName;
+    readonly info: import("@linaria/core").LinariaClassName;
+};
+export declare const outlineColors: {
+    readonly default: import("@linaria/core").LinariaClassName;
+    readonly primary: import("@linaria/core").LinariaClassName;
+    readonly success: import("@linaria/core").LinariaClassName;
+    readonly warning: import("@linaria/core").LinariaClassName;
+    readonly danger: import("@linaria/core").LinariaClassName;
+    readonly info: import("@linaria/core").LinariaClassName;
+};
+/**
+ * The full variant × color skin matrix in the `ChipProps` shape —
+ * `chipVariants.solid.primary` is the class a solid primary chip wears
+ * (the same lookup the component itself performs).
+ */
+export declare const chipVariants: {
+    readonly solid: {
+        readonly default: import("@linaria/core").LinariaClassName;
+        readonly primary: import("@linaria/core").LinariaClassName;
+        readonly success: import("@linaria/core").LinariaClassName;
+        readonly warning: import("@linaria/core").LinariaClassName;
+        readonly danger: import("@linaria/core").LinariaClassName;
+        readonly info: import("@linaria/core").LinariaClassName;
+    };
+    readonly outline: {
+        readonly default: import("@linaria/core").LinariaClassName;
+        readonly primary: import("@linaria/core").LinariaClassName;
+        readonly success: import("@linaria/core").LinariaClassName;
+        readonly warning: import("@linaria/core").LinariaClassName;
+        readonly danger: import("@linaria/core").LinariaClassName;
+        readonly info: import("@linaria/core").LinariaClassName;
+    };
+};
+export declare const iconStyle: import("@linaria/core").LinariaClassName;
+export declare const closeBtn: import("@linaria/core").LinariaClassName;

package/dist/types/components/Chip/index.d.ts

@@ -1,2 +1,3 @@
-export { default as Chip } from './Chip';
-export type { ChipProps } from './Chip';
+export { default as Chip } from './Chip.js';
+export type { ChipProps } from './Chip.js';
+export { chipVariants } from './chip-styles.js';

package/dist/types/components/CodeBlock/index.d.ts

@@ -1,2 +1,2 @@
-export { default as CodeBlock } from './CodeBlock';
-export type { CodeBlockProps, Highlighter } from './CodeBlock';
+export { default as CodeBlock } from './CodeBlock.js';
+export type { CodeBlockProps, Highlighter } from './CodeBlock.js';

package/dist/types/components/Collapsible/index.d.ts

@@ -1,2 +1,2 @@
-export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './Collapsible';
-export type { CollapsibleProps, CollapsibleTriggerProps, CollapsibleContentProps, CollapsibleClassNames } from './Collapsible';
+export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './Collapsible.js';
+export type { CollapsibleProps, CollapsibleTriggerProps, CollapsibleContentProps, CollapsibleClassNames } from './Collapsible.js';

package/dist/types/components/ColorPicker/ColorPicker.d.ts

@@ -1,6 +1,7 @@
 import type { Ref } from 'react';
 import type { ControlOrValue } from 'react-use-control';
-import type { ColorFormat } from './color-math';
+import type { ColorFormat } from './color-math.js';
+import type { ColorPickerPreset } from './gradient.js';
 type ColorPickerProps = {
     /** Color value in any supported format (hex / rgb / hsl). */
     value?: ControlOrValue<string>;
@@ -29,15 +30,47 @@ type ColorPickerProps = {
      * the opaque form.
      */
     allowAlpha?: boolean;
-    /** Swatch row pinned above the recent row; any parsable format. */
-    presets?: string[];
+    /**
+     * Preset swatches: plain color strings (the original flat shape) or
+     * structured entries — labeled solid groups `{ label?, colors }` and
+     * single gradients `{ label?, gradient }` rendered as preview bars
+     * of the actual gradient. Clicking any entry applies it (gradient
+     * entries emit their canonical `linear-gradient()` string).
+     */
+    presets?: ColorPickerPreset[];
     /**
      * Tracks recently used colors (last 10, newest first) as internal
      * state: every committed pick — drag release, swatch click, arrow
      * key, text commit — moves its color to the front, deduplicated.
+     * Gradient values are not colors and never enter the list.
      */
     recent?: boolean;
+    /**
+     * Enables gradient editing: the panel gains a Solid/Gradient toggle
+     * and, while the value is a `linear-gradient()` string, an angle
+     * field plus a stop list (add/remove stops, per-stop color through
+     * the SV/hue rails and the text field, position 0..100). The mode is
+     * value-derived, and switching modes applies the default of the
+     * target mode rather than remembering the departed mode's value:
+     * solid → gradient opens the current color into
+     * `linear-gradient(90deg, <color> 0%, #ffffff 100%)`; gradient →
+     * solid takes the first stop's color. Gradient values still paint
+     * the trigger and submit through `name` when this prop is off — only
+     * the editor is gated.
+     */
+    gradient?: boolean;
     className?: string;
+    /**
+     * Form field name: renders a hidden input bridge next to the control
+     * so `<form action={fn}>` / `new FormData(form)` receive the value —
+     * serialized in `format` exactly like the panel's text field and
+     * `onChange` emissions (`formatColor(parseColor(value), format,
+     * allowAlpha)`), or the canonical gradient string when the value is
+     * a gradient, so what submits always matches what the picker
+     * shows. react-f0rm `FormItem` usage never passes it, so both worlds
+     * coexist.
+     */
+    name?: string;
     /**
      * Accessible name of the trigger (floating mode) and the panel;
      * defaults to the locale's "Pick color". Set it whenever more than
@@ -50,5 +83,5 @@ type ColorPickerProps = {
      */
     ref?: Ref<HTMLButtonElement | HTMLDivElement>;
 };
-export default function ColorPicker({ value: valueControl, onChange, open: openControl, inline, format, allowAlpha, presets, recent, className, 'aria-label': ariaLabel, ref, }: ColorPickerProps): import("react").JSX.Element;
+export default function ColorPicker({ value: valueControl, onChange, open: openControl, inline, format, allowAlpha, presets, recent, gradient, className, name, 'aria-label': ariaLabel, ref, }: ColorPickerProps): import("react").JSX.Element;
 export type { ColorPickerProps };

package/dist/types/components/ColorPicker/ColorPickerPanel.d.ts

@@ -1,28 +1,47 @@
-import type { ColorFormat } from './color-math';
+import type { ColorFormat } from './color-math.js';
+import type { ColorPickerPreset } from './gradient.js';
 type ColorPickerPanelProps = {
     /** Current color in any supported format; unparsable values fall back to black. */
     value: string;
     /**
      * Continuous value callback — fires for every drag move (Slider
      * precedent: values stream while the gesture runs), always serialized
-     * in `format`.
+     * in `format` (solid) or as a canonical gradient (gradient mode).
      */
     onChange: (value: string) => void;
     /**
-     * "The user settled on this color": gesture release, discrete pick
-     * (preset/recent swatch, arrow keys) or committed text. The
-     * recent-colors bookkeeping in the sugar layer rides on this.
+     * "The user settled on this value": gesture release, discrete pick
+     * (preset/recent swatch, arrow keys, mode switch, stop edit) or
+     * committed text. The recent-colors bookkeeping in the sugar layer
+     * rides on this.
      */
     onCommit?: (value: string) => void;
-    /** Serialization format of the text field and every emitted value. */
+    /** Serialization format of the text field and every emitted solid value. */
     format?: ColorFormat;
     /** Adds the alpha rail; alpha serializes into the value when below 1. */
     allowAlpha?: boolean;
-    /** Swatch row pinned above the recent row; any parsable format. */
-    presets?: string[];
+    /**
+     * Preset entries: plain color strings (the original flat-list shape,
+     * rendered under one "Presets" heading), labeled solid groups
+     * (`{ label, colors }`) and single gradients (`{ label, gradient }`,
+     * rendered as a preview bar of the actual gradient). Clicking a solid
+     * entry always emits a solid color; clicking a gradient entry emits
+     * its canonical gradient — either one flips the editing mode.
+     */
+    presets?: ColorPickerPreset[];
     /** Recent-color swatches to render (owned by the sugar layer). */
     recentColors?: string[];
+    /**
+     * Adds the Solid/Gradient mode toggle and, while the value is a
+     * gradient, the gradient editor (angle, stop list). The mode is
+     * derived from the value — a parsable `linear-gradient()` string IS
+     * gradient mode — so switching modes is a plain value emission:
+     * entering gradient mode opens the current color into a two-stop
+     * `90deg` run to white, returning to solid takes the first stop's
+     * color. No per-mode value memory.
+     */
+    gradient?: boolean;
     className?: string;
 };
-export default function ColorPickerPanel({ value, onChange, onCommit, format, allowAlpha, presets, recentColors, className, }: ColorPickerPanelProps): import("react").JSX.Element;
+export default function ColorPickerPanel({ value, onChange, onCommit, format, allowAlpha, presets, recentColors, gradient, className, }: ColorPickerPanelProps): import("react").JSX.Element;
 export type { ColorPickerPanelProps };

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

@@ -46,5 +46,32 @@ export declare const swatchRow: import("@linaria/core").LinariaClassName;
 export declare const swatchBtn: import("@linaria/core").LinariaClassName;
 export declare const swatchFill: import("@linaria/core").LinariaClassName;
 export declare const swatchActive: import("@linaria/core").LinariaClassName;
+/** Solid/Gradient segmented toggle riding on top of the panel. */
+export declare const modeToggle: import("@linaria/core").LinariaClassName;
+/** One segment of the mode toggle; the pressed state paints it active. */
+export declare const modeBtn: import("@linaria/core").LinariaClassName;
+/** Live preview bar painted (inline style) with the current gradient. */
+export declare const gradientPreview: import("@linaria/core").LinariaClassName;
+/** Angle row: a labelled compact number input (0..360 degrees). */
+export declare const angleRow: import("@linaria/core").LinariaClassName;
+/** Compact mono number input (angle, stop positions). */
+export declare const numberInput: import("@linaria/core").LinariaClassName;
+/** Column of stop rows (one line per gradient stop). */
+export declare const stopsList: import("@linaria/core").LinariaClassName;
+/** One stop line: select swatch, position input, remove button. */
+export declare const stopRow: import("@linaria/core").LinariaClassName;
+/** The stop's select swatch — smaller than a preset, ringed when selected. */
+export declare const stopSwatchBtn: import("@linaria/core").LinariaClassName;
+/** Selected stop: the primary ring marks which stop the rails edit. */
+export declare const stopSwatchActive: import("@linaria/core").LinariaClassName;
+/** Stop remover; disabled at the two-stop floor. */
+export declare const stopRemoveBtn: import("@linaria/core").LinariaClassName;
+/** Full-width dashed "Add stop" affordance under the stop list. */
+export declare const addStopBtn: import("@linaria/core").LinariaClassName;
+/**
+ * A gradient preset entry: a full-width bar previewing the actual
+ * gradient (painted via inline style), stacked one per row.
+ */
+export declare const gradientSwatch: import("@linaria/core").LinariaClassName;
 /** The floating-mode trigger: a color swatch button. */
 export declare const trigger: import("@linaria/core").LinariaClassName;

package/dist/types/components/ColorPicker/gradient.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure linear-gradient value model for the ColorPicker family: a
+ * tolerant parser of CSS `linear-gradient()` strings, canonical
+ * serialization, and the preset-entry union the sugar layer accepts.
+ *
+ * Mirrors `color-math.ts`'s contract — byte-stable round trips through
+ * canonical forms, invalid input is `null` (never throws) so the
+ * component treats it as "not a gradient" and falls back to the solid
+ * path. Only `linear-gradient()` is the subject matter; radial/conic/
+ * repeating variants return `null`.
+ */
+import type { Rgb } from './color-math.js';
+/** One gradient stop: a canonical CSS color string and its position on the 0..100% scale. */
+export type GradientStop = {
+    color: string;
+    position: number;
+};
+/** A parsed linear gradient: angle in degrees (0..360) and 2+ stops sorted by position. */
+export type Gradient = {
+    angle: number;
+    stops: GradientStop[];
+};
+/**
+ * One `presets` entry: a plain color string (the original flat-list
+ * shape), a labeled group of solid colors, or a single gradient
+ * (rendered as a preview bar of the actual gradient).
+ */
+export type ColorPickerPreset = string | {
+    label?: string;
+    colors: string[];
+} | {
+    label?: string;
+    gradient: string;
+};
+/**
+ * Canonical form: angle modulo 360, positions clamped to 0..100, stops
+ * sorted by position (stable), and consecutive stops sharing a
+ * position AND a color collapsed — distinct colors at one position
+ * survive (the CSS hard-stop technique).
+ */
+export declare function normalizeGradient(gradient: Gradient): Gradient;
+/**
+ * Parses a CSS `linear-gradient()` string into the value model:
+ * `Ndeg` / `to`-keyword angles (default 180deg, the CSS `to bottom`),
+ * colors in any format `parseColor` accepts, positions as percentages
+ * (omitted positions follow the CSS distribution rules). Stop colors
+ * canonicalize to hex (`#rrggbb` / `#rrggbbaa`), the angle to 0..360,
+ * stops sort by position. Returns `null` for anything that is not a
+ * 2+ stop linear gradient — the solid-color path handles those.
+ */
+export declare function parseGradient(input: string): Gradient | null;
+/**
+ * Serializes to the canonical CSS string —
+ * `linear-gradient(90deg, #667eea 0%, #764ba2 100%)`. The input is
+ * normalized first (clamped, sorted, deduplicated), so the output of a
+ * round trip is byte-identical.
+ */
+export declare function serializeGradient(gradient: Gradient): string;
+/**
+ * The gradient a solid color opens into when the mode toggles: a
+ * 90deg two-stop run from the color to white (functional color values
+ * — the component's subject matter, like the hue spectrum).
+ */
+export declare function gradientFromColor(rgb: Rgb): Gradient;

package/dist/types/components/ColorPicker/index.d.ts

@@ -1,4 +1,5 @@
-export { default as ColorPicker } from './ColorPicker';
-export type { ColorPickerProps } from './ColorPicker';
-export { default as ColorPickerCore } from './ColorPickerCore';
-export type { ColorPickerCoreProps } from './ColorPickerCore';
+export { default as ColorPicker } from './ColorPicker.js';
+export type { ColorPickerProps } from './ColorPicker.js';
+export type { ColorPickerPreset } from './gradient.js';
+export { default as ColorPickerCore } from './ColorPickerCore.js';
+export type { ColorPickerCoreProps } from './ColorPickerCore.js';