@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/scroll-preview-dock/engine.ts

@@ -0,0 +1,228 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { reduced } from '../../core/reduced';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press } from '../../motion/micro';
+
+export interface ScrollPreviewDockItem {
+  id: string;
+  label: string;
+  description?: string;
+  thumbnail?: string;
+  /** A section element or selector. Defaults to the element with this item's id. */
+  section?: HTMLElement | string;
+  disabled?: boolean;
+}
+export interface ScrollPreviewDockOptions {
+  items?: ScrollPreviewDockItem[];
+  scroller?: HTMLElement | string | null;
+  offset?: number;
+  label?: string;
+  disabled?: boolean;
+  onChange?: (id: string) => void;
+}
+export interface ScrollPreviewDockInstance extends Instance {
+  select(id: string): void;
+  update(): void;
+  setOptions(options: Partial<ScrollPreviewDockOptions>): void;
+  readonly value: string;
+}
+
+/** Native section links, a travelling selection pill, and a focus/hover preview. */
+export function createScrollPreviewDock(root: HTMLElement | null, options: ScrollPreviewDockOptions = {}): ScrollPreviewDockInstance {
+  if (!root) return inert({ select() {}, update() {}, setOptions() {}, value: '' });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let current = '';
+  let previewed = '';
+  let frame = 0;
+  let scrolling: gsap.core.Tween | null = null;
+  let unbindScroller = () => {};
+  let scroller: HTMLElement | null = null;
+  const original = [...root.childNodes];
+  const animations = new Set<gsap.core.Animation>();
+  const track = (animation: gsap.core.Animation | null) => { if (animation) animations.add(animation); };
+  const panel = document.createElement('div');
+  panel.className = 'mk-scroll-preview-dock__preview';
+  panel.setAttribute('aria-hidden', 'true');
+  const image = document.createElement('span');
+  image.className = 'mk-scroll-preview-dock__image';
+  const copy = document.createElement('span');
+  const title = document.createElement('strong');
+  const description = document.createElement('span');
+  description.className = 'mk-scroll-preview-dock__description';
+  copy.append(title, description);
+  panel.append(image, copy);
+  const nav = document.createElement('nav');
+  nav.className = 'mk-scroll-preview-dock__nav';
+  const pill = document.createElement('span');
+  pill.className = 'mk-scroll-preview-dock__pill';
+  pill.setAttribute('aria-hidden', 'true');
+  const empty = document.createElement('p');
+  empty.className = 'mk-scroll-preview-dock__empty';
+  empty.textContent = 'No hay secciones para explorar.';
+  root.replaceChildren(panel, nav, empty);
+  scope.attr(root, 'class', `${root.className} mk-scroll-preview-dock`.trim());
+  scope.attr(root, 'data-mk-ready', '');
+  const items = () => opts.items ?? [];
+  const enabled = (item: ScrollPreviewDockItem) => !opts.disabled && !item.disabled;
+  const section = (item: ScrollPreviewDockItem) => {
+    if (item.section instanceof HTMLElement) return item.section;
+    if (!item.section) return document.getElementById(item.id);
+    try { return (scroller ?? document).querySelector<HTMLElement>(item.section); } catch { return null; }
+  };
+  const links = () => [...nav.querySelectorAll<HTMLAnchorElement>('a')];
+  const thumb = (node: HTMLElement, item: ScrollPreviewDockItem) => {
+    node.replaceChildren();
+    if (item.thumbnail) { const img = document.createElement('img'); img.src = item.thumbnail; img.alt = ''; img.draggable = false; node.append(img); }
+    else { const letter = document.createElement('span'); letter.textContent = item.label.slice(0, 2); node.append(letter); }
+  };
+  const preview = (id: string, animate = true) => {
+    const item = items().find((item) => item.id === id);
+    if (!item || previewed === id) return;
+    previewed = id;
+    thumb(image, item);
+    title.textContent = item.label;
+    description.textContent = item.description ?? 'Explorar sección';
+    for (const link of links()) link.dataset.mkPreview = String(link.dataset.mkSection === id);
+    if (animate) { gsap.killTweensOf(panel); track(blurIn(panel, { from: 'soft', duration: .28 })); }
+  };
+  const place = (animate = true) => {
+    const active = links().find((link) => link.dataset.mkSection === current);
+    pill.hidden = !active;
+    if (!active) return;
+    track(gsap.to(pill, { x: active.offsetLeft, y: active.offsetTop, width: active.offsetWidth, height: active.offsetHeight, duration: reduced() || !animate ? 0 : .45, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+  const activate = (id: string, notify = true) => {
+    if (scope.disposed || current === id) return;
+    current = id;
+    for (const link of links()) {
+      if (link.dataset.mkSection === id) link.setAttribute('aria-current', 'location');
+      else link.removeAttribute('aria-current');
+    }
+    place();
+    if (!root.contains(document.activeElement) && !root.matches(':hover')) preview(id);
+    else if (!previewed) preview(id, false);
+    if (notify) {
+      opts.onChange?.(id);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: id } }));
+    }
+  };
+  const update = () => {
+    frame = 0;
+    if (scope.disposed) return;
+    const top = scroller ? scroller.getBoundingClientRect().top + scroller.clientTop : 0;
+    const height = scroller ? scroller.clientHeight : window.innerHeight;
+    const line = top + Math.min(120, height * .3) + (opts.offset ?? 0);
+    const targets = items().filter(enabled).map((item) => ({ item, node: section(item) })).filter((entry): entry is { item: ScrollPreviewDockItem; node: HTMLElement } => !!entry.node);
+    let target: (typeof targets)[number] | undefined = targets[0];
+    for (const entry of targets) if (entry.node.getBoundingClientRect().top <= line) target = entry;
+    const atEnd = scroller ? scroller.scrollHeight > scroller.clientHeight && scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2 : document.documentElement.scrollHeight > window.innerHeight && window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+    if (atEnd) target = targets.at(-1);
+    if (target) activate(target.item.id);
+    place(false);
+  };
+  const queue = () => { if (!frame) frame = requestAnimationFrame(update); };
+  const bindScroller = () => {
+    unbindScroller();
+    scroller = typeof opts.scroller === 'string' ? (() => { try { return root.closest<HTMLElement>(opts.scroller) ?? document.querySelector<HTMLElement>(opts.scroller); } catch { return null; } })() : opts.scroller ?? null;
+    const target = scroller ?? window;
+    target.addEventListener('scroll', queue, { passive: true });
+    target.addEventListener('wheel', cancelScroll, { passive: true });
+    target.addEventListener('touchstart', cancelScroll, { passive: true });
+    unbindScroller = () => { target.removeEventListener('scroll', queue); target.removeEventListener('wheel', cancelScroll); target.removeEventListener('touchstart', cancelScroll); };
+  };
+  function cancelScroll() { scrolling?.kill(); scrolling = null; }
+  const select = (id: string) => {
+    if (scope.disposed) return;
+    const item = items().find((entry) => entry.id === id);
+    if (!item || !enabled(item)) return;
+    const target = section(item);
+    if (!target) return;
+    cancelScroll();
+    const top = Math.max(0, (scroller ? scroller.scrollTop + target.getBoundingClientRect().top - scroller.getBoundingClientRect().top - scroller.clientTop : window.scrollY + target.getBoundingClientRect().top) - (opts.offset ?? 0));
+    activate(id);
+    preview(id);
+    if (scroller) {
+      if (reduced()) scroller.scrollTop = top;
+      else scrolling = gsap.to(scroller, { scrollTop: top, duration: .65, ease: EASE.signature, overwrite: 'auto', onUpdate: queue });
+    } else if (reduced()) window.scrollTo({ top, behavior: 'instant' });
+    else {
+      const position = { top: window.scrollY };
+      scrolling = gsap.to(position, { top, duration: .65, ease: EASE.signature, onUpdate: () => { window.scrollTo(0, position.top); queue(); } });
+    }
+  };
+  const render = () => {
+    gsap.killTweensOf(pill);
+    nav.replaceChildren(pill);
+    nav.setAttribute('aria-label', opts.label ?? 'Explorar secciones');
+    const unique = new Set<string>();
+    for (const item of items()) {
+      if (!item.id || unique.has(item.id)) continue;
+      unique.add(item.id);
+      const link = document.createElement('a');
+      link.href = `#${encodeURIComponent(section(item)?.id || item.id)}`;
+      link.dataset.mkSection = item.id;
+      link.className = 'mk-scroll-preview-dock__item';
+      const cover = document.createElement('span');
+      cover.className = 'mk-scroll-preview-dock__thumb';
+      cover.setAttribute('aria-hidden', 'true');
+      thumb(cover, item);
+      const label = document.createElement('span');
+      label.textContent = item.label;
+      link.append(cover, label);
+      if (!enabled(item)) { link.setAttribute('aria-disabled', 'true'); link.tabIndex = -1; }
+      nav.append(link);
+    }
+    empty.hidden = unique.size > 0;
+    panel.hidden = unique.size === 0;
+    nav.hidden = unique.size === 0;
+    scope.attr(root, 'data-mk-disabled', opts.disabled ? '' : null);
+    previewed = '';
+    const next = items().find((item) => item.id === current && enabled(item)) ?? items().find(enabled);
+    current = '';
+    if (next) { activate(next.id, false); preview(next.id, false); }
+    else pill.hidden = true;
+  };
+  scope.on(nav, 'click', (event) => {
+    const link = (event.target as Element).closest<HTMLAnchorElement>('a[data-mk-section]');
+    if (!link) return;
+    if (link.getAttribute('aria-disabled') === 'true') { event.preventDefault(); return; }
+    if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.button !== 0) return;
+    const item = items().find((item) => item.id === link.dataset.mkSection);
+    if (!item || !section(item)) return;
+    event.preventDefault(); track(press(link)); select(item.id);
+  });
+  scope.on(nav, 'pointerover', (event) => { const link = (event.target as Element).closest<HTMLElement>('a[data-mk-section]'); if (link && link.getAttribute('aria-disabled') !== 'true') preview(link.dataset.mkSection!); });
+  scope.on(nav, 'focusin', (event) => { const link = (event.target as Element).closest<HTMLElement>('a[data-mk-section]'); if (link) preview(link.dataset.mkSection!); });
+  scope.on(root, 'pointerleave', () => { if (!root.contains(document.activeElement)) preview(current); });
+  scope.on(root, 'focusout', (event) => { if (!root.contains(event.relatedTarget as Node | null)) preview(current); });
+  scope.on(nav, 'keydown', (event) => {
+    if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) { if (['PageUp', 'PageDown', 'ArrowUp', 'ArrowDown', ' '].includes(event.key)) cancelScroll(); return; }
+    const available = links().filter((link) => link.getAttribute('aria-disabled') !== 'true');
+    const index = available.indexOf(document.activeElement as HTMLAnchorElement);
+    if (index < 0 || !available.length) return;
+    event.preventDefault();
+    available[event.key === 'Home' ? 0 : event.key === 'End' ? available.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : -1) + available.length) % available.length]?.focus();
+  });
+  scope.on(window, 'resize', queue, { passive: true });
+  if (typeof ResizeObserver === 'function') { const resize = scope.observe(new ResizeObserver(queue)); resize.observe(nav); }
+  bindScroller(); render(); update();
+  return {
+    select, update,
+    get value() { return current; },
+    setOptions(next) {
+      if (scope.disposed) return;
+      const focusedId = root.contains(document.activeElement)
+        ? (document.activeElement as HTMLElement | null)?.closest<HTMLAnchorElement>('a[data-mk-section]')?.dataset.mkSection
+        : undefined;
+      opts = { ...opts, ...next };
+      if ('scroller' in next) { cancelScroll(); bindScroller(); }
+      render();
+      if (focusedId) { const target = links().find((link) => link.dataset.mkSection === focusedId && link.getAttribute('aria-disabled') !== 'true') ?? links().find((link) => link.getAttribute('aria-disabled') !== 'true'); if (target) target.focus(); else { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); } }
+      update();
+    },
+    destroy() { if (scope.disposed) return; cancelAnimationFrame(frame); cancelScroll(); unbindScroller(); animations.forEach((animation) => animation.kill()); gsap.killTweensOf([...root.querySelectorAll('*')]); scope.dispose(); root.replaceChildren(...original); },
+  };
+}

