@yewdiel21/motion-kit 0.9.1 → 0.14.0

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

@@ -0,0 +1,45 @@
+# color-picker
+
+Selector de color completo: un botón con la muestra y el código que, al pulsarlo, crece hasta un panel (el mismo `dialog` anclado de motion-kit, que sale del botón y se pliega de vuelta en él; como las opciones de `menu`, sus secciones entran en cascada mientras la superficie crece). El panel tiene un área de saturación y brillo (`color-area`), un deslizador de tono, uno de opacidad (con `alpha`), un campo de código (`color-field`), colores guardados y un cuentagotas donde el navegador ofrece `EyeDropper`. Con `inline` el panel se muestra en su sitio, sin botón.
+
+Hay un solo color: cambie el control que cambie, los demás se deslizan al nuevo valor (curva swing), la muestra del botón cambia en directo y su código rueda al confirmar. Los colores guardados rebotan al pulsarlos y se marcan con `aria-pressed`.
+
+Importa también `css/components/dialog.css` (el panel es un diálogo anclado), `color-area.css`, `color-slider.css` y `color-field.css`, o el CSS completo. La CLI los copia: la entrada `requires` dialog, color-area, color-slider y color-field.
+
+## HTML / Astro
+
+```html
+<mk-color-picker class="mk-color-picker" value="#3b82f6" label="Color del evento"></mk-color-picker>
+<mk-color-picker class="mk-color-picker" inline alpha swatches="#111111,#ef4444,#22c55e"></mk-color-picker>
+```
+
+## React
+
+```tsx
+const [color, setColor] = useState('#22c55e');
+<ColorPicker value={color} onInput={setColor} label="Color de la etiqueta" />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `value` | `value` | `'#ff8800'` | Color de partida. |
+| `alpha` | `alpha` | `false` | Añade el deslizador de opacidad y conserva la transparencia. |
+| `format` | `format` | `'hex'` | Formato del campo de código: `hex`, `rgb` o `hsl`. |
+| `swatches` | `swatches` (lista con comas) | 8 colores | Colores guardados; `[]` los quita. |
+| `label` | `label` | `'Color'` | Nombre accesible; el botón dice «<label>: #rrggbb». |
+| `name` | `name` | — | Un input oculto envía el hex. |
+| `disabled` | `disabled` | `false` | Desactiva botón y controles. |
+| `inline` | `inline` | `false` | Panel en su sitio, sin botón ni popover. |
+| `eyedropper` | `eyedropper` | `true` | Botón de cuentagotas donde exista la API. |
+| `onInput(hex, hsva)` | — | — | En directo, al arrastrar. |
+| `onChange(hex, hsva)` | — | — | Color confirmado. |
+
+## API y eventos
+
+`open()`, `close()`, `setColor(color, notify = true)`, `value`, `color`, `isOpen`, `destroy()`. Eventos `mk:input` y `mk:change` con `{ value, color }`; los de las piezas internas se detienen en el panel, así que quien escucha al selector solo oye al selector.
+
+## Accesibilidad
+
+El botón tiene `aria-haspopup="dialog"` y `aria-expanded`. Escape o un clic fuera cierran el panel y el foco vuelve al botón. El cuentagotas, si se cancela, no cambia nada. Con movimiento reducido el panel aparece sin crecer y los controles saltan a su valor.

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

@@ -0,0 +1,130 @@
+/* color-picker — a swatch button (12 px, the hex beside it) that grows into a 20 px panel: area, hue, alpha, field,
+   eyedropper and 8 px preset swatches. Inline, the panel sits in place. Needs dialog.css for the popover, and the
+   color-area, color-slider and color-field stylesheets for its parts. */
+.mk-color-picker,
+mk-color-picker {
+  --mk-color-checker: repeating-conic-gradient(#d4d4d4 0 25%, #fff 0 50%) 0 0 / 8px 8px;
+  display: inline-block;
+  max-width: 100%;
+}
+
+:is(.mk-color-picker, mk-color-picker) [data-mk-color-trigger] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.6rem;
+  height: 2.75rem;
+  padding: 0 0.9rem 0 0.4rem;
+  border: 0;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: 500 0.9375rem/1 var(--mk-font-mono, ui-monospace, monospace);
+  cursor: pointer;
+}
+
+:is(.mk-color-picker, mk-color-picker) [data-mk-color-trigger]:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 2px;
+}
+
+:is(.mk-color-picker, mk-color-picker) [data-mk-color-trigger]:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+:is(.mk-color-picker, mk-color-picker) [data-mk-color-trigger] [data-mk-color-swatch],
+[data-mk-color-preset] {
+  border-radius: 8px;
+  background: linear-gradient(var(--mk-color-swatch), var(--mk-color-swatch)), var(--mk-color-checker, repeating-conic-gradient(#d4d4d4 0 25%, #fff 0 50%) 0 0 / 8px 8px);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-text) 22%, transparent);
+  transition: background 0.25s ease;
+}
+
+:is(.mk-color-picker, mk-color-picker) [data-mk-color-trigger] [data-mk-color-swatch] {
+  width: 2rem;
+  height: 2rem;
+}
+
+/* Classes, not data attributes: the copy that folds back into the swatch on close keeps only the classes. */
+.mk-dialog.mk-color-panel {
+  --mk-dialog-width: 18rem;
+  --mk-dialog-radius: 20px;
+  --mk-dialog-bg: var(--mk-surface-1);
+}
+
+[data-mk-color-panel-body] {
+  display: grid;
+  gap: 0.9rem;
+  padding: 0.9rem;
+}
+
+/* The loupes pop above the area and the sliders: the panel leaves them room. */
+.mk-dialog.mk-color-panel [data-mk-color-panel-body] {
+  padding-top: 1.1rem;
+}
+
+:is(.mk-color-picker, mk-color-picker)[data-mk-inline] [data-mk-color-panel-body] {
+  width: min(18rem, 100%);
+  box-sizing: border-box;
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft, rgb(0 0 0 / 0.08));
+}
+
+[data-mk-color-panel-body] .mk-color-slider {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+[data-mk-color-row] {
+  display: flex;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+[data-mk-color-row] > .mk-color-field {
+  flex: 1;
+}
+
+[data-mk-color-eyedropper] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  border: 0;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  cursor: pointer;
+}
+
+[data-mk-color-swatches] {
+  display: grid;
+  grid-template-columns: repeat(8, minmax(0, 1fr));
+  gap: 0.4rem;
+}
+
+[data-mk-color-preset] {
+  aspect-ratio: 1;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  cursor: pointer;
+}
+
+[data-mk-color-preset][aria-pressed='true'] {
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-text) 22%, transparent), 0 0 0 2px var(--mk-surface-1), 0 0 0 4px var(--mk-text);
+}
+
+[data-mk-color-preset]:focus-visible,
+[data-mk-color-eyedropper]:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-color-picker, mk-color-picker) [data-mk-color-swatch],
+  [data-mk-color-preset] {
+    transition: none;
+  }
+}

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

@@ -0,0 +1,45 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createColorPicker, type ColorPickerInstance } from './engine';
+
+/**
+ * <mk-color-picker class="mk-color-picker" value="#3b82f6" label="Color del evento"></mk-color-picker>
+ * `inline` shows the panel in place; `swatches="#111,#ef4444"` sets the presets.
+ * Emits mk:input (live) and mk:change (committed) with {value, color}.
+ */
+export class MkColorPickerElement extends MkElement<ColorPickerInstance> {
+  static options: Record<string, OptionType> = {
+    value: 'string',
+    alpha: 'boolean',
+    format: 'string',
+    swatches: 'list',
+    label: 'string',
+    name: 'string',
+    disabled: 'boolean',
+    inline: 'boolean',
+    eyedropper: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createColorPicker(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);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+}
+
+export const defineColorPicker = () => defineElement('mk-color-picker', MkColorPickerElement);

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

@@ -0,0 +1,314 @@
+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, sameColor, toHex, toHsva, type ColorFormat, type Hsva } from '../../core/color';
+import { press, ringPulse, rollDigits } from '../../motion/micro';
+import { flowInMenu } from '../../motion/entrances';
+import { createDialog } from '../dialog/engine';
+import { createColorArea } from '../color-area/engine';
+import { createColorSlider } from '../color-slider/engine';
+import { createColorField } from '../color-field/engine';
+
+/*
+ * Color picker: a swatch button that grows into a panel (an anchored dialog,
+ * motion/morph.ts container transform; like a menu's options, its sections
+ * flow in while the surface grows) holding a color-area, a hue slider, an
+ * alpha slider (alpha: true), a color-field, preset swatches and an eyedropper
+ * where the browser has one. `inline` puts the panel in place, without button.
+ * One source of truth: whichever control changes, the others glide to the new
+ * colour (setColor(…, false)); the trigger swatch follows live and its hex
+ * label rolls on commit. Presets press, pop and mark themselves (aria-pressed).
+ * The children's mk:input / mk:change stop at the panel: listeners on the
+ * picker hear only the picker's own.
+ */
+
+export const DEFAULT_SWATCHES = ['#111111', '#6b7280', '#ef4444', '#f59e0b', '#22c55e', '#14b8a6', '#3b82f6', '#a855f7'];
+
+export interface ColorPickerOptions {
+  value?: string | Hsva;
+  alpha?: boolean;
+  format?: ColorFormat;
+  swatches?: string[];
+  /** Accessible name; the trigger reads "<label>: <hex>". */
+  label?: string;
+  name?: string;
+  disabled?: boolean;
+  /** The panel in place, without a button or popover. */
+  inline?: boolean;
+  /** Eyedropper button where the browser has the EyeDropper API (default true). */
+  eyedropper?: boolean;
+  onInput?: (value: string, color: Hsva) => void;
+  onChange?: (value: string, color: Hsva) => void;
+}
+
+export interface ColorPickerInstance extends Instance {
+  open(): void;
+  close(): void;
+  setColor(color: string | Hsva, notify?: boolean): void;
+  readonly value: string;
+  readonly color: Hsva;
+  readonly isOpen: boolean;
+}
+
+const PIPETTE =
+  '<svg aria-hidden="true" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14.5 4.5l5 5"/><path d="M17 2.5a2.1 2.1 0 0 1 3 3l-3 3-3-3z"/><path d="M14 6.5l-9.3 9.3a2 2 0 0 0-.5.9L3.5 20.5l3.8-.7a2 2 0 0 0 .9-.5L17.5 10"/></svg>';
+
+interface EyeDropperLike {
+  open(): Promise<{ sRGBHex: string }>;
+}
+
+const div = (attribute: string, className?: string) => {
+  const element = document.createElement('div');
+  element.setAttribute(attribute, '');
+  if (className) element.className = className;
+  return element;
+};
+
+export function createColorPicker(root: HTMLElement | null, options: ColorPickerOptions = {}): ColorPickerInstance {
+  if (!root) return inert({ open() {}, close() {}, setColor() {}, value: '', color: { h: 0, s: 0, v: 0, a: 1 }, isOpen: false });
+  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);
+  };
+
+  const alpha = Boolean(options.alpha);
+  const format: ColorFormat = options.format === 'rgb' || options.format === 'hsl' ? options.format : 'hex';
+  const label = options.label ?? 'Color';
+  const inline = Boolean(options.inline);
+  const swatches = options.swatches ?? DEFAULT_SWATCHES;
+  const opaque = (color: Hsva) => (alpha ? { ...color } : { ...color, a: 1 });
+  let current = opaque(toHsva(options.value ?? '#ff8800'));
+
+  const made: Element[] = [];
+  let trigger: HTMLButtonElement | null = null;
+  let triggerSwatch: HTMLElement | null = null;
+  let triggerLabel: HTMLElement | null = null;
+  let dialogElement: HTMLDialogElement | null = null;
+  if (!inline) {
+    trigger = document.createElement('button');
+    trigger.type = 'button';
+    trigger.dataset.mkColorTrigger = '';
+    trigger.setAttribute('aria-haspopup', 'dialog');
+    trigger.setAttribute('aria-expanded', 'false');
+    trigger.disabled = Boolean(options.disabled);
+    triggerSwatch = document.createElement('span');
+    triggerSwatch.dataset.mkColorSwatch = '';
+    triggerSwatch.setAttribute('aria-hidden', 'true');
+    triggerLabel = document.createElement('span');
+    triggerLabel.dataset.mkColorTriggerLabel = '';
+    triggerLabel.setAttribute('aria-hidden', 'true');
+    trigger.append(triggerSwatch, triggerLabel);
+    dialogElement = document.createElement('dialog');
+    // A class, not only an attribute: the copy that folds back into the swatch on close keeps classes only.
+    dialogElement.className = 'mk-dialog mk-color-panel';
+    dialogElement.dataset.mkColorPanel = '';
+    dialogElement.setAttribute('aria-label', label);
+    root.append(trigger, dialogElement);
+    made.push(trigger, dialogElement);
+  }
+
+  const body = div('data-mk-color-panel-body');
+  const areaHost = div('data-mk-color-area-host', 'mk-color-area');
+  const hueHost = div('data-mk-color-hue', 'mk-color-slider');
+  const alphaHost = alpha ? div('data-mk-color-alpha', 'mk-color-slider') : null;
+  const row = div('data-mk-color-row');
+  const fieldHost = div('data-mk-color-field-host', 'mk-color-field');
+  row.append(fieldHost);
+  let eyedropper: HTMLButtonElement | null = null;
+  const EyeDropper = typeof window !== 'undefined' ? (window as unknown as { EyeDropper?: new () => EyeDropperLike }).EyeDropper : undefined;
+  if (options.eyedropper !== false && typeof EyeDropper === 'function') {
+    eyedropper = document.createElement('button');
+    eyedropper.type = 'button';
+    eyedropper.dataset.mkColorEyedropper = '';
+    eyedropper.setAttribute('aria-label', 'Tomar un color de la pantalla');
+    eyedropper.innerHTML = PIPETTE;
+    eyedropper.disabled = Boolean(options.disabled);
+    row.append(eyedropper);
+  }
+  const presetsHost = div('data-mk-color-swatches');
+  presetsHost.setAttribute('role', 'group');
+  presetsHost.setAttribute('aria-label', 'Colores guardados');
+  const presets = swatches.map((swatch, index) => {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.dataset.mkColorPreset = '';
+    button.dataset.mkIndex = String(index);
+    button.setAttribute('aria-label', swatch);
+    button.setAttribute('aria-pressed', 'false');
+    button.disabled = Boolean(options.disabled);
+    button.style.setProperty('--mk-color-swatch', formatColor(toHsva(swatch), 'rgb'));
+    presetsHost.append(button);
+    return button;
+  });
+  body.append(areaHost, hueHost, ...(alphaHost ? [alphaHost] : []), row);
+  if (presets.length) body.append(presetsHost);
+  if (dialogElement) dialogElement.append(body);
+  else {
+    root.append(body);
+    made.push(body);
+  }
+  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()));
+  if (inline) scope.attr(root, 'data-mk-inline', '');
+  scope.attr(root, 'data-mk-ready', '');
+  // Listeners on the picker hear the picker, not its parts.
+  for (const type of ['mk:input', 'mk:change']) scope.on(body, type, (event) => event.stopPropagation());
+
+  const emit = (type: 'input' | 'change') => {
+    const value = toHex(current);
+    (type === 'input' ? options.onInput : options.onChange)?.(value, { ...current });
+    root.dispatchEvent(new CustomEvent(`mk:${type}`, { bubbles: true, detail: { value, color: { ...current } } }));
+  };
+
+  const paintTrigger = (commit: boolean) => {
+    if (hidden) hidden.value = toHex(current);
+    if (!trigger || !triggerSwatch || !triggerLabel) return;
+    const hex = toHex(current);
+    triggerSwatch.style.setProperty('--mk-color-swatch', formatColor(current, 'rgb'));
+    trigger.setAttribute('aria-label', `${label}: ${hex}`);
+    if (commit && !reduced() && triggerLabel.textContent) keep(rollDigits(triggerLabel, hex, 1, 0.28));
+    else if (commit || !triggerLabel.textContent) triggerLabel.textContent = hex;
+  };
+  const markPresets = () => {
+    for (const preset of presets) {
+      const on = sameColor(opaque(toHsva(preset.getAttribute('aria-label'))), current);
+      preset.setAttribute('aria-pressed', String(on));
+      preset.toggleAttribute('data-mk-checked', on);
+    }
+  };
+
+  type Child = { setColor(color: Hsva, notify?: boolean): void; destroy(): void };
+  const children: Child[] = [];
+  const update = (next: Hsva, source: Child | null, commit: boolean, notify = true) => {
+    if (scope.disposed) return;
+    current = opaque(next);
+    for (const child of children) if (child !== source) child.setColor(current, false);
+    paintTrigger(commit);
+    markPresets();
+    if (!notify) return;
+    emit('input');
+    if (commit) emit('change');
+  };
+  const area: Child = createColorArea(areaHost, {
+    value: current,
+    label,
+    disabled: options.disabled,
+    onInput: (_, color) => update(color, area, false),
+    onChange: (_, color) => update(color, area, true),
+  });
+  const hue: Child = createColorSlider(hueHost, {
+    channel: 'hue',
+    value: current,
+    disabled: options.disabled,
+    onInput: (_, color) => update(color, hue, false),
+    onChange: (_, color) => update(color, hue, true),
+  });
+  const opacity: Child | null = alphaHost
+    ? createColorSlider(alphaHost, {
+        channel: 'alpha',
+        value: current,
+        disabled: options.disabled,
+        onInput: (_, color) => update(color, opacity, false),
+        onChange: (_, color) => update(color, opacity, true),
+      })
+    : null;
+  const field: Child = createColorField(fieldHost, {
+    value: current,
+    format,
+    alpha,
+    label: 'Código de color',
+    disabled: options.disabled,
+    onChange: (_, color) => update(color, field, true),
+  });
+  children.push(area, hue, ...(opacity ? [opacity] : []), field);
+  scope.add(() => children.forEach((child) => child.destroy()));
+  paintTrigger(true);
+  markPresets();
+
+  scope.on(presetsHost, 'click', (event) => {
+    const preset = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-color-preset]');
+    if (!preset || options.disabled) return;
+    keep(press(preset));
+    update(toHsva(preset.getAttribute('aria-label'), current), null, true);
+    if (!reduced()) keep(gsap.fromTo(preset, { scale: 0.85 }, { scale: 1, duration: 0.3, ease: EASE.pop, clearProps: 'scale,transform' }));
+  });
+
+  if (eyedropper && EyeDropper) {
+    scope.on(eyedropper, 'click', () => {
+      keep(press(eyedropper));
+      new EyeDropper()
+        .open()
+        .then(({ sRGBHex }) => {
+          if (scope.disposed) return;
+          update(toHsva(sRGBHex, current), null, true);
+          keep(ringPulse(triggerSwatch ?? areaHost));
+        })
+        // Escape or a refused permission: nothing changes.
+        .catch(() => {});
+    });
+  }
+
+  const panel = dialogElement
+    ? createDialog(dialogElement, {
+        placement: 'anchor',
+        backdrop: false,
+        drag: false,
+        autoResize: false,
+        triggers: false,
+        animateContent: false,
+        // Like a menu's options: the area, the sliders, the field and the swatches flow in while the surface grows.
+        onOpen: () => keep(flowInMenu([...body.children])),
+        onClose: () => trigger?.setAttribute('aria-expanded', 'false'),
+      })
+    : null;
+  if (panel) scope.add(() => panel.destroy());
+  const open = () => {
+    if (!panel || !trigger || options.disabled || panel.isOpen) return;
+    panel.open(trigger);
+    trigger.setAttribute('aria-expanded', 'true');
+  };
+  if (trigger && panel) {
+    scope.on(trigger, 'click', () => {
+      if (panel.isOpen) panel.close();
+      else open();
+    });
+  }
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf(presets);
+  });
+
+  return {
+    open,
+    close: () => panel?.close(),
+    setColor(next, notify = true) {
+      const target = opaque(toHsva(next, current));
+      if (sameColor(target, current) && target.h === current.h) return;
+      update(target, null, true, notify);
+    },
+    get value() {
+      return toHex(current);
+    },
+    get color() {
+      return { ...current };
+    },
+    get isOpen() {
+      return panel?.isOpen ?? false;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

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

@@ -0,0 +1,47 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { toHex, toHsva } from '../../core/color';
+import { createColorPicker, type ColorPickerInstance, type ColorPickerOptions } from './engine';
+
+export interface ColorPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onInput' | 'onChange' | 'defaultValue'>, Omit<ColorPickerOptions, 'value'> {
+  /** Controlled colour; without it the picker keeps its own (defaultValue). */
+  value?: string;
+  defaultValue?: string;
+}
+
+/** <ColorPicker value={color} onInput={setColor} alpha /> or <ColorPicker inline … />. */
+export function ColorPicker({ value, defaultValue, alpha, format, swatches, label, name, disabled, inline, eyedropper, onInput, onChange, className, ...props }: ColorPickerProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ColorPickerInstance | null>(null);
+  const input = useLatest(onInput);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue);
+  const key = JSON.stringify(swatches ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createColorPicker(ref.current, {
+      value: value ?? start.current,
+      alpha,
+      format,
+      swatches,
+      label,
+      name,
+      disabled,
+      inline,
+      eyedropper,
+      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
+  }, [alpha, format, key, label, name, disabled, inline, eyedropper]);
+  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-picker', className].filter(Boolean).join(' ')} />;
+}

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

@@ -0,0 +1,55 @@
+# color-slider
+
+Deslizador de un canal de color (tono, saturación, brillo, luminosidad, rojo, verde, azul u opacidad) sobre un `<input type="range">` nativo: teclado, táctil y formularios vienen de la plataforma. El motor pinta la pista con el degradado de ese canal para el color actual (la opacidad sobre un damero) y un pulgar redondo relleno del color.
+
+Origen: línea Melon Mind. El pulgar se desliza 0,35 s con la curva swing (`.38,.49,0,1.5`) al usar el teclado o `setColor`, y sigue al puntero en 0,1 s al arrastrar. Al agarrarlo crece (curva click `.37,1.42,.37,1`) y aparece encima una lupa con el color (curva pop); al soltar, la lupa se desvanece con blur. El valor mostrado rueda.
+
+## HTML / Astro
+
+```html
+<mk-color-slider class="mk-color-slider" channel="hue" value="#ff8800" show-value></mk-color-slider>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-color-slider']);
+</script>
+```
+
+## React
+
+```tsx
+const [color, setColor] = useState('#ff8800');
+<ColorSlider channel="hue" value={color} onInput={setColor} showValue />
+```
+
+Con `value` es controlado; con `defaultValue` guarda su propio color.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `channel` | `channel` | `'hue'` | Canal: `hue`, `saturation`, `brightness`, `lightness`, `red`, `green`, `blue`, `alpha`. |
+| `value` | `value` | `'hsl(0 100% 50%)'` | Color de partida: hex, `rgb()`, `hsl()` o un objeto HSVA. |
+| `label` | `label` | nombre del canal | Nombre accesible (Tono, Saturación, Brillo, Luminosidad, Rojo, Verde, Azul, Opacidad). |
+| `orientation` | `orientation` | `'horizontal'` | `vertical` pone la pista de pie (abajo es el mínimo). |
+| `step` | `step` | `1` (opacidad `0.01`) | Paso del input. |
+| `showValue` | `show-value` | `false` | Muestra el valor («210°», «64 %», «136») en un `<output>`. |
+| `name` | `name` | — | Un input oculto envía el hex con el formulario. |
+| `disabled` | `disabled` | `false` | Desactiva el input. |
+| `onInput(hex, hsva)` | — | — | Cada movimiento. |
+| `onChange(hex, hsva)` | — | — | Valor confirmado (al soltar o con una tecla). |
+
+## API
+
+`setColor(color, notify = true)` cambia el color (otro control lo movió; con `notify=false` no llama a los callbacks), `value` (hex, `#rrggbbaa` si es translúcido), `color` (copia HSVA), `destroy()`.
+
+## Eventos
+
+`mk:input` y `mk:change` con `{ value, color }`.
+
+## Variables CSS
+
+`--mk-color-size` (1.75rem, alto de la pista y del pulgar), `--mk-color-length` (12rem, alto en vertical), `--mk-color-checker` (damero bajo los colores translúcidos). El motor escribe `--mk-color-track`, `--mk-color-thumb` y `--mk-color-pos`.
+
+## Accesibilidad
+
+Es un input range nativo con `aria-valuetext` legible («210°», «64 %») y `aria-orientation`. Con movimiento reducido no hay escalas ni deslizamientos: el pulgar salta a su sitio y la lupa aparece sin animar mientras se arrastra. Deja unos 3,5 rem libres encima para que la lupa no se corte.