@yewdiel21/motion-kit 0.17.0 → 0.19.0

package/src/components/handwriting-text/engine.ts

@@ -0,0 +1,108 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { GLYPHS } from './glyphs';
+
+export interface HandwritingTextOptions {
+  text?: string;
+  /** Duration of the complete pen drawing in seconds, default 2.4. */
+  duration?: number;
+  autoplay?: boolean;
+  onComplete?: () => void;
+}
+export interface HandwritingTextInstance extends Instance {
+  setText(text: string, animate?: boolean): void;
+  replay(): void;
+  readonly text: string;
+}
+
+const SVG = 'http://www.w3.org/2000/svg';
+export function createHandwritingText(root: HTMLElement | null, options: HandwritingTextOptions = {}): HandwritingTextInstance {
+  if (!root) return inert({ setText() {}, replay() {}, text: '' });
+  registerMotion();
+  const scope = createScope();
+  let text = options.text ?? root.textContent ?? '';
+  const authored = [...root.childNodes];
+  const svg = document.createElementNS(SVG, 'svg');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.dataset.mkHandwritingDrawing = '';
+  root.replaceChildren(svg);
+  scope.add(() => { svg.remove(); root.append(...authored); });
+  scope.attr(root, 'data-mk-handwriting', '');
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'role', 'img');
+  let strokes: SVGPathElement[] = [];
+  let timeline: gsap.core.Timeline | null = null;
+  const duration = Number.isFinite(options.duration) ? Math.max(0.1, Math.min(30, options.duration!)) : 2.4;
+  const complete = () => {
+    if (scope.disposed) return;
+    options.onComplete?.();
+    root.dispatchEvent(new CustomEvent('mk:complete', { bubbles: true }));
+  };
+  const replay = () => {
+    if (scope.disposed) return;
+    timeline?.kill();
+    timeline = null;
+    if (reduced() || !strokes.length) { gsap.set(strokes, { strokeDashoffset: 0 }); return; }
+    gsap.set(strokes, { strokeDashoffset: 1 });
+    timeline = gsap.timeline({ onComplete: complete });
+    // Each pen lift is explicit: the paths draw sequentially, never by revealing typed characters.
+    const step = duration / strokes.length;
+    for (const stroke of strokes) timeline.to(stroke, { strokeDashoffset: 0, duration: step, ease: EASE.wipe });
+  };
+  const draw = () => {
+    timeline?.kill();
+    timeline = null;
+    strokes = [];
+    svg.replaceChildren();
+    scope.attr(root, 'aria-label', text);
+    scope.attr(root, 'data-mk-empty', text ? null : '');
+    let x = 5;
+    let y = 6;
+    let width = 10;
+    for (const char of text) {
+      if (char === '\n') { width = Math.max(width, x + 5); x = 5; y += 64; continue; }
+      if (/\s/u.test(char)) { x += 14; continue; }
+      const normalized = char.normalize('NFD');
+      const glyph = GLYPHS[normalized[0]!];
+      if (glyph) {
+        const paths = [...glyph.strokes];
+        if (normalized.includes('\u0301')) paths.push('M16 14L23 7');
+        if (normalized.includes('\u0303')) paths.push('M11 14Q16 8 20 13Q24 17 28 10');
+        if (normalized.includes('\u0308')) paths.push('M12 12L12.3 12.3M23 12L23.3 12.3');
+        for (const d of paths) {
+          const path = document.createElementNS(SVG, 'path');
+          path.setAttribute('d', d);
+          path.setAttribute('transform', `translate(${x} ${y})`);
+          path.setAttribute('pathLength', '1');
+          path.setAttribute('stroke-dasharray', '1');
+          path.setAttribute('stroke-dashoffset', '0');
+          svg.append(path);
+          strokes.push(path);
+        }
+        x += glyph.width;
+      } else {
+        // Unsupported symbols remain honest, readable SVG text; they are never claimed as pen strokes.
+        const fallback = document.createElementNS(SVG, 'text');
+        fallback.textContent = char;
+        fallback.setAttribute('x', String(x));
+        fallback.setAttribute('y', String(y + 42));
+        fallback.setAttribute('data-mk-handwriting-fallback', '');
+        svg.append(fallback);
+        x += 34;
+      }
+    }
+    svg.setAttribute('viewBox', `0 0 ${Math.max(width, x + 8)} ${y + 64}`);
+    svg.setAttribute('preserveAspectRatio', 'xMinYMid meet');
+  };
+  draw();
+  if (options.autoplay !== false) replay();
+  scope.add(() => { timeline?.kill(); gsap.killTweensOf(strokes); });
+  return {
+    replay,
+    setText(next, animate = true) { if (scope.disposed || next === text) return; text = String(next); draw(); if (animate) replay(); },
+    get text() { return text; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/handwriting-text/glyphs.ts

@@ -0,0 +1,71 @@
+/** Original monoline pen drawings. Coordinates use a 44-unit baseline; no font outlines. */
+export const GLYPHS: Record<string, { width: number; strokes: string[] }> = {
+  A: { width: 35, strokes: ['M2 43L26 5L27 42', 'M10 30L31 28'] },
+  B: { width: 34, strokes: ['M4 43L14 7', 'M10 8C40 -2 35 25 11 25C40 14 37 45 4 43'] },
+  C: { width: 34, strokes: ['M33 12C18 -8 -3 20 5 36Q12 52 31 35'] },
+  D: { width: 35, strokes: ['M5 43L15 7', 'M10 7C46 -3 40 48 4 43'] },
+  E: { width: 30, strokes: ['M31 7L13 9L4 42L29 40', 'M10 25L27 23'] },
+  F: { width: 29, strokes: ['M4 43L14 8L32 7', 'M10 25L27 24'] },
+  G: { width: 36, strokes: ['M33 12C15 -8 -4 27 7 39Q21 51 31 26L19 28'] },
+  H: { width: 36, strokes: ['M4 43L14 7', 'M28 43L37 7', 'M8 27L32 24'] },
+  I: { width: 20, strokes: ['M17 8L8 42', 'M9 9L25 7', 'M1 43L17 41'] },
+  J: { width: 28, strokes: ['M19 8L32 7L24 33Q17 54 3 38'] },
+  K: { width: 34, strokes: ['M4 43L14 7', 'M35 7L10 29L29 43'] },
+  L: { width: 28, strokes: ['M14 7L4 42Q15 39 29 41'] },
+  M: { width: 47, strokes: ['M3 43L15 7L22 35L44 7L35 43'] },
+  N: { width: 37, strokes: ['M4 43L14 7L28 42L38 7'] },
+  O: { width: 36, strokes: ['M25 7C5 1 -5 43 15 43C35 46 46 3 25 7Z'] },
+  P: { width: 32, strokes: ['M4 43L14 8C40 -2 39 30 8 27'] },
+  Q: { width: 37, strokes: ['M25 7C5 1 -5 43 15 43C35 46 46 3 25 7Z', 'M19 33L33 48'] },
+  R: { width: 34, strokes: ['M4 43L14 8C40 -2 39 30 8 27L29 44'] },
+  S: { width: 31, strokes: ['M31 12C19 -5 -4 16 16 25C39 35 12 55 2 36'] },
+  T: { width: 31, strokes: ['M3 10L34 7', 'M20 9L11 43'] },
+  U: { width: 36, strokes: ['M13 7L5 31C-1 52 27 48 31 29L37 7'] },
+  V: { width: 35, strokes: ['M7 7L10 43L37 7'] },
+  W: { width: 48, strokes: ['M7 7L9 43L27 15L28 43L50 7'] },
+  X: { width: 34, strokes: ['M10 7L28 43', 'M36 7L2 43'] },
+  Y: { width: 34, strokes: ['M8 7L19 27L37 7', 'M19 27L14 43'] },
+  Z: { width: 32, strokes: ['M7 9L34 7L2 43L29 41'] },
+  a: { width: 27, strokes: ['M23 23C9 12 2 40 13 42C21 44 26 21 23 22L20 39Q20 47 29 37'] },
+  b: { width: 27, strokes: ['M4 42Q21 -6 13 3Q5 7 7 36C19 7 34 30 19 40Q11 46 7 38L29 36'] },
+  c: { width: 25, strokes: ['M23 24C17 13 3 26 6 37Q10 49 27 35'] },
+  d: { width: 28, strokes: ['M22 24C8 12 0 39 11 42Q20 46 29 4Q31 -1 27 3L21 38Q21 46 31 35'] },
+  e: { width: 25, strokes: ['M5 33Q25 29 21 21Q17 13 8 27C-1 43 15 49 27 35'] },
+  f: { width: 23, strokes: ['M2 57Q1 63 7 52L22 7Q24 -3 16 5Q7 17 11 27L24 24', 'M3 27L20 26'] },
+  g: { width: 28, strokes: ['M24 24C10 12 1 39 12 42Q20 45 24 23L18 54Q12 68 6 57Q3 48 31 36'] },
+  h: { width: 28, strokes: ['M4 42Q24 -6 14 4Q8 10 5 41C17 9 26 18 21 34Q17 49 31 35'] },
+  i: { width: 15, strokes: ['M9 24L5 36Q2 47 18 35', 'M12 13L12.2 13.2'] },
+  j: { width: 18, strokes: ['M13 24L6 53Q1 68 -4 56Q-6 48 21 35', 'M16 13L16.2 13.2'] },
+  k: { width: 27, strokes: ['M4 42Q24 -7 14 4Q8 10 5 41', 'M25 22Q8 38 10 32Q17 27 19 37Q21 45 30 35'] },
+  l: { width: 18, strokes: ['M3 32Q28 -4 15 3Q7 8 6 31Q3 49 21 35'] },
+  m: { width: 40, strokes: ['M3 41L9 23L5 39Q18 11 20 25L17 39Q31 11 32 25L29 36Q28 46 43 35'] },
+  n: { width: 28, strokes: ['M3 41L9 23L5 39Q21 10 23 25L20 36Q19 46 31 35'] },
+  o: { width: 27, strokes: ['M22 22C7 14 0 39 12 42Q22 46 26 28Q26 18 19 24Q15 33 30 32'] },
+  p: { width: 28, strokes: ['M-1 58L11 22L7 35Q19 12 25 25Q29 40 14 42L8 39L31 35'] },
+  q: { width: 28, strokes: ['M23 24C10 12 1 39 12 42Q22 45 24 23L17 58Q15 62 19 53L31 36'] },
+  r: { width: 23, strokes: ['M2 41L9 22Q8 31 16 24Q20 18 21 23Q21 27 17 28L26 35'] },
+  s: { width: 24, strokes: ['M22 21Q18 15 10 24Q6 28 17 33Q25 39 14 43Q3 46 6 38L27 35'] },
+  t: { width: 21, strokes: ['M16 10L7 35Q3 48 24 35', 'M2 25L23 23'] },
+  u: { width: 29, strokes: ['M9 23L4 35Q1 52 24 24L20 38Q21 45 32 35'] },
+  v: { width: 26, strokes: ['M6 23Q-1 58 22 27Q25 20 21 23Q19 31 29 31'] },
+  w: { width: 39, strokes: ['M7 23Q-1 56 19 27Q10 56 34 27Q37 20 33 23Q31 31 42 31'] },
+  x: { width: 25, strokes: ['M7 24Q14 28 17 39Q20 45 28 35', 'M24 23L3 42'] },
+  y: { width: 28, strokes: ['M8 23L4 35Q2 50 24 24L16 54Q11 67 5 58Q0 50 31 36'] },
+  z: { width: 25, strokes: ['M6 25Q16 19 24 24L5 41Q14 36 20 43Q25 51 10 59Q1 63 5 54L28 36'] },
+  '0': { width: 29, strokes: ['M23 8C4 0 -2 42 13 43C28 44 34 7 23 8Z'] },
+  '1': { width: 20, strokes: ['M5 17L17 8L9 42', 'M2 43L18 43'] },
+  '2': { width: 28, strokes: ['M4 17C10 -2 35 7 23 22L3 42Q14 38 28 42'] },
+  '3': { width: 27, strokes: ['M6 11Q32 0 23 20L13 25Q34 17 24 36Q17 48 3 39'] },
+  '4': { width: 29, strokes: ['M20 7L2 31L30 29', 'M25 9L17 43'] },
+  '5': { width: 28, strokes: ['M29 8L10 9L5 25Q27 14 25 32Q20 49 3 39'] },
+  '6': { width: 28, strokes: ['M25 8C7 -1 -6 43 13 43C30 43 29 16 13 25L5 33'] },
+  '7': { width: 27, strokes: ['M4 10L29 9L9 43', 'M9 26L24 25'] },
+  '8': { width: 28, strokes: ['M18 24C-6 12 23 -2 27 12Q28 21 10 28C-5 37 13 52 24 38Q33 27 18 24Z'] },
+  '9': { width: 28, strokes: ['M24 20Q5 38 4 21C4 3 31 1 25 21L14 44'] },
+  '.': { width: 12, strokes: ['M6 41L6.4 41.4'] },
+  ',': { width: 12, strokes: ['M8 40L4 49'] },
+  '!': { width: 13, strokes: ['M12 5L6 31', 'M5 41L5.4 41.4'] },
+  '?': { width: 25, strokes: ['M3 14Q10 0 23 10Q29 18 16 24L11 31', 'M9 42L9.4 42.4'] },
+  '-': { width: 23, strokes: ['M4 28L22 27'] },
+  "'": { width: 11, strokes: ['M9 7L6 15'] },
+};

package/src/components/handwriting-text/handwriting-text.css

@@ -0,0 +1,14 @@
+.mk-handwriting-text,
+mk-handwriting-text {
+  --mk-handwriting-width: 28rem;
+  display: inline-block;
+  width: min(100%, var(--mk-handwriting-width));
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+  line-height: 1;
+}
+[data-mk-handwriting] [data-mk-handwriting-drawing] { display: block; width: 100%; height: auto; overflow: visible; }
+[data-mk-handwriting] path { fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+[data-mk-handwriting-fallback] { fill: currentColor; stroke: none; font: 30px var(--mk-font); }
+[data-mk-handwriting][data-mk-empty] { min-height: 1rem; }
+@media (prefers-reduced-motion: reduce) { [data-mk-handwriting] path { stroke-dashoffset: 0 !important; } }

package/src/components/handwriting-text/react.tsx

@@ -0,0 +1,23 @@
+'use client';
+import { useRef, type HTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createHandwritingText, type HandwritingTextInstance, type HandwritingTextOptions } from './engine';
+
+export interface HandwritingTextProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'dangerouslySetInnerHTML' | 'onComplete'>, HandwritingTextOptions { instanceRef?: Ref<HandwritingTextInstance>; }
+export function HandwritingText({ text = 'make it move.', duration, autoplay, onComplete, instanceRef, className, ...props }: HandwritingTextProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as HTMLAttributes<HTMLSpanElement>;
+  const root = useRef<HTMLSpanElement>(null);
+  const instance = useRef<HandwritingTextInstance | null>(null);
+  const latest = useLatest({ text, onComplete });
+  useIsomorphicLayoutEffect(() => {
+    const created = createHandwritingText(root.current, { text: latest.current.text, duration, autoplay, onComplete: () => latest.current.onComplete?.() });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [duration, autoplay]);
+  useIsomorphicLayoutEffect(() => { instance.current?.setText(text, autoplay !== false); }, [text, autoplay]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, duration, autoplay]);
+  return <span {...safe} ref={root} role="img" aria-label={text} className={['mk-handwriting-text', className].filter(Boolean).join(' ')} />;
+}

package/src/components/heatmap-chart/README.md

@@ -1,48 +1,48 @@
-# heatmap-chart
-
-Calendario de actividad tipo GitHub con intensidad por día, tooltips y desplazamiento horizontal.
-
-## Instalación
-
-```tsx
-import '@yewdiel21/motion-kit/css';
-import { HeatmapChart } from '@yewdiel21/motion-kit/react';
-```
-
-```sh
-npx @yewdiel21/motion-kit add heatmap-chart --react --elements
-```
-
-## React
-
-```tsx
-<HeatmapChart end="2026-10-31" weeks={26} data={{ "2026-10-30": 4, "2026-10-31": 8 }} unit="sesiones" locale="es-MX" />
-```
-
-Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
-
-## HTML / Astro
-
-```html
-<mk-heatmap-chart end="2026-10-31" weeks="26" data='{"2026-10-30":4,"2026-10-31":8}'></mk-heatmap-chart>
-<script type="module">
-  import { defineElements } from '@yewdiel21/motion-kit/elements';
-  defineElements(['mk-heatmap-chart']);
-</script>
-```
-
-En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createHeatmapChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
-
-## Opciones
-
-data: {date, value}[] o mapa YYYY-MM-DD a valor. end: hoy. weeks: 53. firstDay: 1 (lunes). levels: 4. color: acento. locale, unit, legend. onSelect(date, value). Instancia: select(date | null), update(options), selected.
-
-Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
-
-Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
-
-## Estilos y accesibilidad
-
-Variables: --mk-heatmap-color, --mk-heatmap-empty; --mk-chart-surface.
-
-Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.
+# heatmap-chart
+
+Calendario de actividad tipo GitHub con intensidad por día, tooltips y desplazamiento horizontal. Las semanas se desplazan con la barra de [`scroll-area`](../scroll-area/README.md), que tiene su propio carril bajo la última fila.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { HeatmapChart } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add heatmap-chart --react --elements
+```
+
+## React
+
+```tsx
+<HeatmapChart end="2026-10-31" weeks={26} data={{ "2026-10-30": 4, "2026-10-31": 8 }} unit="sesiones" locale="es-MX" />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-heatmap-chart end="2026-10-31" weeks="26" data='{"2026-10-30":4,"2026-10-31":8}'></mk-heatmap-chart>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-heatmap-chart']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createHeatmapChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+data: {date, value}[] o mapa YYYY-MM-DD a valor. end: hoy. weeks: 53. firstDay: 1 (lunes). levels: 4. color: acento. locale, unit, legend. onSelect(date, value). Instancia: select(date | null), update(options), selected.
+
+Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-heatmap-color, --mk-heatmap-empty; --mk-chart-surface.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

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

@@ -4,6 +4,7 @@ import { reduced } from '../../core/reduced';
 import { createScope } from '../../core/scope';
 import { inert, type Instance } from '../../core/types';
 import { chartFrame, finite, formatNumber, onWidth, round, svg } from '../chart/parts';
+import { createScrollArea } from '../scroll-area/engine';
 
 /*
  * Heatmap chart: daily activity on a calendar, a column per week like
@@ -13,7 +14,8 @@ import { chartFrame, finite, formatNumber, onWidth, round, svg } from '../chart/
  * crossfades their colours. Pointing at a day (or the arrows: up and down a
  * day, left and right a week, PageUp/PageDown four) lifts it with a ring and
  * the tooltip says its value and date; the "less … more" scale lights the
- * days of a step. Narrow screens scroll the weeks, ending on the latest.
+ * days of a step. Narrow screens scroll the weeks, ending on the latest, under
+ * the kit's scroll-area bar (its own lane below the last row).
  */
 
 export interface HeatmapDatum {
@@ -70,6 +72,9 @@ export function createHeatmapChart(root: HTMLElement | null, initial: HeatmapCha
   plot.prepend(scroller);
   scroller.append(canvas);
   scope.add(() => scroller.remove());
+  // The arrows already move through the days: the bar is not a tab stop.
+  const area = createScrollArea(plot, { viewport: scroller, axis: 'x', focusable: false, decorative: true });
+  scope.add(() => area.destroy());
 
   const scale = document.createElement('div');
   scale.dataset.mkHeatmapScale = '';

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

@@ -13,7 +13,11 @@ mk-heatmap-chart {
   overflow-x: auto;
   overflow-y: hidden;
   padding-block: 4px;
-  scrollbar-width: thin;
+}
+
+/* Weeks that scroll leave the scroll-area bar a lane below the last row, so a click on a day never lands on it. */
+[data-mk-overflow-x] > [data-mk-heatmap-scroll] {
+  padding-bottom: 16px;
 }
 
 [data-mk-chart-type='heatmap'] [data-mk-chart-svg] {

package/src/components/icons.ts

@@ -14,6 +14,7 @@ export const ICON_PATHS = {
   mic: 'M12 3a3 3 0 00-3 3v6a3 3 0 006 0V6a3 3 0 00-3-3zM5.5 11a6.5 6.5 0 0013 0M12 17.5V21',
   sparkle: 'M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9z',
   grip: 'M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01',
+  toTop: 'M12 20V9M6.5 14.5L12 9l5.5 5.5M6 4.5h12',
 } as const;
 
 export type IconName = keyof typeof ICON_PATHS;

package/src/components/magnetize-button/README.md

@@ -0,0 +1,26 @@
+# Magnetize button
+
+Partículas discretas reposan alrededor de un botón tonal. Hover o foco las atrae hacia el perímetro; al salir se separan y vuelven a reposar. Es un efecto de atracción de partículas, con el botón estable. Las transiciones usan `EASE.swatch` y se pueden interrumpir. No usa RAF ni un ticker propio en reposo.
+
+```ts
+import { createMagnetizeButton } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/magnetize-button';
+const magnet = createMagnetizeButton(document.querySelector('#gather'), {
+  onAction: () => groupSelectedIdeas(),
+});
+// magnet.attract(); magnet.release(); magnet.destroy();
+```
+
+`MagnetizeButtonOptions`: `label` (Reunir ideas, solo si falta contenido), `count` (14, limitado a 4–24), `reach` (42px, limitado a 16–90), `onAction`. `MagnetizeButtonInstance`: `attract()`, `release()`, `attracted`, `destroy()`. Emite `mk:action` en clic nativo, incluido teclado y tacto. El factory acepta un botón, un host con botón o crea uno si falta. Su `type` predeterminado es `button`.
+
+```tsx
+<MagnetizeButton label="Reunir ideas" onAction={groupSelectedIdeas} instanceRef={magnetRef} />
+```
+
+`MagnetizeButtonProps` añade atributos nativos e `instanceRef`. El motor posee los hijos; se usa `label` y se filtran `children`/`dangerouslySetInnerHTML` en ejecución.
+
+```html
+<mk-magnetize-button count="14" reach="42"><button type="button">Reunir ideas</button></mk-magnetize-button>
+```
+
+`defineMagnetizeButton()` registra `MkMagnetizeButtonElement`; atributos `label`, `count`, `reach`. Teclado muestra la misma atracción y un anillo de foco. Movimiento reducido o disabled oculta partículas; la acción sigue siendo nativa. Reserva hasta `reach` de aire alrededor del botón para ver el efecto. `destroy()` desconecta observers, media listeners, eventos y animaciones, retira partículas y restaura nodos y estilos originales.

package/src/components/magnetize-button/element.ts

@@ -0,0 +1,13 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMagnetizeButton, type MagnetizeButtonInstance } from './engine';
+
+export class MkMagnetizeButtonElement extends MkElement<MagnetizeButtonInstance> {
+  static options: Record<string, OptionType> = { label: 'string', count: 'number', reach: 'number' };
+  protected create(options: Record<string, unknown>) { return createMagnetizeButton(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focused = this.contains(document.activeElement);
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) this.querySelector<HTMLButtonElement>('button')?.focus({ preventScroll: true });
+  }
+}
+export const defineMagnetizeButton = () => defineElement('mk-magnetize-button', MkMagnetizeButtonElement);

package/src/components/magnetize-button/engine.ts

@@ -0,0 +1,84 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+export interface MagnetizeButtonOptions {
+  label?: string;
+  /** Discrete particles, clamped to 4–24. No idle ticker. */
+  count?: number;
+  /** Distance outside the button where the particles rest, default 42px. */
+  reach?: number;
+  onAction?: () => void;
+}
+export interface MagnetizeButtonInstance extends Instance { attract(): void; release(): void; readonly attracted: boolean; }
+
+export function createMagnetizeButton(root: HTMLElement | null, options: MagnetizeButtonOptions = {}): MagnetizeButtonInstance {
+  if (!root) return inert({ attract() {}, release() {}, attracted: false });
+  registerMotion();
+  const scope = createScope();
+  let button = root.matches('button') ? root as HTMLButtonElement : root.querySelector<HTMLButtonElement>('button');
+  if (!button) { button = document.createElement('button'); root.append(button); const made = button; scope.add(() => made.remove()); }
+  const control = button;
+  if (!control.textContent?.trim() && !control.querySelector('[aria-label], svg, img')) {
+    const label = document.createElement('span'); label.textContent = options.label ?? 'Reunir ideas'; control.append(label); scope.add(() => label.remove());
+  }
+  const originalStyle = control.getAttribute('style');
+  const originalTransform = control.style.transform;
+  scope.add(() => { if (originalStyle === null) control.removeAttribute('style'); else control.setAttribute('style', originalStyle); });
+  scope.attr(control, 'type', control.getAttribute('type') ?? 'button');
+  scope.attr(control, 'data-mk-magnetize-button', '');
+  scope.attr(root, 'data-mk-ready', '');
+  const layer = document.createElement('span'); layer.dataset.mkMagnetParticles = ''; layer.setAttribute('aria-hidden', 'true'); control.append(layer); scope.add(() => layer.remove());
+  const count = Number.isFinite(options.count) ? Math.min(24, Math.max(4, Math.round(options.count!))) : 14;
+  const reach = Number.isFinite(options.reach) ? Math.min(90, Math.max(16, options.reach!)) : 42;
+  const dots: HTMLElement[] = [];
+  for (let i = 0; i < count; i++) { const dot = document.createElement('i'); layer.append(dot); dots.push(dot); }
+  let hovered = false;
+  let focused = false;
+  let attracted = false;
+  let tween: gsap.core.Timeline | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const disabled = () => control.disabled || control.getAttribute('aria-disabled') === 'true';
+  const positions = (near: boolean) => {
+    const w = control.offsetWidth || 160;
+    const h = control.offsetHeight || 48;
+    return dots.map((_, i) => {
+      const angle = i / count * Math.PI * 2 - Math.PI / 2;
+      // Intersect a ray with the rounded rectangle envelope; attraction lands at the perimeter.
+      const c = Math.cos(angle); const s = Math.sin(angle);
+      const boundary = Math.min((w / 2 + 4) / Math.max(.001, Math.abs(c)), (h / 2 + 4) / Math.max(.001, Math.abs(s)));
+      const radius = boundary + (near ? 0 : reach * (.72 + (i % 3) * .14));
+      return { x: c * radius, y: s * radius, opacity: near ? .88 : .25, scale: near ? 1 : .6 };
+    });
+  };
+  const paint = (near: boolean, animate: boolean) => {
+    tween?.kill(); tween = null;
+    layer.hidden = reduced() || disabled();
+    if (layer.hidden) { attracted = false; scope.attr(control, 'data-mk-attracted', null); return; }
+    attracted = near;
+    scope.attr(control, 'data-mk-attracted', near ? '' : null);
+    const targets = positions(near);
+    if (!animate) { dots.forEach((dot, i) => gsap.set(dot, targets[i]!)); return; }
+    tween = gsap.timeline();
+    dots.forEach((dot, i) => tween!.to(dot, { ...targets[i]!, duration: near ? .62 : .48, ease: near ? EASE.swatch : EASE.signature }, i * .008));
+  };
+  const sync = () => paint(hovered || focused, true);
+  scope.on(control, 'pointerenter', () => { hovered = true; sync(); });
+  scope.on(control, 'pointerleave', () => { hovered = false; sync(); });
+  scope.on(control, 'focus', () => { focused = true; sync(); });
+  scope.on(control, 'blur', () => { focused = false; sync(); });
+  scope.on(control, 'click', (event) => {
+    if (disabled()) { event.preventDefault(); return; }
+    pressing?.kill(); pressing = press(control);
+    pressing?.eventCallback('onComplete', () => { gsap.set(control, { clearProps: 'transform,scale' }); control.style.transform = originalTransform; if (!control.getAttribute('style')) control.removeAttribute('style'); });
+    options.onAction?.(); root.dispatchEvent(new CustomEvent('mk:action', { bubbles: true }));
+  });
+  if (typeof ResizeObserver !== 'undefined') scope.observe(new ResizeObserver(() => paint(attracted, false))).observe(control);
+  if (typeof MutationObserver !== 'undefined') scope.observe(new MutationObserver(() => paint(hovered || focused, false))).observe(control, { attributes: true, attributeFilter: ['disabled', 'aria-disabled'] });
+  if (typeof matchMedia === 'function') { const media = matchMedia('(prefers-reduced-motion: reduce)'); scope.on(media, 'change', () => paint(hovered || focused, false)); }
+  paint(false, false);
+  scope.add(() => { tween?.kill(); pressing?.kill(); gsap.killTweensOf(dots); });
+  return { attract: () => { if (!scope.disposed) paint(true, true); }, release: () => { if (!scope.disposed) paint(false, true); }, get attracted() { return attracted; }, destroy: () => scope.dispose() };
+}

package/src/components/magnetize-button/magnetize-button.css

@@ -0,0 +1,17 @@
+.mk-magnetize-button,
+mk-magnetize-button { display: inline-flex; overflow: visible; }
+[data-mk-magnetize-button] {
+  position: relative; display: inline-flex; align-items: center; justify-content: center; gap: .6rem; min-height: 48px;
+  padding: .8rem 1.5rem; border: 1px solid var(--mk-outline-soft); border-radius: 16px; background: var(--mk-surface-3);
+  color: var(--mk-text); font: 500 .9375rem var(--mk-font); cursor: pointer; overflow: visible;
+  transition: background 160ms, border-radius 350ms var(--mk-ease-swatch);
+}
+[data-mk-magnetize-button]:is(:hover, [data-mk-attracted]):not(:disabled) { border-radius: 24px; background: var(--mk-surface-4); }
+[data-mk-magnetize-button]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 8px; }
+[data-mk-magnetize-button]:disabled,
+[data-mk-magnetize-button][aria-disabled='true'] { opacity: .4; cursor: not-allowed; }
+[data-mk-magnet-particles] { position: absolute; inset: 0; pointer-events: none; }
+[data-mk-magnet-particles][hidden] { display: none; }
+[data-mk-magnet-particles] i { position: absolute; top: 50%; left: 50%; width: 4px; height: 4px; margin: -2px; border-radius: 999px; background: var(--mk-muted); }
+[data-mk-magnet-particles] i:nth-child(4n) { width: 5px; height: 5px; background: var(--mk-accent); }
+@media (prefers-reduced-motion: reduce) { [data-mk-magnet-particles] { display: none; } [data-mk-magnetize-button] { transition: none; } }

package/src/components/magnetize-button/react.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createMagnetizeButton, type MagnetizeButtonInstance, type MagnetizeButtonOptions } from './engine';
+
+export interface MagnetizeButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'dangerouslySetInnerHTML'>, MagnetizeButtonOptions { instanceRef?: Ref<MagnetizeButtonInstance>; }
+export function MagnetizeButton({ label = 'Reunir ideas', count, reach, onAction, instanceRef, type = 'button', className, ...props }: MagnetizeButtonProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as ButtonHTMLAttributes<HTMLButtonElement>;
+  const root = useRef<HTMLButtonElement>(null);
+  const instance = useRef<MagnetizeButtonInstance | null>(null);
+  const action = useLatest(onAction);
+  useIsomorphicLayoutEffect(() => {
+    const created = createMagnetizeButton(root.current, { label, count, reach, onAction: () => action.current?.() });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [label, count, reach]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, label, count, reach]);
+  return <button {...safe} type={type} ref={root} className={['mk-magnetize-button', className].filter(Boolean).join(' ')} />;
+}

package/src/components/morphing-page-dots/README.md

@@ -0,0 +1,28 @@
+# Morphing page dots
+
+Indicador de páginas: una píldora se estira hacia el nuevo índice y su cola alcanza el destino con `EASE.swatch`. Los puntos siguen siendo botones nativos de 44px con foco visible y `aria-current="page"`. No inicia reproducción automática ni crea diapositivas.
+
+```ts
+import { createMorphingPageDots } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/morphing-page-dots';
+const dots = createMorphingPageDots(document.querySelector('#pages'), {
+  count: 4, value: 0, pageIds: ['slide-a', 'slide-b', 'slide-c', 'slide-d'],
+  onChange: (index) => showSlide(index),
+});
+dots.setValue(2, true);
+// dots.destroy();
+```
+
+`MorphingPageDotsOptions`: `count` (5, entre 1–20), `value` (índice desde 0), `label` (Páginas), `labels` (nombres de cada página), `pageIds` (aria-controls opcional), `disabled`, `onChange(index)`. `MorphingPageDotsInstance`: `setValue(index, notify = false)`, `value`, `destroy()`. Emite `mk:change` con `{value}` al notificar. Flechas izquierda/derecha recorren y seleccionan con wrapping; Home/End van a los extremos. Respeta RTL. La app debe mantener las diapositivas y su contenido accesible sincronizados.
+
+```tsx
+<MorphingPageDots count={slides.length} value={index} onChange={setIndex} />
+```
+
+React admite `value` controlado o `defaultValue`, `instanceRef` y atributos de div. El estado controlado sigue siendo la autoridad si se rechaza el cambio. El motor posee todos los hijos; `children` y `dangerouslySetInnerHTML` se filtran también en ejecución.
+
+```html
+<mk-morphing-page-dots count="4" value="0" labels='["Sierra","Lago","Pinar","Dunas"]'></mk-morphing-page-dots>
+```
+
+`defineMorphingPageDots()` registra `MkMorphingPageDotsElement`; atributos `count`, `value`, `label`, `labels` (JSON), `page-ids` (JSON), `disabled`. Conserva la selección al cambiar presentación o reconectar; un cambio del atributo `value` la reemplaza. Movimiento reducido coloca la píldora directamente. `destroy()` elimina observers, animaciones, eventos y devuelve los nodos/atributos originales.

package/src/components/morphing-page-dots/element.ts

@@ -0,0 +1,16 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMorphingPageDots, type MorphingPageDotsInstance } from './engine';
+
+export class MkMorphingPageDotsElement extends MkElement<MorphingPageDotsInstance> {
+  static options: Record<string, OptionType> = { count: 'number', value: 'number', label: 'string', labels: 'json', pageIds: 'json', disabled: 'boolean' };
+  private retained: number | undefined;
+  protected create(options: Record<string, unknown>) { return createMorphingPageDots(this, { ...options, ...(this.retained === undefined ? {} : { value: this.retained }) }); }
+  disconnectedCallback() { this.retained = this.instance?.value ?? this.retained; super.disconnectedCallback(); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focusIndex = [...this.querySelectorAll('button')].findIndex((button) => button === document.activeElement);
+    if (previous !== next) this.retained = name === 'value' ? undefined : this.instance?.value ?? this.retained;
+    super.attributeChangedCallback(name, previous, next);
+    if (focusIndex >= 0) { const buttons = this.querySelectorAll('button'); buttons[Math.min(focusIndex, buttons.length - 1)]?.focus({ preventScroll: true }); }
+  }
+}
+export const defineMorphingPageDots = () => defineElement('mk-morphing-page-dots', MkMorphingPageDotsElement);