@yewdiel21/motion-kit 0.15.0 → 0.17.0

package/src/components/radial-chart/engine.ts

@@ -3,7 +3,7 @@ import { reduced } from '../../core/reduced';
 import { createScope } from '../../core/scope';
 import { inert, type Instance } from '../../core/types';
 import { blurIn, rollDigits } from '../../motion/micro';
-import { chartFrame, finite, formatNumber, onWidth, polar, round, slotColor, svg } from '../chart/parts';
+import { arcPath, chartFrame, finite, formatNumber, onWidth, polar, round, slotColor, svg } from '../chart/parts';
 
 /*
  * Radial chart: totals as rings, one inside the other, each filling its track
@@ -33,6 +33,10 @@ export interface RadialChartOptions {
   size?: number;
   /** Ring thickness in px (default: what fits, up to 16). */
   thickness?: number;
+  /** Discrete sectors per ring (0: continuous, default). */
+  segments?: number;
+  /** Show values (default) or progress toward the goals in the middle. */
+  center?: 'value' | 'percent';
   label?: string;
   /** The middle when nothing is chosen (default 'Total'). */
   totalLabel?: string;
@@ -90,6 +94,7 @@ export function createRadialChart(root: HTMLElement | null, initial: RadialChart
   const percent = (ring: { value: number; max: number }) => new Intl.NumberFormat(undefined, { style: 'percent', maximumFractionDigits: 0 }).format(ring.value / ring.max);
   const sweep = () => (Math.min(360, Math.max(90, finite(options.sweep) ? options.sweep : 360)) * Math.PI) / 180;
   const startAngle = () => -sweep() / 2 + (sweep() >= Math.PI * 2 - 1e-6 ? Math.PI : 0);
+  const segments = () => finite(options.segments) ? Math.max(0, Math.min(80, Math.round(options.segments))) : 0;
 
   let geometry = { size: 240, cx: 120, cy: 120, radii: [] as number[], thickness: 12 };
   let arcs: SVGPathElement[] = [];
@@ -109,17 +114,35 @@ export function createRadialChart(root: HTMLElement | null, initial: RadialChart
     const thickness = finite(options.thickness) ? options.thickness : Math.max(4, Math.min(16, fit));
     const spacing = thickness * 1.35;
     geometry = { size, cx: size / 2, cy: size / 2, thickness, radii: model.map((_, i) => outer - thickness / 2 - i * spacing) };
-    canvas.setAttribute('viewBox', `0 0 ${size} ${size}`);
+    const half = sweep() <= Math.PI + 1e-6;
+    const height = half ? size / 2 + 54 : size;
+    canvas.setAttribute('viewBox', `0 0 ${size} ${height}`);
     canvas.setAttribute('width', String(size));
-    canvas.setAttribute('height', String(size));
+    canvas.setAttribute('height', String(height));
     plot.style.setProperty('--mk-radial-size', `${size}px`);
     plot.style.setProperty('--mk-radial-thickness', `${thickness}px`);
+    plot.style.setProperty('--mk-radial-center-y', half ? `${size / 2}px` : '50%');
+    plot.style.setProperty('--mk-radial-center-width', n === 1 ? '0.68' : '0.36');
   };
   scope.add(() => {
     plot.style.removeProperty('--mk-radial-size');
     plot.style.removeProperty('--mk-radial-thickness');
+    plot.style.removeProperty('--mk-radial-center-y');
+    plot.style.removeProperty('--mk-radial-center-width');
   });
 
+  const segmentedPath = (radius: number, share: number) => {
+    const count = segments(), step = sweep() / count, a0 = startAngle();
+    const gap = Math.min(step * 0.3, 4 / Math.max(1, radius));
+    const limit = a0 + sweep() * Math.min(1, Math.max(0, share));
+    const outer = radius + geometry.thickness / 2 - 1, inner = Math.max(0, radius - geometry.thickness / 2 + 1);
+    return Array.from({ length: count }, (_, index) => {
+      const from = a0 + index * step + gap / 2;
+      const to = Math.min(a0 + (index + 1) * step - gap / 2, limit);
+      return to > from ? arcPath(geometry.cx, geometry.cy, outer, inner, from, to) : '';
+    }).join('');
+  };
+
   const build = () => {
     canvas.replaceChildren();
     const { cx, cy, radii } = geometry;
@@ -127,13 +150,14 @@ export function createRadialChart(root: HTMLElement | null, initial: RadialChart
     const back = svg('g', { 'data-mk-part': 'tracks' });
     const front = svg('g', { 'data-mk-part': 'series' });
     tracks = model.map((_, i) => {
-      const track = svg('path', { d: strokeArc(cx, cy, radii[i]!, a0, a0 + sweep()), 'data-mk-index': i });
+      const track = svg('path', { d: segments() ? segmentedPath(radii[i]!, 1) : strokeArc(cx, cy, radii[i]!, a0, a0 + sweep()), 'data-mk-index': i });
       back.append(track);
       return track;
     });
     arcs = model.map((ring, i) => {
       const arc = svg('path', { 'data-mk-index': i, 'data-mk-part': 'ring' });
       arc.style.stroke = ring.color;
+      if (segments()) arc.style.fill = ring.color;
       front.append(arc);
       return arc;
     });
@@ -146,14 +170,16 @@ export function createRadialChart(root: HTMLElement | null, initial: RadialChart
     const a0 = startAngle();
     arcs.forEach((arc, i) => {
       const share = Math.min(1, Math.max(0, (values[i] ?? 0) / model[i]!.max));
-      arc.setAttribute('d', share > 0.001 ? strokeArc(cx, cy, radii[i]!, a0, a0 + sweep() * share) : '');
+      arc.setAttribute('d', share > 0.001 ? segments() ? segmentedPath(radii[i]!, share) : strokeArc(cx, cy, radii[i]!, a0, a0 + sweep() * share) : '');
     });
   };
 
   const paintCenter = (animate: boolean) => {
     center.hidden = !model.length;
     const ring = selected === null ? null : model[selected];
-    const text = ring ? format(ring.value) : format(total());
+    const denominator = ring ? ring.max : model.reduce((sum, each) => sum + each.max, 0);
+    const value = ring ? ring.value : total();
+    const text = options.center === 'percent' ? new Intl.NumberFormat(undefined, { style: 'percent', maximumFractionDigits: 1 }).format(value / (denominator || 1)) : format(value);
     const caption = ring ? `${ring.label} · ${percent(ring)}` : (options.totalLabel ?? 'Total');
     const changed = centerLabel.textContent !== caption;
     if (centerValue.textContent !== text) {
@@ -178,6 +204,7 @@ export function createRadialChart(root: HTMLElement | null, initial: RadialChart
 
   const draw = (animate: boolean) => {
     glide?.kill();
+    scope.attr(root, 'data-mk-segmented', segments() ? '' : null);
     const name = options.label ?? 'Gráfica radial';
     canvas.setAttribute('aria-label', model.length ? `${name}. ${model.length} anillos, total ${format(total())}. Usa las flechas para recorrerlos.` : `${name}: ${options.emptyLabel ?? 'sin datos'}`);
     frame.fillTable(name, ['Anillo', 'Valor', 'Meta', 'Avance'], model.map((ring) => [ring.label, format(ring.value), format(ring.max), percent(ring)]));

package/src/components/radial-chart/radial-chart.css

@@ -32,6 +32,13 @@ mk-radial-chart {
   stroke: var(--mk-chart-grid);
 }
 
+[data-mk-chart-type='radial'][data-mk-segmented] :is([data-mk-part='tracks'], [data-mk-part='series']) path {
+  stroke-width: 1px;
+  stroke-linejoin: round;
+}
+[data-mk-chart-type='radial'][data-mk-segmented] [data-mk-part='tracks'] path { fill: var(--mk-chart-track); stroke: var(--mk-chart-track); }
+[data-mk-chart-type='radial'][data-mk-segmented] [data-mk-part='series'] path[data-mk-on] { filter: brightness(1.12); stroke-width: 2px; }
+
 [data-mk-chart-type='radial'] :is([data-mk-part='tracks'], [data-mk-part='series']) path[data-mk-on] {
   stroke-width: calc(var(--mk-radial-thickness, 12px) + 4px);
 }
@@ -42,12 +49,12 @@ mk-radial-chart {
 
 [data-mk-radial-center] {
   position: absolute;
-  top: 50%;
+  top: var(--mk-radial-center-y, 50%);
   left: 50%;
   display: grid;
   justify-items: center;
   gap: 0.15rem;
-  max-width: calc(var(--mk-radial-size, 240px) * 0.36);
+  max-width: calc(var(--mk-radial-size, 240px) * var(--mk-radial-center-width, 0.36));
   transform: translate(-50%, -50%);
   text-align: center;
   pointer-events: none;

package/src/components/radial-chart/react.tsx

@@ -8,7 +8,7 @@ export interface RadialChartProps extends Omit<HTMLAttributes<HTMLDivElement>, '
 }
 
 /** <RadialChart label="Metas" data={[{ label: 'Pasos', value: 7400, max: 10000 }, …]} /> */
-export function RadialChart({ data, max, sweep, size, thickness, label, totalLabel, legend, emptyLabel, formatValue, onSelect, instanceRef, className, ...props }: RadialChartProps) {
-  const ref = useChart(createRadialChart, { data, max, sweep, size, thickness, label, totalLabel, legend, emptyLabel } as RadialChartOptions, { formatValue, onSelect }, instanceRef);
+export function RadialChart({ data, max, sweep, size, thickness, segments, center, label, totalLabel, legend, emptyLabel, formatValue, onSelect, instanceRef, className, ...props }: RadialChartProps) {
+  const ref = useChart(createRadialChart, { data, max, sweep, size, thickness, segments, center, label, totalLabel, legend, emptyLabel } as RadialChartOptions, { formatValue, onSelect }, instanceRef);
   return <div {...props} ref={ref} className={['mk-chart mk-radial-chart', className].filter(Boolean).join(' ')} />;
 }

package/src/components/scroll-island/README.md

@@ -1,34 +1,44 @@
-# scroll-island
-
-Qué hace, en una frase.
-
-Origen: archivo del kit y parámetros (tiempos, curvas).
-
-## HTML / Astro
-
-```html
-<mk-scroll-island></mk-scroll-island>
-<script>
-  import { defineElements } from '@yewdiel21/motion-kit/elements';
-  defineElements(['mk-scroll-island']);
-</script>
-```
-
-## React
-
-```tsx
-<ScrollIsland />
-```
-
-## Opciones
-
-| Opción | Atributo | Por defecto | Qué hace |
-|---|---|---|---|
-
-## Variables CSS
-
-`--mk-scroll-island-radius`
-
-## Accesibilidad
-
-Roles, foco y teclado. Con movimiento reducido…
+# scroll-island
+
+Una barra fina que se transforma en una píldora con el porcentaje y la sección actual al acercar el puntero al borde derecho. Arrastra la píldora o pulsa su carril para desplazarte.
+
+## React
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { ScrollIsland } from '@yewdiel21/motion-kit/react';
+
+<ScrollIsland persistent style={{ height: 360, overflow: 'auto' }}
+  tabIndex={0} role="region" aria-label="Guía de diseño">
+  <section style={{ minHeight: 400 }}><h3>Introducción</h3>Contenido…</section>
+  <section style={{ minHeight: 400 }}><h3>Detalles</h3>Contenido…</section>
+</ScrollIsland>
+```
+
+**El contenedor debe tener altura limitada, overflow y contenido suficiente para desplazarse.** Si todo cabe, la barra se oculta. `persistent` deja visible la barra fina mientras está en reposo; por defecto aparece al desplazarse y desaparece después.
+
+## HTML / Astro
+
+```html
+<mk-scroll-island persistent style="display:block;height:360px;overflow:auto"
+  tabindex="0" role="region" aria-label="Guía">
+  <section style="min-height:400px"><h3>Introducción</h3>Contenido…</section>
+  <section style="min-height:400px"><h3>Detalles</h3>Contenido…</section>
+</mk-scroll-island>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-scroll-island']);
+</script>
+```
+
+## Opciones
+
+- `page`: sigue el scroll de la página en vez del contenedor. En React `<ScrollIsland page />` no dibuja contenedor propio.
+- `sections`: selector de encabezados, `h2, h3` por defecto; `false` omite el nombre de sección en la factory/React.
+- `reach`: distancia del borde que activa la píldora, 56 px.
+- `idle`: demora para ocultarse, 900 ms.
+- `persistent`: mantiene la barra fina visible, false por defecto.
+- `onSection(section)`: cambio de sección, también `mk:section` con `detail.section`.
+- Factory `createScrollIsland(root, options)`; instancia `refresh()` y `destroy()`.
+
+El overlay decorativo usa `aria-hidden`; el contenido mantiene su desplazamiento nativo por teclado y tacto. Dale `tabindex="0"` y un nombre al panel. Respeta movimiento reducido, se adapta al tamaño del contenedor y elimina el overlay al desmontarse.

package/src/components/scroll-island/element.ts

@@ -6,7 +6,7 @@ import { createScrollIsland, type ScrollIslandInstance } from './engine';
  * or <mk-scroll-island page></mk-scroll-island> for the page. Emits mk:section ({section}).
  */
 export class MkScrollIslandElement extends MkElement<ScrollIslandInstance> {
-  static options: Record<string, OptionType> = { sections: 'string', reach: 'number', idle: 'number', page: 'boolean' };
+  static options: Record<string, OptionType> = { sections: 'string', reach: 'number', idle: 'number', persistent: 'boolean', page: 'boolean' };
 
   protected create(options: Record<string, unknown>) {
     return createScrollIsland(options.page ? document.documentElement : this, options);

package/src/components/scroll-island/engine.ts

@@ -23,6 +23,8 @@ export interface ScrollIslandOptions {
   reach?: number;
   /** ms the bar stays after scrolling stops (default 900). */
   idle?: number;
+  /** Keep the thin bar visible while idle (default false). */
+  persistent?: boolean;
   /** Follow the page's scroll (default: when the root is <html> or <body>). */
   page?: boolean;
   /** The current section changed (its heading's text, or null before the first). */
@@ -52,6 +54,7 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
   const marked = page ? document.documentElement : root;
   // The scroller's own bar hides (scroll-island.css).
   scope.attr(marked, 'data-mk-scroll-island-host', '');
+  scope.attr(root, 'data-mk-ready', '');
 
   const island = document.createElement('div');
   island.dataset.mkScrollIsland = '';
@@ -99,6 +102,16 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
   let section: string | null | undefined;
   let hideTimer: ReturnType<typeof setTimeout> | undefined;
   let dragging: { id: number; offset: number } | null = null;
+  let scrollBehavior: { value: string; priority: string; hadStyle: boolean } | null = null;
+  const restoreBehavior = () => {
+    if (!scrollBehavior) return;
+    const previous = scrollBehavior;
+    if (previous.value) scroller.style.setProperty('scroll-behavior', previous.value, previous.priority);
+    else scroller.style.removeProperty('scroll-behavior');
+    if (!previous.hadStyle && !scroller.getAttribute('style')) scroller.removeAttribute('style');
+    scrollBehavior = null;
+  };
+  scope.add(restoreBehavior);
   scope.add(() => clearTimeout(hideTimer));
 
   const headings = () => (options.sections === false ? [] : [...(page ? document.body : root).querySelectorAll<HTMLElement>(options.sections ?? 'h2, h3')]);
@@ -116,7 +129,7 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
     const size = as === 'island' ? ISLAND_HEIGHT : Math.max(MIN_BAR, Math.min(height, height * (scroller.clientHeight / Math.max(1, scroller.scrollHeight))));
     const top = (height - size) * progress();
     if (as !== 'island') return { top, height: size, width: BAR_WIDTH, borderRadius: BAR_WIDTH / 2 };
-    return { top, height: size, width: Math.max(ISLAND_HEIGHT, content.scrollWidth + 28), borderRadius: size / 2 };
+    return { top, height: size, width: Math.min(Math.max(ISLAND_HEIGHT, track().right - track().left - INSET * 2), Math.max(ISLAND_HEIGHT, content.scrollWidth + 28)), borderRadius: size / 2 };
   };
 
   const place = () => {
@@ -158,7 +171,7 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
   const settleLater = () => {
     clearTimeout(hideTimer);
     hideTimer = setTimeout(() => {
-      if (state === 'bar' && !dragging) go('hidden');
+      if (state === 'bar' && !dragging && !options.persistent) go('hidden');
     }, idle);
   };
 
@@ -213,6 +226,9 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
     if (state !== 'island' || down.button !== 0) return;
     down.preventDefault();
     down.stopPropagation();
+    if (!scrollBehavior) scrollBehavior = { value: scroller.style.getPropertyValue('scroll-behavior'), priority: scroller.style.getPropertyPriority('scroll-behavior'), hadStyle: scroller.hasAttribute('style') };
+    // A drag follows the pointer directly even when the app uses smooth scrolling.
+    scroller.style.setProperty('scroll-behavior', 'auto', 'important');
     const box = thumb.getBoundingClientRect();
     dragging = { id: down.pointerId, offset: down.clientY - box.top || ISLAND_HEIGHT / 2 };
     island.setAttribute('data-mk-dragging', '');
@@ -225,6 +241,7 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
   const release = (event: Event) => {
     if (!dragging || (event as PointerEvent).pointerId !== dragging.id) return;
     dragging = null;
+    restoreBehavior();
     island.removeAttribute('data-mk-dragging');
   };
   scope.on(window, 'pointerup', release);
@@ -240,7 +257,12 @@ export function createScrollIsland(root: HTMLElement | null, options: ScrollIsla
   });
 
   paintText();
-  go('hidden');
+  go(options.persistent ? 'bar' : 'hidden');
+  if (typeof ResizeObserver === 'function') {
+    const observer = scope.observe(new ResizeObserver(() => { paintText(); go(state, true); }));
+    observer.observe(root);
+    for (const child of root.children) observer.observe(child);
+  }
 
   return {
     refresh: () => {

package/src/components/scroll-island/react.tsx

@@ -9,14 +9,14 @@ export interface ScrollIslandProps extends HTMLAttributes<HTMLDivElement>, Scrol
  * <ScrollIsland style={{ height: 400, overflow: 'auto' }}>…</ScrollIsland> scrolls its children with the island;
  * <ScrollIsland page /> puts it on the page (it renders nothing of its own then).
  */
-export function ScrollIsland({ sections, reach, idle, page, onSection, className, children, ...props }: ScrollIslandProps) {
+export function ScrollIsland({ sections, reach, idle, persistent, page, onSection, className, children, ...props }: ScrollIslandProps) {
   const ref = useRef<HTMLDivElement>(null);
   const section = useLatest(onSection);
   useIsomorphicLayoutEffect(() => {
-    const created = createScrollIsland(page ? document.documentElement : ref.current, { sections, reach, idle, page, onSection: (name) => section.current?.(name) });
+    const created = createScrollIsland(page ? document.documentElement : ref.current, { sections, reach, idle, persistent, page, onSection: (name) => section.current?.(name) });
     return () => created.destroy();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [sections, reach, idle, page]);
+  }, [sections, reach, idle, persistent, page]);
   if (page) return null;
   return (
     <div {...props} ref={ref} className={['mk-scroll-island', className].filter(Boolean).join(' ')}>

package/src/components/scroll-island/scroll-island.css

@@ -73,6 +73,8 @@ mk-scroll-island {
 [data-mk-island-content] {
   display: inline-flex;
   flex: none;
+  max-width: 100%;
+  min-width: 0;
   align-items: center;
   gap: 0.5rem;
   padding: 0 14px;
@@ -91,6 +93,7 @@ mk-scroll-island {
 }
 
 [data-mk-island-section] {
+  min-width: 0;
   max-width: 12rem;
   overflow: hidden;
   color: rgb(255 255 255 / 0.68);

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