@yewdiel21/motion-kit 0.16.0 → 0.17.0

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

@@ -0,0 +1,437 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+/** Coordinates are fractions of the drawing area, independent of its size. */
+export interface SignaturePoint { x: number; y: number }
+export interface SignatureStroke { points: SignaturePoint[]; color: string; width: number }
+export interface SignatureData { version: 1; strokes: SignatureStroke[] }
+export type SignaturePadChangeReason = 'draw' | 'undo' | 'redo' | 'clear' | 'import' | 'reset';
+export interface SignaturePadChangeDetail {
+  data: SignatureData;
+  reason: SignaturePadChangeReason;
+  isEmpty: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+export interface SignatureExportOptions {
+  /** CSS pixels; default is the current drawing area, or 640 × 240 before layout. */
+  width?: number;
+  height?: number;
+  /** Omit for transparency. Accepts a literal CSS color, without variables or URLs. */
+  background?: string;
+}
+export interface SignaturePNGOptions extends SignatureExportOptions {
+  /** Raster resolution multiplier, clamped to 1–4 (default 2). */
+  scale?: number;
+}
+export interface SignaturePadOptions {
+  data?: SignatureData;
+  label?: string;
+  hint?: string;
+  placeholder?: string;
+  /** Literal CSS ink color; defaults to the theme's text color. */
+  color?: string;
+  /** Ink width in CSS pixels, default 2.4. */
+  width?: number;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Include native undo, redo and clear buttons (default true). */
+  toolbar?: boolean;
+  /** Adds a hidden input containing the versioned JSON data. */
+  name?: string;
+  /** Maximum undo steps, clamped to 1–100 (default 50). */
+  historyLimit?: number;
+  onChange?: (data: SignatureData, detail: SignaturePadChangeDetail) => void;
+}
+export interface SignaturePadInstance extends Instance {
+  readonly data: SignatureData;
+  readonly isEmpty: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  undo(): void;
+  redo(): void;
+  clear(): void;
+  /** Invalid input returns false and leaves the signature untouched. Import resets history. */
+  importData(data: unknown, notify?: boolean): boolean;
+  exportData(): SignatureData;
+  exportSVG(options?: SignatureExportOptions): string;
+  /** Returns null when rasterization is unavailable or fails. */
+  exportPNG(options?: SignaturePNGOptions): Promise<Blob | null>;
+  setDisabled(disabled: boolean): void;
+  setReadOnly(readOnly: boolean): void;
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const MAX_STROKES = 500;
+const MAX_POINTS = 50_000;
+const emptyData = (): SignatureData => ({ version: 1, strokes: [] });
+const cloneStrokes = (strokes: SignatureStroke[]) => strokes.map((stroke) => ({ ...stroke, points: stroke.points.map((point) => ({ ...point })) }));
+const sameStrokes = (left: SignatureStroke[], right: SignatureStroke[]) => left.length === right.length && left.every((stroke, index) => {
+  const other = right[index]!;
+  return stroke.color === other.color && stroke.width === other.width && stroke.points.length === other.points.length && stroke.points.every((point, index) => point.x === other.points[index]!.x && point.y === other.points[index]!.y);
+});
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
+
+/** Reject paint servers, CSS variables and markup so exports stay self-contained. */
+function validColor(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length > 100) return false;
+  if (/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(value)) return true;
+  if (!/^(?:rgba?|hsla?)\([\d\s.,%/+\-degratun]+\)$/i.test(value) && !/^[a-z]+$/i.test(value)) return false;
+  if (/^(?:inherit|initial|unset|revert|revertlayer|currentcolor)$/i.test(value)) return false;
+  if (typeof document === 'undefined') return /^(?:black|white|transparent)$/i.test(value);
+  const probe = document.createElement('span');
+  probe.style.color = value;
+  return probe.style.color !== '';
+}
+
+function validatedData(value: unknown): SignatureData | null {
+  if (!value || typeof value !== 'object') return null;
+  const data = value as Record<string, unknown>;
+  if (data.version !== 1 || !Array.isArray(data.strokes) || data.strokes.length > MAX_STROKES) return null;
+  const strokes: SignatureStroke[] = [];
+  let count = 0;
+  for (const candidate of data.strokes) {
+    if (!candidate || typeof candidate !== 'object') return null;
+    const stroke = candidate as Record<string, unknown>;
+    if (!validColor(stroke.color) || !finite(stroke.width) || stroke.width < 0.1 || stroke.width > 64 || !Array.isArray(stroke.points) || !stroke.points.length) return null;
+    count += stroke.points.length;
+    if (count > MAX_POINTS) return null;
+    const points: SignaturePoint[] = [];
+    for (const candidate of stroke.points) {
+      if (!candidate || typeof candidate !== 'object') return null;
+      const point = candidate as Record<string, unknown>;
+      if (!finite(point.x) || !finite(point.y) || point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1) return null;
+      points.push({ x: point.x, y: point.y });
+    }
+    strokes.push({ color: stroke.color, width: stroke.width, points });
+  }
+  return { version: 1, strokes };
+}
+
+const rounded = (value: number) => Number(value.toFixed(3));
+function strokePath(points: SignaturePoint[], width: number, height: number) {
+  const coordinates = points.map((point) => [rounded(point.x * width), rounded(point.y * height)] as const);
+  const first = coordinates[0]!;
+  let path = `M ${first[0]} ${first[1]}`;
+  if (coordinates.length === 1) return `${path} l 0.001 0`;
+  for (let i = 1; i < coordinates.length - 1; i++) {
+    const current = coordinates[i]!;
+    const next = coordinates[i + 1]!;
+    path += ` Q ${current[0]} ${current[1]} ${rounded((current[0] + next[0]) / 2)} ${rounded((current[1] + next[1]) / 2)}`;
+  }
+  const last = coordinates[coordinates.length - 1]!;
+  return `${path} L ${last[0]} ${last[1]}`;
+}
+
+function makePath(stroke: SignatureStroke, width: number, height: number) {
+  const path = document.createElementNS(SVG_NS, 'path');
+  path.setAttribute('d', strokePath(stroke.points, width, height));
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke', stroke.color);
+  path.setAttribute('stroke-width', String(stroke.width));
+  path.setAttribute('stroke-linecap', 'round');
+  path.setAttribute('stroke-linejoin', 'round');
+  return path;
+}
+
+let nextId = 0;
+
+/** A responsive SVG drawing pad. Drawing is immediate; only toolbar feedback uses motion. */
+export function createSignaturePad(root: HTMLElement | null, options: SignaturePadOptions = {}): SignaturePadInstance {
+  if (!root) return inert<SignaturePadInstance>({
+    data: emptyData(), isEmpty: true, canUndo: false, canRedo: false,
+    undo() {}, redo() {}, clear() {}, importData: () => false, exportData: emptyData,
+    exportSVG: () => '', exportPNG: async () => null, setDisabled() {}, setReadOnly() {},
+  });
+  registerMotion();
+  const scope = createScope();
+  let strokes = validatedData(options.data)?.strokes ?? [];
+  const initialStrokes = cloneStrokes(strokes);
+  let disabled = Boolean(options.disabled);
+  let readOnly = Boolean(options.readOnly);
+  let undoStack: SignatureStroke[][] = [];
+  let redoStack: SignatureStroke[][] = [];
+  const historyLimit = finite(options.historyLimit) ? clamp(Math.floor(options.historyLimit), 1, 100) : 50;
+  const inkWidth = finite(options.width) ? clamp(options.width, 0.1, 64) : 2.4;
+  const exportData = (): SignatureData => ({ version: 1, strokes: cloneStrokes(strokes) });
+  const wrapper = document.createElement('div');
+  wrapper.dataset.mkSignatureBody = '';
+  const surface = document.createElement('div');
+  surface.dataset.mkSignatureSurface = '';
+  const svg = document.createElementNS(SVG_NS, 'svg');
+  svg.dataset.mkSignatureDrawing = '';
+  svg.setAttribute('role', 'img');
+  svg.setAttribute('aria-label', options.label ?? 'Área de firma');
+  svg.setAttribute('preserveAspectRatio', 'none');
+  const placeholder = document.createElement('span');
+  placeholder.dataset.mkSignaturePlaceholder = '';
+  placeholder.setAttribute('aria-hidden', 'true');
+  placeholder.textContent = options.placeholder ?? 'Firma aquí';
+  surface.append(svg, placeholder);
+  const footer = document.createElement('div');
+  footer.dataset.mkSignatureFooter = '';
+  const toolbar = document.createElement('div');
+  toolbar.dataset.mkSignatureToolbar = '';
+  toolbar.setAttribute('role', 'group');
+  toolbar.setAttribute('aria-label', 'Herramientas de firma');
+  const makeButton = (action: string, text: string) => {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.dataset.mkSignatureAction = action;
+    button.textContent = text;
+    toolbar.append(button);
+    return button;
+  };
+  const undoButton = makeButton('undo', 'Deshacer');
+  const redoButton = makeButton('redo', 'Rehacer');
+  const clearButton = makeButton('clear', 'Limpiar');
+  if (options.toolbar !== false) footer.append(toolbar);
+  const status = document.createElement('span');
+  status.dataset.mkSignatureStatus = '';
+  status.setAttribute('role', 'status');
+  status.setAttribute('aria-live', 'polite');
+  footer.append(status);
+  const hint = document.createElement('p');
+  hint.dataset.mkSignatureHint = '';
+  hint.id = `mk-signature-hint-${++nextId}`;
+  hint.textContent = options.hint ?? 'Dibuja con el ratón, el dedo o un lápiz. Puedes deshacer cada trazo.';
+  svg.setAttribute('aria-describedby', hint.id);
+  wrapper.append(surface, footer, hint);
+  let hidden: HTMLInputElement | null = null;
+  if (options.name) {
+    hidden = document.createElement('input');
+    hidden.type = 'hidden';
+    hidden.name = options.name;
+    wrapper.append(hidden);
+  }
+  root.append(wrapper);
+  scope.add(() => wrapper.remove());
+  for (const name of ['data-mk-disabled', 'data-mk-readonly', 'data-mk-drawing', 'data-mk-empty']) scope.attr(root, name, null);
+  scope.attr(root, 'data-mk-ready', '');
+  let dimensions = { width: 640, height: 240 };
+  let active: { pointerId: number; stroke: SignatureStroke; path: SVGPathElement } | null = null;
+  let feedback: gsap.core.Tween | null = null;
+  const locked = () => disabled || readOnly;
+
+  const update = () => {
+    root.toggleAttribute('data-mk-empty', !strokes.length && !active);
+    root.toggleAttribute('data-mk-disabled', disabled);
+    root.toggleAttribute('data-mk-readonly', readOnly);
+    svg.setAttribute('aria-disabled', String(disabled));
+    placeholder.hidden = strokes.length > 0 || active !== null;
+    undoButton.disabled = locked() || !undoStack.length;
+    redoButton.disabled = locked() || !redoStack.length;
+    clearButton.disabled = locked() || !strokes.length;
+    status.textContent = strokes.length ? `${strokes.length} ${strokes.length === 1 ? 'trazo' : 'trazos'} · ${readOnly ? 'Solo lectura' : 'Firma capturada'}` : 'Sin firma';
+    if (hidden) {
+      hidden.disabled = disabled;
+      hidden.value = JSON.stringify(exportData());
+    }
+  };
+  const render = () => {
+    const rect = surface.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) dimensions = { width: rect.width, height: rect.height };
+    svg.setAttribute('viewBox', `0 0 ${dimensions.width} ${dimensions.height}`);
+    svg.replaceChildren(...strokes.map((stroke) => makePath(stroke, dimensions.width, dimensions.height)));
+    if (active) {
+      active.path = makePath(active.stroke, dimensions.width, dimensions.height);
+      svg.append(active.path);
+    }
+  };
+  const emit = (reason: SignaturePadChangeReason) => {
+    const detail: SignaturePadChangeDetail = { data: exportData(), reason, isEmpty: !strokes.length, canUndo: !!undoStack.length, canRedo: !!redoStack.length };
+    options.onChange?.(exportData(), { ...detail, data: exportData() });
+    if (scope.disposed) return;
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail }));
+  };
+  const release = (pointerId: number) => {
+    try { surface.releasePointerCapture?.(pointerId); } catch { /* The pointer may already be released. */ }
+  };
+  const cancel = () => {
+    if (!active) return;
+    const pointerId = active.pointerId;
+    active = null;
+    root.removeAttribute('data-mk-drawing');
+    release(pointerId);
+    render();
+    update();
+  };
+  const remember = () => {
+    undoStack.push(strokes);
+    if (undoStack.length > historyLimit) undoStack.shift();
+    redoStack = [];
+  };
+  const pulse = (button: HTMLButtonElement) => {
+    feedback?.progress(1).kill();
+    if (reduced()) return;
+    feedback = gsap.fromTo(button, { scale: 0.95 }, { scale: 1, duration: 0.24, ease: EASE.click });
+  };
+  const undo = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!undoStack.length) return;
+    redoStack.push(strokes);
+    strokes = undoStack.pop()!;
+    render(); update(); emit('undo');
+  };
+  const redo = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!redoStack.length) return;
+    undoStack.push(strokes);
+    strokes = redoStack.pop()!;
+    render(); update(); emit('redo');
+  };
+  const clear = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!strokes.length) return;
+    remember(); strokes = [];
+    render(); update(); emit('clear');
+  };
+  const form = hidden?.form;
+  if (form) scope.on(form, 'reset', (event) => {
+    // Native reset runs after dispatch. Waiting also observes preventDefault from later listeners.
+    scope.timeout(() => {
+      if (scope.disposed || event.defaultPrevented || hidden?.form !== form) return;
+      const changed = !sameStrokes(strokes, initialStrokes);
+      cancel(); strokes = cloneStrokes(initialStrokes); undoStack = []; redoStack = [];
+      render(); update();
+      if (changed) emit('reset');
+    }, 0);
+  });
+  const pointFrom = (event: PointerEvent): SignaturePoint | null => {
+    const rect = surface.getBoundingClientRect();
+    if (!rect.width || !rect.height || !finite(event.clientX) || !finite(event.clientY)) return null;
+    return { x: clamp((event.clientX - rect.left) / rect.width, 0, 1), y: clamp((event.clientY - rect.top) / rect.height, 0, 1) };
+  };
+  const addPoint = (event: PointerEvent) => {
+    if (!active) return;
+    const point = pointFrom(event);
+    if (!point || active.stroke.points.length >= MAX_POINTS - strokes.reduce((sum, stroke) => sum + stroke.points.length, 0)) return;
+    const last = active.stroke.points[active.stroke.points.length - 1]!;
+    if (point.x === last.x && point.y === last.y) return;
+    active.stroke.points.push(point);
+    active.path.setAttribute('d', strokePath(active.stroke.points, dimensions.width, dimensions.height));
+  };
+  scope.on(surface, 'pointerdown', (event) => {
+    const pointer = event as PointerEvent;
+    if (locked() || active || pointer.button !== 0 || pointer.isPrimary === false || strokes.length >= MAX_STROKES || strokes.reduce((sum, stroke) => sum + stroke.points.length, 0) >= MAX_POINTS) return;
+    const point = pointFrom(pointer);
+    if (!point) return;
+    pointer.preventDefault();
+    const themed = getComputedStyle(root).getPropertyValue('--mk-signature-ink').trim() || getComputedStyle(root).color;
+    const color = validColor(options.color) ? options.color : validColor(themed) ? themed : '#252735';
+    const stroke: SignatureStroke = { points: [point], color, width: inkWidth };
+    active = { pointerId: pointer.pointerId, stroke, path: makePath(stroke, dimensions.width, dimensions.height) };
+    render(); update();
+    root.setAttribute('data-mk-drawing', '');
+    try { surface.setPointerCapture?.(pointer.pointerId); } catch { /* Synthetic events have no active pointer. */ }
+  });
+  // Window listeners also finish safely when capture is unavailable in an embedded browser.
+  scope.on(window, 'pointermove', (event) => {
+    const pointer = event as PointerEvent;
+    if (!active || pointer.pointerId !== active.pointerId) return;
+    pointer.preventDefault();
+    const samples = typeof pointer.getCoalescedEvents === 'function' ? pointer.getCoalescedEvents() : [];
+    for (const sample of samples) addPoint(sample);
+    addPoint(pointer);
+  }, { passive: false });
+  scope.on(window, 'pointerup', (event) => {
+    const pointer = event as PointerEvent;
+    if (!active || pointer.pointerId !== active.pointerId) return;
+    addPoint(pointer);
+    const completed = active;
+    active = null;
+    root.removeAttribute('data-mk-drawing');
+    release(completed.pointerId);
+    remember(); strokes = [...strokes, completed.stroke];
+    update(); emit('draw');
+  });
+  for (const type of ['pointercancel', 'lostpointercapture']) scope.on(type === 'pointercancel' ? window : surface, type, (event) => {
+    if (active?.pointerId === (event as PointerEvent).pointerId) cancel();
+  });
+  scope.on(window, 'blur', cancel);
+  scope.on(document, 'visibilitychange', () => { if (document.hidden) cancel(); });
+  for (const [button, action] of [[undoButton, undo], [redoButton, redo], [clearButton, clear]] as const) scope.on(button, 'click', () => {
+    if (locked() || button.disabled) return;
+    pulse(button); action();
+  });
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(render)).observe(surface);
+  scope.on(window, 'resize', render);
+  scope.add(() => { cancel(); feedback?.kill(); });
+  render(); update();
+
+  const exportSVG = (settings: SignatureExportOptions = {}) => {
+    const width = finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width;
+    const height = finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height;
+    const output = document.createElementNS(SVG_NS, 'svg');
+    output.setAttribute('width', String(rounded(width)));
+    output.setAttribute('height', String(rounded(height)));
+    output.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    if (validColor(settings.background)) {
+      const background = document.createElementNS(SVG_NS, 'rect');
+      background.setAttribute('width', '100%'); background.setAttribute('height', '100%'); background.setAttribute('fill', settings.background);
+      output.append(background);
+    }
+    output.append(...strokes.map((stroke) => makePath(stroke, width, height)));
+    return new XMLSerializer().serializeToString(output);
+  };
+  const pending = new Set<() => void>();
+  scope.add(() => { for (const cancelExport of pending) cancelExport(); pending.clear(); });
+  return {
+    get data() { return exportData(); },
+    get isEmpty() { return !strokes.length; },
+    get canUndo() { return !!undoStack.length; },
+    get canRedo() { return !!redoStack.length; },
+    undo, redo, clear, exportData,
+    importData(value, notify = true) {
+      if (scope.disposed) return false;
+      const next = validatedData(value);
+      if (!next) return false;
+      if (sameStrokes(next.strokes, strokes)) return true;
+      cancel(); strokes = next.strokes; undoStack = []; redoStack = [];
+      render(); update();
+      if (notify) emit('import');
+      return true;
+    },
+    exportSVG: (settings) => scope.disposed ? '' : exportSVG(settings),
+    exportPNG(settings = {}) {
+      if (scope.disposed) return Promise.resolve(null);
+      const canvas = document.createElement('canvas');
+      let context: CanvasRenderingContext2D | null;
+      try { context = canvas.getContext('2d'); }
+      catch { return Promise.resolve(null); }
+      if (!context || typeof canvas.toBlob !== 'function') return Promise.resolve(null);
+      const scale = finite(settings.scale) ? clamp(settings.scale, 1, 4) : 2;
+      canvas.width = Math.round((finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width) * scale);
+      canvas.height = Math.round((finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height) * scale);
+      return new Promise<Blob | null>((resolve) => {
+        const image = new Image();
+        let finished = false;
+        const done = (blob: Blob | null) => {
+          if (finished) return;
+          finished = true; image.onload = null; image.onerror = null;
+          pending.delete(cancelExport); clearTimeout(timer); resolve(scope.disposed ? null : blob);
+        };
+        const cancelExport = () => { done(null); image.src = ''; };
+        const timer = setTimeout(cancelExport, 10_000);
+        pending.add(cancelExport);
+        image.onerror = () => done(null);
+        image.onload = () => {
+          try {
+            context.drawImage(image, 0, 0, canvas.width, canvas.height);
+            canvas.toBlob(done, 'image/png');
+          } catch { done(null); }
+        };
+        image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(exportSVG(settings))}`;
+      });
+    },
+    setDisabled(value) { if (!scope.disposed) { cancel(); disabled = Boolean(value); update(); } },
+    setReadOnly(value) { if (!scope.disposed) { cancel(); readOnly = Boolean(value); update(); } },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/signature-pad/react.tsx

@@ -0,0 +1,56 @@
+'use client';
+import { useReducer, useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createSignaturePad, type SignatureData, type SignaturePadInstance, type SignaturePadOptions } from './engine';
+
+export interface SignaturePadProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children' | 'dangerouslySetInnerHTML' | 'defaultValue'>, Omit<SignaturePadOptions, 'data'> {
+  /** Controlled data. Accept edits through onChange; rejected edits are restored after rendering. */
+  value?: SignatureData;
+  defaultValue?: SignatureData;
+  instanceRef?: MutableRefObject<SignaturePadInstance | null>;
+}
+
+/** <SignaturePad value={signature} onChange={setSignature} name="signature" />. */
+export function SignaturePad({ value, defaultValue, label, hint, placeholder, color, width, disabled, readOnly, toolbar, name, historyLimit, onChange, instanceRef, className, ...props }: SignaturePadProps) {
+  // JavaScript callers can still supply these props; the engine owns all child nodes.
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SignaturePadInstance | null>(null);
+  const edited = useRef(value ?? defaultValue);
+  const current = useLatest(value);
+  const change = useLatest(onChange);
+  const [, refresh] = useReducer((revision: number) => revision + 1, 0);
+  useIsomorphicLayoutEffect(() => {
+    const created = createSignaturePad(ref.current, {
+      data: current.current ?? edited.current,
+      label, hint, placeholder, color, width, disabled, readOnly, toolbar, name, historyLimit,
+      onChange: (data, detail) => {
+        edited.current = data;
+        change.current?.(data, detail);
+        // A render also reconciles an unchanged controlled prop when the owner rejects an edit.
+        if (current.current !== undefined) refresh();
+      },
+    });
+    instance.current = created;
+    return () => {
+      edited.current = created.exportData();
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [label, hint, placeholder, color, width, toolbar, name, historyLimit]);
+  useIsomorphicLayoutEffect(() => {
+    const created = instance.current;
+    if (!created) return;
+    created.setDisabled(Boolean(disabled));
+    created.setReadOnly(Boolean(readOnly));
+  }, [disabled, readOnly]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) instance.current?.importData(value, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, label, hint, placeholder, color, width, toolbar, name, historyLimit]);
+  return <div {...rootProps} ref={ref} className={['mk-signature-pad', className].filter(Boolean).join(' ')} />;
+}

package/src/components/signature-pad/signature-pad.css

@@ -0,0 +1,103 @@
+/* Normalized SVG ink survives layout changes. Only the drawing area captures touch. */
+.mk-signature-pad,
+mk-signature-pad {
+  --mk-signature-height: clamp(12rem, 32vw, 17rem);
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 24px;
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface] {
+  position: relative;
+  height: var(--mk-signature-height);
+  min-height: 8rem;
+  overflow: hidden;
+  background: var(--mk-signature-paper, var(--mk-surface-2));
+  cursor: crosshair;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface]::after {
+  position: absolute;
+  right: 1.5rem;
+  bottom: 2rem;
+  left: 1.5rem;
+  border-bottom: 1px dashed var(--mk-outline-soft);
+  content: '';
+  pointer-events: none;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-drawing] {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder] {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  color: var(--mk-muted);
+  font-size: 1.5rem;
+  font-style: italic;
+  font-weight: 400;
+  pointer-events: none;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder][hidden] { display: none; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-footer] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.875rem 1rem 0;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-toolbar] {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action] {
+  min-height: 2.75rem;
+  padding: 0.5rem 0.875rem;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 64px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:hover:enabled { background: var(--mk-surface-4); }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:disabled { opacity: 0.4; cursor: default; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status],
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] {
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  line-height: 1.5;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status] { font-variant-numeric: tabular-nums; }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] { margin: 0; padding: 0.75rem 1rem 1rem; }
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-readonly] [data-mk-signature-surface],
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { cursor: default; touch-action: auto; }
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { opacity: 0.55; }

package/src/components/voice-message-bubble/README.md

@@ -0,0 +1,31 @@
+# Voice Message Bubble
+
+Burbuja entrante/saliente con autor, hora y estado de entrega. Compone el reproductor real [Waveform Player](../waveform-player/README.md); no graba, no solicita micrófono y no inicia audio automáticamente.
+
+```tsx
+import { VoiceMessageBubble } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css/components/waveform-player';
+import '@yewdiel21/motion-kit/css/components/voice-message-bubble';
+
+<VoiceMessageBubble src="/mensaje.wav" peaks={[.2, .6, .9, .4]} author="Ana"
+  timestamp="10:42" direction="incoming" />
+<VoiceMessageBubble src="/respuesta.wav" peaks={peaks} author="Tú"
+  timestamp="10:43" direction="outgoing" status="read" />
+```
+
+```html
+<mk-voice-message-bubble src="/mensaje.wav" peaks="[0.2,0.6,0.9,0.4]"
+  author="Ana" timestamp="10:42" direction="incoming"></mk-voice-message-bubble>
+<script type="module">
+  import { defineVoiceMessageBubble } from '@yewdiel21/motion-kit/elements';
+  defineVoiceMessageBubble();
+</script>
+```
+
+`createVoiceMessageBubble(root, options)` acepta todas las opciones del reproductor y añade `direction` (`incoming` por defecto u `outgoing`), `author`, `timestamp` (texto visible), `dateTime` (fecha legible por máquinas, opcional) y `status` (`sending`, `sent`, `delivered`, `read`, `failed`). El estado de entrega lo controla tu aplicación; no implica envío de mensajes. Autor/hora/estado vacíos se ocultan. El nombre accesible del reproductor incluye el autor, o usa `label` si lo especificas.
+
+La instancia ofrece `play(): Promise<boolean>`, `pause()`, `seek(seconds)`, `update(partialOptions)`, `state`, `audio`, `destroy()`. `VoiceMessageBubble` admite `instanceRef`. `MkVoiceMessageBubbleElement` expone los mismos métodos y actualiza atributos sin recrear el audio. `peaks` y `playback-rates` son JSON; el atributo de fecha es `date-time`. Los cambios de autor, dirección y hora conservan la reproducción. Eventos `mk:audio-*` del reproductor burbujean desde la burbuja.
+
+Necesita **waveform-player.css y voice-message-bubble.css**. El motor también depende de `waveform-player/engine.ts`; copiar la receta debe incluir esa dependencia. Usa los tokens del tema y respeta movimiento reducido a través del reproductor. Los picos se suministran de antemano; no realiza análisis automático de audio. Agrega una transcripción cerca del mensaje para contenido hablado. Los demos usan un sonido sintetizado original local de seis segundos, sin voz humana.
+
+Tipos: `VoiceMessageBubbleOptions`, `VoiceMessageBubbleInstance`, `VoiceMessageStatus`, `VoiceMessageBubbleProps`.

package/src/components/voice-message-bubble/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createVoiceMessageBubble, type VoiceMessageBubbleInstance, type VoiceMessageBubbleOptions } from './engine';
+
+export class MkVoiceMessageBubbleElement extends MkElement<VoiceMessageBubbleInstance> {
+  static options: Record<string, OptionType> = { src: 'string', peaks: 'json', label: 'string', disabled: 'boolean', playbackRates: 'json', direction: 'string', author: 'string', timestamp: 'string', dateTime: 'string', status: 'string' };
+  protected create(options: Record<string, unknown>) { return createVoiceMessageBubble(this, options as VoiceMessageBubbleOptions); }
+  play() { return this.instance?.play() ?? Promise.resolve(false); }
+  pause() { this.instance?.pause(); }
+  seek(seconds: number) { this.instance?.seek(seconds); }
+  update(options: Partial<VoiceMessageBubbleOptions>) { this.instance?.update(options); }
+  get state() { return this.instance?.state; }
+  get audio() { return this.instance?.audio ?? null; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    if (!Object.hasOwn(MkVoiceMessageBubbleElement.options, option)) return;
+    this.instance.update({ [option]: this.options[option] });
+  }
+}
+export const defineVoiceMessageBubble = () => defineElement('mk-voice-message-bubble', MkVoiceMessageBubbleElement);