@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/ColorPicker/SVSquare.tsx

@@ -0,0 +1,189 @@
+import {
+  forwardRef,
+  useCallback,
+  useRef,
+  type KeyboardEvent,
+  type PointerEvent,
+  type CSSProperties,
+  type HTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './ColorPicker.module.scss';
+
+export interface SVSquareProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Current hue (0–360). Drives the solid base color of the pad. */
+  hue: number;
+  /** Current saturation (0–100). Drives the indicator's x position. */
+  s: number;
+  /** Current value/brightness (0–100). Drives the indicator's y position. */
+  v: number;
+  /** Fires per drag tick + per keyboard step with the new (s, v) tuple. */
+  onChange: (s: number, v: number) => void;
+  /** Fires on pointer release (end of a drag gesture). */
+  onChangeEnd?: () => void;
+  /** Disable interaction. */
+  disabled?: boolean;
+}
+
+/**
+ * 2D saturation/value pad. Background is a solid hue color overlaid with
+ * stacked CSS gradients (white→transparent left→right + black→transparent
+ * bottom→top), so the visible pixel at (x, y) in the pad represents the
+ * color at (S = x%, V = 100 - y%) in HSV space. Picking is pointer-driven;
+ * keyboard nav adjusts S/V by 1% per arrow press (10% with Shift).
+ *
+ * Not exported from the package — used internally by ColorPickerPanel.
+ *
+ * @remarks Why role="application"
+ * 2D pointer-driven controls don't have a standard ARIA pattern (slider is
+ * 1D, button is binary). The accepted compromise is `role="application"`
+ * with an aria-valuetext describing the current state.
+ */
+export const SVSquare = forwardRef<HTMLDivElement, SVSquareProps>(function SVSquare(
+  { hue, s, v, onChange, onChangeEnd, disabled = false, className, ...rest },
+  ref,
+) {
+  const t = useTranslation();
+  const padRef = useRef<HTMLDivElement | null>(null);
+  const isDraggingRef = useRef(false);
+
+  // Combine the forwarded ref with our internal padRef.
+  const setRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      padRef.current = node;
+      if (typeof ref === 'function') ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref],
+  );
+
+  const commitFromPointer = useCallback(
+    (clientX: number, clientY: number) => {
+      const el = padRef.current;
+      if (!el) return;
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 || rect.height === 0) return;
+      const nextS = Math.max(0, Math.min(100, ((clientX - rect.left) / rect.width) * 100));
+      const nextV = Math.max(0, Math.min(100, (1 - (clientY - rect.top) / rect.height) * 100));
+      onChange(nextS, nextV);
+    },
+    [onChange],
+  );
+
+  const handlePointerDown = useCallback(
+    (e: PointerEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      e.preventDefault();
+      try {
+        e.currentTarget.setPointerCapture(e.pointerId);
+      } catch {
+        // jsdom doesn't implement setPointerCapture; drag still works via pointermove.
+      }
+      isDraggingRef.current = true;
+      commitFromPointer(e.clientX, e.clientY);
+    },
+    [commitFromPointer, disabled],
+  );
+
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLDivElement>) => {
+      if (disabled || !isDraggingRef.current) return;
+      commitFromPointer(e.clientX, e.clientY);
+    },
+    [commitFromPointer, disabled],
+  );
+
+  const handlePointerUp = useCallback(
+    (e: PointerEvent<HTMLDivElement>) => {
+      if (disabled || !isDraggingRef.current) return;
+      try {
+        e.currentTarget.releasePointerCapture(e.pointerId);
+      } catch {
+        // jsdom — ignore.
+      }
+      isDraggingRef.current = false;
+      onChangeEnd?.();
+    },
+    [disabled, onChangeEnd],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      const step = e.shiftKey ? 10 : 1;
+      let nextS = s;
+      let nextV = v;
+      switch (e.key) {
+        case 'ArrowLeft':
+          nextS = Math.max(0, s - step);
+          break;
+        case 'ArrowRight':
+          nextS = Math.min(100, s + step);
+          break;
+        case 'ArrowUp':
+          nextV = Math.min(100, v + step);
+          break;
+        case 'ArrowDown':
+          nextV = Math.max(0, v - step);
+          break;
+        case 'Home':
+          nextS = 0;
+          break;
+        case 'End':
+          nextS = 100;
+          break;
+        case 'PageUp':
+          nextV = 100;
+          break;
+        case 'PageDown':
+          nextV = 0;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      if (nextS !== s || nextV !== v) {
+        onChange(nextS, nextV);
+      }
+    },
+    [disabled, onChange, s, v],
+  );
+
+  // Reset drag state if `disabled` flips true mid-gesture (defensive — same
+  // pattern as ImageCrop). We don't need a useEffect because the next
+  // pointermove with disabled=true bails before reading the ref, but we DO
+  // need to clear it so future interactions start fresh.
+  if (disabled && isDraggingRef.current) {
+    isDraggingRef.current = false;
+  }
+
+  // hsl(<h>, 100%, 50%) gives the solid hue base; CSS pseudos add the
+  // saturation + value gradients.
+  const baseStyle: CSSProperties = {
+    backgroundColor: `hsl(${hue}, 100%, 50%)`,
+  };
+
+  return (
+    <div
+      ref={setRef}
+      role="application"
+      aria-label={t('colorPicker.saturationBrightness')}
+      aria-valuetext={t('colorPicker.saturationBrightnessValue', {
+        s: Math.round(s),
+        v: Math.round(v),
+      })}
+      aria-disabled={disabled || undefined}
+      tabIndex={disabled ? -1 : 0}
+      className={clsx(styles.svSquare, disabled && styles.svSquareDisabled, className)}
+      style={baseStyle}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onKeyDown={handleKeyDown}
+      {...rest}
+    >
+      <div className={styles.svIndicator} style={{ left: `${s}%`, top: `${100 - v}%` }} />
+    </div>
+  );
+});

