@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/color-area/engine.ts

@@ -0,0 +1,246 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { numberFormat } from '../../core/dates';
+import { CHANNEL_LABELS, areaBackground, channelText, formatColor, sameColor, toHex, toHsva, type Hsva } from '../../core/color';
+
+/*
+ * Color area: the saturation (x) × brightness (y) square at the current hue.
+ * Pressing jumps the thumb there (swing glide, .35 s), then it follows the
+ * pointer tightly (.1 s); release commits. Two visually hidden range inputs
+ * (Saturación, Brillo) carry the value for assistive tech and the keyboard:
+ * ←/→ saturation, ↑/↓ brightness, Shift ×10, PageUp/PageDown brightness ±10,
+ * Home/End saturation min/max. Grabbing grows the thumb (click curve) and pops
+ * a loupe with the colour, like color-slider; near the top edge the loupe flips
+ * below the thumb ([data-mk-loupe-below]), so a panel that clips its content
+ * (the color-picker popover) never cuts it. Vars: --mk-color-area,
+ * --mk-color-thumb, --mk-color-x, --mk-color-y.
+ */
+
+export interface ColorAreaOptions {
+  value?: string | Hsva;
+  /** Accessible name of the group (default 'Color'). */
+  label?: string;
+  /** Default 1. */
+  step?: number;
+  name?: string;
+  disabled?: boolean;
+  onInput?: (value: string, color: Hsva) => void;
+  onChange?: (value: string, color: Hsva) => void;
+}
+
+export interface ColorAreaInstance extends Instance {
+  setColor(color: string | Hsva, notify?: boolean): void;
+  readonly value: string;
+  readonly color: Hsva;
+}
+
+/** Room the loupe needs above the thumb's centre (thumb half, gap, loupe), in px. */
+const LOUPE_ROOM = 70;
+
+const KEYS: Record<string, ['s' | 'v', number]> = {
+  ArrowLeft: ['s', -1],
+  ArrowRight: ['s', 1],
+  ArrowUp: ['v', 1],
+  ArrowDown: ['v', -1],
+  PageUp: ['v', 10],
+  PageDown: ['v', -10],
+  Home: ['s', -Infinity],
+  End: ['s', Infinity],
+};
+
+export function createColorArea(root: HTMLElement | null, options: ColorAreaOptions = {}): ColorAreaInstance {
+  if (!root) return inert({ setColor() {}, value: '', color: { h: 0, s: 0, v: 0, a: 1 } });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+  scope.attr(root, 'style', root.getAttribute('style'));
+
+  const step = options.step && options.step > 0 ? options.step : 1;
+  let color = toHsva(options.value ?? 'hsl(0 100% 50%)');
+  const format = numberFormat(root, { maximumFractionDigits: 0 });
+
+  const made: Element[] = [];
+  const surface = document.createElement('div');
+  surface.dataset.mkColorAreaSurface = '';
+  surface.setAttribute('role', 'group');
+  surface.setAttribute('aria-label', options.label ?? 'Color');
+  const thumb = document.createElement('span');
+  thumb.dataset.mkColorThumb = '';
+  thumb.setAttribute('aria-hidden', 'true');
+  const loupe = document.createElement('span');
+  loupe.dataset.mkColorLoupe = '';
+  thumb.append(loupe);
+  surface.append(thumb);
+  const range = (axis: 'x' | 'y', label: string) => {
+    const input = document.createElement('input');
+    input.type = 'range';
+    input.className = 'mk-sr-only';
+    input.dataset.mkColorInput = axis;
+    input.min = '0';
+    input.max = '100';
+    input.step = String(step);
+    input.disabled = Boolean(options.disabled);
+    input.setAttribute('aria-label', label);
+    input.setAttribute('aria-roledescription', 'selector de color 2D');
+    surface.append(input);
+    return input;
+  };
+  const inputs = { x: range('x', CHANNEL_LABELS.saturation), y: range('y', CHANNEL_LABELS.brightness) };
+  root.append(surface);
+  made.push(surface);
+  let hidden: HTMLInputElement | null = null;
+  if (options.name) {
+    hidden = document.createElement('input');
+    hidden.type = 'hidden';
+    hidden.name = options.name;
+    root.append(hidden);
+    made.push(hidden);
+  }
+  scope.add(() => made.forEach((node) => node.remove()));
+  scope.attr(root, 'data-mk-grabbing', null);
+  scope.attr(root, 'data-mk-loupe-below', null);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const snap = (n: number) => Math.min(100, Math.max(0, Math.round(n / step) * step));
+  const shown = { x: 0, y: 0 };
+  let glide: gsap.core.Tween | null = null;
+  scope.add(() => {
+    glide?.kill();
+    gsap.killTweensOf([thumb, loupe]);
+  });
+  const place = () => {
+    root.style.setProperty('--mk-color-x', String(Number(shown.x.toFixed(4))));
+    root.style.setProperty('--mk-color-y', String(Number(shown.y.toFixed(4))));
+  };
+  const paint = (mode: 'set' | 'drag' | 'glide') => {
+    const text = `${CHANNEL_LABELS.saturation} ${channelText('saturation', color.s, format)}, ${CHANNEL_LABELS.brightness.toLowerCase()} ${channelText('brightness', color.v, format)}`;
+    root.style.setProperty('--mk-color-area', areaBackground(color.h));
+    root.style.setProperty('--mk-color-thumb', formatColor(color, 'rgb'));
+    inputs.x.value = String(color.s);
+    inputs.y.value = String(color.v);
+    for (const input of [inputs.x, inputs.y]) input.setAttribute('aria-valuetext', text);
+    if (hidden) hidden.value = toHex(color);
+    const target = { x: color.s / 100, y: 1 - color.v / 100 };
+    const height = surface.getBoundingClientRect().height;
+    root.toggleAttribute('data-mk-loupe-below', height > 0 && target.y * height < LOUPE_ROOM);
+    glide?.kill();
+    if (mode === 'set' || reduced()) {
+      Object.assign(shown, target);
+      place();
+      return;
+    }
+    glide = gsap.to(shown, { ...target, duration: mode === 'drag' ? 0.1 : 0.35, ease: mode === 'drag' ? 'power3.out' : EASE.swatch, onUpdate: place });
+  };
+
+  const emit = (type: 'input' | 'change') => {
+    const value = toHex(color);
+    (type === 'input' ? options.onInput : options.onChange)?.(value, { ...color });
+    root.dispatchEvent(new CustomEvent(`mk:${type}`, { bubbles: true, detail: { value, color: { ...color } } }));
+  };
+
+  let grabbed = false;
+  const grab = (on: boolean) => {
+    if (grabbed === on) return;
+    grabbed = on;
+    root.toggleAttribute('data-mk-grabbing', on);
+    if (reduced()) return;
+    keep(gsap.to(thumb, { scale: on ? 1.25 : 1, duration: 0.25, ease: EASE.click }));
+    if (on) keep(gsap.fromTo(loupe, { scale: 0.6, opacity: 0, filter: 'blur(6px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: 0.3, ease: EASE.pop }));
+    else keep(gsap.to(loupe, { scale: 0.8, opacity: 0, filter: 'blur(6px)', duration: 0.2, ease: 'power2.in' }));
+  };
+
+  const fromPoint = (event: PointerEvent) => {
+    const rect = surface.getBoundingClientRect();
+    if (!rect.width || !rect.height) return;
+    const s = ((event.clientX - rect.left) / rect.width) * 100;
+    const v = (1 - (event.clientY - rect.top) / rect.height) * 100;
+    color = { ...color, s: snap(s), v: snap(v) };
+  };
+  let dragging = false;
+  scope.on(surface, 'pointerdown', (event) => {
+    const down = event as PointerEvent;
+    if (options.disabled || down.button !== 0 || down.target instanceof HTMLInputElement) return;
+    down.preventDefault();
+    try {
+      surface.setPointerCapture(down.pointerId);
+    } catch {
+      // jsdom and synthetic events have no active pointer to capture.
+    }
+    dragging = true;
+    grab(true);
+    fromPoint(down);
+    paint('glide');
+    emit('input');
+    inputs.x.focus({ preventScroll: true });
+  });
+  scope.on(surface, 'pointermove', (event) => {
+    if (!dragging) return;
+    fromPoint(event as PointerEvent);
+    paint('drag');
+    emit('input');
+  });
+  const release = () => {
+    if (!dragging) return;
+    dragging = false;
+    grab(false);
+    emit('change');
+  };
+  for (const type of ['pointerup', 'pointercancel', 'lostpointercapture']) scope.on(surface, type, release);
+
+  for (const input of [inputs.x, inputs.y]) {
+    scope.on(input, 'keydown', (event) => {
+      const key = event as KeyboardEvent;
+      const move = KEYS[key.key];
+      if (!move || options.disabled) return;
+      key.preventDefault();
+      const [axis, amount] = move;
+      const delta = Number.isFinite(amount) ? amount * step * (key.shiftKey ? 10 : 1) : amount;
+      color = { ...color, [axis]: snap(Math.min(100, Math.max(0, color[axis] + delta))) };
+      paint('glide');
+      emit('input');
+      emit('change');
+    });
+    // Assistive tech can set a range's value directly.
+    scope.on(input, 'input', () => {
+      color = { ...color, s: snap(Number(inputs.x.value)), v: snap(Number(inputs.y.value)) };
+      paint('glide');
+      emit('input');
+    });
+    scope.on(input, 'change', () => emit('change'));
+  }
+
+  paint('set');
+
+  return {
+    setColor(next, notify = true) {
+      if (scope.disposed) return;
+      const target = toHsva(next, color);
+      if (sameColor(target, color) && target.h === color.h) return;
+      color = target;
+      paint('glide');
+      if (notify) {
+        emit('input');
+        emit('change');
+      }
+    },
+    get value() {
+      return toHex(color);
+    },
+    get color() {
+      return { ...color };
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/color-area/react.tsx

@@ -0,0 +1,42 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { toHex, toHsva } from '../../core/color';
+import { createColorArea, type ColorAreaInstance, type ColorAreaOptions } from './engine';
+
+export interface ColorAreaProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onInput' | 'onChange' | 'defaultValue'>, Omit<ColorAreaOptions, 'value'> {
+  /** Controlled colour; without it the area keeps its own (defaultValue). */
+  value?: string;
+  defaultValue?: string;
+}
+
+/** <ColorArea value={color} onInput={setColor} />. */
+export function ColorArea({ value, defaultValue, label, step, name, disabled, onInput, onChange, className, ...props }: ColorAreaProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ColorAreaInstance | null>(null);
+  const input = useLatest(onInput);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue);
+  useIsomorphicLayoutEffect(() => {
+    const created = createColorArea(ref.current, {
+      value: value ?? start.current,
+      label,
+      step,
+      name,
+      disabled,
+      onInput: (hex, color) => input.current?.(hex, color),
+      onChange: (hex, color) => change.current?.(hex, color),
+    });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [label, step, name, disabled]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== toHex(toHsva(value))) instance.current.setColor(value, false);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-color-area', className].filter(Boolean).join(' ')} />;
+}

package/src/components/color-field/README.md

@@ -0,0 +1,43 @@
+# color-field
+
+Campo de texto para colores con una muestra al lado. Acepta todo lo que lee `parseColor`: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()` y `hsl()`/`hsla()` (con comas o espacios y `/ alfa`).
+
+Mientras escribes, un color válido pinta la muestra (transición de 0,25 s); un texto que aún no es color marca la muestra con un borde discontinuo. Enter o salir del campo lo confirman: un color válido se reescribe en el formato elegido y la muestra rebota (curva pop); uno no válido o vacío sacude el campo, vuelve al último color válido y un estado discreto anuncia «Color no válido». Escape devuelve el último color.
+
+## HTML / Astro
+
+```html
+<mk-color-field class="mk-color-field" value="#ff8800"></mk-color-field>
+<mk-color-field class="mk-color-field" value="#ff8800" format="rgb" alpha></mk-color-field>
+
+<!-- Con tu propio input y etiqueta: se reutiliza y se devuelve tal cual al destruir. -->
+<label class="mk-color-field" data-mk="color-field">Fondo <input name="fondo" value="#123456" /></label>
+```
+
+## React
+
+```tsx
+<ColorField value={color} onChange={setColor} format="hsl" />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `value` | `value` | el valor del input, o negro | Color de partida. |
+| `format` | `format` | `'hex'` | Cómo se escribe al confirmar: `hex`, `rgb` o `hsl`. |
+| `alpha` | `alpha` | `false` | Conserva la transparencia; sin él, los colores se confirman opacos. |
+| `label` | `label` | `'Color'` | `aria-label` si el input no tiene etiqueta propia. |
+| `name` | `name` | — | Nombre del input en el formulario (envía el texto). |
+| `disabled`, `readOnly` | `disabled`, `read-only` | `false` | Estados del input. |
+| `onChange(hex, hsva)` | — | — | Al confirmar un color nuevo. |
+
+## API y eventos
+
+`setColor(color, notify = true)`, `value` (hex), `color` (HSVA), `destroy()`. Evento `mk:change` con `{ value, color }`.
+
+## Variables CSS
+
+`--mk-color-checker` (damero bajo los colores translúcidos). El motor escribe `--mk-color-swatch`. Campo de 12 px, muestra de 8 px.
+
+Con movimiento reducido no hay sacudida ni rebote: el texto vuelve igual y el estado lo anuncia.

package/src/components/color-field/color-field.css

@@ -0,0 +1,66 @@
+/* color-field — a 12 px field on surface-3 with a colour swatch (8 px corners, checkerboard under translucent colours)
+   and a mono text input; focus draws a 3 px accent ring; an unparsed text dashes the swatch. */
+.mk-color-field,
+mk-color-field {
+  --mk-color-checker: repeating-conic-gradient(#d4d4d4 0 25%, #fff 0 50%) 0 0 / 8px 8px;
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  min-width: 0;
+  height: 2.75rem;
+  padding: 0 0.75rem 0 0.5rem;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  transition: box-shadow 0.2s ease;
+}
+
+:is(.mk-color-field, mk-color-field):focus-within {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+:is(.mk-color-field, mk-color-field) [data-mk-color-swatch] {
+  flex: none;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: 8px;
+  background: linear-gradient(var(--mk-color-swatch), var(--mk-color-swatch)), var(--mk-color-checker);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-text) 22%, transparent);
+  transition: background 0.25s ease;
+}
+
+:is(.mk-color-field, mk-color-field)[data-mk-unparsed] [data-mk-color-swatch] {
+  outline: 2px dashed var(--mk-muted);
+  outline-offset: 2px;
+}
+
+:is(.mk-color-field, mk-color-field) [data-mk-color-text] {
+  flex: 1;
+  min-width: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: 500 0.9375rem/1 var(--mk-font-mono, ui-monospace, monospace);
+  text-overflow: ellipsis;
+  outline: none;
+}
+
+:is(.mk-color-field, mk-color-field) [data-mk-color-status] {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-color-field, mk-color-field) {
+    transition: none;
+  }
+
+  :is(.mk-color-field, mk-color-field) [data-mk-color-swatch] {
+    transition: none;
+  }
+}

package/src/components/color-field/element.ts

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createColorField, type ColorFieldInstance } from './engine';
+
+/**
+ * <mk-color-field class="mk-color-field" value="#ff8800" format="hex"></mk-color-field>
+ * Emits mk:change ({value, color}) when a new colour is committed.
+ */
+export class MkColorFieldElement extends MkElement<ColorFieldInstance> {
+  static options: Record<string, OptionType> = { value: 'string', format: 'string', alpha: 'boolean', label: 'string', name: 'string', disabled: 'boolean', readOnly: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createColorField(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value' && next) this.instance.setColor(next, false);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+}
+
+export const defineColorField = () => defineElement('mk-color-field', MkColorFieldElement);

package/src/components/color-field/engine.ts

@@ -0,0 +1,174 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { formatColor, parseColor, sameColor, toHex, toHsva, type ColorFormat, type Hsva } from '../../core/color';
+import { shake } from '../../motion/micro';
+
+/*
+ * Color field: a text input that takes any colour parseColor reads (hex, rgb(),
+ * hsl()) beside a swatch. While typing, a readable colour paints the swatch
+ * (CSS transition .25 s). Enter or blur commits: a valid colour is rewritten in
+ * `format` and the swatch pops (pop curve); an invalid or empty text shakes the
+ * field, goes back to the last valid colour and a polite status says
+ * "Color no válido". Escape puts the last colour back. Without `alpha`, colours
+ * are committed opaque. Var: --mk-color-swatch.
+ */
+
+export interface ColorFieldOptions {
+  value?: string | Hsva;
+  format?: ColorFormat;
+  /** Keep transparency (default false: committed colours are opaque). */
+  alpha?: boolean;
+  /** aria-label when the input has no label of its own (default 'Color'). */
+  label?: string;
+  name?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  onChange?: (value: string, color: Hsva) => void;
+}
+
+export interface ColorFieldInstance extends Instance {
+  setColor(color: string | Hsva, notify?: boolean): void;
+  readonly value: string;
+  readonly color: Hsva;
+}
+
+export function createColorField(root: HTMLElement | null, options: ColorFieldOptions = {}): ColorFieldInstance {
+  if (!root) return inert({ setColor() {}, value: '', color: { h: 0, s: 0, v: 0, a: 1 } });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+  scope.attr(root, 'style', root.getAttribute('style'));
+
+  const format: ColorFormat = options.format === 'rgb' || options.format === 'hsl' ? options.format : 'hex';
+  const alpha = Boolean(options.alpha);
+
+  let input = root.querySelector('input');
+  if (!input) {
+    input = document.createElement('input');
+    input.type = 'text';
+    root.append(input);
+    const created = input;
+    scope.add(() => created.remove());
+  }
+  const field = input;
+  const original = field.value;
+  scope.add(() => {
+    field.value = original;
+  });
+  scope.attr(field, 'data-mk-color-text', '');
+  scope.attr(field, 'autocomplete', 'off');
+  scope.attr(field, 'spellcheck', 'false');
+  scope.attr(field, 'autocapitalize', 'off');
+  if (options.name) scope.attr(field, 'name', options.name);
+  if (options.disabled) scope.attr(field, 'disabled', '');
+  if (options.readOnly) scope.attr(field, 'readonly', '');
+  const labelled = field.closest('label') || field.labels?.length || field.hasAttribute('aria-label') || field.hasAttribute('aria-labelledby');
+  if (!labelled) scope.attr(field, 'aria-label', options.label ?? 'Color');
+
+  const swatch = document.createElement('span');
+  swatch.dataset.mkColorSwatch = '';
+  swatch.setAttribute('aria-hidden', 'true');
+  field.before(swatch);
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.dataset.mkColorStatus = '';
+  status.setAttribute('role', 'status');
+  root.append(status);
+  scope.add(() => {
+    swatch.remove();
+    status.remove();
+    gsap.killTweensOf(swatch);
+  });
+  scope.attr(root, 'data-mk-unparsed', null);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const opaque = (color: Hsva) => (alpha ? color : { ...color, a: 1 });
+  let color = opaque(toHsva(options.value ?? (field.value || undefined), { h: 0, s: 0, v: 0, a: 1 }));
+  const text = () => formatColor(color, format);
+  const paintSwatch = (shown: Hsva) => root.style.setProperty('--mk-color-swatch', formatColor(shown, 'rgb'));
+  const pop = () => {
+    if (!reduced()) keep(gsap.fromTo(swatch, { scale: 1.18 }, { scale: 1, duration: 0.3, ease: EASE.pop, clearProps: 'scale,transform' }));
+  };
+  const emit = () => {
+    const value = toHex(color);
+    options.onChange?.(value, { ...color });
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value, color: { ...color } } }));
+  };
+
+  field.value = text();
+  paintSwatch(color);
+
+  scope.on(field, 'input', () => {
+    const parsed = parseColor(field.value, color.h);
+    if (parsed) paintSwatch(opaque(parsed));
+    root.toggleAttribute('data-mk-unparsed', !parsed && field.value.trim() !== '');
+  });
+
+  const commit = () => {
+    const parsed = parseColor(field.value, color.h);
+    root.removeAttribute('data-mk-unparsed');
+    if (!parsed) {
+      keep(shake(root));
+      field.value = text();
+      paintSwatch(color);
+      status.textContent = 'Color no válido';
+      return;
+    }
+    const next = opaque(parsed);
+    const changed = !sameColor(next, color);
+    color = next;
+    field.value = text();
+    paintSwatch(color);
+    status.textContent = '';
+    if (!changed) return;
+    pop();
+    emit();
+  };
+  scope.on(field, 'blur', commit);
+  scope.on(field, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if (key === 'Enter') {
+      event.preventDefault();
+      commit();
+    } else if (key === 'Escape' && field.value !== text()) {
+      event.preventDefault();
+      field.value = text();
+      paintSwatch(color);
+      root.removeAttribute('data-mk-unparsed');
+    }
+  });
+
+  return {
+    setColor(next, notify = true) {
+      if (scope.disposed) return;
+      const target = opaque(toHsva(next, color));
+      const changed = !sameColor(target, color);
+      color = target;
+      field.value = text();
+      paintSwatch(color);
+      root.removeAttribute('data-mk-unparsed');
+      if (!changed) return;
+      pop();
+      if (notify) emit();
+    },
+    get value() {
+      return toHex(color);
+    },
+    get color() {
+      return { ...color };
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/color-field/react.tsx

@@ -0,0 +1,42 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { toHex, toHsva } from '../../core/color';
+import { createColorField, type ColorFieldInstance, type ColorFieldOptions } from './engine';
+
+export interface ColorFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<ColorFieldOptions, 'value'> {
+  /** Controlled colour; without it the field keeps its own (defaultValue). */
+  value?: string;
+  defaultValue?: string;
+}
+
+/** <ColorField value={color} onChange={setColor} format="rgb" />. The engine creates the input. */
+export function ColorField({ value, defaultValue, format, alpha, label, name, disabled, readOnly, onChange, className, ...props }: ColorFieldProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ColorFieldInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue);
+  useIsomorphicLayoutEffect(() => {
+    const created = createColorField(ref.current, {
+      value: value ?? start.current,
+      format,
+      alpha,
+      label,
+      name,
+      disabled,
+      readOnly,
+      onChange: (hex, color) => change.current?.(hex, color),
+    });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [format, alpha, label, name, disabled, readOnly]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== toHex(toHsva(value))) instance.current.setColor(value, false);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-color-field', className].filter(Boolean).join(' ')} />;
+}