package/src/components/scroll-preview-dock/react.tsx

@@ -0,0 +1,26 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createScrollPreviewDock, type ScrollPreviewDockOptions, type ScrollPreviewDockInstance } from './engine';
+
+export interface ScrollPreviewDockProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children' | 'dangerouslySetInnerHTML'>, ScrollPreviewDockOptions {
+  instanceRef?: MutableRefObject<ScrollPreviewDockInstance | null>;
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function ScrollPreviewDock({ items, scroller, offset, label, disabled, onChange, instanceRef, className, children, dangerouslySetInnerHTML: _html, ...props }: ScrollPreviewDockProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<ScrollPreviewDockInstance | null>(null);
+  const onChangeRef = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createScrollPreviewDock(root.current, { items, scroller, offset, label, disabled, onChange: (...args) => onChangeRef.current?.(...args) });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+    // Options update the existing engine so timers, selection and scroll state survive.
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setOptions({ items, scroller, offset, label, disabled });
+  }, [items, scroller, offset, label, disabled]);
+  useIsomorphicLayoutEffect(() => { if (instanceRef) instanceRef.current = instance.current; return () => { if (instanceRef) instanceRef.current = null; }; }, [instanceRef]);
+  return <div {...props} ref={root} className={['mk-scroll-preview-dock', className].filter(Boolean).join(' ')}></div>;
+}

