@djangocfg/ui-tools 2.1.412 → 2.1.415

package/src/tools/overlay/Tour/types.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import type * as React from 'react';
+
+export interface TourStep {
+  id: string;
+  target: string;
+  title: string;
+  description?: string;
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+export interface TourContextValue {
+  isOpen: boolean;
+  currentStep: number;
+  steps: TourStep[];
+  totalSteps: number;
+  goToStep: (index: number) => void;
+  nextStep: () => void;
+  prevStep: () => void;
+  close: () => void;
+  open: () => void;
+}
+
+export interface TourProps {
+  children: React.ReactNode;
+  steps: TourStep[];
+  /** Called when tour completes */
+  onComplete?: () => void;
+  /** Called when tour is dismissed */
+  onDismiss?: () => void;
+  /** Start open */
+  defaultOpen?: boolean;
+}
+
+export interface TourPopoverProps {
+  className?: string;
+}
+
+export interface TourNavigationProps {
+  className?: string;
+}

package/src/tools/visual/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/tools/visual/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/tools/visual/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/tools/visual/ColorPicker/context/index.ts

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

package/src/tools/visual/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';

package/src/tools/visual/ColorPicker/lazy.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import { createLazyComponent } from '../../../components/lazy-wrapper';
+import type { ColorPickerProps } from './types';
+
+export const LazyColorPicker = createLazyComponent<ColorPickerProps>(
+  () => import('./ColorPicker').then((mod) => ({ default: mod.ColorPicker })),
+  {
+    displayName: 'LazyColorPicker',
+    fallback: (
+      <div className="flex w-[340px] flex-col gap-4 p-4">
+        <div className="h-40 w-full animate-pulse rounded-sm bg-muted" />
+        <div className="h-3 w-full animate-pulse rounded-full bg-muted" />
+        <div className="h-3 w-full animate-pulse rounded-full bg-muted" />
+        <div className="flex gap-2">
+          <div className="h-8 w-8 animate-pulse rounded-sm bg-muted" />
+          <div className="h-8 flex-1 animate-pulse rounded-sm bg-muted" />
+        </div>
+      </div>
+    ),
+  }
+);
+
+export type { ColorPickerProps } from './types';