@yewdiel21/motion-kit 0.16.0 → 0.17.0

package/src/components/drilldown-menu/engine.ts

@@ -0,0 +1,338 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface DrilldownMenuItem {
+  /** Unique among siblings; IDs form the navigation path. */
+  id: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  /** Present (even an empty array) for a level; absent for an action. */
+  children?: DrilldownMenuItem[];
+}
+
+export interface DrilldownMenuOptions {
+  items?: DrilldownMenuItem[];
+  /** IDs of branches from the root to the initial level. */
+  path?: string[];
+  /** Root heading and accessible name (default 'Actions'). */
+  label?: string;
+  backLabel?: string;
+  emptyText?: string;
+  /** An action's complete path, including the action's ID. */
+  onSelect?: (item: DrilldownMenuItem, path: string[]) => void;
+  /** Navigation only; the path contains branch IDs. */
+  onPathChange?: (path: string[]) => void;
+}
+
+export interface DrilldownMenuInstance extends Instance {
+  /** Open a branch in the current level; false for missing, disabled or leaf items. */
+  open(id: string): boolean;
+  back(): boolean;
+  root(): void;
+  reset(): void;
+  /** Invalid, disabled or non-branch IDs truncate the requested path safely. */
+  setPath(path: string[], notify?: boolean): void;
+  setItems(items: DrilldownMenuItem[]): void;
+  update(options: Partial<DrilldownMenuOptions>): void;
+  focusItem(id: string): void;
+  readonly path: string[];
+  /** Items in the current level. */
+  readonly items: DrilldownMenuItem[];
+  readonly element: HTMLElement;
+}
+
+const CHEVRON = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 6 6 6-6 6"/></svg>';
+let sequence = 0;
+const samePath = (a: string[], b: string[]) => a.length === b.length && a.every((id, i) => id === b[i]);
+const branch = (item: DrilldownMenuItem) => Array.isArray(item.children);
+const copyItems = (items: DrilldownMenuItem[]): DrilldownMenuItem[] => items.map((item) => ({ ...item, ...(branch(item) ? { children: copyItems(item.children!) } : {}) }));
+
+/** A single live level: directional slide + blur, roving menu focus, and reversible DOM ownership. */
+export function createDrilldownMenu(root: HTMLElement | null, options: DrilldownMenuOptions = {}): DrilldownMenuInstance {
+  if (!root) return inert({ open: () => false, back: () => false, root() {}, reset() {}, setPath() {}, setItems() {}, update() {}, focusItem() {}, path: [], items: [], element: null as unknown as HTMLElement });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-drilldown-${++sequence}`;
+  const authored = [...root.childNodes];
+  // Keep the authored nodes themselves, including any listeners, for destroy().
+  const holder = document.createDocumentFragment();
+  holder.append(...authored);
+  let config = { ...options };
+  let data = copyItems(options.items ?? []);
+  let path: string[] = [];
+  let focused: string | null = null;
+  const remembered = new Map<string, string>();
+  let animation: gsap.core.Timeline | null = null;
+
+  const header = document.createElement('div');
+  header.dataset.mkDrilldownHeader = '';
+  const backButton = document.createElement('button');
+  backButton.type = 'button';
+  backButton.dataset.mkDrilldownBack = '';
+  backButton.innerHTML = CHEVRON;
+  const heading = document.createElement('span');
+  heading.id = `${uid}-heading`;
+  heading.dataset.mkDrilldownHeading = '';
+  header.append(backButton, heading);
+  const breadcrumb = document.createElement('nav');
+  breadcrumb.dataset.mkDrilldownBreadcrumb = '';
+  const crumbs = document.createElement('ol');
+  breadcrumb.append(crumbs);
+  const viewport = document.createElement('div');
+  viewport.dataset.mkDrilldownViewport = '';
+  const menu = document.createElement('div');
+  menu.dataset.mkDrilldownLevel = '';
+  menu.id = `${uid}-level`;
+  menu.setAttribute('role', 'menu');
+  menu.setAttribute('aria-labelledby', heading.id);
+  const empty = document.createElement('p');
+  empty.dataset.mkDrilldownEmpty = '';
+  empty.setAttribute('role', 'status');
+  viewport.append(menu, empty);
+  backButton.setAttribute('aria-controls', menu.id);
+  root.append(header, breadcrumb, viewport);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const levelAt = (requested: string[]) => {
+    const valid: string[] = [];
+    const ancestors: DrilldownMenuItem[] = [];
+    let items = data;
+    for (const id of requested) {
+      const item = items.find((entry) => entry.id === id);
+      if (!item || item.disabled || !branch(item)) break;
+      valid.push(id);
+      ancestors.push(item);
+      items = item.children!;
+    }
+    return { valid, ancestors, items };
+  };
+  const level = () => levelAt(path);
+  const enabled = () => [...menu.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-item]')].filter((item) => !item.disabled);
+  const buttonOf = (id: string) => enabled().find((item) => item.dataset.mkDrilldownItem === id);
+  const cancelMotion = () => {
+    animation?.kill();
+    animation = null;
+    gsap.set(menu, { clearProps: 'transform,opacity,filter' });
+    gsap.set(viewport, { clearProps: 'height' });
+  };
+  const roving = (id: string | null, focus = false) => {
+    const items = enabled();
+    const target = items.find((item) => item.dataset.mkDrilldownItem === id) ?? items[0];
+    focused = target?.dataset.mkDrilldownItem ?? null;
+    for (const item of menu.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-item]')) item.tabIndex = item === target ? 0 : -1;
+    // Empty/all-disabled levels remain a keyboard stop so Left/Escape can return.
+    menu.tabIndex = target ? -1 : 0;
+    if (focused) remembered.set(JSON.stringify(path), focused);
+    if (focus) (target ?? menu).focus({ preventScroll: true });
+  };
+  const notifyPath = () => {
+    const next = [...path];
+    root.dispatchEvent(new CustomEvent('mk:path-change', { bubbles: true, detail: { path: [...next] } }));
+    config.onPathChange?.(next);
+  };
+
+  const render = (direction: number, focus: boolean, preferred?: string | null) => {
+    const oldHeight = viewport.getBoundingClientRect().height;
+    cancelMotion();
+    const current = level();
+    const label = config.label ?? 'Actions';
+    const title = current.ancestors.at(-1)?.label ?? label;
+    heading.textContent = title;
+    backButton.hidden = path.length === 0;
+    backButton.setAttribute('aria-label', config.backLabel ?? 'Back');
+    breadcrumb.setAttribute('aria-label', `${label} path`);
+    const labels = [label, ...current.ancestors.map((item) => item.label)];
+    crumbs.replaceChildren(...labels.map((text, index) => {
+      const li = document.createElement('li');
+      if (index === labels.length - 1) {
+        const span = document.createElement('span');
+        span.setAttribute('aria-current', 'location');
+        span.textContent = text;
+        li.append(span);
+      } else {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.dataset.mkDrilldownCrumb = String(index);
+        button.textContent = text;
+        button.setAttribute('aria-controls', menu.id);
+        li.append(button);
+      }
+      return li;
+    }));
+    menu.replaceChildren(...current.items.map((item, index) => {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.dataset.mkDrilldownItem = item.id;
+      button.setAttribute('role', 'menuitem');
+      button.disabled = Boolean(item.disabled);
+      if (item.disabled) button.setAttribute('aria-disabled', 'true');
+      const text = document.createElement('span');
+      text.dataset.mkDrilldownText = '';
+      const name = document.createElement('span');
+      name.id = `${uid}-item-${index}`;
+      name.dataset.mkDrilldownLabel = '';
+      name.textContent = item.label;
+      button.setAttribute('aria-labelledby', name.id);
+      text.append(name);
+      if (item.description) {
+        const description = document.createElement('span');
+        description.id = `${uid}-description-${index}`;
+        description.dataset.mkDrilldownDescription = '';
+        description.textContent = item.description;
+        button.setAttribute('aria-describedby', description.id);
+        text.append(description);
+      }
+      button.append(text);
+      if (branch(item)) {
+        button.setAttribute('aria-haspopup', 'menu');
+        const arrow = document.createElement('span');
+        arrow.dataset.mkDrilldownArrow = '';
+        arrow.innerHTML = CHEVRON;
+        button.append(arrow);
+      }
+      return button;
+    }));
+    empty.textContent = config.emptyText ?? 'No actions available';
+    empty.hidden = current.items.length !== 0;
+    roving(preferred ?? remembered.get(JSON.stringify(path)) ?? null);
+    if (direction && !reduced()) {
+      // There is only one live menu. Replacing its content before animating avoids
+      // duplicated menuitems and allows rapid navigation without stale callbacks.
+      animation = gsap.timeline({ onComplete: () => { animation = null; } })
+        .fromTo(menu, { x: 28 * direction, opacity: 0, filter: 'blur(6px)' }, { x: 0, opacity: 1, filter: 'blur(0px)', duration: 0.36, ease: EASE.signature, clearProps: 'transform,opacity,filter' });
+      const nextHeight = viewport.getBoundingClientRect().height;
+      if (oldHeight > 0 && nextHeight > 0 && oldHeight !== nextHeight) {
+        animation.fromTo(viewport, { height: oldHeight }, { height: nextHeight, duration: 0.36, ease: EASE.signature, clearProps: 'height' }, 0);
+      }
+    }
+    // Transform measurement may temporarily detach a zero-size element. Restore
+    // focus after GSAP has measured, including in hidden surfaces and jsdom.
+    if (focus) roving(focused, true);
+  };
+
+  const navigate = (requested: string[], notify: boolean, focus: boolean, preferred?: string | null) => {
+    if (scope.disposed) return false;
+    const next = levelAt(requested).valid;
+    if (samePath(path, next)) return false;
+    const previous = path;
+    if (focused) remembered.set(JSON.stringify(previous), focused);
+    const direction = next.length > path.length ? 1 : -1;
+    path = next;
+    render(direction, focus, preferred);
+    if (notify) notifyPath();
+    return true;
+  };
+  const open = (id: string) => {
+    if (scope.disposed) return false;
+    const item = level().items.find((entry) => entry.id === id);
+    if (!item || item.disabled || !branch(item)) return false;
+    return navigate([...path, id], true, true);
+  };
+  const back = () => path.length ? navigate(path.slice(0, -1), true, true, path.at(-1)) : false;
+  const reset = () => navigate([], true, root.contains(document.activeElement), path[0]);
+  const activate = (id: string) => {
+    const item = level().items.find((entry) => entry.id === id);
+    if (!item || item.disabled) return;
+    if (branch(item)) return void open(id);
+    const selected = copyItems([item])[0]!;
+    const selectedPath = [...path, item.id];
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { item: selected, path: [...selectedPath] } }));
+    config.onSelect?.(copyItems([item])[0]!, [...selectedPath]);
+  };
+
+  scope.on(menu, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (!button || !menu.contains(button) || button.disabled) return;
+    roving(button.dataset.mkDrilldownItem!, false);
+    activate(button.dataset.mkDrilldownItem!);
+  });
+  scope.on(menu, 'focusin', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (button && !button.disabled) roving(button.dataset.mkDrilldownItem!, false);
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if ((key === 'ArrowLeft' || key === 'Escape') && path.length) {
+      event.preventDefault();
+      event.stopPropagation();
+      back();
+      return;
+    }
+    if (!menu.contains(event.target as Node)) return;
+    const items = enabled();
+    const at = items.indexOf(document.activeElement as HTMLButtonElement);
+    const moves: Record<string, number> = { ArrowDown: (at + 1) % items.length, ArrowUp: at < 0 ? items.length - 1 : (at - 1 + items.length) % items.length, Home: 0, End: items.length - 1 };
+    if (key in moves && items.length) {
+      event.preventDefault();
+      roving(items[moves[key]]!.dataset.mkDrilldownItem!, true);
+      return;
+    }
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (!button || button.disabled || !menu.contains(button)) return;
+    if (key === 'Enter' || key === ' ' || key === 'ArrowRight') {
+      const item = level().items.find((entry) => entry.id === button.dataset.mkDrilldownItem);
+      if (key === 'ArrowRight' && (!item || !branch(item))) return;
+      event.preventDefault();
+      activate(button.dataset.mkDrilldownItem!);
+    }
+  });
+  scope.on(backButton, 'click', () => back());
+  scope.on(breadcrumb, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-crumb]');
+    if (!button || !breadcrumb.contains(button)) return;
+    const depth = Number(button.dataset.mkDrilldownCrumb);
+    navigate(path.slice(0, depth), true, true, path[depth]);
+  });
+  scope.add(() => {
+    cancelMotion();
+    remembered.clear();
+    header.remove();
+    breadcrumb.remove();
+    viewport.remove();
+    root.append(holder);
+  });
+  path = levelAt(options.path ?? []).valid;
+  render(0, false);
+
+  const update = (next: Partial<DrilldownMenuOptions>) => {
+    if (scope.disposed) return;
+    const active = document.activeElement as HTMLElement | null;
+    const hadFocus = root.contains(active);
+    const backFocused = active === backButton;
+    const crumbFocused = active?.dataset.mkDrilldownCrumb;
+    const previousPath = path;
+    const previousFocus = focused;
+    config = { ...config, ...next };
+    if (next.items !== undefined) data = copyItems(next.items);
+    path = levelAt(next.path ?? path).valid;
+    const changed = !samePath(previousPath, path);
+    const preferred = changed ? previousPath[path.length] : previousFocus;
+    render(0, hadFocus, preferred);
+    if (hadFocus && !changed) {
+      if (backFocused && !backButton.hidden) backButton.focus({ preventScroll: true });
+      else if (crumbFocused !== undefined) {
+        [...crumbs.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-crumb]')]
+          .find((button) => button.dataset.mkDrilldownCrumb === crumbFocused)?.focus({ preventScroll: true });
+      }
+    }
+    // Updating data may invalidate a controlled path; report the repaired path.
+    if (changed && next.path === undefined) notifyPath();
+  };
+  return {
+    open,
+    back,
+    root: reset,
+    reset,
+    setPath: (next, notify = false) => { navigate(next, notify, root.contains(document.activeElement)); },
+    setItems: (items) => update({ items }),
+    update,
+    focusItem(id) { if (!scope.disposed && buttonOf(id)) roving(id, true); },
+    get path() { return [...path]; },
+    get items() { return copyItems(level().items); },
+    element: root,
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/drilldown-menu/react.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { forwardRef, useImperativeHandle, useReducer, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createDrilldownMenu, type DrilldownMenuInstance, type DrilldownMenuItem, type DrilldownMenuOptions } from './engine';
+
+export interface DrilldownMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'onSelect'>, Omit<DrilldownMenuOptions, 'items' | 'path'> {
+  items: DrilldownMenuItem[];
+  /** Controlled branch path; pair with onPathChange. */
+  path?: string[];
+  /** Initial branch path when uncontrolled. */
+  defaultPath?: string[];
+}
+
+export type DrilldownMenuHandle = Pick<DrilldownMenuInstance, 'open' | 'back' | 'root' | 'reset' | 'setPath' | 'focusItem'>;
+
+/** Data-driven hierarchical actions with controlled or internal navigation. */
+export const DrilldownMenu = forwardRef<DrilldownMenuHandle, DrilldownMenuProps>(function DrilldownMenu(
+  { items, path, defaultPath, label, backLabel, emptyText, onSelect, onPathChange, className, ...props },
+  handle,
+) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<DrilldownMenuInstance | null>(null);
+  const select = useLatest(onSelect);
+  const changed = useLatest(onPathChange);
+  const controlled = useLatest(path);
+  const [, refresh] = useReducer((value: number) => value + 1, 0);
+  useImperativeHandle(handle, () => ({
+    open: (id) => instance.current?.open(id) ?? false,
+    back: () => instance.current?.back() ?? false,
+    root: () => instance.current?.root(),
+    reset: () => instance.current?.reset(),
+    setPath: (next, notify) => {
+      instance.current?.setPath(next, notify);
+      // Silent engine synchronization does not invoke onPathChange. Controlled
+      // refs must still reconcile with the parent's current path on a render.
+      if (controlled.current !== undefined) refresh();
+    },
+    focusItem: (id) => instance.current?.focusItem(id),
+  }), []);
+  const itemsKey = JSON.stringify(items);
+  useIsomorphicLayoutEffect(() => {
+    const created = createDrilldownMenu(ref.current, {
+      items,
+      path: path ?? defaultPath,
+      label,
+      backLabel,
+      emptyText,
+      onSelect: (item, selectedPath) => select.current?.(item, selectedPath),
+      onPathChange: (next) => {
+        changed.current?.(next);
+        // Also render if a controlled parent declines the navigation request.
+        if (controlled.current !== undefined) refresh();
+      },
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // The engine owns its DOM for this mount; subsequent props update it below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    // Controlled data and its path are one external model. Applying the path in
+    // this update avoids repairing a stale level against replacement items.
+    instance.current?.update({ items, label, backLabel, emptyText, ...(path !== undefined ? { path } : {}) });
+    // JSON keys also catch edited data without forcing redraws on equal arrays.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [itemsKey, label, backLabel, emptyText]);
+  useIsomorphicLayoutEffect(() => {
+    if (path !== undefined) instance.current?.setPath(path);
+  });
+  return <div {...rootProps} ref={ref} className={['mk-drilldown-menu', className].filter(Boolean).join(' ')} />;
+});

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);