@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/equalizer-slider/README.md

@@ -0,0 +1,43 @@
+# EqualizerSlider
+
+Un control de nivel con barras de onda y un cursor que acompaña inmediatamente al rango nativo. Las barras que cambian de estado responden con swatch; el número rueda con las teclas o la API y el cursor responde al presionarlo.
+
+```ts
+import { createEqualizerSlider } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/equalizer-slider';
+
+const control = createEqualizerSlider(document.querySelector('.mk-equalizer-slider'), {
+  value: 60, name: 'volume', label: 'Volumen',
+  onInput: (value) => { audio.volume = value / 100; },
+});
+control.setValue(35);
+```
+
+## Opciones y contrato
+
+`min` (0), `max` (100), `step` (1), `value` / `defaultValue` (60), `waveform: number[]` (alturas 0–1), `bars` (40, 12–72), `label`, `name`, `disabled`, `error`, `formatValue`, `onInput(value)`, `onChange(value)`.
+
+Es un control numérico; no reproduce, captura ni analiza audio. waveform es una forma decorativa estática. onInput se emite durante el ajuste; onChange al confirmar, una sola vez por valor. En React se puede actualizar con onInput o confirmar con onChange. El arrastre siempre cambia la geometría sin esperar a una animación.
+
+La instancia expone `value: number`, `setValue(value, notify = false)`, `reset(notify = false)` y `destroy()`. Las escrituras imperativas actualizan el control incluso estando disabled. `setValue` no cambia el valor inicial al que vuelve reset. Las notificaciones usan callbacks y eventos `mk:input / mk:change` con `detail: { value }`.
+
+## React y HTML
+
+```tsx
+import { EqualizerSlider } from '@yewdiel21/motion-kit/react';
+
+<EqualizerSlider value={level} onInput={setLevel} label="Nivel" name="level" />
+```
+
+`value` controla la instancia; `defaultValue` inicia una instancia que conserva sus propios cambios. Las opciones pueden cambiar sin perder la selección no controlada. `instanceRef` recibe la instancia y admite cambiar de objeto ref. Los children y dangerouslySetInnerHTML no se pasan al host porque el motor posee ese DOM.
+
+```html
+<mk-equalizer-slider class="mk-equalizer-slider" value="60" label="Nivel" name="level" bars="44"></mk-equalizer-slider>
+```
+
+Registra con `defineEqualizerSlider()` desde `@yewdiel21/motion-kit/elements` o utiliza el auto registro. Los atributos de opciones se pueden cambiar en vivo; el valor imperativo se conserva al cambiar otra opción. `disabled="false"` se lee como false. El elemento expone `value`, `setValue`, `reset`.
+
+## Accesibilidad y lifecycle
+
+Se conserva el input nativo, su etiqueta, teclado, tacto, validación y participación en formularios. El reset de formulario es cancelable; el control espera al reset nativo y verifica defaultPrevented. Movimiento reducido conserva toda la funcionalidad. destroy es idempotente y libera animaciones, eventos y timers, elimina solo las partes creadas y restaura los atributos del host. Los temas utilizan DM Sans y tokens --mk-*; el CSS de este componente es independiente de los otros estilos.
+

package/src/components/equalizer-slider/element.ts

@@ -0,0 +1,41 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createEqualizerSlider, type EqualizerSliderInstance } from './engine';
+
+/** Light DOM; attribute changes keep the current imperative value and reset baseline. */
+export class MkEqualizerSliderElement extends MkElement<EqualizerSliderInstance> {
+  static options: Record<string, OptionType> = {"min":"number","max":"number","step":"number","value":"number","label":"string","name":"string","disabled":"boolean","error":"string","waveform":"json","bars":"number"};
+  private baseline: number | undefined;
+  private saved: number | undefined;
+  protected create(options: Record<string, unknown>) {
+    const created = createEqualizerSlider(this, { ...options, value: this.saved !== undefined ? this.saved : options.value as number | undefined, defaultValue: this.baseline });
+    if (this.baseline === undefined) this.baseline = created.value;
+    this.saved = undefined;
+    return created;
+  }
+  disconnectedCallback() {
+    this.saved = this.instance?.value;
+    super.disconnectedCallback();
+  }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'value' && (!this.instance || !this.isConnected)) {
+      this.saved = next === null ? this.baseline ?? 60 : Number.isFinite(Number(next)) ? Number(next) : this.baseline ?? 60;
+      return;
+    }
+    if (!this.instance || !this.isConnected) return;
+    if (name === 'value') {
+      const parsed = next === null ? this.baseline ?? 60 : Number(next);
+      this.instance.setValue(parsed, false);
+      return;
+    }
+    this.saved = this.instance.value;
+    super.attributeChangedCallback(name, previous, next);
+  }
+  get value(): number { return this.instance?.value ?? this.saved ?? 60; }
+  set value(next: number) { this.setValue(next); }
+  setValue(value: number, notify = false) { if (this.instance) this.instance.setValue(value, notify); else this.saved = value; }
+  reset(notify = false) { this.instance?.reset(notify); }
+  
+}
+export const defineEqualizerSlider = () => defineElement('mk-equalizer-slider', MkEqualizerSliderElement);
+

