@yewdiel21/motion-kit 0.17.0 → 0.18.0

package/src/components/bento-grid/engine.ts

@@ -0,0 +1,153 @@
+import { Flip, gsap, EASE, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { reduced } from '../../core/reduced';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press } from '../../motion/micro';
+
+export interface BentoGridOptions {
+  columns?: number;
+  gap?: number;
+  /** Matches a whitespace-separated data-mk-category. Null shows every item. */
+  filter?: string | null;
+  duration?: number;
+  onChange?: (keys: string[]) => void;
+}
+export interface BentoGridInstance extends Instance {
+  refresh(): void;
+  setFilter(filter: string | null): void;
+  reorder(keys: string[]): void;
+  /** Capture before an authored DOM mutation (add/remove/replace), then animate to its layout. */
+  mutate(change: () => void): void;
+  setOptions(options: Partial<BentoGridOptions>): void;
+  readonly filter: string | null;
+  readonly keys: string[];
+}
+
+/** Authored direct children are the grid items. Spans live in data-mk-col-span / data-mk-row-span. */
+export function createBentoGrid(root: HTMLElement | null, options: BentoGridOptions = {}): BentoGridInstance {
+  if (!root) return inert({ refresh() {}, setFilter() {}, reorder() {}, mutate() {}, setOptions() {}, filter: null, keys: [] });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let filter = opts.filter ?? null;
+  let animation: gsap.core.Timeline | null = null;
+  const micro = new Set<gsap.core.Animation>();
+  const track = (value: gsap.core.Animation | null) => { if (value) micro.add(value); };
+  const originals = [...root.childNodes];
+  const originalItems = new Set(root.children);
+  const remembered = new Set<HTMLElement>();
+  let queued = 0;
+  scope.attr(root, 'class', `${root.className} mk-bento-grid`.trim());
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  const items = () => [...root.children].filter((node): node is HTMLElement => node instanceof HTMLElement && node.hasAttribute('data-mk-bento-item'));
+  const key = (item: HTMLElement) => item.dataset.mkBentoItem!;
+  const visible = () => items().filter((item) => !item.hidden);
+  const save = (item: HTMLElement) => {
+    if (remembered.has(item)) return;
+    remembered.add(item);
+    for (const attr of ['style', 'hidden', 'inert', 'aria-hidden', 'data-flip-id']) scope.attr(item, attr, item.getAttribute(attr));
+  };
+  items().forEach(save);
+  let last: ReturnType<typeof Flip.getState> | undefined;
+  const notify = () => {
+    const keys = visible().map(key);
+    opts.onChange?.(keys);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { keys, filter } }));
+  };
+  const paint = () => {
+    const desired = Number.isFinite(opts.columns) ? Math.max(1, Math.min(12, Math.round(opts.columns!))) : 3;
+    const cols = root.clientWidth > 0 && root.clientWidth < 280 ? 1 : root.clientWidth > 0 && root.clientWidth < 440 ? Math.min(2, desired) : desired;
+    root.style.setProperty('--mk-bento-columns', String(cols));
+    root.style.setProperty('--mk-bento-gap', `${Math.max(0, opts.gap ?? 12)}px`);
+    items().forEach((item) => {
+      save(item);
+      item.style.setProperty('--mk-bento-col-span', String(Math.max(1, Math.min(cols, Number(item.dataset.mkColSpan) || 1))));
+      item.style.setProperty('--mk-bento-row-span', String(Math.max(1, Math.min(8, Number(item.dataset.mkRowSpan) || 1))));
+      const show = !filter || (item.dataset.mkCategory ?? '').split(/\s+/).includes(filter);
+      if (!show && item.contains(document.activeElement)) { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); }
+      item.hidden = !show;
+      item.inert = !show;
+      item.setAttribute('aria-hidden', String(!show));
+    });
+    scope.attr(root, 'data-mk-empty', visible().length ? null : '');
+    if (!root.hasAttribute('data-mk-empty-label')) scope.attr(root, 'data-mk-empty-label', 'No hay elementos en esta vista.');
+  };
+  const transition = (state = last, entering: HTMLElement[] = []) => {
+    if (scope.disposed) return;
+    animation?.kill();
+    paint();
+    if (!reduced()) {
+      animation = Flip.from(state ?? Flip.getState([]), { targets: visible(), duration: Math.max(0, opts.duration ?? .55), ease: EASE.signature, stagger: .025, absolute: false, scale: false, prune: true, onComplete: () => { if (!scope.disposed) last = Flip.getState(visible()); } });
+      track(blurIn(entering.filter((item) => !item.hidden), { from: 'soft', stagger: .04, duration: .35 }));
+    }
+    if (!reduced()) last = Flip.getState(visible());
+  };
+  const capture = () => {
+    animation?.kill();
+    if (reduced()) return undefined;
+    const focused = document.activeElement as HTMLElement | null;
+    Flip.killFlipsOf(items());
+    const state = Flip.getState(visible());
+    if (focused?.isConnected && focused !== document.activeElement) focused.focus({ preventScroll: true });
+    return state;
+  };
+  const mutate = (change: () => void) => {
+    if (scope.disposed) return;
+    const focused = document.activeElement as HTMLElement | null;
+    const state = capture();
+    const before = new Set(items());
+    change();
+    transition(state, items().filter((item) => !before.has(item)));
+    if (focused && focused !== document.body && root.contains(focused) && !focused.closest('[hidden], [inert]')) focused.focus({ preventScroll: true });
+    else if (focused && !focused.isConnected) { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); }
+    observer?.takeRecords();
+    notify();
+  };
+  const setFilter = (next: string | null) => {
+    if (scope.disposed || next === filter) return;
+    const state = capture();
+    const before = new Set(visible());
+    filter = next;
+    paint();
+    transition(state, visible().filter((item) => !before.has(item)));
+    notify();
+  };
+  const refresh = () => {
+    if (scope.disposed) return;
+    transition(last, items().filter((item) => !remembered.has(item)));
+  };
+  const observer = typeof MutationObserver === 'function' ? scope.observe(new MutationObserver((records) => {
+    // Observe authored data only: engine style/hidden writes and nested content
+    // changes must not schedule another layout or create an observer loop.
+    if (!records.some((record) => record.type === 'childList' ? record.target === root : record.target instanceof HTMLElement && record.target.parentElement === root)) return;
+    cancelAnimationFrame(queued);
+    queued = requestAnimationFrame(refresh);
+  })) : null;
+  observer?.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-mk-category', 'data-mk-col-span', 'data-mk-row-span'] });
+  scope.on(root, 'click', (event) => {
+    const control = (event.target as Element).closest<HTMLElement>('button, a');
+    if (control && root.contains(control) && !control.matches(':disabled, [aria-disabled="true"]')) { scope.attr(control, 'style', control.getAttribute('style')); track(press(control)); }
+  });
+  if (typeof ResizeObserver === 'function') {
+    let width = root.clientWidth;
+    const resize = scope.observe(new ResizeObserver(() => { if (root.clientWidth !== width) { width = root.clientWidth; animation?.kill(); paint(); last = Flip.getState(visible()); } }));
+    resize.observe(root);
+  }
+  paint(); if (!reduced()) last = Flip.getState(visible());
+  track(blurIn(visible(), { from: 'soft', stagger: .04 }));
+  return {
+    refresh, mutate, setFilter,
+    reorder(keys) { mutate(() => { const byKey = new Map(items().map((item) => [key(item), item])); for (const id of new Set(keys)) { const item = byKey.get(id); if (item) { root.append(item); byKey.delete(id); } } byKey.forEach((item) => root.append(item)); }); },
+    setOptions(next) { if (scope.disposed) return; const state = capture(); opts = { ...opts, ...next }; if (next.filter !== undefined) filter = next.filter; transition(state); },
+    get filter() { return filter; }, get keys() { return visible().map(key); },
+    destroy() {
+      if (scope.disposed) return;
+      cancelAnimationFrame(queued); animation?.kill(); micro.forEach((value) => value.kill()); if (!reduced()) Flip.killFlipsOf(items()); gsap.killTweensOf([...remembered]);
+      scope.dispose();
+      // Preserve externally added content while restoring the initial authored order.
+      const added = [...root.childNodes].filter((node) => !originals.includes(node) && !(node instanceof Element && originalItems.has(node)));
+      root.replaceChildren(...originals, ...added);
+    },
+  };
+}

package/src/components/bento-grid/react.tsx

@@ -0,0 +1,25 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createBentoGrid, type BentoGridOptions, type BentoGridInstance } from './engine';
+
+export interface BentoGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, BentoGridOptions {
+  instanceRef?: MutableRefObject<BentoGridInstance | null>;
+
+}
+export function BentoGrid({ columns, gap, filter, duration, onChange, instanceRef, className, children, ...props }: BentoGridProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<BentoGridInstance | null>(null);
+  const onChangeRef = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createBentoGrid(root.current, { columns, gap, filter, duration, onChange: (...args) => onChangeRef.current?.(...args) });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+    // Options update the existing engine so timers, selection and scroll state survive.
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setOptions({ columns, gap, filter, duration });
+  }, [columns, gap, filter, duration]);
+  useIsomorphicLayoutEffect(() => { if (instanceRef) instanceRef.current = instance.current; return () => { if (instanceRef) instanceRef.current = null; }; }, [instanceRef]);
+  return <div {...props} ref={root} className={['mk-bento-grid', className].filter(Boolean).join(' ')}>{children}</div>;
+}

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