package/src/components/scroll-preview-dock/scroll-preview-dock.css

@@ -0,0 +1,17 @@
+.mk-scroll-preview-dock, mk-scroll-preview-dock { box-sizing: border-box; display: grid; gap: 10px; width: min(100%, 400px); color: var(--mk-text); font-family: var(--mk-font); }
+.mk-scroll-preview-dock__preview { display: flex; align-items: center; gap: 12px; min-height: 60px; box-sizing: border-box; padding: 12px 16px; border-radius: 24px; background: var(--mk-surface-2); box-shadow: 0 1px 0 var(--mk-outline-soft) inset; }
+.mk-scroll-preview-dock__image { display: grid; place-items: center; flex: 0 0 44px; width: 44px; height: 44px; border-radius: 12px; background: var(--mk-surface-3, var(--mk-surface)); overflow: hidden; font-weight: 600; font-size: 14px; }
+.mk-scroll-preview-dock__image img, .mk-scroll-preview-dock__thumb img { display: block; width: 100%; height: 100%; object-fit: cover; }
+.mk-scroll-preview-dock__preview strong { display: block; font-size: 13px; font-weight: 600; line-height: 1.4; }
+.mk-scroll-preview-dock__description { display: block; color: var(--mk-muted); font-size: 11px; line-height: 1.5; }
+.mk-scroll-preview-dock__nav { position: relative; box-sizing: border-box; display: flex; align-items: stretch; justify-content: space-between; gap: 4px; width: 100%; padding: 6px; border-radius: 32px; background: var(--mk-surface); }
+.mk-scroll-preview-dock__pill { position: absolute; top: 0; left: 0; border-radius: 24px; background: var(--mk-surface-3, var(--mk-surface-2)); pointer-events: none; box-shadow: 0 1px 0 var(--mk-outline-soft) inset; }
+.mk-scroll-preview-dock__item { position: relative; z-index: 1; display: flex; flex: 1 1 0; align-items: center; flex-direction: column; justify-content: center; gap: 6px; min-width: 0; min-height: 68px; padding: 6px; border-radius: 24px; text-align: center; color: var(--mk-muted); text-decoration: none; font-size: 10px; line-height: 1.3; -webkit-tap-highlight-color: transparent; transition: color .2s; }
+.mk-scroll-preview-dock__thumb { display: grid; place-items: center; width: 32px; height: 32px; border-radius: 12px; background: var(--mk-surface-2); overflow: hidden; color: var(--mk-text); font-size: 10px; font-weight: 600; transition: transform .4s var(--mk-ease-swatch), border-radius .4s var(--mk-ease-swatch); }
+.mk-scroll-preview-dock__item[aria-current] { color: var(--mk-text); }
+.mk-scroll-preview-dock__item[data-mk-preview=true] .mk-scroll-preview-dock__thumb { transform: translateY(-3px) rotate(-4deg) scale(1.08); border-radius: 8px; }
+.mk-scroll-preview-dock__item:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+.mk-scroll-preview-dock__item[aria-disabled=true] { opacity: .4; cursor: not-allowed; }
+.mk-scroll-preview-dock [hidden] { display: none !important; }
+.mk-scroll-preview-dock__empty { margin: 0; padding: 20px; text-align: center; background: var(--mk-surface); border-radius: 24px; font-size: 12px; color: var(--mk-muted); }
+@media (prefers-reduced-motion: reduce) { .mk-scroll-preview-dock * { transition: none !important; } }