package/src/components/equalizer-slider/engine.ts

@@ -0,0 +1,32 @@
+import { gsap, EASE } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createNumericRange, type NumericOptions, type NumericInstance } from './shared';
+
+export interface EqualizerSliderOptions extends NumericOptions {
+  /** Static waveform heights 0…1. This control does not analyze or play audio. */
+  waveform?: number[];
+  /** Number of decorative bars, 12…72; default 40. */
+  bars?: number;
+}
+export interface EqualizerSliderInstance extends NumericInstance {}
+export function createEqualizerSlider(root: HTMLElement | null, options: EqualizerSliderOptions = {}): EqualizerSliderInstance {
+  return createNumericRange(root, options, {
+    prefix: 'equalizer', label: 'Volumen', min: 0, max: 100, value: 60, format: (n) => `${n} %`,
+    decorate({ track, keep }) {
+      const wave = document.createElement('span'); wave.dataset.mkEqualizerWave = ''; wave.setAttribute('aria-hidden', 'true'); track.prepend(wave);
+      const count = Math.max(12, Math.min(72, Math.round(Number.isFinite(options.bars) ? options.bars! : 40)));
+      const bars = Array.from({ length: count }, (_, i) => {
+        const bar = document.createElement('span');
+        const supplied = options.waveform?.[i % options.waveform.length];
+        const height = Number.isFinite(supplied) ? Math.max(0.1, Math.min(1, supplied!)) : 0.25 + 0.75 * Math.abs(Math.sin(i * 1.73) * Math.cos(i * 0.41));
+        bar.style.height = `${height * 100}%`; wave.append(bar); return bar;
+      });
+      return (ratio, _value, animate) => bars.forEach((bar, i) => {
+        const on = i / Math.max(1, count - 1) <= ratio;
+        const changed = bar.hasAttribute('data-mk-on') !== on;
+        bar.toggleAttribute('data-mk-on', on);
+        if (animate && changed && !reduced()) keep(gsap.fromTo(bar, { scaleY: 0.72 }, { scaleY: 1, duration: 0.35, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+      });
+    },
+  });
+}

package/src/components/equalizer-slider/equalizer-slider.css

@@ -0,0 +1,26 @@
+:is(.mk-equalizer-slider, mk-equalizer-slider) { display: block; width: 100%; min-width: 0; color: var(--mk-text); font: 500 .875rem/1.4 var(--mk-font); }
+[data-mk-equalizer-body] { display: grid; gap: .875rem; }
+[data-mk-equalizer-header] { display: flex; justify-content: space-between; align-items: center; gap: 1rem; }
+[data-mk-equalizer-output] { font-variant-numeric: tabular-nums; white-space: nowrap; }
+[data-mk-equalizer-track] { position: relative; height: 76px; min-width: 0; border-radius: 24px; background: var(--mk-surface-2); }
+[data-mk-equalizer-input] { position: absolute; z-index: 3; inset: 0; box-sizing: border-box; width: 100%; height: 100%; margin: 0; appearance: none; -webkit-appearance: none; background: transparent; cursor: ew-resize; opacity: 0; }
+[data-mk-equalizer-input]::-webkit-slider-thumb { appearance: none; -webkit-appearance: none; width: 32px; height: 76px; background: transparent; }
+[data-mk-equalizer-input]::-moz-range-thumb { width: 32px; height: 76px; border: 0; background: transparent; }
+[data-mk-equalizer-thumb] { position: absolute; z-index: 2; top: 50%; left: calc(16px + (100% - 32px) * var(--mk-equalizer-ratio, .5)); translate: -50% -50%; pointer-events: none; }
+[data-mk-equalizer-track]:has(:focus-visible) { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-equalizer-ends] { display: flex; justify-content: space-between; margin-top: -.375rem; color: var(--mk-muted); font-size: .75rem; font-variant-numeric: tabular-nums; }
+[data-mk-equalizer-message] { color: var(--mk-error); font-size: .8125rem; font-weight: 400; }
+[data-mk-equalizer-message]:empty { display: none; }
+:is(.mk-equalizer-slider, mk-equalizer-slider)[data-mk-disabled] { opacity: .4; }
+:is(.mk-equalizer-slider, mk-equalizer-slider)[data-mk-disabled] [data-mk-equalizer-input] { cursor: not-allowed; }
+:is(.mk-equalizer-slider, mk-equalizer-slider)[data-mk-error] [data-mk-equalizer-track] { outline: 1px solid var(--mk-error); }
+[data-mk-equalizer-output] { padding: .375rem .75rem; border-radius: 64px; background: var(--mk-surface-2); font-size: .8125rem; }
+[data-mk-equalizer-wave] { position: absolute; inset: 14px 16px; display: flex; align-items: center; gap: 3px; pointer-events: none; }
+[data-mk-equalizer-wave] > span { flex: 1; min-width: 1px; border-radius: 64px; background: var(--mk-outline-soft); transform-origin: center; transition: background .16s; }
+[data-mk-equalizer-wave] > span[data-mk-on] { background: var(--mk-text); }
+[data-mk-equalizer-thumb] { width: 4px; height: 54px; border: 3px solid var(--mk-surface-2); border-radius: 64px; background: var(--mk-text); box-sizing: content-box; transition: height .35s var(--mk-ease-swatch), border-width .35s var(--mk-ease-swatch); }
+:is(.mk-equalizer-slider, mk-equalizer-slider)[data-mk-held] [data-mk-equalizer-thumb] { height: 66px; border-width: 5px; }
+@media (hover: hover) { [data-mk-equalizer-track]:has(:not(:disabled):hover) [data-mk-equalizer-thumb] { height: 62px; } }
+@media (prefers-reduced-motion: reduce) { [data-mk-equalizer-thumb], [data-mk-equalizer-wave] > span { transition: none; } }
+@media (forced-colors: active) { [data-mk-equalizer-wave] > span { background: GrayText; } [data-mk-equalizer-wave] > span[data-mk-on], [data-mk-equalizer-thumb] { background: Highlight; } }
+

package/src/components/equalizer-slider/react.tsx

@@ -0,0 +1,60 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createEqualizerSlider, type EqualizerSliderOptions, type EqualizerSliderInstance } from './engine';
+
+export interface EqualizerSliderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue' | 'children' | 'dangerouslySetInnerHTML'>, Omit<EqualizerSliderOptions, 'value' | 'defaultValue'> {
+  value?: number;
+  defaultValue?: number;
+  instanceRef?: MutableRefObject<EqualizerSliderInstance | null>;
+  /** The engine owns this component's DOM. */
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function EqualizerSlider({ value, defaultValue, min, max, step, label, name, disabled, error, formatValue, waveform, bars, onChange, onInput, instanceRef, className, children: _children, dangerouslySetInnerHTML: _html, ...props }: EqualizerSliderProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const engine = useRef<EqualizerSliderInstance | null>(null);
+  const latestValue = useLatest(value);
+  const change = useLatest(onChange);
+  const input = useLatest(onInput);
+  const baseline = useRef(value !== undefined ? value : defaultValue);
+  const current = useRef(baseline.current);
+  const reconcile = () => queueMicrotask(() => {
+    if (latestValue.current !== undefined) engine.current?.setValue(latestValue.current, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    const created = createEqualizerSlider(root.current, {
+      min, max, step, label, name, disabled, error, formatValue, waveform, bars, value: latestValue.current !== undefined ? latestValue.current : current.current, defaultValue: baseline.current,
+      onChange: (next) => { change.current?.(next); reconcile(); },
+      onInput: (next) => { input.current?.(next); if (input.current || !change.current) reconcile(); },
+    });
+    engine.current = created;
+    const form = root.current?.closest('form');
+    const pending = new Set<ReturnType<typeof setTimeout>>();
+    const reset = (event: Event) => {
+      const timer = setTimeout(() => {
+        pending.delete(timer);
+        if (!event.defaultPrevented && latestValue.current !== undefined) created.setValue(latestValue.current, false);
+      }, 0);
+      pending.add(timer);
+    };
+    form?.addEventListener('reset', reset);
+    return () => {
+      form?.removeEventListener('reset', reset);
+      pending.forEach((timer) => clearTimeout(timer));
+      current.current = created.value; created.destroy(); engine.current = null;
+    };
+    // Callbacks and controlled value are read through refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [min, max, step, label, name, disabled, error, formatValue, waveform, bars]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) engine.current?.setValue(value, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (!instanceRef) return;
+    instanceRef.current = engine.current;
+    return () => { instanceRef.current = null; };
+  }, [instanceRef, min, max, step, label, name, disabled, error, formatValue, waveform, bars]);
+  return <div {...props} ref={root} className={['mk-equalizer-slider', className].filter(Boolean).join(' ')} />;
+}
+

package/src/components/equalizer-slider/shared.ts

@@ -0,0 +1,161 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope, type Scope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press, rollDigits } from '../../motion/micro';
+
+export interface NumericOptions {
+  min?: number; max?: number; step?: number; value?: number; defaultValue?: number; label?: string;
+  name?: string; disabled?: boolean; error?: string; formatValue?: (value: number) => string;
+  onInput?: (value: number) => void; onChange?: (value: number) => void;
+}
+export interface NumericInstance extends Instance { readonly value: number; setValue(value: number, notify?: boolean): void; reset(notify?: boolean): void }
+/** Private: changes the range or format in place, so the change can glide instead of remounting. */
+export interface NumericRange extends NumericInstance { configure(next: { min?: number; max?: number; step?: number; format?: (value: number) => string; value?: number }, notify?: boolean): void }
+export interface NumericParts { root: HTMLElement; track: HTMLElement; thumb: HTMLElement; scope: Scope; keep(effect: gsap.core.Animation | null): void }
+export interface NumericDesign {
+  prefix: string; label: string; min: number; max: number; value: number;
+  format(value: number): string;
+  decorate?(parts: NumericParts): ((ratio: number, value: number, animate: boolean) => void) | void;
+}
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n);
+let sequence = 0;
+
+/** Private renderer: transparent native range over an immediate visual track. */
+export function createNumericRange(root: HTMLElement | null, options: NumericOptions, design: NumericDesign): NumericRange {
+  if (!root) return inert({ value: design.value, setValue() {}, reset() {}, configure() {} });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const prior of effects) if (prior.totalProgress() === 1) effects.delete(prior);
+    if (effect) effects.add(effect);
+  };
+  scope.add(() => { effects.forEach((effect) => effect.kill()); effects.clear(); });
+  let min = finite(options.min) ? options.min : design.min;
+  let max = finite(options.max) && options.max > min ? options.max : Math.max(min + 1, design.max);
+  let step = finite(options.step) && options.step > 0 ? options.step : 1;
+  let lastStep = Math.max(0, Math.floor((max - min) / step + 1e-8));
+  let format = options.formatValue ?? design.format;
+  const snap = (n: number) => Number((min + Math.max(0, Math.min(lastStep, Math.round((n - min) / step))) * step).toFixed(8));
+  const initial = snap(finite(options.defaultValue) ? options.defaultValue : finite(options.value) ? options.value : design.value);
+  let value = snap(finite(options.value) ? options.value : initial); let committed = value; let held = false;
+  const prefix = design.prefix;
+  const part = <K extends keyof HTMLElementTagNameMap>(tag: K, parent: Element, name: string) => {
+    const el = document.createElement(tag); el.setAttribute(`data-mk-${prefix}-${name}`, ''); parent.append(el); return el;
+  };
+  const shell = part('div', root, 'body');
+  scope.add(() => shell.remove());
+  const header = part('div', shell, 'header');
+  const label = part('label', header, 'label');
+  label.textContent = options.label ?? design.label;
+  const output = part('output', header, 'output');
+  output.setAttribute('aria-hidden', 'true');
+  const track = part('div', shell, 'track');
+  const thumb = part('span', track, 'thumb');
+  thumb.setAttribute('aria-hidden', 'true');
+  const input = part('input', track, 'input');
+  input.type = 'range'; input.min = String(min); input.max = String(max); input.step = String(step);
+  input.defaultValue = String(initial); input.value = String(value);
+  input.id = `mk-${prefix}-${++sequence}`; label.htmlFor = input.id;
+  input.disabled = Boolean(options.disabled);
+  if (options.name) input.name = options.name;
+  const message = part('span', shell, 'message');
+  message.textContent = options.error ?? '';
+  if (options.error) {
+    message.id = `${input.id}-error`; input.setAttribute('aria-invalid', 'true'); input.setAttribute('aria-describedby', message.id);
+  }
+  const ends = part('div', shell, 'ends');
+  ends.setAttribute('aria-hidden', 'true');
+  const minEnd = part('span', ends, 'min'); minEnd.textContent = format(min);
+  const maxEnd = part('span', ends, 'max'); maxEnd.textContent = format(max);
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-disabled', options.disabled ? '' : null);
+  scope.attr(root, 'data-mk-error', options.error ? '' : null);
+  scope.attr(root, 'data-mk-held', null);
+  scope.attr(root, 'style', root.getAttribute('style'));
+  const decorate = design.decorate?.({ root, track, thumb, scope, keep });
+  let shown: number | null = null;
+  let glide: gsap.core.Tween | null = null;
+  scope.add(() => glide?.kill());
+  const show = (ratio: number, animate: boolean) => {
+    shown = ratio;
+    root.style.setProperty(`--mk-${prefix}-ratio`, String(ratio));
+    decorate?.(ratio, value, animate);
+  };
+  const paint = (animate: boolean, before: number) => {
+    const ratio = (value - min) / (max - min);
+    const text = format(value);
+    input.value = String(value); input.setAttribute('aria-valuetext', text);
+    if (animate && !held && !reduced()) keep(rollDigits(output, text, value >= before ? 1 : -1, 0.3));
+    else { const roll = rollDigits(output, text, value >= before ? 1 : -1, 0); roll?.progress(1).kill(); output.textContent = text; }
+    glide?.kill(); glide = null;
+    // Presets, keys and range changes glide on the kit's swatch spring; a held
+    // thumb follows the pointer exactly. The value itself is already final.
+    if (animate && !held && !reduced() && shown !== null && Math.abs(ratio - shown) > 1e-4) {
+      const proxy = { ratio: shown };
+      glide = gsap.to(proxy, { ratio, duration: 0.5, ease: EASE.swatch, onUpdate: () => show(Math.max(0, Math.min(1, proxy.ratio)), true) });
+    } else show(ratio, animate && !held);
+  };
+  const emit = (type: 'input' | 'change') => {
+    if (scope.disposed) return;
+    const emitted = value;
+    (type === 'input' ? options.onInput : options.onChange)?.(emitted);
+    if (!scope.disposed) root.dispatchEvent(new CustomEvent(`mk:${type}`, { bubbles: true, detail: { value: emitted } }));
+  };
+  const set = (next: number, notify = false, animate = true) => {
+    if (scope.disposed || !finite(next)) return;
+    const before = value; value = snap(next); paint(animate, before);
+    if (notify && value !== before) { emit('input'); committed = value; emit('change'); }
+    // A controlled onInput render commonly writes this same value back before
+    // the native change event. Keep its pending commit until release.
+    else if (!notify && value !== before) committed = value;
+  };
+  scope.on(input, 'input', () => {
+    if (input.disabled || input.matches(':disabled')) { input.value = String(value); return; }
+    const before = value; value = snap(Number(input.value)); paint(true, before);
+    if (value !== before) emit('input');
+  });
+  scope.on(input, 'change', () => {
+    if (input.disabled || input.matches(':disabled')) return;
+    const before = value; value = snap(Number(input.value));
+    if (value !== before) paint(true, before);
+    if (value !== committed) { committed = value; emit('change'); }
+  });
+  scope.on(input, 'pointerdown', () => {
+    if (input.disabled || input.matches(':disabled')) return;
+    held = true; root.setAttribute('data-mk-held', ''); keep(press(thumb));
+  });
+  const release = () => {
+    if (!held) return;
+    held = false; root.removeAttribute('data-mk-held');
+    if (!reduced()) keep(gsap.fromTo(thumb, { scale: 1.12 }, { scale: 1, duration: 0.4, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+  };
+  scope.on(window, 'pointerup', release); scope.on(window, 'pointercancel', release); scope.on(input, 'blur', release);
+  if (input.form) scope.on(input.form, 'reset', (event) => scope.timeout(() => {
+    if (!scope.disposed && !event.defaultPrevented) set(initial);
+  }, 0));
+  const configure: NumericRange['configure'] = (next, notify = false) => {
+    if (scope.disposed) return;
+    const before = value;
+    if (finite(next.min)) min = next.min;
+    if (finite(next.max)) max = next.max > min ? next.max : min + 1;
+    if (finite(next.step) && next.step > 0) step = next.step;
+    if (next.format) format = next.format;
+    lastStep = Math.max(0, Math.floor((max - min) / step + 1e-8));
+    input.min = String(min); input.max = String(max); input.step = String(step);
+    const ends = [[minEnd, format(min)], [maxEnd, format(max)]] as const;
+    for (const [end, text] of ends) {
+      if (reduced()) end.textContent = text;
+      else keep(rollDigits(end, text, 1, 0.3));
+    }
+    value = snap(finite(next.value) ? next.value : value);
+    paint(true, before);
+    if (value !== before) {
+      committed = value;
+      if (notify) { emit('input'); emit('change'); }
+    }
+  };
+  paint(false, value);
+  return { get value() { return value; }, setValue: set, reset: (notify = false) => set(initial, notify), configure, destroy: () => scope.dispose() };
+}

package/src/components/handwriting-text/README.md

@@ -0,0 +1,29 @@
+# Handwriting text
+
+Una línea de tinta se escribe con trazos SVG originales. Cada trazo se dibuja mediante `stroke-dashoffset`; no es una animación de texto tecleado ni depende de una fuente externa. Incluye glifos latinos A–Z/a–z, cifras, puntuación básica y acentos agudo, diéresis y tilde. Los símbolos no incluidos se muestran como texto SVG normal, sin fingir que se escriben a mano. El texto completo conserva su nombre accesible.
+
+```ts
+import { createHandwritingText } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/handwriting-text';
+
+const drawing = createHandwritingText(document.querySelector('#signature'), {
+  text: 'Make it move.', duration: 2.4,
+});
+drawing.setText('Una nueva idea');
+drawing.replay();
+// Al desmontar: drawing.destroy();
+```
+
+`HandwritingTextOptions`: `text` (por defecto el texto del host), `duration` (segundos, 2.4), `autoplay` (true), `onComplete`. `HandwritingTextInstance`: `setText(text, animate = true)`, `replay()`, `text`, `destroy()`. Emite `mk:complete` cuando termina una reproducción animada. Una cadena vacía produce un estado vacío; admite saltos de línea. Movimiento reducido muestra los trazos completos inmediatamente.
+
+```tsx
+<HandwritingText text={message} instanceRef={drawingRef} />
+```
+
+El adaptador React controla `text`; recibe `instanceRef` y los atributos de un span. El motor posee los hijos, por lo que `children` y `dangerouslySetInnerHTML` no se admiten y se filtran también en ejecución.
+
+```html
+<mk-handwriting-text text="Make it move." duration="2.4"></mk-handwriting-text>
+```
+
+`defineHandwritingText()` registra `MkHandwritingTextElement`. Sus atributos son `text`, `duration` y `autoplay`; `element.instance` expone el motor. Conserva el texto imperativo al cambiar presentación o reconectar; un cambio explícito del atributo `text` lo reemplaza. CSS: `--mk-handwriting-width` (28rem); hereda `color` y todos los temas. `destroy()` detiene la reproducción y devuelve los nodos y atributos originales.

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

@@ -0,0 +1,14 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createHandwritingText, type HandwritingTextInstance } from './engine';
+
+export class MkHandwritingTextElement extends MkElement<HandwritingTextInstance> {
+  static options: Record<string, OptionType> = { text: 'string', duration: 'number', autoplay: 'boolean' };
+  private retained: string | undefined;
+  protected create(options: Record<string, unknown>) { return createHandwritingText(this, { ...options, ...(this.retained === undefined ? {} : { text: this.retained }) }); }
+  disconnectedCallback() { this.retained = this.instance?.text ?? this.retained; super.disconnectedCallback(); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous !== next) this.retained = name === 'text' ? undefined : this.instance?.text ?? this.retained;
+    super.attributeChangedCallback(name, previous, next);
+  }
+}
+export const defineHandwritingText = () => defineElement('mk-handwriting-text', MkHandwritingTextElement);

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(' ')} />;
+}