@zag-js/color-picker 1.41.0 → 2.0.0-next.0

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();
@@ -70,11 +71,14 @@ 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(() => ({
         defaultValue: void 0
-      }))
+      })),
+      positioned: bindable(() => ({ defaultValue: false }))
     };
   },
   computed: {
@@ -83,8 +87,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"],
@@ -362,6 +365,7 @@ var machine = createMachine({
           defer: true,
           onComplete(data) {
             context.set("currentPlacement", data.placement);
+            context.set("positioned", true);
           }
         });
       },
@@ -432,36 +436,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 +533,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,5 +1,6 @@
 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';
@@ -160,8 +161,14 @@ type ColorPickerSchema = {
         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;
+        positioned: boolean;
         restoreFocus: boolean;
     };
     event: EventObject;
@@ -186,6 +193,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
@@ -236,6 +253,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
      */
@@ -282,6 +304,15 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
     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 +331,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 ElementIds, type ExtendedColorChannel, type FormatChangeDetails, GamutOverlayData, type GamutOverlayProps, type OpenChangeDetails, type SwatchProps, type SwatchTriggerProps, type SwatchTriggerState, type TransparencyGridProps, type ValueChangeDetails };

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

@@ -1,5 +1,6 @@
 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';
@@ -160,8 +161,14 @@ type ColorPickerSchema = {
         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;
+        positioned: boolean;
         restoreFocus: boolean;
     };
     event: EventObject;
@@ -186,6 +193,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
@@ -236,6 +253,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
      */
@@ -282,6 +304,15 @@ interface ColorPickerApi<T extends PropTypes = PropTypes> {
     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 +331,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 ElementIds, type ExtendedColorChannel, type FormatChangeDetails, GamutOverlayData, type GamutOverlayProps, type OpenChangeDetails, type SwatchProps, type SwatchTriggerProps, type SwatchTriggerState, type TransparencyGridProps, 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, ElementIds, ExtendedColorChannel, FormatChangeDetails, GamutOverlayProps, ColorPickerMachine as Machine, OpenChangeDetails, ColorPickerProps as Props, ColorPickerService as Service, SwatchProps, SwatchTriggerProps, SwatchTriggerState, TransparencyGridProps, 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';

package/dist/index.d.ts

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

package/dist/utils/get-area-format.d.mts

@@ -0,0 +1,6 @@
+import { ColorFormat } from '@zag-js/color-utils';
+
+/** Color space used for the 2D area for the active output format. */
+declare function getAreaFormat(format: ColorFormat): ColorFormat;
+
+export { getAreaFormat };

package/dist/utils/get-area-format.d.ts

@@ -0,0 +1,6 @@
+import { ColorFormat } from '@zag-js/color-utils';
+
+/** Color space used for the 2D area for the active output format. */
+declare function getAreaFormat(format: ColorFormat): ColorFormat;
+
+export { getAreaFormat };

package/dist/utils/get-area-format.js

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/get-area-format.ts
+var get_area_format_exports = {};
+__export(get_area_format_exports, {
+  getAreaFormat: () => getAreaFormat
+});
+module.exports = __toCommonJS(get_area_format_exports);
+function getAreaFormat(format) {
+  if (format.startsWith("hsl")) return "hsla";
+  if (format.startsWith("hsb")) return "hsba";
+  if (format.startsWith("rgb")) return "rgba";
+  if (format === "oklab") return "hsba";
+  if (format === "oklch") return "hsba";
+  return "hsba";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAreaFormat
+});

package/dist/utils/get-area-format.mjs

@@ -0,0 +1,12 @@
+// src/utils/get-area-format.ts
+function getAreaFormat(format) {
+  if (format.startsWith("hsl")) return "hsla";
+  if (format.startsWith("hsb")) return "hsba";
+  if (format.startsWith("rgb")) return "rgba";
+  if (format === "oklab") return "hsba";
+  if (format === "oklch") return "hsba";
+  return "hsba";
+}
+export {
+  getAreaFormat
+};

package/dist/utils/get-channel-display-color.js