package/src/components/select/README.md

@@ -1,34 +1,48 @@
 # select
 
-Qué hace, en una frase.
-
-Origen: archivo del kit y parámetros (tiempos, curvas).
+Una elección de una lista que se abre como el `menu` del kit (crece desde su botón y las opciones entran escalonadas) en lugar de la lista del sistema. Mejora un `<select>` escrito a mano, o crea uno desde `options`, y lo mantiene sincronizado y oculto: los formularios lo envían y sus escuchas de `change` siguen funcionando. El valor elegido entra con un blur breve y el chevron gira.
 
 ## HTML / Astro
 
 ```html
-<mk-select></mk-select>
+<mk-select class="mk-select" label="Responsable">
+  <select name="owner">
+    <option value="">Elige a alguien</option>
+    <optgroup label="Diseño"><option value="ana">Ana Gómez</option></optgroup>
+    <optgroup label="Código"><option value="leo">Leo Ruiz</option></optgroup>
+  </select>
+</mk-select>
 <script>
   import { defineElements } from '@yewdiel21/motion-kit/elements';
   defineElements(['mk-select']);
 </script>
 ```
 
+Dentro de un `.mk-field` el botón toma la altura, el radio y el relleno de los demás campos. Para cambiar el valor desde fuera usa el atributo `value` (o `setValue` en la instancia); el `<select>` y el botón se actualizan juntos.
+
 ## React
 
 ```tsx
-<Select />
+<Select label="Prioridad" name="priority" value={priority} onChange={setPriority}
+  options={[{ value: 'low', label: 'Baja' }, { value: 'normal', label: 'Normal' }, { value: 'high', label: 'Alta' }]} />
 ```
 
