@djangocfg/widget-visual 0.1.1

package/src/design/ColorPalette/utils.ts

@@ -0,0 +1,114 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { ColorFormat } from './types';
+
+/**
+ * Parse a `#rrggbb` / `#rgb` hex string into `{ r, g, b }` (0–255).
+ * Returns `null` for malformed input.
+ */
+function parseHex(hex: string): { r: number; g: number; b: number } | null {
+  const cleaned = hex.trim().replace(/^#/, '');
+  if (cleaned.length === 3) {
+    const [c0, c1, c2] = cleaned;
+    if (c0 === undefined || c1 === undefined || c2 === undefined) return null;
+    const r = parseInt(c0 + c0, 16);
+    const g = parseInt(c1 + c1, 16);
+    const b = parseInt(c2 + c2, 16);
+    if ([r, g, b].some(Number.isNaN)) return null;
+    return { r, g, b };
+  }
+  if (cleaned.length === 6) {
+    const r = parseInt(cleaned.slice(0, 2), 16);
+    const g = parseInt(cleaned.slice(2, 4), 16);
+    const b = parseInt(cleaned.slice(4, 6), 16);
+    if ([r, g, b].some(Number.isNaN)) return null;
+    return { r, g, b };
+  }
+  return null;
+}
+
+function rgbToHsl(
+  r: number,
+  g: number,
+  b: number,
+): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case rn:
+        h = (gn - bn) / d + (gn < bn ? 6 : 0);
+        break;
+      case gn:
+        h = (bn - rn) / d + 2;
+        break;
+      case bn:
+        h = (rn - gn) / d + 4;
+        break;
+    }
+    h /= 6;
+  }
+  return { h: Math.round(h * 360), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+/**
+ * Format a hex color into the requested {@link ColorFormat}. Falls
+ * back to the original string when the hex is unparseable.
+ */
+export function formatColor(hex: string, format: ColorFormat): string {
+  if (format === 'hex') return hex.toLowerCase();
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+  if (format === 'rgb') return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+  const { h, s, l } = rgbToHsl(rgb.r, rgb.g, rgb.b);
+  return `hsl(${h}, ${s}%, ${l}%)`;
+}
+
+/**
+ * WCAG relative luminance — the same formula `ui-core`'s preset-contrast gate
+ * uses (`scripts/check-preset-contrast.mjs`), so a swatch and a theme token
+ * are judged by one standard.
+ *
+ * Note the gamma step: sRGB channels are gamma-encoded, and skipping the
+ * linearisation is what makes a naive brightness number disagree with what an
+ * eye sees.
+ */
+function relativeLuminance({ r, g, b }: { r: number; g: number; b: number }): number {
+  const linear = [r, g, b].map((channel) => {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return (linear[0] ?? 0) * 0.2126 + (linear[1] ?? 0) * 0.7152 + (linear[2] ?? 0) * 0.0722;
+}
+
+/**
+ * Return `'light'` when black text reads better against the colour than white
+ * does, otherwise `'dark'`.
+ *
+ * **This compares the two actual contrast ratios rather than testing a
+ * brightness threshold.** It used to be Rec. 601 luminance against a
+ * hard-coded `> 0.6`, which put pure green (`0.587`) on the wrong side: the
+ * swatch got white text at **1.37:1**, where black would have given 15.30:1.
+ * AA wants 4.5:1, so that was not a near miss — and it took the whole
+ * bright-green band and the mid greys with it (`#999999`: 2.85:1 white vs
+ * 7.37:1 black).
+ *
+ * A threshold is a guess at where the crossover sits. The crossover is
+ * computable, so compute it.
+ */
+export function getReadableContrast(hex: string): 'light' | 'dark' {
+  const rgb = parseHex(hex);
+  if (!rgb) return 'dark';
+  const luminance = relativeLuminance(rgb);
+  const contrastWithBlack = (luminance + 0.05) / 0.05;
+  const contrastWithWhite = 1.05 / (luminance + 0.05);
+  return contrastWithBlack >= contrastWithWhite ? 'light' : 'dark';
+}

package/src/design/ColorPicker/ColorPicker.tsx

@@ -0,0 +1,257 @@
+'use client';
+
+import { Slot as SlotPrimitive } from '@radix-ui/react-slot';
+import { useDirection as useDirectionPrimitive } from '@radix-ui/react-direction';
+import * as React from 'react';
+import { useComposedRefs } from '@djangocfg/ui-core/lib';
+import { cn } from '@djangocfg/ui-core/lib';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@djangocfg/ui-core/components';
+import { VisuallyHiddenInput } from '@djangocfg/ui-core/components';
+import { Button } from '@djangocfg/ui-core/components';
+import { ColorPickerStoreProvider, useStoreContext, useStore } from './context/ColorPickerStore';
+import { ColorPickerProvider, useColorPickerContext } from './context/ColorPickerContext';
+import { hexToRgb, rgbToHsv, rgbToHex } from './lib/color-utils';
+import type { ColorPickerProps, DivProps, StoreState, ColorValue } from './types';
+
+const ROOT_NAME = 'ColorPicker';
+const TRIGGER_NAME = 'ColorPickerTrigger';
+const CONTENT_NAME = 'ColorPickerContent';
+
+function useLazyRef<T>(init: () => T): React.RefObject<T> {
+  const ref = React.useRef<T | null>(null);
+  if (ref.current === null) {
+    ref.current = init();
+  }
+  return ref as React.RefObject<T>;
+}
+
+function useAsRef<T>(value: T) {
+  const ref = React.useRef(value);
+  React.useEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+}
+
+export function ColorPicker(props: ColorPickerProps) {
+  const {
+    value: valueProp,
+    defaultValue = '#000000',
+    onValueChange,
+    format: formatProp,
+    defaultFormat = 'hex',
+    onFormatChange,
+    defaultOpen,
+    open: openProp,
+    onOpenChange,
+    name,
+    disabled,
+    inline,
+    readOnly,
+    required,
+    ...rootProps
+  } = props;
+
+  const colorString = valueProp ?? defaultValue;
+  const color = hexToRgb(colorString);
+
+  const initialState = React.useMemo(() => ({
+    color,
+    hsv: rgbToHsv(color),
+    open: openProp ?? defaultOpen ?? false,
+    format: formatProp ?? defaultFormat,
+  }), []);
+
+  return (
+    <ColorPickerStoreProvider
+      initialColor={initialState.color}
+      initialHsv={initialState.hsv}
+      initialOpen={initialState.open}
+      initialFormat={initialState.format}
+      onValueChange={onValueChange}
+      onOpenChange={onOpenChange}
+      onFormatChange={onFormatChange}
+    >
+      <ColorPickerImpl
+        {...rootProps}
+        value={valueProp}
+        defaultOpen={defaultOpen}
+        open={openProp}
+        name={name}
+        disabled={disabled}
+        inline={inline}
+        readOnly={readOnly}
+        required={required}
+      />
+    </ColorPickerStoreProvider>
+  );
+}
+
+ColorPicker.displayName = ROOT_NAME;
+
+interface ColorPickerImplProps extends Omit<ColorPickerProps, 'defaultValue' | 'onValueChange' | 'onOpenChange' | 'format' | 'defaultFormat' | 'onFormatChange'> {}
+
+function ColorPickerImpl(props: ColorPickerImplProps) {
+  const {
+    value: valueProp,
+    dir: dirProp,
+    defaultOpen,
+    open: openProp,
+    name,
+    ref,
+    asChild,
+    disabled,
+    inline,
+    modal,
+    readOnly,
+    required,
+    ...rootProps
+  } = props;
+
+  const store = useStoreContext('ColorPickerImpl');
+
+  const dir = useDirectionPrimitive(dirProp);
+
+  const [formTrigger, setFormTrigger] = React.useState<HTMLDivElement | null>(null);
+  const composedRef = useComposedRefs(ref, (node: HTMLDivElement | null) => setFormTrigger(node));
+  const isFormControl = formTrigger ? !!formTrigger.closest('form') : true;
+
+  React.useLayoutEffect(() => {
+    if (valueProp !== undefined) {
+      const currentState = store.getState();
+      const color = hexToRgb(valueProp, currentState.color.a);
+      const hsv = rgbToHsv(color);
+      store.setColor(color);
+      store.setHsv(hsv);
+    }
+  }, [valueProp, store]);
+
+  React.useLayoutEffect(() => {
+    if (openProp !== undefined) {
+      store.setOpen(openProp);
+    }
+  }, [openProp, store]);
+
+  const contextValue = React.useMemo(() => ({
+    dir,
+    disabled,
+    inline,
+    readOnly,
+    required,
+  }), [dir, disabled, inline, readOnly, required]);
+
+  const value = useStore((state) => rgbToHex(state.color));
+  const open = useStore((state) => state.open);
+
+  const RootPrimitive = asChild ? SlotPrimitive : 'div';
+
+  if (inline) {
+    return (
+      <ColorPickerProvider value={contextValue}>
+        <RootPrimitive {...rootProps} ref={composedRef} />
+        {isFormControl && (
+          <VisuallyHiddenInput
+            type="hidden"
+            control={formTrigger}
+            name={name}
+            value={value}
+            disabled={disabled}
+            readOnly={readOnly}
+            required={required}
+          />
+        )}
+      </ColorPickerProvider>
+    );
+  }
+
+  return (
+    <ColorPickerProvider value={contextValue}>
+      <Popover
+        defaultOpen={defaultOpen}
+        open={open}
+        onOpenChange={store.setOpen}
+        modal={modal}
+      >
+        <RootPrimitive {...rootProps} ref={composedRef} />
+        {isFormControl && (
+          <VisuallyHiddenInput
+            type="hidden"
+            control={formTrigger}
+            name={name}
+            value={value}
+            disabled={disabled}
+            readOnly={readOnly}
+            required={required}
+          />
+        )}
+      </Popover>
+    </ColorPickerProvider>
+  );
+}
+
+ColorPickerImpl.displayName = 'ColorPickerImpl';
+
+export function ColorPickerTrigger(props: React.ComponentProps<typeof PopoverTrigger> & { asChild?: boolean }) {
+  const { asChild, disabled, ...triggerProps } = props;
+
+  const context = useColorPickerContext(TRIGGER_NAME);
+
+  const isDisabled = disabled || context.disabled;
+
+  const TriggerPrimitive = asChild ? SlotPrimitive : Button;
+
+  if (context.inline) {
+    return (
+      <TriggerPrimitive
+        data-slot="color-picker-trigger"
+        disabled={isDisabled}
+        {...triggerProps}
+      />
+    );
+  }
+
+  return (
+    <PopoverTrigger asChild disabled={isDisabled}>
+      <TriggerPrimitive data-slot="color-picker-trigger" {...triggerProps} />
+    </PopoverTrigger>
+  );
+}
+
+ColorPickerTrigger.displayName = TRIGGER_NAME;
+
+export function ColorPickerContent(props: React.ComponentProps<typeof PopoverContent> & { asChild?: boolean }) {
+  const { asChild, className, children, ...popoverContentProps } = props;
+
+  const context = useColorPickerContext(CONTENT_NAME);
+
+  if (context.inline) {
+    const ContentPrimitive = asChild ? SlotPrimitive : 'div';
+
+    return (
+      <ContentPrimitive
+        data-slot="color-picker-content"
+        {...popoverContentProps}
+        className={cn('flex w-[340px] flex-col gap-4 p-4', className)}
+      >
+        {children}
+      </ContentPrimitive>
+    );
+  }
+
+  return (
+    <PopoverContent
+      data-slot="color-picker-content"
+      asChild={asChild}
+      {...popoverContentProps}
+      className={cn('flex w-[340px] flex-col gap-4 p-4', className)}
+    >
+      {children}
+    </PopoverContent>
+  );
+}
+
+ColorPickerContent.displayName = CONTENT_NAME;

package/src/design/ColorPicker/color-picker.stories.tsx

@@ -0,0 +1,113 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  ColorPicker,
+  ColorPickerTrigger,
+  ColorPickerContent,
+  ColorPickerArea,
+  ColorPickerHueSlider,
+  ColorPickerAlphaSlider,
+  ColorPickerSwatch,
+  ColorPickerFormatSelect,
+  ColorPickerInput,
+} from '.';
+
+const meta = {
+  title: 'Widgets/Visual/ColorPicker',
+  component: ColorPicker,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Color picker with popover or inline layout. Supports HEX / RGBA / HSV formats. ' +
+          'Trigger is the swatch + value preview; the popover (or inline panel) hosts the ' +
+          'gradient area, hue/alpha sliders, format select and text input.',
+      },
+    },
+  },
+} satisfies Meta<typeof ColorPicker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+interface HostArgs {
+  defaultValue?: string;
+  inline?: boolean;
+  disabled?: boolean;
+  defaultOpen?: boolean;
+}
+
+function ColorPickerHost({
+  defaultValue = '#3b82f6',
+  inline,
+  disabled,
+  defaultOpen,
+}: HostArgs) {
+  const [value, setValue] = useState(defaultValue);
+  return (
+    <ColorPicker
+      value={value}
+      onValueChange={setValue}
+      inline={inline}
+      disabled={disabled}
+      defaultOpen={defaultOpen}
+    >
+      <ColorPickerTrigger asChild>
+        <button
+          type="button"
+          className="inline-flex items-center gap-2 rounded-md border border-border bg-card px-3 py-1.5 text-sm shadow-sm hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          disabled={disabled}
+        >
+          <ColorPickerSwatch />
+          <span className="font-mono">{value.toUpperCase()}</span>
+        </button>
+      </ColorPickerTrigger>
+      <ColorPickerContent className="w-[300px]">
+        <ColorPickerArea />
+        <ColorPickerHueSlider />
+        <ColorPickerAlphaSlider />
+        <div className="flex items-center gap-2">
+          <ColorPickerSwatch />
+          <ColorPickerFormatSelect />
+        </div>
+        <ColorPickerInput />
+      </ColorPickerContent>
+    </ColorPicker>
+  );
+}
+
+/** Popover trigger — popover opened by default so the docs page shows the full picker. */
+export const Default: Story = {
+  render: () => <ColorPickerHost defaultOpen />,
+};
+
+/** Trigger only — click the swatch to open the popover. */
+export const PopoverClosed: Story = {
+  render: () => <ColorPickerHost />,
+};
+
+/** Inline panel without a popover — full editor mounted in place. */
+export const Inline: Story = {
+  render: () => (
+    <div className="w-[300px] rounded-lg border border-border bg-card p-4">
+      <ColorPicker value="#3b82f6" inline>
+        <ColorPickerContent className="w-full p-0">
+          <ColorPickerArea />
+          <ColorPickerHueSlider />
+          <ColorPickerAlphaSlider />
+          <div className="flex items-center gap-2">
+            <ColorPickerSwatch />
+            <ColorPickerFormatSelect />
+          </div>
+          <ColorPickerInput />
+        </ColorPickerContent>
+      </ColorPicker>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => <ColorPickerHost disabled defaultValue="#ef4444" />,
+};

package/src/design/ColorPicker/context/ColorPickerContext.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import * as React from 'react';
+import type { ColorPickerContextValue } from '../types';
+
+const ColorPickerContext = React.createContext<ColorPickerContextValue | null>(null);
+
+export function useColorPickerContext(consumerName: string) {
+  const context = React.useContext(ColorPickerContext);
+  if (!context) {
+    throw new Error(`\`${consumerName}\` must be used within ColorPicker`);
+  }
+  return context;
+}
+
+export function ColorPickerProvider({
+  children,
+  value,
+}: {
+  children: React.ReactNode;
+  value: ColorPickerContextValue;
+}) {
+  return (
+    <ColorPickerContext.Provider value={value}>
+      {children}
+    </ColorPickerContext.Provider>
+  );
+}

package/src/design/ColorPicker/context/ColorPickerStore.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import * as React from 'react';
+import type { StoreState, Store, ColorValue, HSVColorValue, ColorFormat } from '../types';
+import { rgbToHex, rgbToHsl, rgbToHsv, hsvToRgb as hsvToRgbFn } from '../lib/color-utils';
+
+const StoreContext = React.createContext<Store | null>(null);
+
+export function useStoreContext(consumerName: string) {
+  const context = React.useContext(StoreContext);
+  if (!context) {
+    throw new Error(`\`${consumerName}\` must be used within ColorPicker`);
+  }
+  return context;
+}
+
+export function useStore<U>(selector: (state: StoreState) => U): U {
+  const store = useStoreContext('useStore');
+
+  const getSnapshot = React.useCallback(
+    () => selector(store.getState()),
+    [store, selector],
+  );
+
+  return React.useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+function useLazyRef<T>(init: () => T): React.RefObject<T> {
+  const ref = React.useRef<T | null>(null);
+  if (ref.current === null) {
+    ref.current = init();
+  }
+  return ref as React.RefObject<T>;
+}
+
+interface ColorPickerStoreProviderProps {
+  children: React.ReactNode;
+  initialColor: ColorValue;
+  initialHsv: HSVColorValue;
+  initialOpen: boolean;
+  initialFormat: ColorFormat;
+  onValueChange?: (value: string) => void;
+  onOpenChange?: (open: boolean) => void;
+  onFormatChange?: (format: ColorFormat) => void;
+}
+
+export function ColorPickerStoreProvider(props: ColorPickerStoreProviderProps) {
+  const {
+    children,
+    initialColor,
+    initialHsv,
+    initialOpen,
+    initialFormat,
+    onValueChange,
+    onOpenChange,
+    onFormatChange,
+  } = props;
+
+  const listenersRef = useLazyRef(() => new Set<() => void>());
+  const stateRef = useLazyRef<StoreState>(() => ({
+    color: initialColor,
+    hsv: initialHsv,
+    open: initialOpen,
+    format: initialFormat,
+  }));
+
+  const callbacksRef = React.useRef({ onValueChange, onOpenChange, onFormatChange });
+  React.useEffect(() => {
+    callbacksRef.current = { onValueChange, onOpenChange, onFormatChange };
+  });
+
+  const store = React.useMemo<Store>(() => {
+    return {
+      subscribe: (cb) => {
+        listenersRef.current.add(cb);
+        return () => listenersRef.current.delete(cb);
+      },
+      getState: () => stateRef.current,
+      setColor: (value: ColorValue) => {
+        if (Object.is(stateRef.current.color, value)) return;
+
+        const prevState = { ...stateRef.current };
+        stateRef.current.color = value;
+
+        const cb = callbacksRef.current.onValueChange;
+        if (cb) {
+          const colorString = colorToString(value, prevState.format);
+          cb(colorString);
+        }
+
+        store.notify();
+      },
+      setHsv: (value: HSVColorValue) => {
+        if (Object.is(stateRef.current.hsv, value)) return;
+
+        const prevState = { ...stateRef.current };
+        stateRef.current.hsv = value;
+
+        const cb = callbacksRef.current.onValueChange;
+        if (cb) {
+          const colorValue = hsvToRgb(value);
+          const colorString = colorToString(colorValue, prevState.format);
+          cb(colorString);
+        }
+
+        store.notify();
+      },
+      setOpen: (value: boolean) => {
+        if (Object.is(stateRef.current.open, value)) return;
+
+        stateRef.current.open = value;
+
+        const cb = callbacksRef.current.onOpenChange;
+        if (cb) cb(value);
+
+        store.notify();
+      },
+      setFormat: (value: ColorFormat) => {
+        if (Object.is(stateRef.current.format, value)) return;
+
+        stateRef.current.format = value;
+
+        const cb = callbacksRef.current.onFormatChange;
+        if (cb) cb(value);
+
+        store.notify();
+      },
+      notify: () => {
+        for (const cb of listenersRef.current) {
+          cb();
+        }
+      },
+    };
+  }, [listenersRef, stateRef]);
+
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}
+
+function colorToString(color: ColorValue, format: ColorFormat): string {
+  switch (format) {
+    case 'hex':
+      return rgbToHex(color);
+    case 'rgb':
+      return color.a < 1
+        ? `rgba(${color.r}, ${color.g}, ${color.b}, ${color.a})`
+        : `rgb(${color.r}, ${color.g}, ${color.b})`;
+    case 'hsl': {
+      const hsl = rgbToHsl(color);
+      return color.a < 1
+        ? `hsla(${hsl.h}, ${hsl.s}%, ${hsl.l}%, ${color.a})`
+        : `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`;
+    }
+    case 'hsb': {
+      const hsv = rgbToHsv(color);
+      return color.a < 1
+        ? `hsba(${hsv.h}, ${hsv.s}%, ${hsv.v}%, ${color.a})`
+        : `hsb(${hsv.h}, ${hsv.s}%, ${hsv.v}%)`;
+    }
+    default:
+      return rgbToHex(color);
+  }
+}
+
+function hsvToRgb(hsv: HSVColorValue): ColorValue {
+  return hsvToRgbFn(hsv);
+}

package/src/design/ColorPicker/context/index.ts

@@ -0,0 +1,2 @@
+export { ColorPickerStoreProvider, useStore, useStoreContext } from './ColorPickerStore';
+export { ColorPickerProvider, useColorPickerContext } from './ColorPickerContext';

package/src/design/ColorPicker/index.ts

@@ -0,0 +1,15 @@
+export {
+  ColorPicker,
+  ColorPickerTrigger,
+  ColorPickerContent,
+} from './ColorPicker';
+export {
+  ColorPickerArea,
+  ColorPickerHueSlider,
+  ColorPickerAlphaSlider,
+  ColorPickerSwatch,
+  ColorPickerEyeDropper,
+  ColorPickerFormatSelect,
+  ColorPickerInput,
+} from './parts';
+export type { ColorPickerProps, ColorPickerInputProps } from './types';