@@ -25,10 +25,17 @@ __export(get_channel_display_color_exports, {
 module.exports = __toCommonJS(get_channel_display_color_exports);
 var import_color_utils = require("@zag-js/color-utils");
 function getChannelDisplayColor(color, channel) {
+  const fmt = color.getFormat();
   switch (channel) {
     case "hue":
+      if (fmt === "oklch") {
+        return color.withChannelValue("alpha", 1);
+      }
       return (0, import_color_utils.parseColor)(`hsl(${color.getChannelValue("hue")}, 100%, 50%)`);
     case "lightness":
+    case "chroma":
+    case "a":
+    case "b":
     case "brightness":
     case "saturation":
     case "red":

package/dist/utils/get-channel-display-color.mjs

@@ -1,10 +1,17 @@
 // src/utils/get-channel-display-color.ts
 import { parseColor } from "@zag-js/color-utils";
 function getChannelDisplayColor(color, channel) {
+  const fmt = color.getFormat();
   switch (channel) {
     case "hue":
+      if (fmt === "oklch") {
+        return color.withChannelValue("alpha", 1);
+      }
       return parseColor(`hsl(${color.getChannelValue("hue")}, 100%, 50%)`);
     case "lightness":
+    case "chroma":
+    case "a":
+    case "b":
     case "brightness":
     case "saturation":
     case "red":

package/dist/utils/get-channel-input-value.d.mts

@@ -1,5 +1,6 @@
 import { Color, ColorChannelRange } from '@zag-js/color-utils';
 import { ExtendedColorChannel } from '../color-picker.types.mjs';
+import './get-gamut-overlay-path.mjs';
 import '@zag-js/core';
 import '@zag-js/dismissable';
 import '@zag-js/popper';

package/dist/utils/get-channel-input-value.d.ts

@@ -1,5 +1,6 @@
 import { Color, ColorChannelRange } from '@zag-js/color-utils';
 import { ExtendedColorChannel } from '../color-picker.types.js';
+import './get-gamut-overlay-path.js';
 import '@zag-js/core';
 import '@zag-js/dismissable';
 import '@zag-js/popper';

package/dist/utils/get-channel-input-value.js

@@ -34,26 +34,45 @@ function getChannelValue(color, channel) {
     return color.toString("css");
   }
   if (channel in color) {
-    return color.getChannelValue(channel).toString();
+    return roundedValue(color, channel);
   }
-  const isHSL = color.getFormat() === "hsla";
+  const fmt = color.getFormat();
+  const isHSL = fmt === "hsla";
   switch (channel) {
     case "hue":
-      return isHSL ? color.toFormat("hsla").getChannelValue("hue").toString() : color.toFormat("hsba").getChannelValue("hue").toString();
+      if (fmt === "oklch") {
+        return roundedValue(color.toFormat("oklch"), "hue");
+      }
+      return isHSL ? roundedValue(color.toFormat("hsla"), "hue") : roundedValue(color.toFormat("hsba"), "hue");
     case "saturation":
-      return isHSL ? color.toFormat("hsla").getChannelValue("saturation").toString() : color.toFormat("hsba").getChannelValue("saturation").toString();
+      return isHSL ? roundedValue(color.toFormat("hsla"), "saturation") : roundedValue(color.toFormat("hsba"), "saturation");
     case "lightness":
-      return color.toFormat("hsla").getChannelValue("lightness").toString();
+      if (fmt === "oklab" || fmt === "oklch") {
+        return roundedValue(color, "lightness");
+      }
+      return roundedValue(color.toFormat("hsla"), "lightness");
     case "brightness":
-      return color.toFormat("hsba").getChannelValue("brightness").toString();
+      return roundedValue(color.toFormat("hsba"), "brightness");
+    case "a":
+    case "b":
+      return roundedValue(color.toFormat("oklab"), channel);
+    case "chroma":
+      return roundedValue(color.toFormat("oklch"), channel);
     case "red":
     case "green":
     case "blue":
-      return color.toFormat("rgba").getChannelValue(channel).toString();
+      return roundedValue(color.toFormat("rgba"), channel);
     default:
-      return color.getChannelValue(channel).toString();
+      return roundedValue(color, channel);
   }
 }
+function roundedValue(color, channel) {
+  const value = color.getChannelValue(channel);
+  const { step } = color.getChannelRange(channel);
+  if (step >= 1) return Math.round(value).toString();
+  const decimals = Math.min(4, Math.max(0, Math.ceil(-Math.log10(step))));
+  return parseFloat(value.toFixed(decimals)).toString();
+}
 function getChannelRange(color, channel) {
   switch (channel) {
     case "hex":
@@ -68,11 +87,23 @@ function getChannelRange(color, channel) {
     case "css":
       return void 0;
     case "hue":
+      if (color.getFormat() === "oklch") {
+        return color.toFormat("oklch").getChannelRange("hue");
+      }
+      return color.toFormat("hsla").getChannelRange(channel);
     case "saturation":
     case "lightness":
+      if (color.getFormat() === "oklab" || color.getFormat() === "oklch") {
+        return color.getChannelRange(channel);
+      }
       return color.toFormat("hsla").getChannelRange(channel);
     case "brightness":
       return color.toFormat("hsba").getChannelRange(channel);
+    case "a":
+    case "b":
+      return color.toFormat("oklab").getChannelRange(channel);
+    case "chroma":
+      return color.toFormat("oklch").getChannelRange(channel);
     case "red":
     case "green":
     case "blue":

package/dist/utils/get-channel-input-value.mjs

@@ -9,26 +9,45 @@ function getChannelValue(color, channel) {
     return color.toString("css");
   }
   if (channel in color) {
-    return color.getChannelValue(channel).toString();
+    return roundedValue(color, channel);
   }
-  const isHSL = color.getFormat() === "hsla";
+  const fmt = color.getFormat();
+  const isHSL = fmt === "hsla";
   switch (channel) {
     case "hue":
-      return isHSL ? color.toFormat("hsla").getChannelValue("hue").toString() : color.toFormat("hsba").getChannelValue("hue").toString();
+      if (fmt === "oklch") {
+        return roundedValue(color.toFormat("oklch"), "hue");
+      }
+      return isHSL ? roundedValue(color.toFormat("hsla"), "hue") : roundedValue(color.toFormat("hsba"), "hue");
     case "saturation":
-      return isHSL ? color.toFormat("hsla").getChannelValue("saturation").toString() : color.toFormat("hsba").getChannelValue("saturation").toString();
+      return isHSL ? roundedValue(color.toFormat("hsla"), "saturation") : roundedValue(color.toFormat("hsba"), "saturation");
     case "lightness":
-      return color.toFormat("hsla").getChannelValue("lightness").toString();
+      if (fmt === "oklab" || fmt === "oklch") {
+        return roundedValue(color, "lightness");
+      }
+      return roundedValue(color.toFormat("hsla"), "lightness");
     case "brightness":
-      return color.toFormat("hsba").getChannelValue("brightness").toString();
+      return roundedValue(color.toFormat("hsba"), "brightness");
+    case "a":
+    case "b":
+      return roundedValue(color.toFormat("oklab"), channel);
+    case "chroma":
+      return roundedValue(color.toFormat("oklch"), channel);
     case "red":
     case "green":
     case "blue":
-      return color.toFormat("rgba").getChannelValue(channel).toString();
+      return roundedValue(color.toFormat("rgba"), channel);
     default:
-      return color.getChannelValue(channel).toString();
+      return roundedValue(color, channel);
   }
 }
+function roundedValue(color, channel) {
+  const value = color.getChannelValue(channel);
+  const { step } = color.getChannelRange(channel);
+  if (step >= 1) return Math.round(value).toString();
+  const decimals = Math.min(4, Math.max(0, Math.ceil(-Math.log10(step))));
+  return parseFloat(value.toFixed(decimals)).toString();
+}
 function getChannelRange(color, channel) {
   switch (channel) {
     case "hex":
@@ -43,11 +62,23 @@ function getChannelRange(color, channel) {
     case "css":
       return void 0;
     case "hue":
+      if (color.getFormat() === "oklch") {
+        return color.toFormat("oklch").getChannelRange("hue");
+      }
+      return color.toFormat("hsla").getChannelRange(channel);
     case "saturation":
     case "lightness":
+      if (color.getFormat() === "oklab" || color.getFormat() === "oklch") {
+        return color.getChannelRange(channel);
+      }
       return color.toFormat("hsla").getChannelRange(channel);
     case "brightness":
       return color.toFormat("hsba").getChannelRange(channel);
+    case "a":
+    case "b":
+      return color.toFormat("oklab").getChannelRange(channel);
+    case "chroma":
+      return color.toFormat("oklch").getChannelRange(channel);
     case "red":
     case "green":
     case "blue":

package/dist/utils/get-gamut-overlay-path.d.mts

@@ -0,0 +1,33 @@
+import { Color, ColorChannel, ColorFormat } from '@zag-js/color-utils';
+
+interface GamutOverlayOptions {
+    xChannel: ColorChannel;
+    yChannel: ColorChannel;
+}
+interface GamutOverlayData {
+    path: string;
+    labelPosition: {
+        x: number;
+        y: number;
+    };
+}
+interface GamutOverlayComputeOptions {
+    /**
+     * Device pixel ratio; higher values sample more rows along brightness (Chrome DevTools–style).
+     * Default `1` when not passed (callers may pass `globalThis.devicePixelRatio` in browsers).
+     */
+    pixelRatio?: number | undefined;
+}
+/**
+ * Computes an SVG path (0–100 user units) tracing the sRGB gamut boundary
+ * over the HSB color area when in a wide-gamut output format (oklch/oklab).
+ *
+ * Approach (matching Chrome DevTools): treat the HSV area as Display P3 gamut,
+ * then for each brightness row, sweep saturation left→right to find where
+ * the P3 color exits the sRGB gamut.
+ */
+declare function getGamutOverlayData(areaValue: Color, axes: GamutOverlayOptions, format: ColorFormat, options?: GamutOverlayComputeOptions): GamutOverlayData | null;
+/** Visible boundary rows scale with DPR (analogous to Chrome `step = 1 / devicePixelRatio` in px space). */
+declare function gamutOverlayRowCount(pixelRatio: number): number;
+
+export { type GamutOverlayComputeOptions, type GamutOverlayData, gamutOverlayRowCount, getGamutOverlayData };