@zag-js/color-picker 1.43.0 → 2.0.0-next.1

package/dist/color-picker.machine.js

@@ -41,6 +41,7 @@ var import_popper = require("@zag-js/popper");
 var import_utils = require("@zag-js/utils");
 var dom = __toESM(require("./color-picker.dom.js"));
 var import_color_picker = require("./color-picker.parse.js");
+var import_get_area_format = require("./utils/get-area-format.js");
 var import_get_channel_input_value = require("./utils/get-channel-input-value.js");
 var import_is_valid_hex = require("./utils/is-valid-hex.js");
 var { and } = (0, import_core.createGuards)();
@@ -71,6 +72,9 @@ var machine = (0, import_core.createMachine)({
   },
   context({ prop, bindable, getContext }) {
     return {
+      layer: bindable(() => ({
+        defaultValue: null
+      })),
       value: bindable(() => ({
         defaultValue: prop("defaultValue").toFormat(prop("format") ?? prop("defaultFormat")),
         value: prop("value")?.toFormat(prop("format") ?? prop("defaultFormat")),
@@ -96,6 +100,8 @@ var machine = (0, import_core.createMachine)({
       activeId: bindable(() => ({ defaultValue: null })),
       activeChannel: bindable(() => ({ defaultValue: null })),
       activeOrientation: bindable(() => ({ defaultValue: null })),
+      areaBaseColor: bindable(() => ({ defaultValue: null })),
+      areaDragPosition: bindable(() => ({ defaultValue: null })),
       fieldsetDisabled: bindable(() => ({ defaultValue: false })),
       restoreFocus: bindable(() => ({ defaultValue: true })),
       currentPlacement: bindable(() => ({
@@ -109,8 +115,7 @@ var machine = (0, import_core.createMachine)({
     interactive: ({ prop }) => !(prop("disabled") || prop("readOnly")),
     valueAsString: ({ context }) => context.get("value").toString(context.get("format")),
     areaValue: ({ context }) => {
-      const format = context.get("format").startsWith("hsl") ? "hsla" : "hsba";
-      return context.get("value").toFormat(format);
+      return context.get("value").toFormat((0, import_get_area_format.getAreaFormat)(context.get("format")));
     }
   },
   effects: ["trackFormControl"],
@@ -396,6 +401,9 @@ var machine = (0, import_core.createMachine)({
         const getContentEl2 = () => dom.getContentEl(scope);
         return (0, import_dismissable.trackDismissableElement)(getContentEl2, {
           type: "popover",
+          onLayerChange(layer) {
+            context.set("layer", layer);
+          },
           exclude: dom.getTriggerEl(scope),
           defer: true,
           onInteractOutside(event) {
@@ -458,36 +466,47 @@ var machine = (0, import_core.createMachine)({
           });
         }).catch(() => void 0);
       },
-      setActiveChannel({ context, event }) {
+      setActiveChannel({ context, event, computed }) {
         context.set("activeId", event.id);
         if (event.channel) context.set("activeChannel", event.channel);
         if (event.orientation) context.set("activeOrientation", event.orientation);
+        const areaFormat = (0, import_get_area_format.getAreaFormat)(context.get("format"));
+        if (areaFormat !== context.get("format")) {
+          context.set("areaBaseColor", computed("areaValue"));
+        }
       },
       clearActiveChannel({ context }) {
         context.set("activeChannel", null);
         context.set("activeId", null);
         context.set("activeOrientation", null);
+        context.set("areaBaseColor", null);
+        context.set("areaDragPosition", null);
       },
       setAreaColorFromPoint({ context, event, computed, scope, prop }) {
-        const v = event.format ? context.get("value").toFormat(event.format) : computed("areaValue");
+        const storeFormat = context.get("format");
+        const v = event.format ? context.get("value").toFormat(event.format) : context.get("areaBaseColor") ?? computed("areaValue");
         const { xChannel, yChannel } = event.channel || context.get("activeChannel");
         const percent = dom.getAreaValueFromPoint(scope, event.point, prop("dir"));
         if (!percent) return;
+        context.set("areaDragPosition", { x: percent.x, y: percent.y });
         const xValue = v.getChannelPercentValue(xChannel, percent.x);
         const yValue = v.getChannelPercentValue(yChannel, 1 - percent.y);
-        const color = v.withChannelValue(xChannel, xValue).withChannelValue(yChannel, yValue);
+        const color = v.withChannelValue(xChannel, xValue).withChannelValue(yChannel, yValue).toFormat(storeFormat);
         context.set("value", color);
       },
       setChannelColorFromPoint({ context, event, computed, scope, prop }) {
+        const storeFormat = context.get("format");
         const channel = event.channel || context.get("activeId");
-        const normalizedValue = event.format ? context.get("value").toFormat(event.format) : computed("areaValue");
+        const baseColor = context.get("areaBaseColor");
+        const normalizedValue = event.format ? context.get("value").toFormat(event.format) : baseColor ?? computed("areaValue");
         const percent = dom.getChannelSliderValueFromPoint(scope, event.point, channel, prop("dir"));
         if (!percent) return;
         const orientation = event.orientation || context.get("activeOrientation") || "horizontal";
         const channelPercent = orientation === "horizontal" ? percent.x : percent.y;
         const value = normalizedValue.getChannelPercentValue(channel, channelPercent);
-        const color = normalizedValue.withChannelValue(channel, value);
-        context.set("value", color);
+        const updatedBase = normalizedValue.withChannelValue(channel, value);
+        context.set("areaBaseColor", updatedBase);
+        context.set("value", updatedBase.toFormat(storeFormat));
       },
       setValue({ context, event }) {
         const format = context.get("format");
@@ -544,24 +563,32 @@ var machine = (0, import_core.createMachine)({
         const color = context.get("value").decrementChannel(event.channel, event.step);
         context.set("value", color);
       },
-      incrementAreaXChannel({ context, event, computed }) {
+      incrementAreaXChannel({ context, event }) {
         const { xChannel } = event.channel;
-        const color = computed("areaValue").incrementChannel(xChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat((0, import_get_area_format.getAreaFormat)(storeFormat));
+        const color = v.incrementChannel(xChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      decrementAreaXChannel({ context, event, computed }) {
+      decrementAreaXChannel({ context, event }) {
         const { xChannel } = event.channel;
-        const color = computed("areaValue").decrementChannel(xChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat((0, import_get_area_format.getAreaFormat)(storeFormat));
+        const color = v.decrementChannel(xChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      incrementAreaYChannel({ context, event, computed }) {
+      incrementAreaYChannel({ context, event }) {
         const { yChannel } = event.channel;
-        const color = computed("areaValue").incrementChannel(yChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat((0, import_get_area_format.getAreaFormat)(storeFormat));
+        const color = v.incrementChannel(yChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      decrementAreaYChannel({ context, event, computed }) {
+      decrementAreaYChannel({ context, event }) {
         const { yChannel } = event.channel;
-        const color = computed("areaValue").decrementChannel(yChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat((0, import_get_area_format.getAreaFormat)(storeFormat));
+        const color = v.decrementChannel(yChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
       setChannelToMax({ context, event }) {

package/dist/color-picker.machine.mjs

@@ -15,6 +15,7 @@ import { getPlacement } from "@zag-js/popper";
 import { tryCatch } from "@zag-js/utils";
 import * as dom from "./color-picker.dom.mjs";
 import { parse } from "./color-picker.parse.mjs";
+import { getAreaFormat } from "./utils/get-area-format.mjs";
 import { getChannelValue } from "./utils/get-channel-input-value.mjs";
 import { prefixHex } from "./utils/is-valid-hex.mjs";
 var { and } = createGuards();
@@ -45,6 +46,9 @@ var machine = createMachine({
   },
   context({ prop, bindable, getContext }) {
     return {
+      layer: bindable(() => ({
+        defaultValue: null
+      })),
       value: bindable(() => ({
         defaultValue: prop("defaultValue").toFormat(prop("format") ?? prop("defaultFormat")),
         value: prop("value")?.toFormat(prop("format") ?? prop("defaultFormat")),
@@ -70,6 +74,8 @@ var machine = createMachine({
       activeId: bindable(() => ({ defaultValue: null })),
       activeChannel: bindable(() => ({ defaultValue: null })),
       activeOrientation: bindable(() => ({ defaultValue: null })),
+      areaBaseColor: bindable(() => ({ defaultValue: null })),
+      areaDragPosition: bindable(() => ({ defaultValue: null })),
       fieldsetDisabled: bindable(() => ({ defaultValue: false })),
       restoreFocus: bindable(() => ({ defaultValue: true })),
       currentPlacement: bindable(() => ({
@@ -83,8 +89,7 @@ var machine = createMachine({
     interactive: ({ prop }) => !(prop("disabled") || prop("readOnly")),
     valueAsString: ({ context }) => context.get("value").toString(context.get("format")),
     areaValue: ({ context }) => {
-      const format = context.get("format").startsWith("hsl") ? "hsla" : "hsba";
-      return context.get("value").toFormat(format);
+      return context.get("value").toFormat(getAreaFormat(context.get("format")));
     }
   },
   effects: ["trackFormControl"],
@@ -370,6 +375,9 @@ var machine = createMachine({
         const getContentEl2 = () => dom.getContentEl(scope);
         return trackDismissableElement(getContentEl2, {
           type: "popover",
+          onLayerChange(layer) {
+            context.set("layer", layer);
+          },
           exclude: dom.getTriggerEl(scope),
           defer: true,
           onInteractOutside(event) {
@@ -432,36 +440,47 @@ var machine = createMachine({
           });
         }).catch(() => void 0);
       },
-      setActiveChannel({ context, event }) {
+      setActiveChannel({ context, event, computed }) {
         context.set("activeId", event.id);
         if (event.channel) context.set("activeChannel", event.channel);
         if (event.orientation) context.set("activeOrientation", event.orientation);
+        const areaFormat = getAreaFormat(context.get("format"));
+        if (areaFormat !== context.get("format")) {
+          context.set("areaBaseColor", computed("areaValue"));
+        }
       },
       clearActiveChannel({ context }) {
         context.set("activeChannel", null);
         context.set("activeId", null);
         context.set("activeOrientation", null);
+        context.set("areaBaseColor", null);
+        context.set("areaDragPosition", null);
       },
       setAreaColorFromPoint({ context, event, computed, scope, prop }) {
-        const v = event.format ? context.get("value").toFormat(event.format) : computed("areaValue");
+        const storeFormat = context.get("format");
+        const v = event.format ? context.get("value").toFormat(event.format) : context.get("areaBaseColor") ?? computed("areaValue");
         const { xChannel, yChannel } = event.channel || context.get("activeChannel");
         const percent = dom.getAreaValueFromPoint(scope, event.point, prop("dir"));
         if (!percent) return;
+        context.set("areaDragPosition", { x: percent.x, y: percent.y });
         const xValue = v.getChannelPercentValue(xChannel, percent.x);
         const yValue = v.getChannelPercentValue(yChannel, 1 - percent.y);
-        const color = v.withChannelValue(xChannel, xValue).withChannelValue(yChannel, yValue);
+        const color = v.withChannelValue(xChannel, xValue).withChannelValue(yChannel, yValue).toFormat(storeFormat);
         context.set("value", color);
       },
       setChannelColorFromPoint({ context, event, computed, scope, prop }) {
+        const storeFormat = context.get("format");
         const channel = event.channel || context.get("activeId");
-        const normalizedValue = event.format ? context.get("value").toFormat(event.format) : computed("areaValue");
+        const baseColor = context.get("areaBaseColor");
+        const normalizedValue = event.format ? context.get("value").toFormat(event.format) : baseColor ?? computed("areaValue");
         const percent = dom.getChannelSliderValueFromPoint(scope, event.point, channel, prop("dir"));
         if (!percent) return;
         const orientation = event.orientation || context.get("activeOrientation") || "horizontal";
         const channelPercent = orientation === "horizontal" ? percent.x : percent.y;
         const value = normalizedValue.getChannelPercentValue(channel, channelPercent);
-        const color = normalizedValue.withChannelValue(channel, value);
-        context.set("value", color);
+        const updatedBase = normalizedValue.withChannelValue(channel, value);
+        context.set("areaBaseColor", updatedBase);
+        context.set("value", updatedBase.toFormat(storeFormat));
       },
       setValue({ context, event }) {
         const format = context.get("format");
@@ -518,24 +537,32 @@ var machine = createMachine({
         const color = context.get("value").decrementChannel(event.channel, event.step);
         context.set("value", color);
       },
-      incrementAreaXChannel({ context, event, computed }) {
+      incrementAreaXChannel({ context, event }) {
         const { xChannel } = event.channel;
-        const color = computed("areaValue").incrementChannel(xChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat(getAreaFormat(storeFormat));
+        const color = v.incrementChannel(xChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      decrementAreaXChannel({ context, event, computed }) {
+      decrementAreaXChannel({ context, event }) {
         const { xChannel } = event.channel;
-        const color = computed("areaValue").decrementChannel(xChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat(getAreaFormat(storeFormat));
+        const color = v.decrementChannel(xChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      incrementAreaYChannel({ context, event, computed }) {
+      incrementAreaYChannel({ context, event }) {
         const { yChannel } = event.channel;
-        const color = computed("areaValue").incrementChannel(yChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat(getAreaFormat(storeFormat));
+        const color = v.incrementChannel(yChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
-      decrementAreaYChannel({ context, event, computed }) {
+      decrementAreaYChannel({ context, event }) {
         const { yChannel } = event.channel;
-        const color = computed("areaValue").decrementChannel(yChannel, event.step);
+        const storeFormat = context.get("format");
+        const v = context.get("value").toFormat(getAreaFormat(storeFormat));
+        const color = v.decrementChannel(yChannel, event.step).toFormat(storeFormat);
         context.set("value", color);
       },
       setChannelToMax({ context, event }) {

package/dist/color-picker.props.d.mts

@@ -1,5 +1,6 @@
 import { AreaProps, ChannelProps, ColorPickerProps, SwatchProps, SwatchTriggerProps, TransparencyGridProps } from './color-picker.types.mjs';
 import '@zag-js/color-utils';
+import './utils/get-gamut-overlay-path.mjs';
 import '@zag-js/core';
 import '@zag-js/dismissable';
 import '@zag-js/popper';

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

@@ -1,5 +1,6 @@
 import { AreaProps, ChannelProps, ColorPickerProps, SwatchProps, SwatchTriggerProps, TransparencyGridProps } from './color-picker.types.js';
 import '@zag-js/color-utils';
+import './utils/get-gamut-overlay-path.js';
 import '@zag-js/core';
 import '@zag-js/dismissable';
 import '@zag-js/popper';

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

@@ -1,8 +1,9 @@
 import { ColorChannel, Color, ColorFormat, ColorAxes } from '@zag-js/color-utils';
 export { Color, ColorAxes, ColorChannel, ColorFormat, ColorType } from '@zag-js/color-utils';
+import { GamutOverlayData } from './utils/get-gamut-overlay-path.mjs';
 import { Service, EventObject, Machine } from '@zag-js/core';
-import { InteractOutsideHandlers } from '@zag-js/dismissable';
-import { PositioningOptions } from '@zag-js/popper';
+import { InteractOutsideHandlers, LayerSnapshot } from '@zag-js/dismissable';
+import { PositioningOptions, Placement, PlacementSide } from '@zag-js/popper';
 export { PositioningOptions } from '@zag-js/popper';
 import { RequiredBy, CommonProperties, DirectionProperty, Orientation, PropTypes } from '@zag-js/types';
 
@@ -155,11 +156,20 @@ type ColorPickerSchema = {
         areaValue: Color;
     };
     context: {
+        /**
+         * The computed layer stack state used for declarative styles and attributes.
+         */
+        layer: LayerSnapshot | null;
         format: ColorFormat;
         value: Color;
         activeId: string | null;
         activeChannel: Partial<ColorAxes> | null;
         activeOrientation: Orientation | null;
+        areaBaseColor: Color | null;
+        areaDragPosition: {
+            x: number;
+            y: number;
+        } | null;
         fieldsetDisabled: boolean;
         currentPlacement: PositioningOptions["placement"] | undefined;
         restoreFocus: boolean;
@@ -186,6 +196,16 @@ interface AreaProps {
     xChannel?: ColorChannel | undefined;
     yChannel?: ColorChannel | undefined;
 }
+/**
+ * Same channel overrides as {@link AreaProps}, plus optional DPR for overlay sampling.
+ * Pass the **same** object to `getAreaProps`, `getGamutOverlay`, and `getGamutOverlayProps`.
+ */
+interface GamutOverlayProps extends AreaProps {
+    /**
+     * Overrides `globalThis.devicePixelRatio` for boundary resolution (default browser DPR in connect).
+     */
+    pixelRatio?: number | undefined;
+}
 interface SwatchTriggerProps {
     /**
      * The color value
@@ -202,6 +222,72 @@ interface SwatchTriggerState {
     checked: boolean;
     disabled: boolean;
 }
+interface RootState {
+    /**
+     * Whether the color picker is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the color picker is read-only
+     */
+    readOnly: boolean;
+    /**
+     * Whether the color picker is invalid
+     */
+    invalid: boolean;
+}
+interface TriggerState {
+    /**
+     * Whether the color picker is open
+     */
+    open: boolean;
+    /**
+     * Whether the trigger is focused
+     */
+    focused: boolean;
+    /**
+     * Whether the trigger is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the color picker is invalid
+     */
+    invalid: boolean;
+    /**
+     * Whether the color picker is read-only
+     */
+    readOnly: boolean;
+    /**
+     * The current placement of the content relative to the trigger
+     */
+    placement: Placement | undefined;
+    /**
+     * The side of the trigger the content is placed on
+     */
+    side: PlacementSide | undefined;
+}
+interface ContentState {
+    /**
+     * Whether the color picker is open
+     */
+    open: boolean;
+    /**
+     * Whether the content is nested within another layered element
+     */
+    nested: boolean;
+    /**
+     * Whether the content has nested layered elements within it
+     */
+    hasNested: boolean;
+    /**
+     * The current placement of the content relative to the trigger
+     */
+    placement: Placement | undefined;
+    /**
+     * The side of the trigger the content is placed on
+     */
+    side: PlacementSide | undefined;
+}
 interface SwatchProps {
     /**
      * The color value
@@ -236,6 +322,11 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
      * The current color value (as a Color object)
      */
     valueAsString: string;
+    /**
+     * Whether the current color lies inside the sRGB gamut (linear RGB cube).
+     * When `false`, wide-gamut CSS strings may still be valid while 8-bit RGB / hex are clamped.
+     */
+    isInSrgbGamut: boolean;
     /**
      * Function to set the color value
      */
@@ -272,16 +363,37 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
      * Function to open or close the color picker
      */
     setOpen: (open: boolean) => void;
+    /**
+     * Returns the state of the root
+     */
+    getRootState: () => RootState;
     getRootProps: () => T["element"];
     getLabelProps: () => T["element"];
     getControlProps: () => T["element"];
+    /**
+     * Returns the state of the trigger
+     */
+    getTriggerState: () => TriggerState;
     getTriggerProps: () => T["button"];
     getPositionerProps: () => T["element"];
+    /**
+     * Returns the state of the content
+     */
+    getContentState: () => ContentState;
     getContentProps: () => T["element"];
     getHiddenInputProps: () => T["input"];
     getValueTextProps: () => T["element"];
     getAreaProps: (props?: AreaProps) => T["element"];
     getAreaBackgroundProps: (props?: AreaProps) => T["element"];
+    /**
+     * SVG path + label position for the sRGB gamut boundary (oklch/oklab + HSB area only); `null` when not shown.
+     * Use the **same** `props` as {@link getAreaProps} / {@link getGamutOverlayProps} (including `pixelRatio`).
+     */
+    getGamutOverlay: (props?: GamutOverlayProps) => GamutOverlayData | null;
+    /**
+     * Props for an `<svg>` gamut overlay; pair with {@link getGamutOverlay} using the same `props`.
+     */
+    getGamutOverlayProps: (props?: GamutOverlayProps) => T["svg"];
     getAreaThumbProps: (props?: AreaProps) => T["element"];
     getChannelInputProps: (props: ChannelInputProps) => T["input"];
     getChannelSliderProps: (props: ChannelSliderProps) => T["element"];
@@ -300,4 +412,4 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
     getFormatTriggerProps: () => T["button"];
 }
 
-export type { AreaProps, ChannelInputProps, ChannelProps, ChannelSliderProps, ColorPickerApi, ColorPickerMachine, ColorPickerProps, ColorPickerSchema, ColorPickerService, ElementIds, ExtendedColorChannel, FormatChangeDetails, OpenChangeDetails, SwatchProps, SwatchTriggerProps, SwatchTriggerState, TransparencyGridProps, ValueChangeDetails };
+export { type AreaProps, type ChannelInputProps, type ChannelProps, type ChannelSliderProps, type ColorPickerApi, type ColorPickerMachine, type ColorPickerProps, type ColorPickerSchema, type ColorPickerService, type ContentState, type ElementIds, type ExtendedColorChannel, type FormatChangeDetails, GamutOverlayData, type GamutOverlayProps, type OpenChangeDetails, type RootState, type SwatchProps, type SwatchTriggerProps, type SwatchTriggerState, type TransparencyGridProps, type TriggerState, type ValueChangeDetails };

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

@@ -1,8 +1,9 @@
 import { ColorChannel, Color, ColorFormat, ColorAxes } from '@zag-js/color-utils';
 export { Color, ColorAxes, ColorChannel, ColorFormat, ColorType } from '@zag-js/color-utils';
+import { GamutOverlayData } from './utils/get-gamut-overlay-path.js';
 import { Service, EventObject, Machine } from '@zag-js/core';
-import { InteractOutsideHandlers } from '@zag-js/dismissable';
-import { PositioningOptions } from '@zag-js/popper';
+import { InteractOutsideHandlers, LayerSnapshot } from '@zag-js/dismissable';
+import { PositioningOptions, Placement, PlacementSide } from '@zag-js/popper';
 export { PositioningOptions } from '@zag-js/popper';
 import { RequiredBy, CommonProperties, DirectionProperty, Orientation, PropTypes } from '@zag-js/types';
 
@@ -155,11 +156,20 @@ type ColorPickerSchema = {
         areaValue: Color;
     };
     context: {
+        /**
+         * The computed layer stack state used for declarative styles and attributes.
+         */
+        layer: LayerSnapshot | null;
         format: ColorFormat;
         value: Color;
         activeId: string | null;
         activeChannel: Partial<ColorAxes> | null;
         activeOrientation: Orientation | null;
+        areaBaseColor: Color | null;
+        areaDragPosition: {
+            x: number;
+            y: number;
+        } | null;
         fieldsetDisabled: boolean;
         currentPlacement: PositioningOptions["placement"] | undefined;
         restoreFocus: boolean;
@@ -186,6 +196,16 @@ interface AreaProps {
     xChannel?: ColorChannel | undefined;
     yChannel?: ColorChannel | undefined;
 }
+/**
+ * Same channel overrides as {@link AreaProps}, plus optional DPR for overlay sampling.
+ * Pass the **same** object to `getAreaProps`, `getGamutOverlay`, and `getGamutOverlayProps`.
+ */
+interface GamutOverlayProps extends AreaProps {
+    /**
+     * Overrides `globalThis.devicePixelRatio` for boundary resolution (default browser DPR in connect).
+     */
+    pixelRatio?: number | undefined;
+}
 interface SwatchTriggerProps {
     /**
      * The color value
@@ -202,6 +222,72 @@ interface SwatchTriggerState {
     checked: boolean;
     disabled: boolean;
 }
+interface RootState {
+    /**
+     * Whether the color picker is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the color picker is read-only
+     */
+    readOnly: boolean;
+    /**
+     * Whether the color picker is invalid
+     */
+    invalid: boolean;
+}
+interface TriggerState {
+    /**
+     * Whether the color picker is open
+     */
+    open: boolean;
+    /**
+     * Whether the trigger is focused
+     */
+    focused: boolean;
+    /**
+     * Whether the trigger is disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether the color picker is invalid
+     */
+    invalid: boolean;
+    /**
+     * Whether the color picker is read-only
+     */
+    readOnly: boolean;
+    /**
+     * The current placement of the content relative to the trigger
+     */
+    placement: Placement | undefined;
+    /**
+     * The side of the trigger the content is placed on
+     */
+    side: PlacementSide | undefined;
+}
+interface ContentState {
+    /**
+     * Whether the color picker is open
+     */
+    open: boolean;
+    /**
+     * Whether the content is nested within another layered element
+     */
+    nested: boolean;
+    /**
+     * Whether the content has nested layered elements within it
+     */
+    hasNested: boolean;
+    /**
+     * The current placement of the content relative to the trigger
+     */
+    placement: Placement | undefined;
+    /**
+     * The side of the trigger the content is placed on
+     */
+    side: PlacementSide | undefined;
+}
 interface SwatchProps {
     /**
      * The color value
@@ -236,6 +322,11 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
      * The current color value (as a Color object)
      */
     valueAsString: string;
+    /**
+     * Whether the current color lies inside the sRGB gamut (linear RGB cube).
+     * When `false`, wide-gamut CSS strings may still be valid while 8-bit RGB / hex are clamped.
+     */
+    isInSrgbGamut: boolean;
     /**
      * Function to set the color value
      */
@@ -272,16 +363,37 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
      * Function to open or close the color picker
      */
     setOpen: (open: boolean) => void;
+    /**
+     * Returns the state of the root
+     */
+    getRootState: () => RootState;
     getRootProps: () => T["element"];
     getLabelProps: () => T["element"];
     getControlProps: () => T["element"];
+    /**
+     * Returns the state of the trigger
+     */
+    getTriggerState: () => TriggerState;
     getTriggerProps: () => T["button"];
     getPositionerProps: () => T["element"];
+    /**
+     * Returns the state of the content
+     */
+    getContentState: () => ContentState;
     getContentProps: () => T["element"];
     getHiddenInputProps: () => T["input"];
     getValueTextProps: () => T["element"];
     getAreaProps: (props?: AreaProps) => T["element"];
     getAreaBackgroundProps: (props?: AreaProps) => T["element"];
+    /**
+     * SVG path + label position for the sRGB gamut boundary (oklch/oklab + HSB area only); `null` when not shown.
+     * Use the **same** `props` as {@link getAreaProps} / {@link getGamutOverlayProps} (including `pixelRatio`).
+     */
+    getGamutOverlay: (props?: GamutOverlayProps) => GamutOverlayData | null;
+    /**
+     * Props for an `<svg>` gamut overlay; pair with {@link getGamutOverlay} using the same `props`.
+     */
+    getGamutOverlayProps: (props?: GamutOverlayProps) => T["svg"];
     getAreaThumbProps: (props?: AreaProps) => T["element"];
     getChannelInputProps: (props: ChannelInputProps) => T["input"];
     getChannelSliderProps: (props: ChannelSliderProps) => T["element"];
@@ -300,4 +412,4 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
     getFormatTriggerProps: () => T["button"];
 }
 
-export type { AreaProps, ChannelInputProps, ChannelProps, ChannelSliderProps, ColorPickerApi, ColorPickerMachine, ColorPickerProps, ColorPickerSchema, ColorPickerService, ElementIds, ExtendedColorChannel, FormatChangeDetails, OpenChangeDetails, SwatchProps, SwatchTriggerProps, SwatchTriggerState, TransparencyGridProps, ValueChangeDetails };
+export { type AreaProps, type ChannelInputProps, type ChannelProps, type ChannelSliderProps, type ColorPickerApi, type ColorPickerMachine, type ColorPickerProps, type ColorPickerSchema, type ColorPickerService, type ContentState, type ElementIds, type ExtendedColorChannel, type FormatChangeDetails, GamutOverlayData, type GamutOverlayProps, type OpenChangeDetails, type RootState, type SwatchProps, type SwatchTriggerProps, type SwatchTriggerState, type TransparencyGridProps, type TriggerState, type ValueChangeDetails };

package/dist/index.d.mts

@@ -4,8 +4,9 @@ export { connect } from './color-picker.connect.mjs';
 export { machine } from './color-picker.machine.mjs';
 export { parse } from './color-picker.parse.mjs';
 export { areaProps, channelProps, props, splitAreaProps, splitChannelProps, splitProps, splitSwatchProps, splitSwatchTriggerProps, splitTransparencyGridProps, swatchProps, swatchTriggerProps, transparencyGridProps } from './color-picker.props.mjs';
-export { ColorPickerApi as Api, AreaProps, ChannelInputProps, ChannelProps, ChannelSliderProps, ElementIds, ExtendedColorChannel, FormatChangeDetails, ColorPickerMachine as Machine, OpenChangeDetails, ColorPickerProps as Props, ColorPickerService as Service, SwatchProps, SwatchTriggerProps, SwatchTriggerState, TransparencyGridProps, ValueChangeDetails } from './color-picker.types.mjs';
+export { ColorPickerApi as Api, AreaProps, ChannelInputProps, ChannelProps, ChannelSliderProps, ContentState, ElementIds, ExtendedColorChannel, FormatChangeDetails, GamutOverlayProps, ColorPickerMachine as Machine, OpenChangeDetails, ColorPickerProps as Props, RootState, ColorPickerService as Service, SwatchProps, SwatchTriggerProps, SwatchTriggerState, TransparencyGridProps, TriggerState, ValueChangeDetails } from './color-picker.types.mjs';
 export { Color, ColorAxes, ColorChannel, ColorFormat, ColorType } from '@zag-js/color-utils';
+export { GamutOverlayData } from './utils/get-gamut-overlay-path.mjs';
 export { PositioningOptions } from '@zag-js/popper';
 import '@zag-js/anatomy';
 import '@zag-js/types';