@volter/sdk 0.0.0-stage → 0.5.203

package/src/widgets/inspector-widgets/ScrubbableInput.tsx

@@ -0,0 +1,180 @@
+import { TextInput } from '../design-system';
+/**
+ * ScrubbableInput — a numeric input whose LABEL is a drag-to-scrub handle
+ * (spec 27 §5 C1). Ported from `visual-edit/inspector.tsx`'s `ScrubbableInput`
+ * (:107-219): drag the label left/right to change the number, Shift = ×10,
+ * Alt = ×0.1, Escape cancels back to the drag-start value. Unlike the
+ * reference (which threaded a `prop` string + string value through a
+ * shared style-bag callback), this widget's contract is the kit-wide pure
+ * `value: number` / `onChange` / `onChangeEnd` (see `shared.tsx`'s doc
+ * comment) — `unit` is display-only (appended to the rendered text, stripped
+ * on parse), keeping the value itself a plain number for callers to compose
+ * into whatever CSS string they write.
+ */
+
+import { type ReactNode, useMemo, useRef, useState } from 'react';
+import { type ChangeHandlers, fireChange, fireEnd, rowStyle, THEME } from './shared';
+
+export interface ScrubbableInputProps extends ChangeHandlers<number> {
+  label: ReactNode;
+  unit?: string | undefined;
+  step?: number | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  precision?: number | undefined;
+  testId?: string | undefined;
+  style?: React.CSSProperties | undefined;
+}
+
+export function ScrubbableInput({
+  label,
+  value,
+  unit = '',
+  step = 1,
+  min,
+  max,
+  precision,
+  disabled,
+  onChange,
+  onChangeEnd,
+  testId,
+  style: extraStyle,
+}: ScrubbableInputProps): React.ReactElement {
+  const dragRef = useRef<{ startX: number; startValue: number; last: number } | null>(null);
+
+  const effectivePrecision = precision ?? (step < 1 ? 2 : step >= 100 ? -2 : 0);
+
+  const round = useMemo(
+    () =>
+      (n: number): number => {
+        if (effectivePrecision < 0) {
+          const factor = 10 ** -effectivePrecision;
+          return Math.round(n / factor) * factor;
+        }
+        const factor = 10 ** effectivePrecision;
+        return Math.round(n * factor) / factor;
+      },
+    [effectivePrecision],
+  );
+
+  const clamp = (n: number): number => {
+    let v = n;
+    if (min !== undefined) v = Math.max(min, v);
+    if (max !== undefined) v = Math.min(max, v);
+    return round(v);
+  };
+
+  const handleScrubStart = (e: React.MouseEvent): void => {
+    if (disabled) return;
+    e.preventDefault();
+    dragRef.current = { startX: e.clientX, startValue: value, last: value };
+    document.body.style.cursor = 'ew-resize';
+
+    const handleMove = (me: MouseEvent): void => {
+      if (!dragRef.current) return;
+      me.preventDefault();
+      const delta = me.clientX - dragRef.current.startX;
+      const multiplier = me.shiftKey ? 10 : me.altKey ? 0.1 : 1;
+      const next = clamp(dragRef.current.startValue + delta * step * multiplier);
+      dragRef.current.last = next;
+      fireChange({ onChange }, next);
+    };
+
+    const cleanup = (): void => {
+      document.body.style.cursor = '';
+      window.removeEventListener('mousemove', handleMove);
+      window.removeEventListener('mouseup', handleUp);
+      window.removeEventListener('keydown', handleKeyDuringScrub);
+    };
+
+    const handleUp = (): void => {
+      if (dragRef.current) {
+        const final = dragRef.current.last;
+        dragRef.current = null;
+        fireEnd({ onChange, onChangeEnd }, final);
+      }
+      cleanup();
+    };
+
+    const handleKeyDuringScrub = (ke: KeyboardEvent): void => {
+      if (ke.key === 'Escape' && dragRef.current) {
+        const original = clamp(dragRef.current.startValue);
+        dragRef.current = null;
+        fireChange({ onChange }, original);
+        fireEnd({ onChange, onChangeEnd }, original);
+        cleanup();
+      }
+    };
+
+    window.addEventListener('mousemove', handleMove);
+    window.addEventListener('mouseup', handleUp);
+    window.addEventListener('keydown', handleKeyDuringScrub);
+  };
+
+  // TYPING IS A DRAFT, COMMITTED ONCE. The text field used to be controlled
+  // by the live value and fire `onChange` per keystroke, so the first digit
+  // was WRITTEN, the write re-projected the board, the field re-rendered
+  // from the new value (and lost focus with it) and every later
+  // digit went nowhere — typing 257 into a width left it at 2 (measured on
+  // production build 59; runhuman pass 135: "it changed to 237.3"). While
+  // focused the field shows its own draft, the whole value selected on
+  // entry; Enter or blur commits, Escape cancels. Scrubbing the label is
+  // unchanged — that path IS live by design.
+  const [draft, setDraft] = useState<string | null>(null);
+  const cancelled = useRef(false);
+  const commitText = (raw: string): void => {
+    const n = Number.parseFloat(raw);
+    if (Number.isNaN(n)) return;
+    const next = clamp(n);
+    if (next === value) return;
+    fireEnd({ onChange, onChangeEnd }, next);
+  };
+
+  return (
+    <div style={{ ...rowStyle, ...extraStyle }}>
+      <span
+        className="volter-scrub-label"
+        data-testid={testId ? `${testId}-label` : undefined}
+        onMouseDown={handleScrubStart}
+        data-disabled={disabled || undefined}
+        style={{
+          fontSize: 11,
+          // Resting/hover color comes from `.volter-scrub-label` in theme.css —
+          // an inline color here forced the hover rule into `!important`.
+          ...(disabled ? { color: THEME.dynamic } : {}),
+          flexShrink: 0,
+          cursor: disabled ? 'not-allowed' : 'ew-resize',
+          userSelect: 'none',
+          fontWeight: 500,
+        }}
+      >
+        {label}
+      </span>
+      <TextInput
+        data-testid={testId}
+        type="text"
+        value={draft ?? `${value}${unit}`}
+        readOnly={disabled}
+        data-dynamic={disabled || undefined}
+        onFocus={(e) => {
+          setDraft(`${value}${unit}`);
+          e.target.select();
+        }}
+        onChange={(e) => setDraft(e.target.value)}
+        onBlur={(e) => {
+          if (!cancelled.current) commitText(e.target.value);
+          cancelled.current = false;
+          setDraft(null);
+        }}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') (e.target as HTMLInputElement).blur();
+          if (e.key === 'Escape') {
+            cancelled.current = true;
+            (e.target as HTMLInputElement).blur();
+          }
+        }}
+        style={{ flex: 1, width: 0 }}
+      />
+    </div>
+  );
+}

