@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/waveform-player/engine.ts

@@ -0,0 +1,344 @@
+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, rollDigits } from '../../motion/micro';
+
+export type WaveformPlayerStatus = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'ended' | 'error';
+export interface WaveformPlayerState {
+  status: WaveformPlayerStatus;
+  currentTime: number;
+  /** 0 until finite metadata is available. Live streams cannot be sought. */
+  duration: number;
+  playbackRate: number;
+  error: string | null;
+}
+export interface WaveformPlayerOptions {
+  src?: string;
+  /** Normalized amplitudes (0…1), supplied by your application, not audio analysis. */
+  peaks?: readonly number[];
+  label?: string;
+  disabled?: boolean;
+  /** Defaults to [1, 1.5, 2]. false hides the rate button. */
+  playbackRates?: readonly number[] | false;
+  /** Status transitions (time changes have their own callback). */
+  onStateChange?: (state: WaveformPlayerState) => void;
+  onTimeUpdate?: (state: WaveformPlayerState) => void;
+  onPlay?: (state: WaveformPlayerState) => void;
+  onPause?: (state: WaveformPlayerState) => void;
+  onEnded?: (state: WaveformPlayerState) => void;
+  onError?: (state: WaveformPlayerState) => void;
+}
+export interface WaveformPlayerInstance extends Instance {
+  /** Resolves false when unavailable, cancelled, or rejected. Never rejects for media errors. */
+  play(): Promise<boolean>;
+  pause(): void;
+  /** Seconds, clamped to the finite duration; ignored until metadata is available. */
+  seek(seconds: number): void;
+  /** Updates presentation/callbacks in place. A different src pauses and resets playback. */
+  update(options: Partial<WaveformPlayerOptions>): void;
+  readonly state: WaveformPlayerState;
+  readonly audio: HTMLAudioElement | null;
+}
+
+const initialState = (): WaveformPlayerState => ({ status: 'idle', currentTime: 0, duration: 0, playbackRate: 1, error: null });
+const finite = (n: number) => Number.isFinite(n) && n >= 0;
+const clock = (n: number) => `${Math.floor(n / 60)}:${String(Math.floor(n % 60)).padStart(2, '0')}`;
+const playIcon = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m9 6 9 6-9 6Z"/></svg>';
+const pauseIcon = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 6v12M16 6v12"/></svg>';
+const level = (n: unknown) => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 0;
+/** Averages (or repeats) the supplied amplitudes into `count` bars; it never invents audio data. */
+const resample = (values: readonly number[], count: number) => count === values.length ? [...values] : Array.from({ length: count }, (_, k) => {
+  const from = Math.floor(k * values.length / count);
+  const slice = values.slice(from, Math.max(from + 1, Math.floor((k + 1) * values.length / count)));
+  return slice.reduce((sum, n) => sum + n, 0) / slice.length;
+});
+
+export function createWaveformPlayer(root: HTMLElement | null, options: WaveformPlayerOptions = {}): WaveformPlayerInstance {
+  if (!root) return inert({ play: async () => false, pause() {}, seek() {}, update() {}, state: initialState(), audio: null });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let state = initialState();
+  let source = '';
+  let request = 0;
+  let requested = false;
+  let pending: Promise<boolean> | null = null;
+  const make = <K extends keyof HTMLElementTagNameMap>(tag: K, part: string, parent: HTMLElement = root) => {
+    const el = document.createElement(tag);
+    el.setAttribute(`data-mk-wave-${part}`, '');
+    parent.append(el);
+    return el;
+  };
+  // A single owned container preserves authored siblings and makes destroy reversible.
+  const container = make('div', 'content');
+  scope.add(() => container.remove());
+  const audio = make('audio', 'audio', container);
+  audio.preload = 'metadata';
+  audio.hidden = true;
+  const toggle = make('button', 'toggle', container);
+  toggle.type = 'button';
+  const icon = make('span', 'icon', toggle);
+  const body = make('div', 'body', container);
+  const track = make('div', 'track', body);
+  const bars = make('div', 'bars', track);
+  bars.setAttribute('aria-hidden', 'true');
+  const head = make('span', 'head', track); head.setAttribute('aria-hidden', 'true');
+  const preview = make('span', 'preview', track); preview.setAttribute('aria-hidden', 'true'); preview.hidden = true;
+  const range = make('input', 'seek', track);
+  range.type = 'range';
+  range.min = '0';
+  range.max = '0';
+  range.step = '0.1';
+  const footer = make('div', 'footer', body);
+  const time = make('span', 'time', footer);
+  const rate = make('button', 'rate', footer);
+  rate.type = 'button';
+  const message = make('span', 'message', container);
+  message.setAttribute('role', 'status');
+  message.setAttribute('aria-live', 'polite');
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-wave-state', 'idle');
+  scope.attr(root, 'data-mk-wave-scrubbing', null);
+  let barNodes: HTMLElement[] = [];
+  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);
+  };
+  let iconMotion: gsap.core.Tween | null = null;
+  let lastPlaying: boolean | undefined;
+  let lastRate = '';
+  let following = false;
+  const scrubbing = () => root.hasAttribute('data-mk-wave-scrubbing');
+  // Same response as the equalizer: bars crossing the head pop back to height,
+  // except while the head is held, where the value follows the pointer directly.
+  const paintProgress = (seconds: number, animate = true) => {
+    const progress = state.duration ? Math.max(0, Math.min(1, seconds / state.duration)) : 0;
+    track.style.setProperty('--mk-wave-progress', String(progress));
+    barNodes.forEach((bar, i) => {
+      const played = (i + .5) / barNodes.length <= progress;
+      if (bar.hasAttribute('data-mk-played') === played) return;
+      bar.toggleAttribute('data-mk-played', played);
+      if (animate && !scrubbing() && !reduced()) keep(gsap.fromTo(bar, { scaleY: .72 }, { scaleY: 1, duration: .35, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+    });
+  };
+  const followPlayback = () => { if (!scope.disposed && state.status === 'playing') paintProgress(audio.currentTime); };
+  const showPreview = (seconds: number, ratio: number) => {
+    preview.textContent = clock(seconds); preview.style.setProperty('--mk-wave-at', String(Math.max(.04, Math.min(.96, ratio)))); preview.hidden = false;
+  };
+  const snapshot = () => ({ ...state });
+  const rates = () => {
+    const values = opts.playbackRates === false ? [] : (opts.playbackRates ?? [1, 1.5, 2]);
+    return Array.isArray(values) ? [...new Set(values.filter(n => typeof n === 'number' && Number.isFinite(n) && n >= 0.25 && n <= 4))] : [];
+  };
+  const paint = () => {
+    const playing = state.status === 'playing';
+    const nextPlaying = playing || requested;
+    if (lastPlaying !== nextPlaying) {
+      icon.innerHTML = nextPlaying ? pauseIcon : playIcon;
+      iconMotion?.kill();
+      if (lastPlaying !== undefined && !reduced()) iconMotion = gsap.fromTo(icon, { scale: .55, opacity: .3, filter: 'blur(5px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: .3, ease: EASE.pop, clearProps: 'transform,opacity,filter' });
+      lastPlaying = nextPlaying;
+    }
+    toggle.setAttribute('aria-label', `${playing || requested ? 'Pausar' : 'Reproducir'} ${opts.label ?? 'audio'}`);
+    toggle.disabled = !!opts.disabled || !source;
+    range.disabled = !!opts.disabled || !state.duration;
+    range.max = String(state.duration);
+    range.value = String(state.currentTime);
+    range.setAttribute('aria-label', `Posición de ${opts.label ?? 'audio'}`);
+    range.setAttribute('aria-valuetext', `${clock(state.currentTime)} de ${clock(state.duration)}`);
+    time.textContent = `${clock(state.currentTime)} / ${clock(state.duration)}`;
+    rate.hidden = rates().length < 2;
+    rate.disabled = !!opts.disabled;
+    const rateLabel = `${state.playbackRate}×`;
+    if (lastRate !== rateLabel) {
+      if (lastRate) keep(rollDigits(rate, rateLabel, 1, .28));
+      else rate.textContent = rateLabel;
+      lastRate = rateLabel;
+    }
+    rate.setAttribute('aria-label', `Velocidad ${state.playbackRate}×. Cambiar velocidad`);
+    paintProgress(state.currentTime);
+    if (document.activeElement === range) showPreview(state.currentTime, state.duration ? state.currentTime / state.duration : 0);
+    if (playing && !following) { following = true; gsap.ticker.add(followPlayback); }
+    else if (!playing && following) { following = false; gsap.ticker.remove(followPlayback); }
+    root.setAttribute('data-mk-wave-state', state.status);
+    message.textContent = state.error ?? (state.status === 'loading' ? 'Cargando audio…' : state.status === 'ended' ? 'Audio finalizado' : '');
+  };
+  const emit = (patch: Partial<WaveformPlayerState>, event?: 'play' | 'pause' | 'ended' | 'error' | 'timeupdate') => {
+    if (scope.disposed) return;
+    const previous = state.status;
+    state = { ...state, ...patch };
+    paint();
+    const next = snapshot();
+    if (event === 'timeupdate') opts.onTimeUpdate?.(next);
+    if (previous !== state.status) opts.onStateChange?.(snapshot());
+    if (event === 'play') opts.onPlay?.(snapshot());
+    if (event === 'pause') opts.onPause?.(snapshot());
+    if (event === 'ended') opts.onEnded?.(snapshot());
+    if (event === 'error') opts.onError?.(snapshot());
+    if (previous !== state.status) root.dispatchEvent(new CustomEvent('mk:audio-statechange', { bubbles: true, detail: snapshot() }));
+    if (event) root.dispatchEvent(new CustomEvent(`mk:audio-${event}`, { bubbles: true, detail: snapshot() }));
+  };
+  const bounce = (target: HTMLElement) => {
+    keep(press(target));
+  };
+  const fail = (message: string) => { requested = false; emit({ status: 'error', error: message }, 'error'); };
+  const pause = () => {
+    if (scope.disposed) return;
+    request++;
+    requested = false;
+    pending = null;
+    audio.pause();
+    if (state.status !== 'idle' && state.status !== 'error' && state.status !== 'ended' && state.status !== 'paused') emit({ status: 'paused' }, 'pause');
+    else paint();
+  };
+  const seek = (seconds: number) => {
+    if (scope.disposed || !state.duration || !Number.isFinite(seconds)) return;
+    const next = Math.max(0, Math.min(state.duration, seconds));
+    try { audio.currentTime = next; }
+    catch { return; }
+    emit({ currentTime: next, ...(state.status === 'ended' && next < state.duration ? { status: 'paused' as const } : {}) }, 'timeupdate');
+  };
+  const play = (): Promise<boolean> => {
+    if (scope.disposed || opts.disabled || !source) return Promise.resolve(false);
+    if (pending) return pending;
+    if (state.status === 'playing') return Promise.resolve(true);
+    if (state.status === 'ended') seek(0);
+    const token = ++request;
+    requested = true;
+    emit({ status: 'loading', error: null });
+    // Promise.resolve also supports older media implementations that return void.
+    let started: Promise<void>;
+    try { started = Promise.resolve(audio.play()); }
+    catch (error) { started = Promise.reject(error); }
+    const result = started.then(() => {
+      if (scope.disposed || token !== request) return false;
+      requested = false;
+      if (audio.paused) { emit({ status: 'paused' }); return false; }
+      if (state.status !== 'playing') emit({ status: 'playing', error: null }, 'play');
+      return true;
+    }).catch((error: unknown) => {
+      if (!scope.disposed && token === request) {
+        requested = false;
+        if (error instanceof Error && error.name === 'AbortError') emit({ status: 'paused' });
+        else fail('No se pudo reproducir el audio. Vuelve a intentarlo.');
+      }
+      return false;
+    }).finally(() => { if (token === request) pending = null; });
+    pending = result;
+    return result;
+  };
+  const peakValues = () => {
+    const supplied = Array.isArray(opts.peaks) ? opts.peaks : [];
+    // Empty data is an explicit neutral placeholder, never fabricated audio analysis.
+    return supplied.length ? supplied.slice(0, 256).map(level) : Array<number>(48).fill(0.24);
+  };
+  // Bars keep the equalizer's pitch (pill plus 3px gap ≈ 8px) at any width.
+  const barCount = (values: readonly number[]) => {
+    const width = bars.clientWidth;
+    return width > 0 ? Math.max(12, Math.min(72, Math.floor((width + 3) / 8))) : values.length;
+  };
+  const renderPeaks = () => {
+    const values = peakValues();
+    bars.replaceChildren();
+    barNodes = resample(values, barCount(values)).map(peak => {
+      const bar = make('i', 'bar', bars);
+      bar.style.height = `${8 + peak * 92}%`;
+      return bar;
+    });
+    paintProgress(state.currentTime, false);
+  };
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => {
+    if (!scope.disposed && barCount(peakValues()) !== barNodes.length) renderPeaks();
+  })).observe(bars);
+  const update = (next: Partial<WaveformPlayerOptions>) => {
+    if (scope.disposed) return;
+    const previousPeaks = opts.peaks;
+    opts = { ...opts, ...next };
+    const nextSource = typeof opts.src === 'string' ? opts.src : '';
+    if (source !== nextSource) {
+      request++;
+      pending = null;
+      requested = false;
+      audio.pause();
+      source = nextSource;
+      if (source) audio.setAttribute('src', source);
+      else audio.removeAttribute('src');
+      // load() aborts the previous resource and any in-flight play request.
+      audio.load();
+      audio.playbackRate = state.playbackRate;
+      emit({ ...initialState(), playbackRate: state.playbackRate, status: source ? 'loading' : 'idle' });
+    }
+    if (opts.disabled && (requested || state.status === 'playing')) pause();
+    if (previousPeaks !== opts.peaks || !barNodes.length) renderPeaks();
+    paint();
+  };
+  scope.on(toggle, 'click', () => { bounce(toggle); if (requested || state.status === 'playing') pause(); else void play(); });
+  scope.on(range, 'input', () => seek(Number(range.value)));
+  scope.on(range, 'pointermove', event => {
+    if (!state.duration || opts.disabled) return;
+    const rect = range.getBoundingClientRect();
+    if (!rect.width) return;
+    // The native thumb spans both insets, as in the equalizer, so its value maps inside them.
+    const inset = parseFloat(getComputedStyle(track).getPropertyValue('--mk-wave-inset')) || 0;
+    const ratio = Math.max(0, Math.min(1, ((event as PointerEvent).clientX - rect.left - inset) / Math.max(1, rect.width - inset * 2)));
+    showPreview(state.duration * ratio, ratio);
+  });
+  scope.on(range, 'pointerleave', () => { if (document.activeElement !== range) preview.hidden = true; });
+  scope.on(range, 'focus', () => { if (state.duration) showPreview(state.currentTime, state.currentTime / state.duration); });
+  scope.on(range, 'blur', () => { preview.hidden = true; });
+  scope.on(range, 'pointerdown', () => {
+    if (range.disabled) return;
+    root.setAttribute('data-mk-wave-scrubbing', ''); keep(press(head));
+  });
+  const release = () => {
+    if (!scrubbing()) return;
+    root.removeAttribute('data-mk-wave-scrubbing');
+    if (!reduced()) keep(gsap.fromTo(head, { scale: 1.12 }, { scale: 1, duration: .4, ease: EASE.swatch, overwrite: 'auto', clearProps: 'transform' }));
+  };
+  scope.on(window, 'pointerup', release);
+  scope.on(window, 'pointercancel', release);
+  scope.on(rate, 'click', () => {
+    const available = rates();
+    const index = available.indexOf(state.playbackRate);
+    const next = available[(index + 1) % available.length];
+    if (next === undefined) return;
+    audio.playbackRate = next;
+    emit({ playbackRate: next });
+    bounce(rate);
+  });
+  const metadata = () => {
+    const duration = finite(audio.duration) ? audio.duration : 0;
+    emit({ duration, currentTime: duration ? Math.min(duration, Math.max(0, audio.currentTime || 0)) : 0,
+      ...(state.status === 'loading' && !requested ? { status: 'ready' as const } : {}) });
+  };
+  scope.on(audio, 'loadedmetadata', metadata);
+  scope.on(audio, 'durationchange', metadata);
+  scope.on(audio, 'timeupdate', () => emit({ currentTime: finite(audio.currentTime) ? audio.currentTime : 0 }, 'timeupdate'));
+  scope.on(audio, 'playing', () => {
+    if (!source || opts.disabled || !requested && state.status !== 'playing') { audio.pause(); return; }
+    requested = false;
+    if (state.status !== 'playing') emit({ status: 'playing', error: null }, 'play');
+  });
+  scope.on(audio, 'pause', () => {
+    if (state.status === 'playing' || requested) { requested = false; emit({ status: 'paused' }, 'pause'); }
+  });
+  scope.on(audio, 'waiting', () => { if (state.status === 'playing') { requested = true; emit({ status: 'loading' }); } });
+  scope.on(audio, 'ended', () => { request++; pending = null; requested = false; emit({ status: 'ended', currentTime: state.duration || state.currentTime }, 'ended'); });
+  scope.on(audio, 'error', () => { request++; pending = null; fail('No se pudo cargar el audio. Comprueba el archivo.'); });
+  scope.on(audio, 'ratechange', () => { if (audio.playbackRate !== state.playbackRate) emit({ playbackRate: audio.playbackRate }); });
+  scope.add(() => {
+    request++;
+    requested = false;
+    pending = null;
+    iconMotion?.kill();
+    for (const effect of effects) effect.kill();
+    gsap.ticker.remove(followPlayback);
+    audio.pause();
+    audio.removeAttribute('src');
+    audio.load();
+  });
+  update(options);
+  return { play, pause, seek, update, get state() { return snapshot(); }, get audio() { return scope.disposed ? null : audio; }, destroy: () => scope.dispose() };
+}

package/src/components/waveform-player/react.tsx

@@ -0,0 +1,27 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createWaveformPlayer, type WaveformPlayerInstance, type WaveformPlayerOptions } from './engine';
+
+export interface WaveformPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPlay' | 'onPause' | 'onEnded' | 'onError' | 'onTimeUpdate' | 'children' | 'dangerouslySetInnerHTML'>, WaveformPlayerOptions {
+  instanceRef?: MutableRefObject<WaveformPlayerInstance | null>;
+}
+export function WaveformPlayer({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError, instanceRef, className, ...props }: WaveformPlayerProps) {
+  // The engine owns descendants. Also filter runtime JS props that bypass the public type.
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<WaveformPlayerInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createWaveformPlayer(root.current);
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.update({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError });
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef]);
+  return <div {...rootProps} ref={root} className={['mk-waveform-player', className].filter(Boolean).join(' ')} />;
+}

