@zag-js/color-picker 0.23.0 → 0.25.0

package/src/color-picker.types.ts

@@ -1,14 +1,21 @@
 import type { Color, ColorAxes, ColorChannel, ColorFormat, ColorType } from "@zag-js/color-utils"
 import type { StateMachine as S } from "@zag-js/core"
-import type { CommonProperties, Context, Orientation, PropTypes, RequiredBy } from "@zag-js/types"
+import type { InteractOutsideHandlers } from "@zag-js/dismissable"
+import type { PositioningOptions } from "@zag-js/popper"
+import type { CommonProperties, Context, MaybeElement, Orientation, PropTypes, RequiredBy } from "@zag-js/types"
+import type { MaybeFunction } from "@zag-js/utils"
 
 /* -----------------------------------------------------------------------------
  * Callback details
  * -----------------------------------------------------------------------------*/
 
 export interface ValueChangeDetails {
-  value: string
-  valueAsColor: Color
+  value: Color
+  valueAsString: string
+}
+
+export interface OpenChangeDetails {
+  open: boolean
 }
 
 /* -----------------------------------------------------------------------------
@@ -18,6 +25,11 @@ export interface ValueChangeDetails {
 export type ExtendedColorChannel = ColorChannel | "hex" | "css"
 
 type ElementIds = Partial<{
+  root: string
+  control: string
+  trigger: string
+  label: string
+  input: string
   content: string
   area: string
   areaGradient: string
@@ -27,7 +39,7 @@ type ElementIds = Partial<{
   channelSliderThumb(id: ColorChannel): string
 }>
 
-interface PublicContext extends CommonProperties {
+interface PublicContext extends CommonProperties, InteractOutsideHandlers {
   /**
    * The ids of the elements in the color picker. Useful for composition.
    */
