@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/color-picker/index.tsx

@@ -0,0 +1,677 @@
+/* eslint-disable teamix-evo/no-color-literal -- ColorPicker inherently deals with color hex values as its core functionality */
+/**
+ * 颜色选择器 ColorPicker
+ *
+ * 完整的颜色选取器 — 色相/饱和度/明度面板 + 色相滑条 + 透明度滑条 +
+ * 格式切换 (hex/rgb/hsb) + 预设色板分组，支持受控/非受控、自定义触发器。
+ *
+ * @when
+ * - 主题定制 / 品牌色设置
+ * - 图表 / 可视化编辑器中选色
+ * - 标签 / 分类颜色标注
+ * - 需要精确颜色输入（含 alpha 透明度）时
+ */
+'use client';
+
+import * as React from 'react';
+import { HsvaColorPicker } from 'react-colorful';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ChevronDownIcon, XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Color, type HsvaColor } from '@/lib/color';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/popover';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@/components/collapsible';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/** 颜色格式。 */
+type ColorFormat = 'hex' | 'rgb' | 'hsb';
+
+/** 预设色组。 */
+interface ColorPresetGroup {
+  /** 分组标签。 */
+  label: React.ReactNode;
+  /** 组内颜色列表。 */
+  colors: string[];
+  /** 默认展开。@default true */
+  defaultOpen?: boolean;
+}
+
+/** 预设色板 — 扁平数组或分组数组。 */
+type ColorPresets = string[] | ColorPresetGroup[];
+
+// ─── Trigger variants ──────────────────────────────────────────────────────
+
+const triggerVariants = cva(
+  'inline-flex cursor-pointer items-center gap-1.5 rounded-md border border-input bg-background transition-colors hover:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      size: {
+        sm: 'h-6 p-0.5',
+        default: 'h-7 p-1',
+        lg: 'h-8 p-1',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+const swatchVariants = cva('shrink-0 rounded-sm', {
+  variants: {
+    size: {
+      sm: 'size-4',
+      default: 'size-5',
+      lg: 'size-5',
+    },
+  },
+  defaultVariants: { size: 'default' },
+});
+
+// ─── Props ─────────────────────────────────────────────────────────────────
+
+interface ColorPickerProps
+  extends Omit<
+      React.ComponentProps<'div'>,
+      'onChange' | 'children' | 'defaultValue'
+    >,
+    VariantProps<typeof triggerVariants> {
+  /** 当前颜色值（受控）。 */
+  value?: string | Color;
+  /** 默认颜色值。@default "#1677ff" */
+  defaultValue?: string | Color;
+  /** 颜色格式。@default "hex" */
+  format?: ColorFormat;
+  /** 默认颜色格式（非受控）。@default "hex" */
+  defaultFormat?: ColorFormat;
+  /** 格式变化回调。 */
+  onFormatChange?: (format: ColorFormat) => void;
+  /** 预设色板 — 字符串数组或分组数组。 */
+  presets?: ColorPresets;
+  /** 是否禁用。@default false */
+  disabled?: boolean;
+  /** 颜色变化回调（拖拽中持续触发）。 */
+  onChange?: (color: Color, hex: string) => void;
+  /** 颜色变化完成回调（拖拽松手 / 输入确认后触发）。 */
+  onChangeComplete?: (color: Color, hex: string) => void;
+  /** 触发器旁显示颜色文本。 */
+  showText?: boolean | ((color: Color) => React.ReactNode);
+  /** 允许清除。@default false */
+  allowClear?: boolean;
+  /** 清除回调。 */
+  onClear?: () => void;
+  /** 禁用透明度通道。@default false */
+  disabledAlpha?: boolean;
+  /** 受控弹出状态。 */
+  open?: boolean;
+  /** 弹出状态变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /** 自定义触发器。 */
+  children?: React.ReactNode;
+  /** 弹出位置。@default "bottom" */
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+/** 透明度棋盘格背景 inline style（无法用 Tailwind token 表达）。 */
+const CHECKERBOARD_STYLE: React.CSSProperties = {
+  backgroundSize: '8px 8px',
+  backgroundPosition: '0 0, 4px 4px',
+  backgroundImage:
+    'linear-gradient(45deg, var(--color-muted) 25%, transparent 25%, transparent 75%, var(--color-muted) 75%), linear-gradient(45deg, var(--color-muted) 25%, transparent 25%, transparent 75%, var(--color-muted) 75%)',
+};
+
+const FORMAT_CYCLE: ColorFormat[] = ['hex', 'rgb', 'hsb'];
+
+function toColor(input: string | Color | undefined, fallback: string): Color {
+  if (!input) return new Color(fallback);
+  return input instanceof Color ? input : new Color(input);
+}
+
+const PICKER_STYLE_OVERRIDES = `
+[data-slot="color-picker-canvas"] .react-colorful {
+  width: 100% !important;
+  height: auto !important;
+  gap: 8px !important;
+}
+[data-slot="color-picker-canvas"] .react-colorful__saturation {
+  height: 160px !important;
+  flex-grow: 0 !important;
+  border-radius: 6px !important;
+  border-bottom: none !important;
+}
+[data-slot="color-picker-canvas"] .react-colorful__hue,
+[data-slot="color-picker-canvas"] .react-colorful__alpha {
+  height: 10px !important;
+  border-radius: 9999px !important;
+}
+[data-slot="color-picker-canvas"] .react-colorful__last-control {
+  border-radius: 9999px !important;
+}
+[data-slot="color-picker-canvas"] .react-colorful__pointer {
+  width: 14px !important;
+  height: 14px !important;
+}
+[data-slot="color-picker-canvas"] .color-picker-no-alpha .react-colorful__alpha {
+  display: none !important;
+}
+`;
+
+function isPresetGroupArray(
+  presets: ColorPresets,
+): presets is ColorPresetGroup[] {
+  return presets.length > 0 && typeof presets[0] === 'object';
+}
+
+function formatColorText(color: Color, format: ColorFormat): string {
+  switch (format) {
+    case 'hex':
+      return color.toHexString();
+    case 'rgb':
+      return color.toRgbString();
+    case 'hsb':
+      return color.toHsbString();
+  }
+}
+
+// ─── Sub-components ────────────────────────────────────────────────────────
+
+function ColorSwatch({
+  color,
+  className,
+  style,
+  ...props
+}: React.ComponentProps<'span'> & { color: string }) {
+  return (
+    <span
+      data-slot="color-picker-swatch"
+      className={cn('relative overflow-hidden', className)}
+      style={{ ...CHECKERBOARD_STYLE, ...style }}
+      {...props}
+    >
+      <span className="absolute inset-0" style={{ backgroundColor: color }} />
+    </span>
+  );
+}
+
+function FormatInputs({
+  color,
+  format,
+  disabledAlpha,
+  onColorChange,
+  onChangeComplete,
+}: {
+  color: Color;
+  format: ColorFormat;
+  disabledAlpha: boolean;
+  onColorChange: (c: Color) => void;
+  onChangeComplete: (c: Color) => void;
+}) {
+  const inputClass =
+    'h-6 rounded-sm border border-input bg-transparent px-1 text-xs outline-none text-center transition-colors focus:border-ring';
+
+  const handleCommit = (c: Color) => {
+    onColorChange(c);
+    onChangeComplete(c);
+  };
+
+  if (format === 'hex') {
+    return (
+      <HexInput
+        color={color}
+        disabledAlpha={disabledAlpha}
+        className={cn(inputClass, disabledAlpha ? 'w-17' : 'w-20')}
+        onCommit={handleCommit}
+      />
+    );
+  }
+
+  if (format === 'rgb') {
+    const { r, g, b, a } = color.toRgb();
+    return (
+      <div className="flex items-center gap-1">
+        <ChannelInput
+          label="R"
+          value={r}
+          max={255}
+          className={cn(inputClass, 'w-10')}
+          onChange={(v) => handleCommit(new Color({ r: v, g, b, a }))}
+        />
+        <ChannelInput
+          label="G"
+          value={g}
+          max={255}
+          className={cn(inputClass, 'w-10')}
+          onChange={(v) => handleCommit(new Color({ r, g: v, b, a }))}
+        />
+        <ChannelInput
+          label="B"
+          value={b}
+          max={255}
+          className={cn(inputClass, 'w-10')}
+          onChange={(v) => handleCommit(new Color({ r, g, b: v, a }))}
+        />
+        {!disabledAlpha && (
+          <ChannelInput
+            label="A"
+            value={Math.round(a * 100)}
+            max={100}
+            suffix="%"
+            className={cn(inputClass, 'w-11')}
+            onChange={(v) => {
+              const next = color.setAlpha(v / 100);
+              handleCommit(next);
+            }}
+          />
+        )}
+      </div>
+    );
+  }
+
+  // hsb
+  const { h, s, b: bv, a } = color.toHsb();
+  return (
+    <div className="flex items-center gap-1">
+      <ChannelInput
+        label="H"
+        value={h}
+        max={360}
+        className={cn(inputClass, 'w-10')}
+        onChange={(v) =>
+          handleCommit(new Color({ h: v, s, v: bv, a } as HsvaColor))
+        }
+      />
+      <ChannelInput
+        label="S"
+        value={s}
+        max={100}
+        className={cn(inputClass, 'w-10')}
+        onChange={(v) =>
+          handleCommit(new Color({ h, s: v, v: bv, a } as HsvaColor))
+        }
+      />
+      <ChannelInput
+        label="B"
+        value={bv}
+        max={100}
+        className={cn(inputClass, 'w-10')}
+        onChange={(v) => handleCommit(new Color({ h, s, v, a } as HsvaColor))}
+      />
+      {!disabledAlpha && (
+        <ChannelInput
+          label="A"
+          value={Math.round(a * 100)}
+          max={100}
+          suffix="%"
+          className={cn(inputClass, 'w-11')}
+          onChange={(v) => {
+            const next = color.setAlpha(v / 100);
+            handleCommit(next);
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+function HexInput({
+  color,
+  disabledAlpha,
+  className,
+  onCommit,
+}: {
+  color: Color;
+  disabledAlpha: boolean;
+  className?: string;
+  onCommit: (c: Color) => void;
+}) {
+  const displayValue = disabledAlpha ? color.toHex() : color.toHexString();
+  const [draft, setDraft] = React.useState(displayValue);
+  const [focused, setFocused] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!focused) setDraft(displayValue);
+  }, [displayValue, focused]);
+
+  const confirm = () => {
+    const hex = draft.startsWith('#') ? draft : `#${draft}`;
+    const parsed = new Color(hex);
+    if (
+      parsed.toHex() !== '#000000' ||
+      hex.toLowerCase() === '#000000' ||
+      hex.toLowerCase() === '#000'
+    ) {
+      onCommit(disabledAlpha ? parsed.setAlpha(1) : parsed);
+    }
+    setFocused(false);
+  };
+
+  return (
+    <input
+      data-slot="color-picker-hex-input"
+      type="text"
+      value={focused ? draft : displayValue}
+      onChange={(e) => setDraft(e.target.value)}
+      onFocus={() => setFocused(true)}
+      onBlur={confirm}
+      onKeyDown={(e) => e.key === 'Enter' && confirm()}
+      className={className}
+    />
+  );
+}
+
+function ChannelInput({
+  label,
+  value,
+  max,
+  suffix,
+  className,
+  onChange,
+}: {
+  label: string;
+  value: number;
+  max: number;
+  suffix?: string;
+  className?: string;
+  onChange: (v: number) => void;
+}) {
+  const display = suffix ? `${Math.round(value)}` : `${Math.round(value)}`;
+  const [draft, setDraft] = React.useState(display);
+  const [focused, setFocused] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!focused) setDraft(display);
+  }, [display, focused]);
+
+  const confirm = () => {
+    const n = parseInt(draft, 10);
+    if (!isNaN(n)) {
+      onChange(Math.min(Math.max(n, 0), max));
+    }
+    setFocused(false);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-0.5">
+      <input
+        type="text"
+        value={focused ? draft : suffix ? `${display}` : display}
+        onChange={(e) => setDraft(e.target.value.replace(/[^\d]/g, ''))}
+        onFocus={(e) => {
+          setFocused(true);
+          e.target.select();
+        }}
+        onBlur={confirm}
+        onKeyDown={(e) => e.key === 'Enter' && confirm()}
+        className={className}
+      />
+      <span className="text-xs text-muted-foreground">{label}</span>
+    </div>
+  );
+}
+
+function PresetGrid({
+  colors,
+  currentColor,
+  onSelect,
+}: {
+  colors: string[];
+  currentColor: Color;
+  onSelect: (hex: string) => void;
+}) {
+  return (
+    <div data-slot="color-picker-presets" className="flex flex-wrap gap-1.5">
+      {colors.map((hex) => (
+        <button
+          key={hex}
+          type="button"
+          onClick={() => onSelect(hex)}
+          className={cn(
+            'size-5 cursor-pointer rounded-sm border border-border transition-transform hover:scale-110 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+            currentColor.toHex() === new Color(hex).toHex() &&
+              'ring-1 ring-ring ring-offset-1',
+          )}
+          style={{ backgroundColor: hex }}
+          aria-label={hex}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ─── ColorPicker ───────────────────────────────────────────────────────────
+
+function ColorPicker({
+  value: controlledValue,
+  defaultValue = '#1677ff',
+  format: controlledFormat,
+  defaultFormat = 'hex',
+  onFormatChange,
+  presets,
+  disabled = false,
+  onChange,
+  onChangeComplete,
+  size = 'default',
+  showText,
+  allowClear = false,
+  onClear,
+  disabledAlpha = false,
+  open: controlledOpen,
+  onOpenChange,
+  children,
+  placement = 'bottom',
+  className,
+  ...props
+}: ColorPickerProps) {
+  // ── Color state ──
+  const isColorControlled = controlledValue !== undefined;
+  const [internalColor, setInternalColor] = React.useState<Color>(() =>
+    toColor(defaultValue, '#1677ff'),
+  );
+  const currentColor = isColorControlled
+    ? toColor(controlledValue, '#1677ff')
+    : internalColor;
+
+  // ── Open state ──
+  const isOpenControlled = controlledOpen !== undefined;
+  const [internalOpen, setInternalOpen] = React.useState(false);
+  const currentOpen = isOpenControlled ? controlledOpen : internalOpen;
+
+  const setOpen = (next: boolean) => {
+    if (!isOpenControlled) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
+  // ── Format state ──
+  const isFormatControlled = controlledFormat !== undefined;
+  const [internalFormat, setInternalFormat] =
+    React.useState<ColorFormat>(defaultFormat);
+  const currentFormat = isFormatControlled ? controlledFormat : internalFormat;
+
+  const cycleFormat = () => {
+    const idx = FORMAT_CYCLE.indexOf(currentFormat);
+    const next = FORMAT_CYCLE[(idx + 1) % FORMAT_CYCLE.length]!;
+    if (!isFormatControlled) setInternalFormat(next);
+    onFormatChange?.(next);
+  };
+
+  // ── Change handlers ──
+  const handleChange = React.useCallback(
+    (c: Color) => {
+      const applied = disabledAlpha ? c.setAlpha(1) : c;
+      if (!isColorControlled) setInternalColor(applied);
+      onChange?.(applied, applied.toHex());
+    },
+    [isColorControlled, onChange, disabledAlpha],
+  );
+
+  const handleChangeComplete = React.useCallback(
+    (c: Color) => {
+      const applied = disabledAlpha ? c.setAlpha(1) : c;
+      onChangeComplete?.(applied, applied.toHex());
+    },
+    [onChangeComplete, disabledAlpha],
+  );
+
+  const handlePickerChange = React.useCallback(
+    (hsva: HsvaColor) => {
+      handleChange(new Color(hsva));
+    },
+    [handleChange],
+  );
+
+  const handlePickerChangeEnd = React.useCallback(
+    (hsva: HsvaColor) => {
+      handleChangeComplete(new Color(hsva));
+    },
+    [handleChangeComplete],
+  );
+
+  // Preset click
+  const handlePresetSelect = (hex: string) => {
+    const c = new Color(hex);
+    handleChange(c);
+    handleChangeComplete(c);
+  };
+
+  // Clear
+  const handleClear = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onClear?.();
+  };
+
+  // ── showText rendering ──
+  const textContent =
+    showText === true
+      ? formatColorText(currentColor, currentFormat)
+      : typeof showText === 'function'
+      ? showText(currentColor)
+      : null;
+
+  // ── Render ──
+  const hsva = currentColor.toHsva();
+
+  return (
+    <div
+      data-slot="color-picker"
+      className={cn('inline-block', className)}
+      {...props}
+    >
+      <Popover open={currentOpen} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          {children ?? (
+            <button
+              type="button"
+              data-slot="color-picker-trigger"
+              data-size={size}
+              disabled={disabled}
+              className={triggerVariants({ size })}
+            >
+              <ColorSwatch
+                color={currentColor.toRgbString()}
+                className={swatchVariants({ size })}
+              />
+              {textContent && (
+                <span className="text-xs text-foreground">{textContent}</span>
+              )}
+              {allowClear && (
+                <span
+                  role="button"
+                  tabIndex={-1}
+                  onClick={handleClear}
+                  className="inline-flex shrink-0 cursor-pointer items-center text-muted-foreground transition-colors hover:text-foreground"
+                >
+                  <XIcon className="size-3" />
+                </span>
+              )}
+            </button>
+          )}
+        </PopoverTrigger>
+
+        <PopoverContent
+          data-slot="color-picker-panel"
+          side={placement}
+          align="start"
+          className="w-68 p-3"
+        >
+          {/* Color picker panel */}
+          <div data-slot="color-picker-canvas">
+            <style>{PICKER_STYLE_OVERRIDES}</style>
+            <HsvaColorPicker
+              color={hsva}
+              onChange={handlePickerChange}
+              onChangeEnd={handlePickerChangeEnd}
+              className={disabledAlpha ? 'color-picker-no-alpha' : undefined}
+            />
+          </div>
+
+          {/* Format inputs */}
+          <div className="mt-3 flex items-start gap-2">
+            <ColorSwatch
+              color={currentColor.toRgbString()}
+              className="size-6 shrink-0 rounded-sm border border-border"
+            />
+            <div className="min-w-0 flex-1">
+              <FormatInputs
+                color={currentColor}
+                format={currentFormat}
+                disabledAlpha={disabledAlpha}
+                onColorChange={handleChange}
+                onChangeComplete={handleChangeComplete}
+              />
+            </div>
+            <button
+              type="button"
+              onClick={cycleFormat}
+              className="h-6 shrink-0 cursor-pointer rounded-sm px-1.5 text-xs font-medium uppercase text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+            >
+              {currentFormat}
+            </button>
+          </div>
+
+          {/* Presets */}
+          {presets && presets.length > 0 && (
+            <div className="mt-3 border-t border-border pt-3">
+              {isPresetGroupArray(presets) ? (
+                <div className="flex flex-col gap-2">
+                  {presets.map((group, i) => (
+                    <Collapsible
+                      key={i}
+                      defaultOpen={group.defaultOpen ?? true}
+                    >
+                      <CollapsibleTrigger className="flex w-full cursor-pointer items-center justify-between text-xs text-muted-foreground transition-colors hover:text-foreground [&[data-state=open]>svg]:rotate-180">
+                        <span>{group.label}</span>
+                        <ChevronDownIcon className="size-3 transition-transform" />
+                      </CollapsibleTrigger>
+                      <CollapsibleContent className="mt-1.5">
+                        <PresetGrid
+                          colors={group.colors}
+                          currentColor={currentColor}
+                          onSelect={handlePresetSelect}
+                        />
+                      </CollapsibleContent>
+                    </Collapsible>
+                  ))}
+                </div>
+              ) : (
+                <PresetGrid
+                  colors={presets as string[]}
+                  currentColor={currentColor}
+                  onSelect={handlePresetSelect}
+                />
+              )}
+            </div>
+          )}
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}
+
+export { ColorPicker, Color };
+export type { ColorPickerProps, ColorFormat, ColorPresetGroup, ColorPresets };