package/src/widgets/inspector-widgets/ShadowEditor.tsx

@@ -0,0 +1,319 @@
+import { Button, Checkbox } from '../design-system';
+/**
+ * ShadowEditor / TextShadowEditor — a list of box/text shadows (add/remove,
+ * x/y/blur/(spread)/color, inset for box-shadow) (spec 27 §5 C1). Ported from
+ * `visual-edit/inspector.tsx`'s `ShadowEditor`/`ShadowRow` (:632-769) and
+ * `TextShadowEditor`/`TextShadowRow` (:1622-1788) — folded into one generic
+ * `ShadowListEditor` since the two are the same list-of-rows shape with
+ * `spread`/`inset` present only for box-shadow.
+ */
+
+import { ColorSwatch } from './ColorPicker';
+import { rgbStringToHex } from './color-utils';
+import { ScrubbableInput } from './ScrubbableInput';
+import { type ChangeHandlers, fireChange, fireEnd, THEME } from './shared';
+
+export interface ShadowValue {
+  x: number;
+  y: number;
+  blur: number;
+  spread: number;
+  color: string;
+  inset: boolean;
+  enabled: boolean;
+}
+
+export const DEFAULT_SHADOW: ShadowValue = {
+  x: 0,
+  y: 4,
+  blur: 8,
+  spread: 0,
+  color: 'rgba(0,0,0,0.25)',
+  inset: false,
+  enabled: true,
+};
+
+export const DEFAULT_TEXT_SHADOW: ShadowValue = {
+  x: 0,
+  y: 2,
+  blur: 4,
+  spread: 0,
+  color: 'rgba(0,0,0,0.3)',
+  inset: false,
+  enabled: true,
+};
+
+function composeOne(s: ShadowValue, withSpreadInset: boolean): string {
+  const parts = withSpreadInset
+    ? [s.inset ? 'inset' : '', `${s.x}px`, `${s.y}px`, `${s.blur}px`, `${s.spread}px`, s.color]
+    : [`${s.x}px`, `${s.y}px`, `${s.blur}px`, s.color];
+  return parts.filter(Boolean).join(' ');
+}
+
+/** `boxShadow`/`textShadow` CSS string <-> the widget's `ShadowValue[]`. */
+export function composeShadows(shadows: ShadowValue[], withSpreadInset = true): string {
+  const enabled = shadows.filter((s) => s.enabled);
+  if (enabled.length === 0) return 'none';
+  return enabled.map((s) => composeOne(s, withSpreadInset)).join(', ');
+}
+
+/** Pulls the color token (`rgba(...)`/hex) out of a shadow's numeric-part
+ *  tail -> `{color, nums}` (nums = whatever's left to parse as x/y/blur/
+ *  spread). Split out of `parseOne` to keep it under biome's
+ *  cognitive-complexity ceiling. */
+function extractShadowColor(rest: string): { color: string; nums: string } {
+  const rgbMatch = rest.match(/(rgba?\([^)]+\))/);
+  if (rgbMatch?.[1]) return { color: rgbMatch[1], nums: rest.replace(rgbMatch[1], '').trim() };
+  const hexMatch = rest.match(/(#[0-9a-fA-F]{3,8})/);
+  if (hexMatch?.[1]) return { color: hexMatch[1], nums: rest.replace(hexMatch[1], '').trim() };
+  return { color: '#000000', nums: rest };
+}
+
+function parseOne(value: string, withSpreadInset: boolean): Omit<ShadowValue, 'enabled'> | null {
+  if (!value || value === 'none') return null;
+  const v = value.trim();
+  const inset = withSpreadInset && v.startsWith('inset');
+  const rest = inset ? v.slice(5).trim() : v;
+  const { color, nums } = extractShadowColor(rest);
+  const parts = nums
+    .split(/\s+/)
+    .map((s) => Number.parseFloat(s))
+    .filter((n) => !Number.isNaN(n));
+  if (withSpreadInset) {
+    return {
+      inset,
+      x: parts[0] ?? 0,
+      y: parts[1] ?? 0,
+      blur: parts[2] ?? 0,
+      spread: parts[3] ?? 0,
+      color,
+    };
+  }
+  if (parts.length < 2) return null;
+  return {
+    inset: false,
+    x: parts[0] ?? 0,
+    y: parts[1] ?? 0,
+    blur: parts[2] ?? 0,
+    spread: 0,
+    color,
+  };
+}
+
+export function parseShadows(value: string, withSpreadInset = true): ShadowValue[] {
+  if (!value || value === 'none') return [];
+  const parts = value.split(/,\s*(?![^(]*\))/);
+  const result: ShadowValue[] = [];
+  for (const part of parts) {
+    const p = parseOne(part.trim(), withSpreadInset);
+    if (p) result.push({ ...p, enabled: true });
+  }
+  return result;
+}
+
+export interface ShadowListEditorProps extends ChangeHandlers<ShadowValue[]> {
+  /** `false` for text-shadow: hides the spread/inset controls. */
+  withSpreadInset?: boolean | undefined;
+  label?: string | undefined;
+  testId?: string | undefined;
+  recentColors?: string[] | undefined;
+  onAddRecentColor?: ((color: string) => void) | undefined;
+}
+
+export function ShadowListEditor({
+  value,
+  onChange,
+  onChangeEnd,
+  disabled,
+  withSpreadInset = true,
+  label = 'Shadow',
+  testId = 'shadow-editor',
+  recentColors,
+  onAddRecentColor,
+}: ShadowListEditorProps): React.ReactElement {
+  const apply = (next: ShadowValue[], commit: boolean): void => {
+    if (commit) fireEnd({ onChange, onChangeEnd }, next);
+    else fireChange({ onChange }, next);
+  };
+
+  const update = (index: number, partial: Partial<ShadowValue>, commit = false): void => {
+    apply(
+      value.map((s, i) => (i === index ? { ...s, ...partial } : s)),
+      commit,
+    );
+  };
+
+  const remove = (index: number): void => {
+    apply(
+      value.filter((_, i) => i !== index),
+      true,
+    );
+  };
+
+  const add = (): void => {
+    apply([...value, { ...(withSpreadInset ? DEFAULT_SHADOW : DEFAULT_TEXT_SHADOW) }], true);
+  };
+
+  return (
+    <div data-testid={testId}>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 6,
+          marginBottom: value.length > 0 ? 4 : 0,
+        }}
+      >
+        <span style={{ fontSize: 9, color: THEME.textMuted }}>{label}</span>
+        <div style={{ flex: 1 }} />
+        {!disabled && (
+          <Button
+            type="button"
+            variant="ghost"
+            size="compact"
+            data-testid={`${testId}-add`}
+            onClick={add}
+          >
+            +
+          </Button>
+        )}
+      </div>
+      {value.map((shadow, i) => {
+        const hexColor = shadow.color.startsWith('#') ? shadow.color : rgbStringToHex(shadow.color);
+        return (
+          <div
+            key={i}
+            data-testid={`${testId}-row-${i}`}
+            style={{ marginBottom: 6, padding: '4px 0', borderBottom: `1px solid ${THEME.border}` }}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', gap: 4, marginBottom: 4 }}>
+              <Button
+                type="button"
+                variant="ghost"
+                size="compact"
+                aria-pressed={shadow.enabled}
+                data-testid={`${testId}-toggle-${i}`}
+                onClick={() => {
+                  if (!disabled) update(i, { enabled: !shadow.enabled }, true);
+                }}
+              >
+                {shadow.enabled ? '●' : '○'}
+              </Button>
+              <ColorSwatch
+                testId={`${testId}-color-${i}`}
+                value={hexColor}
+                disabled={disabled}
+                onChange={(c) => update(i, { color: c })}
+                onChangeEnd={(c) => update(i, { color: c }, true)}
+                recentColors={recentColors}
+                onAddRecentColor={onAddRecentColor}
+              />
+              {withSpreadInset && (
+                <label
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 2,
+                    fontSize: 8,
+                    color: THEME.textMuted,
+                    cursor: 'pointer',
+                  }}
+                >
+                  <Checkbox
+                    // Standard checkbox size via the shared class (I-30: this
+                    // was the one checkbox in the codebase with its own 10px
+                    // explicit dimensions).
+                    className="volter-checkbox"
+                    data-testid={`${testId}-inset-${i}`}
+                    checked={shadow.inset}
+                    disabled={disabled}
+                    onChange={(e) => update(i, { inset: e.target.checked }, true)}
+                  />
+                  in
+                </label>
+              )}
+              <div style={{ flex: 1 }} />
+              {!disabled && (
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="compact"
+                  aria-label={`Remove ${label.toLowerCase()} ${i + 1}`}
+                  data-testid={`${testId}-remove-${i}`}
+                  onClick={() => remove(i)}
+                >
+                  ×
+                </Button>
+              )}
+            </div>
+            {shadow.enabled && (
+              <div style={{ display: 'flex', gap: 4 }}>
+                <ScrubbableInput
+                  label="X"
+                  value={shadow.x}
+                  disabled={disabled}
+                  onChange={(v) => update(i, { x: v })}
+                  onChangeEnd={(v) => update(i, { x: v }, true)}
+                  style={{ flex: 1 }}
+                />
+                <ScrubbableInput
+                  label="Y"
+                  value={shadow.y}
+                  disabled={disabled}
+                  onChange={(v) => update(i, { y: v })}
+                  onChangeEnd={(v) => update(i, { y: v }, true)}
+                  style={{ flex: 1 }}
+                />
+                <ScrubbableInput
+                  label="B"
+                  value={shadow.blur}
+                  min={0}
+                  disabled={disabled}
+                  onChange={(v) => update(i, { blur: Math.max(0, v) })}
+                  onChangeEnd={(v) => update(i, { blur: Math.max(0, v) }, true)}
+                  style={{ flex: 1 }}
+                />
+                {withSpreadInset && (
+                  <ScrubbableInput
+                    label="S"
+                    value={shadow.spread}
+                    disabled={disabled}
+                    onChange={(v) => update(i, { spread: v })}
+                    onChangeEnd={(v) => update(i, { spread: v }, true)}
+                    style={{ flex: 1 }}
+                  />
+                )}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+export function ShadowEditor(
+  props: Omit<ShadowListEditorProps, 'withSpreadInset' | 'testId'>,
+): React.ReactElement {
+  return (
+    <ShadowListEditor
+      {...props}
+      withSpreadInset
+      testId="box-shadow-editor"
+      label={props.label ?? 'Shadow'}
+    />
+  );
+}
+
+export function TextShadowEditor(
+  props: Omit<ShadowListEditorProps, 'withSpreadInset' | 'testId'>,
+): React.ReactElement {
+  return (
+    <ShadowListEditor
+      {...props}
+      withSpreadInset={false}
+      testId="text-shadow-editor"
+      label={props.label ?? 'Text Shadow'}
+    />
+  );
+}

package/src/widgets/inspector-widgets/color-utils.ts

@@ -0,0 +1,201 @@
+/**
+ * Color math for the inspector widget kit (spec 27 §5 C1). Ported from
+ * `visual-edit/inspector.tsx`'s free-floating hex/rgb/hsv/hsl helpers
+ * (993-1035:2781-2855) — pure functions, zero deps, zero DOM. Colour-CHAIN
+ * resolution (the eyedropper's "what's the effective background here" logic)
+ * is NOT re-implemented here — that's `effectiveColorFromChain` in
+ * `ui-source/inspect.ts`, reused as-is by `ColorPicker.tsx`.
+ */
+
+export type ColorFormat = 'hex' | 'rgb' | 'hsl';
+
+export function hexToRgb(hex: string): [number, number, number] {
+  let h = hex.replace('#', '');
+  if (h.length === 3)
+    h = `${h[0] ?? '0'}${h[0] ?? '0'}${h[1] ?? '0'}${h[1] ?? '0'}${h[2] ?? '0'}${h[2] ?? '0'}`;
+  const n = Number.parseInt(h, 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+export function rgbToHex(r: number, g: number, b: number): string {
+  return `#${[r, g, b]
+    .map((c) =>
+      Math.round(Math.max(0, Math.min(255, c)))
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`;
+}
+
+export function rgbToHsv(r: number, g: number, b: number): [number, number, 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 d = max - min;
+  let h = 0;
+  if (d !== 0) {
+    if (max === rn) h = ((((gn - bn) / d) % 6) + 6) % 6;
+    else if (max === gn) h = (bn - rn) / d + 2;
+    else h = (rn - gn) / d + 4;
+    h /= 6;
+  }
+  const s = max === 0 ? 0 : d / max;
+  return [h, s, max];
+}
+
+export function hsvToRgb(h: number, s: number, v: number): [number, number, number] {
+  const i = Math.floor(h * 6);
+  const f = h * 6 - i;
+  const p = v * (1 - s);
+  const q = v * (1 - f * s);
+  const t = v * (1 - (1 - f) * s);
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  switch (i % 6) {
+    case 0:
+      r = v;
+      g = t;
+      b = p;
+      break;
+    case 1:
+      r = q;
+      g = v;
+      b = p;
+      break;
+    case 2:
+      r = p;
+      g = v;
+      b = t;
+      break;
+    case 3:
+      r = p;
+      g = q;
+      b = v;
+      break;
+    case 4:
+      r = t;
+      g = p;
+      b = v;
+      break;
+    case 5:
+      r = v;
+      g = p;
+      b = q;
+      break;
+    default:
+      break;
+  }
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+
+export function hsvToHex(h: number, s: number, v: number): string {
+  const [r, g, b] = hsvToRgb(h, s, v);
+  return rgbToHex(r, g, b);
+}
+
+export function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  let r: number;
+  let g: number;
+  let b: number;
+  if (s === 0) {
+    r = g = b = l;
+  } else {
+    const hue2rgb = (p: number, q: number, t0: number): number => {
+      let t = t0;
+      if (t < 0) t += 1;
+      if (t > 1) t -= 1;
+      if (t < 1 / 6) return p + (q - p) * 6 * t;
+      if (t < 1 / 2) return q;
+      if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+      return p;
+    };
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    r = hue2rgb(p, q, h + 1 / 3);
+    g = hue2rgb(p, q, h);
+    b = hue2rgb(p, q, h - 1 / 3);
+  }
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+
+export function rgbToHsl(r: number, g: number, b: number): [number, number, 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);
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === rn) h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6;
+    else if (max === gn) h = ((bn - rn) / d + 2) / 6;
+    else h = ((rn - gn) / d + 4) / 6;
+  }
+  return [h, s, l];
+}
+
+/** Normalize any hex/rgb(a)/hsl(a) string to a 6-digit hex (alpha dropped). */
+export function toHex(color: string): string {
+  if (color.startsWith('#') && (color.length === 4 || color.length === 7)) return color;
+  if (color.startsWith('#') && color.length === 9) return color.slice(0, 7); // strip alpha from #RRGGBBAA
+  const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+  if (m) {
+    const [, r, g, b] = m;
+    return `#${[r ?? '0', g ?? '0', b ?? '0'].map((c) => Number.parseInt(c, 10).toString(16).padStart(2, '0')).join('')}`;
+  }
+  const hsl = color.match(/hsla?\((\d+),\s*(\d+)%?,\s*(\d+)%?/);
+  if (hsl) {
+    const [r, g, b] = hslToRgb(
+      Number.parseInt(hsl[1] ?? '0', 10) / 360,
+      Number.parseInt(hsl[2] ?? '0', 10) / 100,
+      Number.parseInt(hsl[3] ?? '0', 10) / 100,
+    );
+    return rgbToHex(r, g, b);
+  }
+  return '#000000';
+}
+
+export function parseAlpha(color: string): number {
+  const rgbaMatch = color.match(/rgba\([^,]+,[^,]+,[^,]+,\s*([\d.]+)\)/);
+  if (rgbaMatch?.[1]) return Number.parseFloat(rgbaMatch[1]);
+  const hslaMatch = color.match(/hsla\([^,]+,[^,]+,[^,]+,\s*([\d.]+)\)/);
+  if (hslaMatch?.[1]) return Number.parseFloat(hslaMatch[1]);
+  if (color.startsWith('#') && color.length === 9)
+    return Number.parseInt(color.slice(7, 9), 16) / 255;
+  return 1;
+}
+
+export function colorToString(
+  r: number,
+  g: number,
+  b: number,
+  a: number,
+  format: ColorFormat,
+): string {
+  if (format === 'hex') {
+    const hex = rgbToHex(r, g, b);
+    return a < 1 ? `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})` : hex;
+  }
+  if (format === 'rgb') {
+    return a < 1 ? `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})` : `rgb(${r}, ${g}, ${b})`;
+  }
+  const [h, s, l] = rgbToHsl(r, g, b);
+  const hDeg = Math.round(h * 360);
+  const sPct = Math.round(s * 100);
+  const lPct = Math.round(l * 100);
+  return a < 1
+    ? `hsla(${hDeg}, ${sPct}%, ${lPct}%, ${a.toFixed(2)})`
+    : `hsl(${hDeg}, ${sPct}%, ${lPct}%)`;
+}
+
+export function rgbStringToHex(rgb: string): string {
+  const m = rgb.match(/\d+/g);
+  if (!m || m.length < 3) return '#000000';
+  return `#${[m[0] ?? '0', m[1] ?? '0', m[2] ?? '0'].map((n) => Number.parseInt(n, 10).toString(16).padStart(2, '0')).join('')}`;
+}