package/src/components/ColorPicker/colorMath.ts

@@ -0,0 +1,141 @@
+/**
+ * Hue-saturation-value color representation. h is 0–360 (degrees, wraps),
+ * s and v are 0–100 (percentages).
+ *
+ * HSV is the internal model used by the SV square (S+V axes) and the hue
+ * strip (H axis). HEX (`#RRGGBB`) is the storage format exposed to consumers.
+ */
+export interface HSV {
+  /** Hue in degrees, 0–360 (0 = red, 120 = green, 240 = blue). */
+  h: number;
+  /** Saturation as a percentage, 0 (gray) to 100 (full color). */
+  s: number;
+  /** Value (brightness) as a percentage, 0 (black) to 100 (full brightness). */
+  v: number;
+}
+
+// Loose hex pattern: optional leading #, then 3 or 6 hex characters. We
+// canonicalize on output to `#RRGGBB` (uppercase, full 6 chars, with hash).
+const HEX_PATTERN = /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
+
+/**
+ * Normalize a loose hex string to the canonical `#RRGGBB` form (uppercase,
+ * full 6 chars, with leading `#`). Accepts:
+ * - `#FFF` / `FFF` (3-char shorthand, expanded by doubling each digit)
+ * - `#FFFFFF` / `FFFFFF` / `#ffffff` (6-char)
+ *
+ * @returns the normalized string, or `null` if the input doesn't match.
+ *
+ * @example
+ * normalizeHex('#fff')      // '#FFFFFF'
+ * normalizeHex('FFF')       // '#FFFFFF'
+ * normalizeHex('#4f46e5')   // '#4F46E5'
+ * normalizeHex('orange')    // null
+ * normalizeHex('')          // null
+ */
+export function normalizeHex(input: string): string | null {
+  const match = HEX_PATTERN.exec(input.trim());
+  if (!match) return null;
+  let hex = match[1];
+  if (hex.length === 3) {
+    hex = hex
+      .split('')
+      .map((c) => c + c)
+      .join('');
+  }
+  return `#${hex.toUpperCase()}`;
+}
+
+/**
+ * Convert a hex color string to HSV. Accepts the same loose input forms as
+ * `normalizeHex`. Returns `null` for invalid input — callers should fall
+ * back to a known-good HSV (e.g. `{ h: 0, s: 0, v: 0 }`) when this returns
+ * `null`.
+ *
+ * @example
+ * hexToHsv('#FF0000')  // { h: 0,   s: 100, v: 100 }
+ * hexToHsv('#000000')  // { h: 0,   s: 0,   v: 0   }
+ * hexToHsv('orange')   // null
+ */
+export function hexToHsv(input: string): HSV | null {
+  const normalized = normalizeHex(input);
+  if (!normalized) return null;
+  const r = parseInt(normalized.slice(1, 3), 16) / 255;
+  const g = parseInt(normalized.slice(3, 5), 16) / 255;
+  const b = parseInt(normalized.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  let h = 0;
+  if (delta !== 0) {
+    if (max === r) {
+      h = ((g - b) / delta) % 6;
+    } else if (max === g) {
+      h = (b - r) / delta + 2;
+    } else {
+      h = (r - g) / delta + 4;
+    }
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? 0 : (delta / max) * 100;
+  const v = max * 100;
+  return { h, s, v };
+}
+
+/**
+ * Convert HSV to a canonical `#RRGGBB` hex string. Out-of-range inputs are
+ * clamped silently (hue wraps modulo 360, s/v clamp to [0, 100]).
+ *
+ * @example
+ * hsvToHex({ h: 0,   s: 100, v: 100 })  // '#FF0000'
+ * hsvToHex({ h: 120, s: 100, v: 100 })  // '#00FF00'
+ * hsvToHex({ h: 0,   s: 0,   v: 0   })  // '#000000'
+ */
+export function hsvToHex({ h, s, v }: HSV): string {
+  // NOTE: ColorPickerPanel's local-HSV-state-of-truth model depends on
+  // (localHsv → hex → localHsv) being a fixed point. If you change the
+  // rounding strategy (e.g., switch Math.round to Math.floor below), the
+  // useEffect([value]) external-write detection in ColorPickerPanel.tsx
+  // can flip from "no-op" to "infinite re-sync" because the round-trip
+  // hex no longer matches what we just emitted. Test the round-trip on
+  // colorMath.test.tsx's palette before merging changes here.
+
+  // Clamp / wrap inputs so consumers passing slightly out-of-range values
+  // (e.g. from a slider that overshoots by floating-point) get sane output.
+  const hue = ((h % 360) + 360) % 360;
+  const sat = Math.max(0, Math.min(100, s)) / 100;
+  const val = Math.max(0, Math.min(100, v)) / 100;
+
+  const c = val * sat;
+  const hp = hue / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+  let r1 = 0;
+  let g1 = 0;
+  let b1 = 0;
+  if (hp >= 0 && hp < 1) {
+    r1 = c;
+    g1 = x;
+  } else if (hp < 2) {
+    r1 = x;
+    g1 = c;
+  } else if (hp < 3) {
+    g1 = c;
+    b1 = x;
+  } else if (hp < 4) {
+    g1 = x;
+    b1 = c;
+  } else if (hp < 5) {
+    r1 = x;
+    b1 = c;
+  } else {
+    r1 = c;
+    b1 = x;
+  }
+  const m = val - c;
+  const toHex = (n: number) =>
+    Math.round((n + m) * 255)
+      .toString(16)
+      .padStart(2, '0');
+  return `#${toHex(r1)}${toHex(g1)}${toHex(b1)}`.toUpperCase();
+}

package/src/components/ColorPicker/index.ts

@@ -0,0 +1,6 @@
+export { ColorPicker, ColorPickerTrigger } from './ColorPicker';
+export type { ColorPickerProps, ColorPickerTriggerProps } from './ColorPicker';
+export { ColorPickerPanel } from './ColorPickerPanel';
+export type { ColorPickerPanelProps } from './ColorPickerPanel';
+export { hexToHsv, hsvToHex, normalizeHex } from './colorMath';
+export type { HSV } from './colorMath';

package/src/components/ConfirmationPopover/ConfirmationPopover.module.scss

@@ -0,0 +1,39 @@
+@use '../../styles/mixins' as *;
+@use './ConfirmationPopover.tokens';
+
+.description {
+  /* stylelint-disable-next-line property-disallowed-list -- neutralizing UA <p> default, not component layout */
+  margin: 0;
+  font-size: var(--confirmation-popover-description-font-size);
+  line-height: var(--confirmation-popover-description-line-height);
+  color: var(--confirmation-popover-description-fg);
+}
+
+.spinner {
+  display: inline-block;
+  width: var(--confirmation-popover-spinner-size);
+  height: var(--confirmation-popover-spinner-size);
+  /* stylelint-disable-next-line property-disallowed-list -- internal spacing between spinner disc and label inside Button */
+  margin-right: var(--confirmation-popover-spinner-margin-right);
+  border: var(--confirmation-popover-spinner-border-width) solid currentColor;
+  border-top-color: transparent;
+  border-radius: var(--confirmation-popover-spinner-radius);
+  animation: confirm-spin 0.6s linear infinite;
+  vertical-align: middle;
+}
+
+@keyframes confirm-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+.srOnly {
+  @include visually-hidden;
+}

package/src/components/ConfirmationPopover/ConfirmationPopover.tokens.scss

@@ -0,0 +1,13 @@
+// ConfirmationPopover.tokens.scss — Component-scoped tokens for <ConfirmationPopover>. Each token defaults to the primitive the SCSS used before this migration. ConfirmationPopover's panel chrome is delegated to <Popover>; these tokens cover the description text and the in-flight spinner only.
+:root {
+  // Description text
+  --confirmation-popover-description-font-size: var(--font-size-sm);
+  --confirmation-popover-description-line-height: var(--line-height-normal);
+  --confirmation-popover-description-fg: var(--color-fg-muted);
+
+  // Spinner (shown while the async confirm handler is in flight)
+  --confirmation-popover-spinner-size: var(--space-3);
+  --confirmation-popover-spinner-margin-right: var(--space-1);
+  --confirmation-popover-spinner-border-width: var(--border-width-emphasis);
+  --confirmation-popover-spinner-radius: var(--radius-full);
+}