+`options` acepta `{ value, label, disabled?, group? }`; `group` crea encabezados como `<optgroup>`.
+
 ## Opciones
 
 | Opción | Atributo | Por defecto | Qué hace |
 |---|---|---|---|
+| `options` | — | las del `<select>` | Opciones; sin ellas se leen del `<select>` interior. |
+| `value` | `value` | el del `<select>` | Valor elegido. |
+| `name` | `name` | — | Nombre del `<select>` que crea (uno escrito conserva el suyo). |
+| `label` | `label` | `'Opciones'` | Nombre accesible; el botón se lee «label: elegido». |
+| `placeholder` | `placeholder` | texto de la opción vacía o `'Elige…'` | Texto mientras no hay elección. |
+| `disabled` | `disabled` | `false` | Desactiva el botón. |
+| `onChange(value)` | evento `change` del `<select>` / `mk:change` | — | Avisa al elegir. |
 
-## Variables CSS
-
-`--mk-select-radius`
+Instancia: `setValue(value, notify?)`, `setOptions(options)`, `refresh()`, `open()`, `close()`, `value`, `destroy()`.
 
 ## Accesibilidad
 
-Roles, foco y teclado. Con movimiento reducido…
+El botón tiene `aria-haspopup="menu"` y `aria-expanded`; el menú usa `menuitemradio` con `aria-checked` en la opción elegida. ↓ ↑ Intro y Espacio abren el menú; con el botón cerrado, escribir una letra elige la siguiente opción que empieza por ella. Funciona dentro de diálogos, paneles y popovers sin cerrarlos. Con movimiento reducido el menú aparece sin escalonado y el valor cambia sin blur.

package/src/components/select/select.css

@@ -133,3 +133,19 @@ mk-select {
     transition: none;
   }
 }