package/src/components/waveform-player/waveform-player.css

@@ -0,0 +1,50 @@
+/* Shares the equalizer's vocabulary: tonal track, pill bars, a cut-out head that grows when held. */
+.mk-waveform-player, mk-waveform-player {
+  --mk-wave-color: var(--mk-text);
+  --mk-wave-track: var(--mk-outline-soft);
+  --mk-wave-surface: var(--mk-surface-2);
+  --mk-wave-inset: 14px;
+  display: block;
+  width: 100%;
+  min-width: 0;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+[data-mk-wave-content] { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: center; column-gap: .875rem; }
+[data-mk-wave-toggle] { display: grid; place-items: center; align-self: start; width: 3.5rem; height: 3.5rem; margin-top: .25rem; border: 0; border-radius: 50%; background: var(--mk-text); color: var(--mk-bg); cursor: pointer; transition: border-radius .4s var(--mk-ease-playful); }
+[data-mk-wave-toggle]:hover:enabled { border-radius: 22px; }
+[data-mk-wave-icon] { display: grid; place-items: center; width: 24px; height: 24px; }
+[data-mk-wave-state='playing'] [data-mk-wave-toggle] { border-radius: 20px; }
+[data-mk-wave-toggle] svg { width: 1.4rem; height: 1.4rem; fill: currentColor; stroke: currentColor; stroke-width: 2; stroke-linecap: round; }
+[data-mk-wave-body] { display: grid; gap: .5rem; min-width: 0; }
+[data-mk-wave-track] { position: relative; height: 4rem; min-width: 0; border-radius: 24px; background: var(--mk-wave-surface); }
+[data-mk-wave-bars] { position: absolute; inset: 12px var(--mk-wave-inset); display: flex; align-items: center; gap: 3px; pointer-events: none; }
+[data-mk-wave-bar] { display: block; flex: 1 1 0; min-width: 1px; min-height: 4px; border-radius: 64px; background: var(--mk-wave-track); transform-origin: center; transition: background-color .16s; }
+[data-mk-wave-bar][data-mk-played] { background: var(--mk-wave-color); }
+[data-mk-wave-head] { position: absolute; z-index: 2; top: 50%; left: calc(var(--mk-wave-inset) + (100% - 2 * var(--mk-wave-inset)) * var(--mk-wave-progress, 0)); box-sizing: content-box; width: 4px; height: calc(100% - 20px); border: 3px solid var(--mk-wave-surface); border-radius: 64px; background: var(--mk-wave-color); translate: -50% -50%; pointer-events: none; transition: height .35s var(--mk-ease-swatch), border-width .35s var(--mk-ease-swatch); }
+[data-mk-wave-scrubbing] [data-mk-wave-head] { height: calc(100% - 10px); border-width: 5px; }
+@media (hover: hover) { [data-mk-wave-track]:has(input:enabled:hover) [data-mk-wave-head] { height: calc(100% - 14px); } }
+[data-mk-wave-preview] { position: absolute; bottom: calc(100% + 10px); left: calc(var(--mk-wave-inset) + (100% - 2 * var(--mk-wave-inset)) * var(--mk-wave-at, 0)); z-index: 3; padding: .4rem .7rem; border-radius: 99px; background: var(--mk-glass-inverse); color: var(--mk-bg); backdrop-filter: blur(16px); box-shadow: inset 1px 1px 1px color-mix(in srgb, var(--mk-bg) 20%, transparent); font-size: .6875rem; font-variant-numeric: tabular-nums; translate: -50% 0; pointer-events: none; }
+[data-mk-wave-preview][hidden] { display: none; }
+[data-mk-wave-seek] { position: absolute; z-index: 4; inset: 0; box-sizing: border-box; width: 100%; height: 100%; margin: 0; appearance: none; -webkit-appearance: none; background: transparent; opacity: 0; cursor: ew-resize; }
+[data-mk-wave-seek]::-webkit-slider-thumb { appearance: none; -webkit-appearance: none; width: calc(2 * var(--mk-wave-inset)); height: 4rem; background: transparent; }
+[data-mk-wave-seek]::-moz-range-thumb { width: calc(2 * var(--mk-wave-inset)); height: 4rem; border: 0; background: transparent; }
+[data-mk-wave-track]:has(input:focus-visible) { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-wave-footer] { display: flex; justify-content: space-between; align-items: center; gap: .75rem; min-height: 2rem; }
+[data-mk-wave-time] { color: var(--mk-muted); font-size: .75rem; font-variant-numeric: tabular-nums; }
+[data-mk-wave-rate] { min-width: 44px; min-height: 36px; padding: .375rem .75rem; border: 0; border-radius: 64px; color: var(--mk-text); background: var(--mk-wave-surface); font: 600 .75rem var(--mk-font); font-variant-numeric: tabular-nums; cursor: pointer; transition: padding .35s var(--mk-ease-swatch), background .15s; }
+[data-mk-wave-rate]:hover:enabled { padding-inline: 1rem; background: color-mix(in srgb, var(--mk-text) 8%, var(--mk-wave-surface)); }
+[data-mk-wave-rate][hidden] { display: none; }
+[data-mk-wave-message] { grid-column: 2; color: var(--mk-muted); font-size: .75rem; line-height: 1.5; }
+[data-mk-wave-message]:empty { display: none; }
+[data-mk-wave-toggle]:focus-visible, [data-mk-wave-rate]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+[data-mk-wave-toggle]:disabled, [data-mk-wave-rate]:disabled { opacity: .5; cursor: default; }
+[data-mk-wave-track]:has(input:disabled) { opacity: .55; }
+[data-mk-wave-track]:has(input:disabled) [data-mk-wave-seek] { cursor: default; }
+[data-mk-wave-state='error'] [data-mk-wave-message] { color: var(--mk-error, var(--mk-text)); }
+@media (prefers-reduced-motion: reduce) { [data-mk-wave-bar], [data-mk-wave-toggle], [data-mk-wave-head], [data-mk-wave-rate] { transition: none; } }
+@media (forced-colors: active) {
+  [data-mk-wave-toggle], [data-mk-wave-rate] { border: 1px solid ButtonText; }
+  [data-mk-wave-bar] { background: GrayText; }
+  [data-mk-wave-bar][data-mk-played], [data-mk-wave-head] { background: Highlight; }
+}

package/src/components/wheel-picker/README.md

@@ -0,0 +1,35 @@
+# wheel-picker
+
+Selector de rueda con desplazamiento nativo e inercia en táctil, arrastre de ratón, ajuste al centro y navegación por teclado. El valor elegido queda en un input oculto para formularios.
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { WheelPicker } from '@yewdiel21/motion-kit/react';
+
+<WheelPicker label="Duración" name="duration" value={duration} onChange={setDuration}
+  items={[{ value: '15', label: '15 min' }, { value: '25', label: '25 min' }, { value: '45', label: '45 min' }]} />
+```
+
+En React, `defaultValue` inicializa el estado sin controlarlo; `instanceRef` permite llamar al motor. Los cambios de `items` y `value` se aplican sin sustituir el listbox.
+
+```html
+<mk-wheel-picker label="Duración" name="duration" value="25"
+  items='[{"value":"15","label":"15 min"},{"value":"25","label":"25 min"},{"value":"45","label":"45 min"}]'>
+</mk-wheel-picker>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-wheel-picker']);
+</script>
+```
+
+También puedes usar `createWheelPicker(root, options)` en vanilla. El CLI copia las fuentes con `npx @yewdiel21/motion-kit add wheel-picker --react --elements`.
+
+Opciones: `items` (strings o `{value,label,disabled?}`), `value`, `name`, `label`, `disabled`, `visibleItems` (impar de 3 a 9; 5 por defecto), `itemHeight` (44…96 px; 44 por defecto), `onInput(value)` durante el desplazamiento y `onChange(value)` al confirmar. Los valores duplicados se omiten y las etiquetas siempre se tratan como texto.
+
+La instancia expone `setValue(value, notify=false)`, `setItems(items, notify=false)`, `value` y `destroy()`. Eventos: `mk:input` y `mk:change` con `{value,item}`. Las actualizaciones por código son silenciosas por defecto.
+
+Flechas arriba/abajo omiten opciones deshabilitadas; Home/End van a los extremos y PageUp/PageDown saltan varias filas. Escribir busca una etiqueta por prefijo. El listbox tiene un solo foco y `aria-activedescendant`, las opciones exponen selección/estado deshabilitado y los cambios confirmados se anuncian. El reset de formulario recupera el valor inicial o una opción válida si cambió la lista. Sin opciones, el valor enviado es vacío.
+
+Las filas se proyectan sobre un cilindro cuyo radio es la mitad del marco: cerca de los bordes se comprimen, se estrechan y se desvanecen como en la rueda de iOS, y las que pasan de 90° se ocultan. `visibleItems` fija la altura del marco en filas planas; con la curvatura se ven una o dos filas más en los bordes. Las opciones deshabilitadas se muestran atenuadas.
+
+El movimiento reducido sustituye el cilindro por una lista plana y elimina los desplazamientos programados suaves. Se usan los tokens de superficie, acento, tipografía y forma del kit; `--mk-wheel-row` y `--mk-wheel-rows` reflejan el tamaño configurado. El componente cancela temporizadores y listeners y restaura el contenedor al destruirse.

package/src/components/wheel-picker/element.ts

@@ -0,0 +1,25 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createWheelPicker, type WheelPickerInstance, type WheelPickerEntry, type WheelPickerOptions } from './engine';
+
+export class MkWheelPickerElement extends MkElement<WheelPickerInstance> {
+  static options: Record<string, OptionType> = { items: 'json', value: 'string', name: 'string', label: 'string', disabled: 'boolean', visibleItems: 'number', itemHeight: 'number' };
+  private savedValue: string | undefined;
+  private savedItems: WheelPickerEntry[] | undefined;
+  protected create(options: Record<string, unknown>) { return createWheelPicker(this, { ...options, ...(this.savedItems ? { items: this.savedItems } : {}), value: this.savedValue ?? options.value } as WheelPickerOptions); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'items') this.savedItems = undefined;
+    if (!this.instance) { if (name === 'value') this.savedValue = next ?? undefined; return; }
+    if (name === 'value' && next !== null) { this.instance.setValue(next); return; }
+    if (name === 'items') { this.instance.setItems((this.options.items as WheelPickerEntry[]) ?? []); if (this.options.value !== undefined) this.instance.setValue(String(this.options.value)); return; }
+    this.savedValue = name === 'value' ? undefined : this.instance.value;
+    this.instance.destroy();
+    this.instance = this.create(this.options);
+  }
+  disconnectedCallback() { this.savedValue = this.instance?.value ?? this.savedValue; super.disconnectedCallback(); }
+  get value() { return this.instance?.value ?? ''; }
+  set value(next: string) { this.setAttribute('value', next); }
+  setValue(value: string, notify = false) { this.instance?.setValue(value, notify); }
+  setItems(items: WheelPickerEntry[], notify = false) { this.savedItems = items.map(item => typeof item === 'string' ? item : { ...item }); this.instance?.setItems(items, notify); }
+}
+export const defineWheelPicker = () => defineElement('mk-wheel-picker', MkWheelPickerElement);