@yewdiel21/motion-kit 0.17.0 → 0.19.0

package/src/components/drilldown-menu/drilldown-menu.css

@@ -8,13 +8,13 @@ mk-drilldown-menu {
   width: 100%;
   max-width: 26rem;
   min-width: 0;
-  padding: 10px;
-  border: 1px solid var(--mk-outline-soft);
+  padding: 12px;
+  border: 0;
   border-radius: var(--mk-drilldown-radius);
   background: var(--mk-surface-1);
   color: var(--mk-text);
   font-family: var(--md-sys-typescale-body-large-font, inherit);
-  box-shadow: 0 12px 36px -20px rgb(0 0 0 / 0.25);
+  font-family: var(--mk-font);
 }
 
 [data-mk-drilldown-header] {
@@ -85,8 +85,9 @@ mk-drilldown-menu {
   cursor: pointer;
 }
 
-[data-mk-drilldown-viewport] { overflow: hidden; border-radius: var(--mk-drilldown-item-radius); }
-[data-mk-drilldown-level] { display: grid; gap: 3px; }
+[data-mk-drilldown-viewport] { position: relative; isolation: isolate; overflow: hidden; border-radius: var(--mk-drilldown-item-radius); }
+[data-mk-drilldown-highlight] { position: absolute; top: 0; left: 0; z-index: -1; border-radius: var(--mk-radius-lg); background: var(--mk-surface-3); pointer-events: none; opacity: 0; }
+[data-mk-drilldown-level] { position: relative; display: grid; gap: 6px; }
 [data-mk-drilldown-item] {
   display: flex;
   align-items: center;
@@ -104,16 +105,19 @@ mk-drilldown-menu {
   line-height: 1.4;
   text-align: start;
   cursor: pointer;
-  transition: background-color 0.16s ease;
+  transition: color .15s, border-radius .3s var(--mk-ease-playful);
 }
 
 [data-mk-drilldown-item]:enabled:hover,
-[data-mk-drilldown-item]:focus-visible { background: var(--mk-surface-3); }
+[data-mk-drilldown-item]:focus-visible { background: color-mix(in srgb, var(--mk-text) 3%, transparent); border-radius: var(--mk-radius-xl); }
+[data-mk-drilldown-item][data-mk-chosen]::after { content: '✓'; display: grid; place-items: center; flex: none; width: 26px; height: 26px; border-radius: 50%; color: var(--mk-on-accent); background: var(--mk-accent); }
 [data-mk-drilldown-item]:disabled { opacity: 0.42; cursor: default; }
 [data-mk-drilldown-text] { display: grid; gap: 3px; min-width: 0; overflow-wrap: anywhere; }
 [data-mk-drilldown-label] { font-weight: 550; }
 [data-mk-drilldown-description] { color: var(--mk-muted); font-size: 0.8rem; }
 [data-mk-drilldown-arrow] { display: inline-flex; flex: none; color: var(--mk-muted); }
+[data-mk-drilldown-arrow] svg { transition: transform .35s var(--mk-ease-swatch); }
+[data-mk-highlighted] [data-mk-drilldown-arrow] svg { transform: translateX(3px); }
 [data-mk-drilldown-empty] { margin: 0; padding: 24px 16px; color: var(--mk-muted); font-size: 0.875rem; }
 
 [data-mk-drilldown-item]:focus-visible,

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

@@ -2,6 +2,7 @@ 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, ringPulse } from '../../motion/micro';
 
 export interface DrilldownMenuItem {
   /** Unique among siblings; IDs form the navigation path. */
@@ -66,6 +67,12 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   let focused: string | null = null;
   const remembered = new Map<string, string>();
   let animation: gsap.core.Timeline | null = null;
+  let hoverMotion: gsap.core.Tween | null = null;
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const animation of effects) if (animation.totalProgress() === 1) effects.delete(animation);
+    if (effect) effects.add(effect);
+  };
 
   const header = document.createElement('div');
   header.dataset.mkDrilldownHeader = '';
@@ -91,7 +98,9 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   const empty = document.createElement('p');
   empty.dataset.mkDrilldownEmpty = '';
   empty.setAttribute('role', 'status');
-  viewport.append(menu, empty);
+  const highlight = document.createElement('span');
+  highlight.dataset.mkDrilldownHighlight = ''; highlight.setAttribute('aria-hidden', 'true');
+  viewport.append(highlight, menu, empty);
   backButton.setAttribute('aria-controls', menu.id);
   root.append(header, breadcrumb, viewport);
   scope.attr(root, 'data-mk-ready', '');
@@ -112,10 +121,19 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   const level = () => levelAt(path);
   const enabled = () => [...menu.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-item]')].filter((item) => !item.disabled);
   const buttonOf = (id: string) => enabled().find((item) => item.dataset.mkDrilldownItem === id);