+
+/* Inside a kit field the trigger takes the field's height, radius, fill and type. */
+.mk-field :is(.mk-select, mk-select) {
+  display: flex;
+  width: 100%;
+}
+
+.mk-field [data-mk-select-trigger] {
+  height: auto;
+  min-height: 56px;
+  padding: 0 14px 0 16px;
+  border-radius: var(--mk-field-radius);
+  background: var(--mk-field-bg);
+  font-family: var(--md-sys-typescale-body-large-font);
+  font-size: var(--md-sys-typescale-body-large-size);
+}

package/src/components/signature-pad/README.md

@@ -0,0 +1,97 @@
+# signature-pad
+
+Área de firma con tinta SVG suavizada, captura de puntero para ratón, lápiz y tacto, historial de trazos y exportación. Las coordenadas normalizadas conservan la firma cuando cambia el tamaño. No necesita un contexto canvas para dibujar ni exportar SVG.
+
+```ts
+import { createSignaturePad } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/components/signature-pad';
+
+const pad = createSignaturePad(document.querySelector('.mk-signature-pad'), {
+  label: 'Firma de entrega',
+  name: 'signature',
+  onChange(data, detail) {
+    console.log(data.strokes.length, detail.reason);
+  },
+});
+
+const saved = pad.exportData();
+pad.clear();
+pad.undo();
+pad.importData(saved); // false si los datos no son válidos; no cambia la firma
+const svg = pad.exportSVG({ width: 800, height: 300 });
+const png = await pad.exportPNG({ background: '#ffffff', scale: 2 }); // Blob | null
+pad.destroy();
+```
+
+El contenedor vanilla es `<div class="mk-signature-pad"></div>`. Se añaden el área, las herramientas y el estado; `destroy()` elimina esos nodos, observadores, animaciones, capturas y eventos, y restaura los atributos originales. Los nodos originales del contenedor conservan su identidad. `createSignaturePad(null)` devuelve una instancia inerte.
+
+## React
+
+```tsx
+import { useRef, useState } from 'react';
+import { SignaturePad } from '@yewdiel21/motion-kit/react';
+import type { SignatureData, SignaturePadInstance } from '@yewdiel21/motion-kit';
+
+function Form() {
+  const [value, setValue] = useState<SignatureData>({ version: 1, strokes: [] });
+  const pad = useRef<SignaturePadInstance | null>(null);
+  return <SignaturePad value={value} onChange={setValue} instanceRef={pad} name="signature" />;
+}
+```
+
+`value` controla los datos; acepta las ediciones desde `onChange` para conservarlas. Si el propietario mantiene el mismo valor, la firma vuelve a ese valor al renderizar. Un valor aceptado conserva el historial. `defaultValue` inicia una firma no controlada. Las actualizaciones externas no notifican `onChange`; reemplazar datos diferentes reinicia el historial. `instanceRef` expone la API y vuelve a `null` al desmontar. `disabled` y `readOnly` cambian sin perder datos ni historial. Cambiar otras opciones reconstruye el área conservando los datos, pero reinicia el historial.
+
+## Custom element / Astro
+
+```html
+<mk-signature-pad
+  class="mk-signature-pad"
+  label="Firma de entrega"
+  name="signature"
+  width="2.4"
+></mk-signature-pad>
+```
+
+Registra `defineSignaturePad()` desde `@yewdiel21/motion-kit/elements`, o usa el registro general de elementos. `MkSignaturePadElement` expone `data`, `isEmpty`, `canUndo`, `canRedo`, `undo()`, `redo()`, `clear()`, `importData()`, `exportData()`, `exportSVG()` y `exportPNG()`. Los métodos operan mientras el elemento está conectado. El atributo `data` admite el JSON versionado; un cambio inválido conserva la firma anterior. Las opciones booleanas admiten presencia o `="false"`; la opción `readOnly` corresponde a `read-only`. Las ediciones sobreviven a desconexión y reconexión, aunque el historial se reinicia. Cambiar `disabled` o `read-only` conserva el historial; otras opciones lo reinician.
+
+## Opciones y API
+
+| Opción | Valor inicial | Uso |
+| --- | --- | --- |
+| `data` | `{ version: 1, strokes: [] }` | Datos iniciales del motor. |
+| `label` | `Área de firma` | Nombre accesible del dibujo. |
+| `hint` | Instrucciones en español | Descripción visible y accesible. |
+| `placeholder` | `Firma aquí` | Texto decorativo cuando está vacío. |
+| `color` | Color de texto del tema | Color literal CSS de los trazos nuevos. |
+| `width` | `2.4` | Ancho de tinta en píxeles CSS, limitado a 0.1–64. |
+| `toolbar` | `true` | Botones nativos Deshacer, Rehacer y Limpiar. |
+| `disabled` / `readOnly` | `false` | Bloquean dibujo y herramientas de edición. |
+| `name` | Sin input | Input oculto con el JSON completo. Se excluye del formulario si está deshabilitado. |
+| `historyLimit` | `50` | Entre 1 y 100 pasos de deshacer. |
+| `onChange(data, detail)` | — | Una notificación por trazo completo o cambio de API. |
+
+`data` y `exportData()` devuelven copias profundas. `importData(unknown, notify = true)` valida todo antes de reemplazar; devuelve `false` si falla, sin alterar datos, historial ni el trazo activo. Una importación diferente reinicia deshacer/rehacer. Importar los mismos datos conserva el historial y no notifica. `undo()`, `redo()` y `clear()` son operaciones reversibles; dibujar después de deshacer elimina la rama de rehacer. Un trazo cancelado, la pérdida de captura, el desenfoque o la desactivación descartan el trazo incompleto. Las exportaciones incluyen solo trazos terminados.
+
+`setDisabled(boolean)` y `setReadOnly(boolean)` actualizan el modo del motor. Las llamadas de API pueden modificar datos incluso en modo deshabilitado o de solo lectura; esos modos bloquean la interacción del usuario. Las llamadas que cambian datos no hacen nada después de `destroy()`.
+
+El evento burbujeante `mk:change` contiene `SignaturePadChangeDetail` en `event.detail`: `{ data, reason, isEmpty, canUndo, canRedo }`. `reason` es `draw`, `undo`, `redo`, `clear`, `import` o `reset`. El reset nativo de un formulario restaura los datos iniciales y limpia el historial; respeta un evento cancelado. Los datos entregados al callback y al evento son copias independientes de la firma interna. No se notifica al montar ni durante el movimiento del puntero.
+
+## Datos y exportaciones
+
+```ts
+interface SignaturePoint { x: number; y: number } // ambos 0–1
+interface SignatureStroke { points: SignaturePoint[]; color: string; width: number }
+interface SignatureData { version: 1; strokes: SignatureStroke[] }
+```
+
+Se aceptan como máximo 500 trazos y 50 000 puntos en total. Se rechazan versiones desconocidas, números no finitos, coordenadas fuera de 0–1, trazos sin puntos, anchos fuera de 0.1–64 y colores inválidos. Los colores admiten valores literales hexadecimales, `rgb()` / `hsl()` y nombres CSS; no admiten variables, `currentColor`, URLs ni servidores de pintura. La presión del lápiz no cambia el ancho: todos los trazos tienen un ancho constante y terminaciones redondeadas.
+
+`exportSVG({ width?, height?, background? })` devuelve un SVG independiente sin guías, texto de ayuda ni controles. El tamaño predeterminado es el área actual, o 640 × 240 antes del primer layout. Los tamaños explícitos se limitan a 1–4096 px. El fondo es transparente salvo que pases un color. Las posiciones se escalan al tamaño solicitado; el ancho de tinta sigue expresado en píxeles. Cambiar la proporción del área estira la geometría de la firma proporcionalmente a cada eje.
+
+`exportPNG({ width?, height?, background?, scale? })` rasteriza el mismo SVG mediante canvas e imagen del navegador. `scale` vale 2 por defecto y se limita a 1–4. Devuelve `Promise<Blob | null>`: `null` si no hay canvas 2D, la imagen no carga, el navegador impide la rasterización, pasan 10 segundos o se destruye la instancia. La política CSP de la página debe permitir imágenes `data:` para esta función. SVG y JSON siguen disponibles sin canvas. PNG no tiene dependencias ni peticiones de red.
+
+## Tema, interacción y accesibilidad
+
+La tarjeta usa `--mk-surface-*`, `--mk-outline-soft`, `--mk-text`, `--mk-muted`, `--mk-font` y `--mk-accent`. Personaliza `--mk-signature-height`, `--mk-signature-paper` y `--mk-signature-ink`; esta última debe contener un color literal y afecta los trazos nuevos. El color ya capturado se conserva con los datos.
+
+Los controles nativos están etiquetados, usan foco visible y se recorren con Tab; Enter o Espacio activan sus acciones. El SVG tiene nombre y descripción, y un estado `aria-live="polite"` anuncia el número de trazos. Dibujar a mano requiere puntero y no tiene equivalente completo de teclado; cuando tu flujo necesite otra forma de firmar, proporciona una entrada de nombre o una alternativa adecuada junto al componente. Solo el área de dibujo bloquea los gestos táctiles; las herramientas permiten desplazarse normalmente. El modo de solo lectura y el deshabilitado permiten los gestos de desplazamiento sobre el área. GSAP da un pequeño rebote a las herramientas; con movimiento reducido se omite. La tinta sigue el puntero inmediatamente en ambos modos.