@@ -39,7 +51,7 @@ interface PublicContext extends CommonProperties {
   /**
    * The current color value
    */
-  value: string
+  value: Color
   /**
    * Whether the color picker is disabled
    */
@@ -57,9 +69,30 @@ interface PublicContext extends CommonProperties {
    */
   onValueChangeEnd?: (details: ValueChangeDetails) => void
   /**
-   *  The name for the form input
+   * Handler that is called when the user opens or closes the color picker.
+   */
+  onOpenChange?: (details: OpenChangeDetails) => void
+  /**
+   * The name for the form input
    */
   name?: string
+  /**
+   * The positioning options for the color picker
+   */
+  positioning: PositioningOptions
+  /**
+   * Whether to automatically set focus on the first focusable
+   * content within the color picker when opened.
+   */
+  autoFocus?: boolean
+  /**
+   * The initial focus element when the color picker is opened.
+   */
+  initialFocusEl?: MaybeFunction<MaybeElement>
+  /**
+   * Whether the color picker is open
+   */
+  open?: boolean
 }
 
 type PrivateContext = Context<{
@@ -83,6 +116,11 @@ type PrivateContext = Context<{
    * Whether the checkbox's fieldset is disabled
    */
   fieldsetDisabled: boolean
+  /**
+   * @internal
+   * The current placement of the color picker
+   */
+  currentPlacement?: PositioningOptions["placement"]
 }>
 
 type ComputedContext = Readonly<{
@@ -100,7 +138,7 @@ type ComputedContext = Readonly<{
    * @computed
    * The color value as a Color object
    */
-  valueAsColor: Color
+  valueAsString: string
   /**
    * @computed
    * Whether the color picker is disabled
@@ -113,7 +151,8 @@ export type UserDefinedContext = RequiredBy<PublicContext, "id">
 export interface MachineContext extends PublicContext, PrivateContext, ComputedContext {}
 
 export interface MachineState {
-  value: "idle" | "focused" | "dragging"
+  tags: "open" | "closed" | "dragging" | "focused"
+  value: "idle" | "focused" | "open" | "open:dragging"
 }
 
 export type State = S.State<MachineContext, MachineState>
@@ -124,43 +163,60 @@ export type Send = S.Send<S.AnyEventObject>
  * Component API
  * -----------------------------------------------------------------------------*/
 
-export interface ColorChannelProps {
+export interface ChannelProps {
   channel: ColorChannel
   orientation?: Orientation
 }
 
-export interface ColorChannelInputProps {
+export interface ChannelInputProps {
   channel: ExtendedColorChannel
   orientation?: Orientation
 }
 
-export interface ColorAreaProps {
-  xChannel: ColorChannel
-  yChannel: ColorChannel
+export interface AreaProps {
+  xChannel?: ColorChannel
+  yChannel?: ColorChannel
 }
 
-export interface ColorSwatchProps {
-  readOnly?: boolean
+export interface SwatchTriggerProps {
+  /**
+   * The color value
+   */
   value: string | Color
 }
 
+export interface SwatchProps {
+  /**
+   * The color value
+   */
+  value: string | Color
+  /**
+   * Whether to include the alpha channel in the color
+   */
+  respectAlpha?: boolean
+}
+
+export interface TransparencyGridProps {
+  size?: string
+}
+
 export interface MachineApi<T extends PropTypes = PropTypes> {
   /**
    * Whether the color picker is being dragged
    */
   isDragging: boolean
   /**
-   * The current color value (as a string)
+   * Whether the color picker is open
    */
-  value: string
+  isOpen: boolean
   /**
-   * The current color value (as a Color object)
+   * The current color value (as a string)
    */
-  valueAsColor: Color
+  value: Color
   /**
-   * The alpha value of the color
+   * The current color value (as a Color object)
    */
-  alpha: number
+  valueAsString: string
   /**
    * The current color channels of the color
    */
@@ -169,31 +225,55 @@ export interface MachineApi<T extends PropTypes = PropTypes> {
    * Function to set the color value
    */
   setColor(value: string | Color): void
+  /**
+   * Function to set the color value
+   */
+  getChannelValue(channel: ColorChannel): string
   /**
    * Function to set the color value of a specific channel
    */
   setChannelValue(channel: ColorChannel, value: number): void
+  /**
+   * The current color format
+   */
+  format: ColorFormat
   /**
    * Function to set the color format
    */
   setFormat(format: ColorFormat): void
+  /**
+   * The alpha value of the color
+   */
+  alpha: number
   /**
    * Function to set the color alpha
    */
   setAlpha(value: number): void
 
+  rootProps: T["element"]
+  labelProps: T["element"]
+  controlProps: T["element"]
+  triggerProps: T["button"]
+  positionerProps: T["element"]
   contentProps: T["element"]
   hiddenInputProps: T["input"]
-  getAreaProps(props: ColorAreaProps): T["element"]
-  getAreaGradientProps(props: ColorAreaProps): T["element"]
-  getAreaThumbProps(props: ColorAreaProps): T["element"]
-  getChannelSliderTrackProps(props: ColorChannelProps): T["element"]
-  getChannelSliderBackgroundProps(props: ColorChannelProps): T["element"]
-  getChannelSliderThumbProps(props: ColorChannelProps): T["element"]
-  getChannelInputProps(props: ColorChannelInputProps): T["input"]
+
+  getAreaProps(props?: AreaProps): T["element"]
+  getAreaBackgroundProps(props?: AreaProps): T["element"]
+  getAreaThumbProps(props?: AreaProps): T["element"]
+
+  getChannelSliderProps(props: ChannelProps): T["element"]
+  getChannelSliderTrackProps(props: ChannelProps): T["element"]
+  getChannelSliderThumbProps(props: ChannelProps): T["element"]
+  getChannelInputProps(props: ChannelInputProps): T["input"]
+
+  getTransparencyGridProps(props?: TransparencyGridProps): T["element"]
+
   eyeDropperTriggerProps: T["button"]
-  getSwatchBackgroundProps(props: ColorSwatchProps): T["element"]
-  getSwatchProps(props: ColorSwatchProps): T["element"]
+
+  swatchGroupProps: T["element"]
+  getSwatchTriggerProps(props: SwatchTriggerProps): T["button"]
+  getSwatchProps(props: SwatchProps): T["element"]
 }
 
 /* -----------------------------------------------------------------------------

package/src/index.ts

@@ -1,16 +1,19 @@
 export { anatomy } from "./color-picker.anatomy"
 export { connect } from "./color-picker.connect"
 export { machine } from "./color-picker.machine"
+export { parse } from "./color-picker.parse"
 export type {
+  MachineApi as Api,
+  AreaProps,
+  ChannelInputProps,
+  ChannelProps,
   Color,
   ColorAxes,
-  ColorFormat,
-  ColorAreaProps,
   ColorChannel,
-  ColorChannelProps,
-  ColorChannelInputProps,
-  ColorSwatchProps,
+  ColorFormat,
   ColorType,
   UserDefinedContext as Context,
-  MachineApi as Api,
+  SwatchProps,
+  TransparencyGridProps,
+  SwatchTriggerProps,
 } from "./color-picker.types"

package/src/utils/get-channel-input-value.ts

@@ -1,44 +1,78 @@
-import type { Color } from "@zag-js/color-utils"
+import { parseColor, type Color, type ColorChannelRange } from "@zag-js/color-utils"
 import type { ExtendedColorChannel } from "../color-picker.types"
 
-export function getChannelInputValue(color: Color, channel: ExtendedColorChannel | null | undefined) {
-  if (channel == null) return
+export function getChannelValue(color: Color, channel: ExtendedColorChannel | null | undefined): string {
+  if (channel == null) return ""
+
+  if (channel === "hex") {
+    return color.toString("hex")
+  }
+
+  if (channel === "css") {
+    return color.toString("css")
+  }
+
+  if (channel in color) {
+    return color.getChannelValue(channel).toString()
+  }
+
+  const isHSL = color.getFormat() === "hsl"
 
   switch (channel) {
-    case "hex":
-      return color.toString("hex")
-    case "css":
-      return color.toString("css")
     case "hue":
+      return isHSL
+        ? color.toFormat("hsla").getChannelValue("hue").toString()
+        : color.toFormat("hsba").getChannelValue("hue").toString()
+
     case "saturation":
+      return isHSL
+        ? color.toFormat("hsl").getChannelValue("saturation").toString()
+        : color.toFormat("hsb").getChannelValue("saturation").toString()
+
     case "lightness":
-      return color.toFormat("hsl").getChannelValue("lightness").toString()
+      return color.toFormat("hsla").getChannelValue("lightness").toString()
+
     case "brightness":
-      return color.toFormat("hsb").getChannelValue("brightness").toString()
+      return color.toFormat("hsba").getChannelValue("brightness").toString()
+
     case "red":
     case "green":
     case "blue":
-      return color.toFormat("rgb").getChannelValue(channel).toString()
+      return color.toFormat("rgba").getChannelValue(channel).toString()
+
     default:
       return color.getChannelValue(channel).toString()
   }
 }
 
-export function getChannelInputRange(color: Color, channel: ExtendedColorChannel) {
+export function getChannelRange(color: Color, channel: ExtendedColorChannel): ColorChannelRange | undefined {
   switch (channel) {
     case "hex":
+      const minColor = parseColor("#000000")
+      const maxColor = parseColor("#FFFFFF")
+      return {
+        minValue: minColor.toHexInt(),
+        maxValue: maxColor.toHexInt(),
+        pageSize: 10,
+        step: 1,
+      }
+
     case "css":
       return undefined
+
     case "hue":
     case "saturation":
     case "lightness":
       return color.toFormat("hsl").getChannelRange(channel)
+
     case "brightness":
       return color.toFormat("hsb").getChannelRange(channel)
+
     case "red":
     case "green":
     case "blue":
       return color.toFormat("rgb").getChannelRange(channel)
+
     default:
       return color.getChannelRange(channel)
   }

package/src/utils/get-slider-background.ts

@@ -1,6 +1,6 @@
-import type { ColorChannelProps, MachineContext } from "../color-picker.types"
+import type { ChannelProps, Color, MachineContext } from "../color-picker.types"
 
-function getSliderBgDirection(orientation: "vertical" | "horizontal", dir: "ltr" | "rtl") {
+function getSliderBackgroundDirection(orientation: "vertical" | "horizontal", dir: "ltr" | "rtl") {
   if (orientation === "vertical") {
     return "top"
   } else if (dir === "ltr") {
@@ -10,22 +10,24 @@ function getSliderBgDirection(orientation: "vertical" | "horizontal", dir: "ltr"
   }
 }
 
-export const getSliderBgImage = (ctx: MachineContext, props: Required<ColorChannelProps>) => {
-  const { channel } = props
-
-  const dir = getSliderBgDirection(props.orientation, ctx.dir!)
-  const value = ctx.valueAsColor
+interface SliderBackgroundProps extends Required<ChannelProps> {
+  value: Color
+  dir: MachineContext["dir"]
+}
 
-  const { minValue, maxValue } = ctx.valueAsColor.getChannelRange(channel)
+export const getSliderBackground = (props: SliderBackgroundProps) => {
+  const { channel, value, dir } = props
+  const bgDirection = getSliderBackgroundDirection(props.orientation, dir!)
+  const { minValue, maxValue } = value.getChannelRange(channel)
 
   switch (channel) {
     case "hue":
-      return `linear-gradient(to ${dir}, rgb(255, 0, 0) 0%, rgb(255, 255, 0) 17%, rgb(0, 255, 0) 33%, rgb(0, 255, 255) 50%, rgb(0, 0, 255) 67%, rgb(255, 0, 255) 83%, rgb(255, 0, 0) 100%)`
+      return `linear-gradient(to ${bgDirection}, rgb(255, 0, 0) 0%, rgb(255, 255, 0) 17%, rgb(0, 255, 0) 33%, rgb(0, 255, 255) 50%, rgb(0, 0, 255) 67%, rgb(255, 0, 255) 83%, rgb(255, 0, 0) 100%)`
     case "lightness": {
-      let start = ctx.valueAsColor.withChannelValue(channel, minValue).toString("css")
+      let start = value.withChannelValue(channel, minValue).toString("css")
       let middle = value.withChannelValue(channel, (maxValue - minValue) / 2).toString("css")
       let end = value.withChannelValue(channel, maxValue).toString("css")
-      return `linear-gradient(to ${dir}, ${start}, ${middle}, ${end})`
+      return `linear-gradient(to ${bgDirection}, ${start}, ${middle}, ${end})`
     }
     case "saturation":
     case "brightness":
@@ -35,7 +37,7 @@ export const getSliderBgImage = (ctx: MachineContext, props: Required<ColorChann
     case "alpha": {
       let start = value.withChannelValue(channel, minValue).toString("css")
       let end = value.withChannelValue(channel, maxValue).toString("css")
-      return `linear-gradient(to ${dir}, ${start}, ${end})`
+      return `linear-gradient(to ${bgDirection}, ${start}, ${end})`
     }
     default:
       throw new Error("Unknown color channel: " + channel)

package/src/utils/get-channel-details.ts

@@ -1,60 +0,0 @@
-import type { Color, ColorChannel, ColorType } from "@zag-js/color-utils"
-import { getPercentValue, snapValueToStep } from "@zag-js/numeric-range"
-
-export function getChannelDetails(color: Color, xChannel: ColorChannel, yChannel: ColorChannel) {
-  const channels = color.getColorSpaceAxes({ xChannel, yChannel })
-
-  const xChannelRange = color.getChannelRange(channels.xChannel)
-  const yChannelRange = color.getChannelRange(channels.yChannel)
-
-  const { minValue: minValueX, maxValue: maxValueX, step: stepX, pageSize: pageSizeX } = xChannelRange
-  const { minValue: minValueY, maxValue: maxValueY, step: stepY, pageSize: pageSizeY } = yChannelRange
-
-  const xValue = color.getChannelValue(channels.xChannel)
-  const yValue = color.getChannelValue(channels.yChannel)
-
-  return {
-    channels,
-    xChannelStep: stepX,
-    yChannelStep: stepY,
-    xChannelPageStep: pageSizeX,
-    yChannelPageStep: pageSizeY,
-    xValue,
-    yValue,
-    getThumbPosition() {
-      let x = (xValue - minValueX) / (maxValueX - minValueX)
-      let y = 1 - (yValue - minValueY) / (maxValueY - minValueY)
-      return { x, y }
-    },
-    incrementX(stepSize: number) {
-      return xValue + stepSize > maxValueX ? maxValueX : snapValueToStep(xValue + stepSize, minValueX, maxValueX, stepX)
-    },
-    incrementY(stepSize: number) {
-      return yValue + stepSize > maxValueY ? maxValueY : snapValueToStep(yValue + stepSize, minValueY, maxValueY, stepY)
-    },
-    decrementX(stepSize: number) {
-      return snapValueToStep(xValue - stepSize, minValueX, maxValueX, stepX)
-    },
-    decrementY(stepSize: number) {
-      return snapValueToStep(yValue - stepSize, minValueY, maxValueY, stepY)
-    },
-    getColorFromPoint(x: number, y: number) {
-      let newXValue = getPercentValue(x, minValueX, maxValueX, stepX)
-      let newYValue = getPercentValue(1 - y, minValueY, maxValueY, stepY)
-
-      let newColor: ColorType | undefined
-
-      if (newXValue !== xValue) {
-        newXValue = snapValueToStep(newXValue, minValueX, maxValueX, stepX)
-        newColor = color.withChannelValue(channels.xChannel, newXValue)
-      }
-
-      if (newYValue !== yValue) {
-        newYValue = snapValueToStep(newYValue, minValueY, maxValueY, stepY)
-        newColor = (newColor || color).withChannelValue(channels.yChannel, newYValue)
-      }
-
-      return newColor
-    },
-  }
-}