+  const highlightItem = (button?: HTMLButtonElement | null) => {
+    hoverMotion?.kill();
+    for (const item of enabled()) item.toggleAttribute('data-mk-highlighted', item === button);
+    if (!button) { highlight.style.opacity = '0'; return; }
+    const geometry = { x: button.offsetLeft + menu.offsetLeft, y: button.offsetTop + menu.offsetTop, width: button.offsetWidth, height: button.offsetHeight, opacity: 1 };
+    if (reduced()) gsap.set(highlight, geometry);
+    else hoverMotion = gsap.to(highlight, { ...geometry, duration: .35, ease: EASE.swatch });
+  };
   const cancelMotion = () => {
     animation?.kill();
+    hoverMotion?.kill();
     animation = null;
-    gsap.set(menu, { clearProps: 'transform,opacity,filter' });
+    gsap.set([menu, heading, breadcrumb, ...menu.children], { clearProps: 'transform,opacity,filter' });
     gsap.set(viewport, { clearProps: 'height' });
   };
   const roving = (id: string | null, focus = false) => {
@@ -127,6 +145,7 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
     menu.tabIndex = target ? -1 : 0;
     if (focused) remembered.set(JSON.stringify(path), focused);
     if (focus) (target ?? menu).focus({ preventScroll: true });
+    if (focus) highlightItem(target);
   };
   const notifyPath = () => {
     const next = [...path];
@@ -137,6 +156,7 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   const render = (direction: number, focus: boolean, preferred?: string | null) => {
     const oldHeight = viewport.getBoundingClientRect().height;
     cancelMotion();
+    highlightItem(null);
     const current = level();
     const label = config.label ?? 'Actions';
     const title = current.ancestors.at(-1)?.label ?? label;
@@ -144,6 +164,8 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
     backButton.hidden = path.length === 0;
     backButton.setAttribute('aria-label', config.backLabel ?? 'Back');
     breadcrumb.setAttribute('aria-label', `${label} path`);
+    // At the root the heading already names the only crumb.
+    breadcrumb.hidden = path.length === 0;
     const labels = [label, ...current.ancestors.map((item) => item.label)];
     crumbs.replaceChildren(...labels.map((text, index) => {
       const li = document.createElement('li');
@@ -203,6 +225,8 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
       // duplicated menuitems and allows rapid navigation without stale callbacks.
       animation = gsap.timeline({ onComplete: () => { animation = null; } })
         .fromTo(menu, { x: 28 * direction, opacity: 0, filter: 'blur(6px)' }, { x: 0, opacity: 1, filter: 'blur(0px)', duration: 0.36, ease: EASE.signature, clearProps: 'transform,opacity,filter' });
+      animation.fromTo([heading, breadcrumb], { y: -6, opacity: .3, filter: 'blur(6px)' }, { y: 0, opacity: 1, filter: 'blur(0px)', duration: .3, ease: EASE.pop, clearProps: 'transform,opacity,filter' }, 0)
+        .fromTo([...menu.children], { x: 12 * direction, opacity: 0 }, { x: 0, opacity: 1, duration: .3, stagger: .035, ease: EASE.swatchLight, clearProps: 'transform,opacity' }, .04);
       const nextHeight = viewport.getBoundingClientRect().height;
       if (oldHeight > 0 && nextHeight > 0 && oldHeight !== nextHeight) {
         animation.fromTo(viewport, { height: oldHeight }, { height: nextHeight, duration: 0.36, ease: EASE.signature, clearProps: 'height' }, 0);
@@ -237,6 +261,11 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
     const item = level().items.find((entry) => entry.id === id);
     if (!item || item.disabled) return;
     if (branch(item)) return void open(id);
+    const button = buttonOf(id);
+    if (button) {
+      for (const row of enabled()) row.toggleAttribute('data-mk-chosen', row === button);
+      keep(press(button)); keep(ringPulse(button));
+    }
     const selected = copyItems([item])[0]!;
     const selectedPath = [...path, item.id];
     root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { item: selected, path: [...selectedPath] } }));
@@ -251,8 +280,17 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   });
   scope.on(menu, 'focusin', (event) => {
     const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
-    if (button && !button.disabled) roving(button.dataset.mkDrilldownItem!, false);
+    if (button && !button.disabled) { roving(button.dataset.mkDrilldownItem!, false); highlightItem(button); }
+  });
+  scope.on(menu, 'pointerover', event => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (button && !button.disabled) highlightItem(button);
   });
+  scope.on(menu, 'pointerleave', () => highlightItem(menu.contains(document.activeElement) ? buttonOf(focused ?? '') : null));
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => {
+    const current = menu.querySelector<HTMLButtonElement>('[data-mk-highlighted]');
+    if (current) highlightItem(current);
+  })).observe(menu);
   scope.on(root, 'keydown', (event) => {
     const key = (event as KeyboardEvent).key;
     if ((key === 'ArrowLeft' || key === 'Escape') && path.length) {
@@ -279,7 +317,7 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
       activate(button.dataset.mkDrilldownItem!);
     }
   });
-  scope.on(backButton, 'click', () => back());
+  scope.on(backButton, 'click', () => { keep(press(backButton)); back(); });
   scope.on(breadcrumb, 'click', (event) => {
     const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-crumb]');
     if (!button || !breadcrumb.contains(button)) return;
@@ -288,6 +326,8 @@ export function createDrilldownMenu(root: HTMLElement | null, options: Drilldown
   });
   scope.add(() => {
     cancelMotion();
+    for (const effect of effects) effect.kill();
+    gsap.killTweensOf([heading, breadcrumb, highlight]);
     remembered.clear();
     header.remove();
     breadcrumb.remove();

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