package/src/components/signature-pad/element.ts

@@ -0,0 +1,57 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSignaturePad, type SignatureData, type SignatureExportOptions, type SignaturePNGOptions, type SignaturePadInstance, type SignaturePadOptions } from './engine';
+
+/** Light-DOM element. `data` accepts versioned JSON; mk:change carries data and history state. */
+export class MkSignaturePadElement extends MkElement<SignaturePadInstance> {
+  static options: Record<string, OptionType> = {
+    data: 'json', label: 'string', hint: 'string', placeholder: 'string', color: 'string', width: 'number',
+    disabled: 'boolean', readOnly: 'boolean', toolbar: 'boolean', name: 'string', historyLimit: 'number',
+  };
+  private saved: SignatureData | undefined;
+
+  protected create(options: Record<string, unknown>) {
+    return createSignaturePad(this, { ...options, data: options.data ?? this.saved } as SignaturePadOptions);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance || !this.isConnected) return;
+    if (name === 'disabled') { this.instance.setDisabled(next !== null && next !== 'false'); return; }
+    if (name === 'read-only') { this.instance.setReadOnly(next !== null && next !== 'false'); return; }
+    if (name === 'data') {
+      try { this.instance.importData(next === null ? { version: 1, strokes: [] } : JSON.parse(next), false); }
+      catch { /* Invalid JSON leaves the signature untouched. */ }
+      return;
+    }
+    this.saved = this.instance.exportData();
+    // Preserve live edits when an unrelated option changes, even with initial data markup.
+    this.instance.destroy();
+    this.instance = createSignaturePad(this, { ...this.options, data: this.saved } as SignaturePadOptions);
+  }
+
+  disconnectedCallback() {
+    this.saved = this.instance?.exportData() ?? this.saved;
+    super.disconnectedCallback();
+  }
+
+  connectedCallback() {
+    if (!this.instance) this.instance = createSignaturePad(this, { ...this.options, data: this.saved ?? this.options.data } as SignaturePadOptions);
+  }
+
+  get data(): SignatureData {
+    if (this.instance) return this.instance.exportData();
+    return this.saved ? { version: 1, strokes: this.saved.strokes.map((stroke) => ({ ...stroke, points: stroke.points.map((point) => ({ ...point })) })) } : { version: 1, strokes: [] };
+  }
+  set data(value: SignatureData) { this.importData(value); }
+  get isEmpty() { return this.instance?.isEmpty ?? !this.saved?.strokes.length; }
+  get canUndo() { return this.instance?.canUndo ?? false; }
+  get canRedo() { return this.instance?.canRedo ?? false; }
+  undo() { this.instance?.undo(); }
+  redo() { this.instance?.redo(); }
+  clear() { this.instance?.clear(); }
+  importData(value: unknown, notify = true) { return this.instance?.importData(value, notify) ?? false; }
+  exportData() { return this.instance?.exportData() ?? this.data; }
+  exportSVG(options?: SignatureExportOptions) { return this.instance?.exportSVG(options) ?? ''; }
+  exportPNG(options?: SignaturePNGOptions) { return this.instance?.exportPNG(options) ?? Promise.resolve(null); }
+}
+
+export const defineSignaturePad = () => defineElement('mk-signature-pad', MkSignaturePadElement);