@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/ColorPicker/ColorPicker.tsx

@@ -0,0 +1,367 @@
+import {
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useId,
+  useState,
+  Children,
+  cloneElement,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { Popover } from '../Popover';
+import { Stack } from '../Stack';
+import { useTranslation } from '../../i18n/useTranslation';
+import { ColorPickerPanel } from './ColorPickerPanel';
+import { normalizeHex } from './colorMath';
+import styles from './ColorPicker.module.scss';
+
+const FALLBACK_HEX = '#000000';
+
+type PopoverPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
+
+type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
+type PopoverAlign = 'start' | 'center' | 'end';
+
+const PLACEMENT_MAP: Record<PopoverPlacement, { side: PopoverSide; align: PopoverAlign }> = {
+  top: { side: 'top', align: 'center' },
+  'top-start': { side: 'top', align: 'start' },
+  'top-end': { side: 'top', align: 'end' },
+  bottom: { side: 'bottom', align: 'center' },
+  'bottom-start': { side: 'bottom', align: 'start' },
+  'bottom-end': { side: 'bottom', align: 'end' },
+};
+
+export interface ColorPickerTriggerProps {
+  /**
+   * Currently always behaves as `true` (the child is merged with trigger
+   * semantics via `<Popover.Trigger>`'s cloneElement). Reserved for a
+   * future Slot-style variant where `false` would wrap the child instead
+   * of merging. Documented for API stability.
+   */
+  asChild?: boolean;
+  /**
+   * The element to render as the trigger. Must accept `ref`, `onClick`, `id`, and ARIA
+   * attributes so ColorPicker can connect it to Field. Explicit child ARIA naming,
+   * description, and invalid state win over the parent values; ColorPicker's public `id`
+   * still owns the label association.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Marker child used inside `<ColorPicker>` to override the default trigger.
+ * @see docs/components/ColorPicker.md
+ */
+export function ColorPickerTrigger(_props: ColorPickerTriggerProps): null {
+  return null;
+}
+ColorPickerTrigger.displayName = 'ColorPickerTrigger';
+
+export interface ColorPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Current color as `#RRGGBB`. Controlled — required. */
+  value: string;
+  /** Fires per drag tick + on input change + on preset click. High frequency during drags. */
+  onChange: (hex: string) => void;
+  /** Fires on the trailing edge of an interaction. Use for commit-style logic. */
+  onChangeEnd?: (hex: string) => void;
+  /**
+   * Optional preset color swatches. If provided, rendered as a grid below
+   * the hue slider in the panel.
+   */
+  presets?: string[];
+  /** Disable interaction. Trigger doesn't open; panel is non-interactive. */
+  disabled?: boolean;
+  /** Marks the focusable trigger invalid for Field composition. @default false */
+  invalid?: boolean;
+  /**
+   * Consumed for Field composition so Field can render its visible required marker. Native
+   * buttons do not support `aria-required`, so this does not add required semantics to the
+   * trigger. @default false
+   */
+  required?: boolean;
+  /**
+   * Accessible name for the focusable trigger. Forwarded to the default or custom trigger,
+   * not the root wrapper. On the default trigger the current value is appended
+   * (`aria-label="Accent colour"` → "Accent colour, current value #3366FF"); the popover
+   * dialog is named by the bare `aria-label`. Ignored when `aria-labelledby` is provided. An explicit name on
+   * a custom trigger child takes precedence — but an EMPTY one on that child does not, since
+   * an empty string names nothing.
+   */
+  'aria-label'?: string;
+  /**
+   * Accessible label for the default trigger. Defaults to the i18n value at
+   * `colorPicker.triggerLabel` (`'Pick a color'` in English) when omitted OR
+   * empty — an empty string is not an explicit name, so it takes the default
+   * too. Ignored when
+   * a custom trigger is provided via `<ColorPicker.Trigger>`.
+   */
+  triggerLabel?: string;
+  /**
+   * Id(s) of element(s) that label the trigger button. Forwarded onto the
+   * focusable trigger (not the root wrapper) and takes precedence over the
+   * generated `aria-label`. Set automatically when wrapped in `<Field label>`.
+   * On the default trigger a visually hidden span holding the current HEX is
+   * appended, so the name reads e.g. "Accent colour #0052CC". The popover
+   * dialog is named by these ids alone (purpose, no value).
+   */
+  'aria-labelledby'?: string;
+  /**
+   * Id(s) of element(s) that describe the trigger button (e.g. a Field error or
+   * helper text). Forwarded onto the focusable trigger, not the root wrapper.
+   */
+  'aria-describedby'?: string;
+  /** Popover placement (split internally into side + align). Default `'bottom-start'`. */
+  popoverPlacement?: PopoverPlacement;
+  /**
+   * Optional content rendered inside the popover, below the panel (and below
+   * its presets grid, if any) — for live feedback about the color being
+   * picked, e.g. a contrast-ratio readout that updates as the user drags.
+   * Not available on the standalone `<ColorPicker.Panel>`, which has no
+   * popover to render it inside.
+   *
+   * Not an `aria-live` region by default — announcing every drag tick would
+   * be disruptive. If the footer's text should be announced as it settles,
+   * wire that up yourself (e.g. wrap it in your own `role="status"` span);
+   * that tradeoff is the consumer's call, not the picker's default.
+   *
+   * The footer is wired as the popover dialog's `aria-describedby`, so its
+   * text is read when the dialog opens. Keep it short — it is read in full.
+   *
+   * @example
+   * <ColorPicker
+   *   value={hex}
+   *   onChange={setHex}
+   *   panelFooter={<Text size="sm">{contrastRatio.toFixed(2)}:1 against white text</Text>}
+   * />
+   */
+  panelFooter?: ReactNode;
+  /** Optional `<ColorPicker.Trigger asChild>` override for custom triggers. */
+  children?: ReactNode;
+}
+
+interface DefaultTriggerProps {
+  id?: string;
+  hex: string;
+  label: string;
+  disabled: boolean;
+  invalid: boolean;
+  ariaInvalid?: ColorPickerProps['aria-invalid'];
+  ariaLabel?: string;
+  open: boolean;
+  labelledBy?: string;
+  describedBy?: string;
+  onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
+}
+
+const DefaultTrigger = forwardRef<HTMLButtonElement, DefaultTriggerProps>(function DefaultTrigger(
+  {
+    id,
+    hex,
+    label,
+    disabled,
+    invalid,
+    ariaInvalid,
+    ariaLabel,
+    open,
+    onClick,
+    labelledBy,
+    describedBy,
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const display = normalizeHex(hex) ?? FALLBACK_HEX;
+  return (
+    <button
+      ref={ref}
+      id={id}
+      type="button"
+      className={styles.trigger}
+      disabled={disabled}
+      // An external label (e.g. <Field label>) wins; otherwise an explicit
+      // aria-label, or the trigger label, with the current value appended
+      // (#594). Never set both.
+      aria-label={
+        labelledBy
+          ? undefined
+          : t('colorPicker.triggerAccessibleLabel', { label: ariaLabel || label, value: display })
+      }
+      aria-labelledby={labelledBy}
+      aria-describedby={describedBy}
+      aria-invalid={invalid ? true : ariaInvalid}
+      aria-haspopup="true"
+      aria-expanded={open}
+      onClick={onClick}
+    >
+      <span
+        className={styles.triggerSwatch}
+        style={{ backgroundColor: display }}
+        aria-hidden="true"
+      />
+      <span className={styles.triggerHex} aria-hidden="true">
+        {display}
+      </span>
+    </button>
+  );
+});
+
+/**
+ * Controlled HEX color picker with a Popover trigger by default.
+ * @see docs/components/ColorPicker.md
+ */
+const ColorPickerRoot = forwardRef<HTMLDivElement, ColorPickerProps>(function ColorPickerRoot(
+  {
+    value,
+    onChange,
+    onChangeEnd,
+    presets,
+    disabled = false,
+    invalid = false,
+    // Consumed for Field compatibility; native button triggers do not support required state.
+    required: _required = false,
+    triggerLabel,
+    popoverPlacement = 'bottom-start',
+    panelFooter,
+    id,
+    'aria-label': ariaLabel,
+    'aria-invalid': ariaInvalid,
+    'aria-required': _ariaRequired,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+    children,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const [open, setOpen] = useState(false);
+  const { side, align } = PLACEMENT_MAP[popoverPlacement];
+  const resolvedTriggerLabel = triggerLabel || t('colorPicker.triggerLabel');
+  const valueId = `${useId()}-value`;
+  const footerId = `${useId()}-footer`;
+  // What the popover dialog is named by — the trigger's PURPOSE (Field label,
+  // aria-label, or the default label), without the value, as IconPicker does.
+  let dialogLabelProps: { 'aria-labelledby'?: string; 'aria-label'?: string };
+
+  // Find a <ColorPicker.Trigger> marker child if present; extract its
+  // children to use as the popover trigger element. Other children types
+  // are ignored (no error — keeps the API forgiving).
+  const customTrigger = Children.toArray(children).find(
+    (c): c is ReactElement<ColorPickerTriggerProps> =>
+      isValidElement(c) && c.type === ColorPickerTrigger,
+  );
+
+  let triggerElement: ReactElement;
+  if (customTrigger) {
+    const customChild = customTrigger.props.children as ReactElement<Record<string, unknown>>;
+    const childProps = customChild.props;
+    const childAriaLabel = childProps['aria-label'];
+    const childAriaLabelledBy = childProps['aria-labelledby'];
+    // Truthiness, not `!== undefined`: `aria-label={row.name ?? ''}` is
+    // ordinary consumer code, and an empty aria-label does not name the child
+    // — it contributes nothing and drops the computation through. So an empty
+    // one must neither win over the picker's own label nor suppress its
+    // aria-labelledby.
+    const resolvedLabelledBy = childAriaLabelledBy || (childAriaLabel ? undefined : ariaLabelledBy);
+    const resolvedLabel = childAriaLabel || (resolvedLabelledBy ? undefined : ariaLabel);
+    const resolvedDescribedBy = childProps['aria-describedby'] ?? ariaDescribedBy;
+    const resolvedInvalid = childProps['aria-invalid'] ?? (invalid ? true : ariaInvalid);
+    // The child's props are untyped; its ARIA naming props are strings.
+    dialogLabelProps = resolvedLabelledBy
+      ? { 'aria-labelledby': resolvedLabelledBy as string }
+      : { 'aria-label': (resolvedLabel as string | undefined) || resolvedTriggerLabel };
+
+    // The consumer's child is cloned to receive the supported control attributes;
+    // <Popover.Trigger> clones it again to add disclosure behavior and its ref. A
+    // custom child's explicit ARIA wins, while ColorPicker's public id continues to
+    // own the Field label's htmlFor/id association.
+    triggerElement = cloneElement(customChild, {
+      ...(id !== undefined && { id }),
+      ...(resolvedLabel !== undefined && { 'aria-label': resolvedLabel }),
+      ...(resolvedLabelledBy !== undefined && { 'aria-labelledby': resolvedLabelledBy }),
+      ...(resolvedDescribedBy !== undefined && { 'aria-describedby': resolvedDescribedBy }),
+      ...(resolvedInvalid !== undefined && { 'aria-invalid': resolvedInvalid }),
+      'aria-required': undefined,
+    });
+  } else {
+    dialogLabelProps = ariaLabelledBy
+      ? { 'aria-labelledby': ariaLabelledBy }
+      : { 'aria-label': ariaLabel || resolvedTriggerLabel };
+    triggerElement = (
+      <DefaultTrigger
+        id={id}
+        hex={value}
+        label={resolvedTriggerLabel}
+        disabled={disabled}
+        invalid={invalid}
+        ariaInvalid={ariaInvalid}
+        ariaLabel={ariaLabel}
+        open={open}
+        // The swatch and hex inside the button are aria-hidden, so an external
+        // label alone would drop the value from the name (#594) — append a
+        // hidden span holding it, as IconPicker does.
+        labelledBy={ariaLabelledBy && `${ariaLabelledBy} ${valueId}`}
+        describedBy={ariaDescribedBy}
+        // onClick is overridden by Popover.Trigger's cloneElement; we set a
+        // no-op here so DefaultTrigger's prop type is satisfied.
+        onClick={() => {}}
+      />
+    );
+  }
+
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      if (disabled) return;
+      setOpen(next);
+    },
+    [disabled],
+  );
+
+  return (
+    <div ref={ref} className={clsx(disabled && styles.disabled, className)} {...rest}>
+      {!customTrigger && ariaLabelledBy && (
+        <span id={valueId} className={styles.visuallyHidden}>
+          {normalizeHex(value) ?? FALLBACK_HEX}
+        </span>
+      )}
+      <Popover open={open} onOpenChange={handleOpenChange}>
+        <Popover.Trigger>{triggerElement}</Popover.Trigger>
+        <Popover.Content
+          side={side}
+          align={align}
+          {...dialogLabelProps}
+          aria-describedby={panelFooter != null ? footerId : undefined}
+        >
+          <Stack gap="md">
+            <ColorPickerPanel
+              framed={false}
+              value={value}
+              onChange={onChange}
+              onChangeEnd={onChangeEnd}
+              presets={presets}
+              disabled={disabled}
+            />
+            {panelFooter != null && <div id={footerId}>{panelFooter}</div>}
+          </Stack>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+});
+ColorPickerRoot.displayName = 'ColorPicker';
+
+/**
+ * Compound API: `<ColorPicker>` + `<ColorPicker.Trigger>` + `<ColorPicker.Panel>`.
+ * @see docs/components/ColorPicker.md
+ */
+export const ColorPicker = Object.assign(ColorPickerRoot, {
+  Trigger: ColorPickerTrigger,
+  Panel: ColorPickerPanel,
+});
+
+// Re-export types from the panel for consumers who use `<ColorPicker.Panel>` directly.
+export type { ColorPickerPanelProps } from './ColorPickerPanel';

package/src/components/ColorPicker/ColorPickerPanel.tsx

@@ -0,0 +1,265 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type HTMLAttributes,
+  type KeyboardEvent,
+} from 'react';
+import clsx from 'clsx';
+import { Slider } from '../Slider';
+import { Input } from '../Input';
+import { SVSquare } from './SVSquare';
+import { hexToHsv, hsvToHex, normalizeHex, type HSV } from './colorMath';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './ColorPicker.module.scss';
+
+export interface ColorPickerPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Current color as `#RRGGBB`. Controlled — required. */
+  value: string;
+  /** Fires per drag tick + on input change + on preset click. High frequency during drags. */
+  onChange: (hex: string) => void;
+  /**
+   * Fires on the trailing edge of an interaction — pointer release on the
+   * SV pad / hue slider, blur on the HEX input, preset click. Use for
+   * commit-style logic (network calls, history snapshots).
+   */
+  onChangeEnd?: (hex: string) => void;
+  /**
+   * Optional preset color swatches. If provided, rendered as a grid below
+   * the hue slider. Clicking a swatch commits the color (fires both
+   * onChange and onChangeEnd). Invalid entries are silently dropped.
+   */
+  presets?: string[];
+  /** Disable interaction. */
+  disabled?: boolean;
+  /**
+   * Whether the panel draws its own chrome (border, shadow, padding,
+   * background, radius). Default `true` — the standalone `<ColorPicker.Panel>`
+   * needs that chrome to read as a discrete surface on a page.
+   *
+   * Set `false` when nesting the panel inside a container that already draws
+   * a frame — a `Popover.Content`, a `Card`, or your own bordered surface —
+   * so the two frames don't nest. `<ColorPicker>` renders its popover panel
+   * this way internally, for exactly this reason.
+   *
+   * @default true
+   */
+  framed?: boolean;
+}
+
+const FALLBACK_HSV: HSV = { h: 0, s: 0, v: 0 };
+const FALLBACK_HEX = '#000000';
+
+/**
+ * The picker UI without the popover wrapping, for inline color picking.
+ * @see docs/components/ColorPicker.md
+ */
+export const ColorPickerPanel = forwardRef<HTMLDivElement, ColorPickerPanelProps>(
+  function ColorPickerPanel(
+    { value, onChange, onChangeEnd, presets, disabled = false, framed = true, className, ...rest },
+    ref,
+  ) {
+    const t = useTranslation();
+    // Local HSV state-of-truth. See class JSDoc above for the rationale.
+    const [localHsv, setLocalHsv] = useState<HSV>(() => hexToHsv(value) ?? FALLBACK_HSV);
+
+    // HEX input draft buffer — separate from the committed `value` so we can
+    // hold transient invalid input ("#1" while the user types "#123456")
+    // without disturbing the rest of the UI.
+    const [draft, setDraft] = useState<string>(() => normalizeHex(value) ?? FALLBACK_HEX);
+
+    // One-time dev warning for invalid initial value.
+    const [warned, setWarned] = useState(false);
+    useEffect(() => {
+      if (!warned && hexToHsv(value) === null && process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `<ColorPicker> received invalid value=${JSON.stringify(value)}; falling back to ${FALLBACK_HEX}.`,
+        );
+        setWarned(true);
+      }
+    }, [value, warned]);
+
+    // Sync local HSV when the consumer sets a NEW value externally.
+    // We detect "external write" by comparing the normalized prop HEX to our
+    // round-trip HEX of localHsv — if they differ, the consumer set it,
+    // otherwise we set it and don't need to re-sync.
+    useEffect(() => {
+      const ourHex = hsvToHex(localHsv);
+      const propHex = normalizeHex(value);
+      if (propHex && propHex !== ourHex) {
+        const incoming = hexToHsv(propHex);
+        if (incoming) setLocalHsv(incoming);
+      }
+      // Intentionally not depending on localHsv — we are the writer, not the reader.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+
+    // Sync draft input when value changes externally.
+    useEffect(() => {
+      const normalized = normalizeHex(value);
+      if (normalized && normalized !== normalizeHex(draft)) {
+        setDraft(normalized);
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+
+    const updateHsv = useCallback(
+      (next: HSV) => {
+        setLocalHsv(next);
+        onChange(hsvToHex(next));
+      },
+      [onChange],
+    );
+
+    // SV pad handlers.
+    const handleSVChange = useCallback(
+      (s: number, v: number) => {
+        updateHsv({ ...localHsv, s, v });
+      },
+      [localHsv, updateHsv],
+    );
+
+    const handleSVChangeEnd = useCallback(() => {
+      onChangeEnd?.(hsvToHex(localHsv));
+    }, [localHsv, onChangeEnd]);
+
+    // Hue slider handlers. Slider passes number | [number, number]; this
+    // picker uses single-thumb mode so we narrow to number.
+    const handleHueChange = useCallback(
+      (next: number | [number, number]) => {
+        const h = typeof next === 'number' ? next : next[0];
+        updateHsv({ ...localHsv, h });
+      },
+      [localHsv, updateHsv],
+    );
+
+    const handleHueChangeEnd = useCallback(() => {
+      onChangeEnd?.(hsvToHex(localHsv));
+    }, [localHsv, onChangeEnd]);
+
+    // HEX input handlers.
+    const handleHexChange = useCallback(
+      (e: ChangeEvent<HTMLInputElement>) => {
+        const next = e.target.value;
+        setDraft(next);
+        const normalized = normalizeHex(next);
+        if (normalized) {
+          const incoming = hexToHsv(normalized);
+          if (incoming) {
+            setLocalHsv(incoming);
+            onChange(normalized);
+          }
+        }
+      },
+      [onChange],
+    );
+
+    const handleHexBlur = useCallback(() => {
+      const normalized = normalizeHex(draft);
+      if (normalized) {
+        // Re-snap to canonical form (uppercase, with `#`, 6-char).
+        setDraft(normalized);
+        onChangeEnd?.(normalized);
+      } else {
+        // Invalid on blur — revert to the canonical HEX of the current value.
+        setDraft(normalizeHex(value) ?? FALLBACK_HEX);
+      }
+    }, [draft, value, onChangeEnd]);
+
+    const handleHexKeyDown = useCallback((e: KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === 'Enter') {
+        // Trigger blur to commit / revert.
+        e.currentTarget.blur();
+      }
+    }, []);
+
+    // Preset click handler.
+    const handlePresetClick = useCallback(
+      (preset: string) => {
+        const normalized = normalizeHex(preset);
+        if (!normalized) return;
+        const incoming = hexToHsv(normalized);
+        if (!incoming) return;
+        setLocalHsv(incoming);
+        setDraft(normalized);
+        onChange(normalized);
+        onChangeEnd?.(normalized);
+      },
+      [onChange, onChangeEnd],
+    );
+
+    const draftIsValid = normalizeHex(draft) !== null;
+    const currentNormalized = normalizeHex(value) ?? FALLBACK_HEX;
+
+    return (
+      <div
+        ref={ref}
+        className={clsx(
+          styles.panel,
+          !framed && styles.unframed,
+          disabled && styles.panelDisabled,
+          className,
+        )}
+        {...rest}
+      >
+        <SVSquare
+          hue={localHsv.h}
+          s={localHsv.s}
+          v={localHsv.v}
+          onChange={handleSVChange}
+          onChangeEnd={handleSVChangeEnd}
+          disabled={disabled}
+        />
+        <div className={styles.hueSlider}>
+          <Slider
+            value={localHsv.h}
+            onChange={handleHueChange}
+            onChangeEnd={handleHueChangeEnd}
+            min={0}
+            max={360}
+            step={1}
+            disabled={disabled}
+            aria-label={t('colorPicker.hue')}
+          />
+        </div>
+        <Input
+          size="sm"
+          value={draft}
+          onChange={handleHexChange}
+          onBlur={handleHexBlur}
+          onKeyDown={handleHexKeyDown}
+          invalid={!draftIsValid && draft !== ''}
+          disabled={disabled}
+          aria-label={t('colorPicker.hexValue')}
+          className={styles.hexInput}
+          spellCheck={false}
+          autoCapitalize="none"
+          autoComplete="off"
+        />
+        {presets && presets.length > 0 && (
+          <div className={styles.presets} role="group" aria-label={t('colorPicker.presetColors')}>
+            {presets.map((preset, idx) => {
+              const normalized = normalizeHex(preset);
+              if (!normalized) return null;
+              const selected = normalized === currentNormalized;
+              return (
+                <button
+                  key={`${normalized}-${idx}`}
+                  type="button"
+                  className={clsx(styles.presetSwatch, selected && styles.presetSwatchSelected)}
+                  style={{ backgroundColor: normalized }}
+                  aria-label={normalized}
+                  aria-pressed={selected}
+                  disabled={disabled}
+                  onClick={() => handlePresetClick(normalized)}
+                />
+              );
+            })}
+          </div>
+        )}
+      </div>
+    );
+  },
+);