@yewdiel21/motion-kit 0.16.0 → 0.18.0

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

@@ -0,0 +1,42 @@
+# TemperatureSlider
+
+Rango de temperatura con número rodante, pequeñas marcas y un tinte frío/cálido construido con los tokens del tema. La cifra, el relleno y el pulgar responden inmediatamente al arrastrar.
+
+```ts
+import { createTemperatureSlider } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/temperature-slider';
+
+const control = createTemperatureSlider(document.querySelector('.mk-temperature-slider'), {
+  value: 22, unit: 'C', label: 'Temperatura deseada', name: 'temperature', onInput: console.log,
+});
+control.setValue(24);
+```
+
+## Opciones y contrato
+
+`unit: C | F` (C), `min` (16 / 60), `max` (30 / 86), `step` (1), `value` / `defaultValue` (22 / 72), `label`, `name`, `disabled`, `error`, `formatValue`, `onInput(value)`, `onChange(value)`.
+
+unit determina el sufijo y los límites predeterminados. Cambiar el atributo o la opción `unit` al crear no convierte el número; `setUnit('F' | 'C', range?, notify?)` sí lo convierte en el mismo control: la cifra y los extremos ruedan y el pulgar se desliza sin desmontar nada. En React, cambiar la prop `unit` usa `setUnit`. Los cambios por código, presets y teclado deslizan el pulgar con la curva swatch del kit; al arrastrar sigue al puntero sin retraso. --mk-temperature-cool y --mk-temperature-hot permiten adaptar los dos extremos con colores semánticos del tema.
+
+La instancia expone `value: number`, `unit`, `setValue(value, notify = false)`, `setUnit(unit, range?, 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 { TemperatureSlider } from '@yewdiel21/motion-kit/react';
+
+<TemperatureSlider value={temperature} onInput={setTemperature} unit="C" name="temperature" />
+```
+
+`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-temperature-slider class="mk-temperature-slider" value="22" unit="C" label="Temperatura deseada" name="temperature"></mk-temperature-slider>
+```
+
+Registra con `defineTemperatureSlider()` 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/temperature-slider/element.ts

@@ -0,0 +1,53 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTemperatureSlider, type TemperatureSliderInstance, type TemperatureUnit } from './engine';
+
+/** Light DOM; attribute changes keep the current imperative value and reset baseline. */
+export class MkTemperatureSliderElement extends MkElement<TemperatureSliderInstance> {
+  static options: Record<string, OptionType> = {"min":"number","max":"number","step":"number","value":"number","label":"string","name":"string","disabled":"boolean","error":"string","unit":"string"};
+  private baseline: number | undefined;
+  private saved: number | undefined;
+  private syncing = false;
+  protected create(options: Record<string, unknown>) {
+    const created = createTemperatureSlider(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 || this.syncing) return;
+    if (name === 'value' && (!this.instance || !this.isConnected)) {
+      this.saved = next === null ? this.baseline ?? 22 : Number.isFinite(Number(next)) ? Number(next) : this.baseline ?? 22;
+      return;
+    }
+    if (!this.instance || !this.isConnected) return;
+    if (name === 'value') {
+      const parsed = next === null ? this.baseline ?? 22 : 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 ?? 22; }
+  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); }
+  get unit(): TemperatureUnit { return this.instance?.unit ?? (this.getAttribute('unit') === 'F' ? 'F' : 'C'); }
+  /** Converts in place and glides; the unit, min and max attributes follow without remounting. */
+  setUnit(unit: TemperatureUnit, notify = false) {
+    if (!this.instance) { this.setAttribute('unit', unit); return; }
+    this.instance.setUnit(unit, {}, notify);
+    this.syncing = true;
+    try {
+      this.setAttribute('unit', this.instance.unit);
+      for (const name of ['min', 'max']) this.removeAttribute(name);
+    } finally { this.syncing = false; }
+  }
+  
+}
+export const defineTemperatureSlider = () => defineElement('mk-temperature-slider', MkTemperatureSliderElement);
+

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

@@ -0,0 +1,44 @@
+import { createNumericRange, type NumericOptions, type NumericInstance } from '../equalizer-slider/shared';
+
+export type TemperatureUnit = 'C' | 'F';
+export interface TemperatureSliderOptions extends NumericOptions { unit?: TemperatureUnit }
+export interface TemperatureSliderInstance extends NumericInstance {
+  readonly unit: TemperatureUnit;
+  /** Converts the value into `unit` and glides to it. `min`/`max` default to the unit's comfort range. */
+  setUnit(unit: TemperatureUnit, range?: { min?: number; max?: number; step?: number }, notify?: boolean): void;
+}
+const RANGE = { C: { min: 16, max: 30, value: 22 }, F: { min: 60, max: 86, value: 72 } } as const;
+const convert = (value: number, from: TemperatureUnit, to: TemperatureUnit) => from === to ? value : to === 'F' ? value * 9 / 5 + 32 : (value - 32) * 5 / 9;
+
+export function createTemperatureSlider(root: HTMLElement | null, options: TemperatureSliderOptions = {}): TemperatureSliderInstance {
+  let unit: TemperatureUnit = options.unit === 'F' ? 'F' : 'C';
+  const formatFor = (next: TemperatureUnit) => (n: number) => `${n}°${next}`;
+  const range = createNumericRange(root, options, {
+    prefix: 'temperature', label: 'Temperatura', ...RANGE[unit],
+    format: formatFor(unit),
+    decorate({ track, thumb }) {
+      const rail = document.createElement('span'); rail.dataset.mkTemperatureRail = ''; rail.setAttribute('aria-hidden', 'true'); track.prepend(rail);
+      const fill = document.createElement('span'); fill.dataset.mkTemperatureFill = ''; rail.append(fill);
+      const ticks = document.createElement('span'); ticks.dataset.mkTemperatureTicks = ''; ticks.setAttribute('aria-hidden', 'true');
+      for (let i = 0; i <= 14; i++) ticks.append(document.createElement('i'));
+      track.prepend(ticks); thumb.textContent = '··';
+      return (ratio) => {
+        root?.style.setProperty('--mk-temperature-warm', `${Math.round(ratio * 100)}%`);
+        fill.style.width = `${ratio * 100}%`;
+      };
+    },
+  });
+  return {
+    get value() { return range.value; },
+    get unit() { return unit; },
+    setValue: range.setValue,
+    reset: range.reset,
+    setUnit(next, limits = {}, notify = false) {
+      const target: TemperatureUnit = next === 'F' ? 'F' : 'C';
+      const value = Math.round(convert(range.value, unit, target));
+      unit = target;
+      range.configure({ min: limits.min ?? RANGE[target].min, max: limits.max ?? RANGE[target].max, step: limits.step, format: options.formatValue ?? formatFor(target), value }, notify);
+    },
+    destroy: range.destroy,
+  };
+}

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

@@ -0,0 +1,66 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTemperatureSlider, type TemperatureSliderOptions, type TemperatureSliderInstance } from './engine';
+
+export interface TemperatureSliderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue' | 'children' | 'dangerouslySetInnerHTML'>, Omit<TemperatureSliderOptions, 'value' | 'defaultValue'> {
+  value?: number;
+  defaultValue?: number;
+  instanceRef?: MutableRefObject<TemperatureSliderInstance | null>;
+  /** The engine owns this component's DOM. */
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function TemperatureSlider({ value, defaultValue, min, max, step, label, name, disabled, error, formatValue, unit, onChange, onInput, instanceRef, className, children: _children, dangerouslySetInnerHTML: _html, ...props }: TemperatureSliderProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const engine = useRef<TemperatureSliderInstance | 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 = createTemperatureSlider(root.current, {
+      min, max, step, label, name, disabled, error, formatValue, unit, 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]);
+  // A unit change converts and glides in place instead of remounting the slider.
+  useIsomorphicLayoutEffect(() => {
+    const next = unit === 'F' ? 'F' : 'C';
+    if (engine.current && engine.current.unit !== next) engine.current.setUnit(next, { min, max, step });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [unit]);
+  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]);
+  return <div {...props} ref={root} className={['mk-temperature-slider', className].filter(Boolean).join(' ')} />;
+}
+

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

@@ -0,0 +1,29 @@
+:is(.mk-temperature-slider, mk-temperature-slider) { display: block; width: 100%; min-width: 0; color: var(--mk-text); font: 500 .875rem/1.4 var(--mk-font); }
+[data-mk-temperature-body] { display: grid; gap: .875rem; }
+[data-mk-temperature-header] { display: flex; justify-content: space-between; align-items: center; gap: 1rem; }
+[data-mk-temperature-output] { font-variant-numeric: tabular-nums; white-space: nowrap; }
+[data-mk-temperature-track] { position: relative; height: 76px; min-width: 0; border-radius: 24px; background: var(--mk-surface-2); }
+[data-mk-temperature-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-temperature-input]::-webkit-slider-thumb { appearance: none; -webkit-appearance: none; width: 32px; height: 76px; background: transparent; }
+[data-mk-temperature-input]::-moz-range-thumb { width: 32px; height: 76px; border: 0; background: transparent; }
+[data-mk-temperature-thumb] { position: absolute; z-index: 2; top: 50%; left: calc(16px + (100% - 32px) * var(--mk-temperature-ratio, .5)); translate: -50% -50%; pointer-events: none; }
+[data-mk-temperature-track]:has(:focus-visible) { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-temperature-ends] { display: flex; justify-content: space-between; margin-top: -.375rem; color: var(--mk-muted); font-size: .75rem; font-variant-numeric: tabular-nums; }
+[data-mk-temperature-message] { color: var(--mk-error); font-size: .8125rem; font-weight: 400; }
+[data-mk-temperature-message]:empty { display: none; }
+:is(.mk-temperature-slider, mk-temperature-slider)[data-mk-disabled] { opacity: .4; }
+:is(.mk-temperature-slider, mk-temperature-slider)[data-mk-disabled] [data-mk-temperature-input] { cursor: not-allowed; }
+:is(.mk-temperature-slider, mk-temperature-slider)[data-mk-error] [data-mk-temperature-track] { outline: 1px solid var(--mk-error); }
+:is(.mk-temperature-slider, mk-temperature-slider) { --mk-temperature-cool: var(--mk-accent); --mk-temperature-hot: var(--md-sys-color-tertiary, var(--mk-text)); --mk-temperature-tint: color-mix(in srgb, var(--mk-temperature-cool), var(--mk-temperature-hot) var(--mk-temperature-warm, 50%)); }
+[data-mk-temperature-output] { font-size: clamp(2rem, 6vw, 2.75rem); font-weight: 500; letter-spacing: -.06em; line-height: 1.2; }
+[data-mk-temperature-track] { height: 64px; background: color-mix(in srgb, var(--mk-temperature-tint) 5%, var(--mk-surface-2)); }
+[data-mk-temperature-rail] { position: absolute; inset: 28px 16px; border-radius: 64px; background: var(--mk-outline-soft); overflow: hidden; }
+[data-mk-temperature-fill] { display: block; height: 100%; border-radius: inherit; background: color-mix(in srgb, var(--mk-temperature-tint) 42%, var(--mk-text)); }
+[data-mk-temperature-ticks] { position: absolute; inset: 0 16px; display: flex; justify-content: space-between; align-items: center; pointer-events: none; }
+[data-mk-temperature-ticks] > i { width: 1px; height: 18px; background: var(--mk-outline-soft); }
+[data-mk-temperature-thumb] { display: grid; place-items: center; width: 30px; height: 40px; border-radius: 12px; background: var(--mk-text); color: var(--mk-bg); font: 700 18px/1 var(--mk-font); box-shadow: 0 0 0 4px var(--mk-surface-2); transition: width .35s var(--mk-ease-swatch), border-radius .35s var(--mk-ease-swatch); }
+:is(.mk-temperature-slider, mk-temperature-slider)[data-mk-held] [data-mk-temperature-thumb] { width: 38px; border-radius: 16px; }
+@media (hover: hover) { [data-mk-temperature-track]:has(:not(:disabled):hover) [data-mk-temperature-thumb] { border-radius: 16px; width: 34px; } }
+@media (prefers-reduced-motion: reduce) { [data-mk-temperature-thumb] { transition: none; } }
+@media (forced-colors: active) { [data-mk-temperature-rail] { background: GrayText; } [data-mk-temperature-fill], [data-mk-temperature-thumb] { background: Highlight; } }
+

package/src/components/voice-message-bubble/README.md

@@ -0,0 +1,31 @@
+# Voice Message Bubble
+
+Burbuja entrante/saliente con autor, hora y estado de entrega. Compone el reproductor real [Waveform Player](../waveform-player/README.md); no graba, no solicita micrófono y no inicia audio automáticamente.
+
+```tsx
+import { VoiceMessageBubble } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css/components/waveform-player';
+import '@yewdiel21/motion-kit/css/components/voice-message-bubble';
+
+<VoiceMessageBubble src="/mensaje.wav" peaks={[.2, .6, .9, .4]} author="Ana"
+  timestamp="10:42" direction="incoming" />
+<VoiceMessageBubble src="/respuesta.wav" peaks={peaks} author="Tú"
+  timestamp="10:43" direction="outgoing" status="read" />
+```
+
+```html
+<mk-voice-message-bubble src="/mensaje.wav" peaks="[0.2,0.6,0.9,0.4]"
+  author="Ana" timestamp="10:42" direction="incoming"></mk-voice-message-bubble>
+<script type="module">
+  import { defineVoiceMessageBubble } from '@yewdiel21/motion-kit/elements';
+  defineVoiceMessageBubble();
+</script>
+```
+
+`createVoiceMessageBubble(root, options)` acepta todas las opciones del reproductor y añade `direction` (`incoming` por defecto u `outgoing`), `author`, `timestamp` (texto visible), `dateTime` (fecha legible por máquinas, opcional) y `status` (`sending`, `sent`, `delivered`, `read`, `failed`). El estado de entrega lo controla tu aplicación; no implica envío de mensajes. Autor/hora/estado vacíos se ocultan. El nombre accesible del reproductor incluye el autor, o usa `label` si lo especificas.
+
+La instancia ofrece `play(): Promise<boolean>`, `pause()`, `seek(seconds)`, `update(partialOptions)`, `state`, `audio`, `destroy()`. `VoiceMessageBubble` admite `instanceRef`. `MkVoiceMessageBubbleElement` expone los mismos métodos y actualiza atributos sin recrear el audio. `peaks` y `playback-rates` son JSON; el atributo de fecha es `date-time`. Los cambios de autor, dirección y hora conservan la reproducción. Eventos `mk:audio-*` del reproductor burbujean desde la burbuja.
+
+Necesita **waveform-player.css y voice-message-bubble.css**. El motor también depende de `waveform-player/engine.ts`; copiar la receta debe incluir esa dependencia. Usa los tokens del tema y respeta movimiento reducido a través del reproductor. Los picos se suministran de antemano; no realiza análisis automático de audio. Agrega una transcripción cerca del mensaje para contenido hablado. Los demos usan un sonido sintetizado original local de seis segundos, sin voz humana.
+
+Tipos: `VoiceMessageBubbleOptions`, `VoiceMessageBubbleInstance`, `VoiceMessageStatus`, `VoiceMessageBubbleProps`.

package/src/components/voice-message-bubble/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createVoiceMessageBubble, type VoiceMessageBubbleInstance, type VoiceMessageBubbleOptions } from './engine';
+
+export class MkVoiceMessageBubbleElement extends MkElement<VoiceMessageBubbleInstance> {
+  static options: Record<string, OptionType> = { src: 'string', peaks: 'json', label: 'string', disabled: 'boolean', playbackRates: 'json', direction: 'string', author: 'string', timestamp: 'string', dateTime: 'string', status: 'string' };
+  protected create(options: Record<string, unknown>) { return createVoiceMessageBubble(this, options as VoiceMessageBubbleOptions); }
+  play() { return this.instance?.play() ?? Promise.resolve(false); }
+  pause() { this.instance?.pause(); }
+  seek(seconds: number) { this.instance?.seek(seconds); }
+  update(options: Partial<VoiceMessageBubbleOptions>) { this.instance?.update(options); }
+  get state() { return this.instance?.state; }
+  get audio() { return this.instance?.audio ?? null; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    if (!Object.hasOwn(MkVoiceMessageBubbleElement.options, option)) return;
+    this.instance.update({ [option]: this.options[option] });
+  }
+}
+export const defineVoiceMessageBubble = () => defineElement('mk-voice-message-bubble', MkVoiceMessageBubbleElement);

package/src/components/voice-message-bubble/engine.ts

@@ -0,0 +1,79 @@
+import { createScope } from '../../core/scope';
+import type { WaveformPlayerInstance, WaveformPlayerOptions } from '../waveform-player/engine';
+import { createWaveformPlayer } from '../waveform-player/engine';
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+
+export type VoiceMessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+export interface VoiceMessageBubbleOptions extends WaveformPlayerOptions {
+  direction?: 'incoming' | 'outgoing';
+  author?: string;
+  timestamp?: string;
+  /** Optional machine-readable timestamp for the time element. */
+  dateTime?: string;
+  status?: VoiceMessageStatus;
+}
+export interface VoiceMessageBubbleInstance extends WaveformPlayerInstance {
+  update(options: Partial<VoiceMessageBubbleOptions>): void;
+}
+
+const statusLabels: Record<VoiceMessageStatus, string> = { sending: 'Enviando', sent: 'Enviado', delivered: 'Entregado', read: 'Leído', failed: 'No enviado' };
+
+/** A message presentation around the real waveform audio player. Never records audio. */
+export function createVoiceMessageBubble(root: HTMLElement | null, options: VoiceMessageBubbleOptions = {}): VoiceMessageBubbleInstance {
+  if (!root) return createWaveformPlayer(null, options);
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  const content = document.createElement('div');
+  content.setAttribute('data-mk-voice-message-content', '');
+  const header = document.createElement('div');
+  header.setAttribute('data-mk-voice-message-header', '');
+  const author = document.createElement('span');
+  author.setAttribute('data-mk-voice-message-author', '');
+  const caption = document.createElement('span');
+  caption.setAttribute('data-mk-voice-message-caption', '');
+  caption.textContent = 'Mensaje de voz';
+  header.append(author, caption);
+  const playerRoot = document.createElement('div');
+  playerRoot.className = 'mk-waveform-player';
+  const footer = document.createElement('div');
+  footer.setAttribute('data-mk-voice-message-footer', '');
+  const timestamp = document.createElement('time');
+  const status = document.createElement('span');
+  status.setAttribute('data-mk-voice-message-status', '');
+  footer.append(timestamp, status);
+  content.append(header, playerRoot, footer);
+  root.append(content);
+  scope.add(() => content.remove());
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-direction', 'incoming');
+  const player = createWaveformPlayer(playerRoot);
+  scope.add(() => player.destroy());
+  const update = (next: Partial<VoiceMessageBubbleOptions>) => {
+    if (scope.disposed) return;
+    opts = { ...opts, ...next };
+    author.textContent = opts.author ?? '';
+    author.hidden = !opts.author;
+    timestamp.textContent = opts.timestamp ?? '';
+    timestamp.hidden = !opts.timestamp;
+    if (opts.dateTime) timestamp.dateTime = opts.dateTime;
+    else timestamp.removeAttribute('datetime');
+    status.textContent = opts.status && statusLabels[opts.status] || '';
+    status.hidden = !status.textContent;
+    root.setAttribute('data-mk-direction', opts.direction === 'outgoing' ? 'outgoing' : 'incoming');
+    const { direction: _direction, author: _author, timestamp: _timestamp, dateTime: _dateTime, status: _status, ...audio } = opts;
+    player.update({ ...audio, label: opts.label ?? (opts.author ? `mensaje de voz de ${opts.author}` : 'mensaje de voz') });
+  };
+  update(options);
+  // The message grows from its conversational edge, matching the shared chat
+  // vocabulary. Its real controls remain available throughout the entrance.
+  let entrance: gsap.core.Tween | null = null;
+  if (!reduced()) {
+    content.style.transformOrigin = opts.direction === 'outgoing' ? 'right bottom' : 'left bottom';
+    entrance = gsap.fromTo(content, { scale: .88, opacity: 0, filter: 'blur(12px)', y: 10 }, { scale: 1, opacity: 1, filter: 'blur(0px)', y: 0, duration: .65, ease: EASE.signature, clearProps: 'transform,opacity,filter' });
+  }
+  scope.add(() => entrance?.kill());
+  return { play: () => player.play(), pause: () => player.pause(), seek: n => player.seek(n), update,
+    get state() { return player.state; }, get audio() { return player.audio; }, destroy: () => scope.dispose() };
+}

package/src/components/voice-message-bubble/react.tsx

@@ -0,0 +1,27 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createVoiceMessageBubble, type VoiceMessageBubbleInstance, type VoiceMessageBubbleOptions } from './engine';
+
+export interface VoiceMessageBubbleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPlay' | 'onPause' | 'onEnded' | 'onError' | 'onTimeUpdate' | 'children' | 'dangerouslySetInnerHTML'>, VoiceMessageBubbleOptions {
+  instanceRef?: MutableRefObject<VoiceMessageBubbleInstance | null>;
+}
+export function VoiceMessageBubble({ src, peaks, label, disabled, playbackRates, onStateChange, onTimeUpdate, onPlay, onPause, onEnded, onError, direction, author, timestamp, dateTime, status, instanceRef, className, ...props }: VoiceMessageBubbleProps) {
+  // React must never reconcile descendants owned by the composed player engine.
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<VoiceMessageBubbleInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createVoiceMessageBubble(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, direction, author, timestamp, dateTime, status });
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef]);
+  return <div {...rootProps} ref={root} className={['mk-voice-message-bubble', className].filter(Boolean).join(' ')} />;
+}

package/src/components/voice-message-bubble/voice-message-bubble.css

@@ -0,0 +1,14 @@
+/* Requires waveform-player.css; the bubble composes its player without duplicating it. */
+.mk-voice-message-bubble, mk-voice-message-bubble { display: block; width: min(100%, 25rem); color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-voice-message-content] { display: grid; gap: .5rem; padding: 1rem 1.25rem .75rem; background: var(--mk-surface-2); border: 0; border-radius: 32px 32px 32px 12px; }
+:is(.mk-voice-message-bubble, mk-voice-message-bubble)[data-mk-direction='outgoing'] { margin-inline-start: auto; }
+:is(.mk-voice-message-bubble, mk-voice-message-bubble)[data-mk-direction='outgoing'] [data-mk-voice-message-content] { background: var(--mk-surface-3); border-radius: 32px 32px 12px 32px; }
+[data-mk-voice-message-header], [data-mk-voice-message-footer] { display: flex; flex-wrap: wrap; align-items: center; gap: .375rem .75rem; font-size: .6875rem; color: var(--mk-muted); }
+[data-mk-voice-message-author] { font-weight: 600; color: var(--mk-text); }
+[data-mk-voice-message-caption] { margin-inline-start: auto; }
+[data-mk-voice-message-footer] { justify-content: flex-end; }
+[data-mk-voice-message-status] { color: var(--mk-accent); }
+/* The track steps one tonal level above its bubble, like the equalizer above the page. */
+[data-mk-voice-message-content] .mk-waveform-player { --mk-wave-surface: var(--mk-surface-3); }
+:is(.mk-voice-message-bubble, mk-voice-message-bubble)[data-mk-direction='outgoing'] .mk-waveform-player { --mk-wave-surface: var(--mk-surface-4); }
+@media (forced-colors: active) { [data-mk-voice-message-content] { border-color: CanvasText; } }

package/src/components/waveform-player/README.md

@@ -0,0 +1,30 @@
+# Waveform Player
+
+Reproductor real de `HTMLAudioElement` con onda de barras redondeadas, botón reproducir/pausar, posición nativa accesible, tiempo actual/duración y velocidad opcional. No inicia solo ni solicita el micrófono.
+
+```tsx
+import { WaveformPlayer } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css/components/waveform-player';
+
+<WaveformPlayer src="/audio/mensaje.wav" peaks={[.2, .5, .9, .4]} label="mensaje de Ana" />
+```
+
+```html
+<mk-waveform-player src="/audio/mensaje.wav" peaks="[0.2,0.5,0.9,0.4]" label="mensaje de Ana"></mk-waveform-player>
+<script type="module">
+  import { defineWaveformPlayer } from '@yewdiel21/motion-kit/elements';
+  defineWaveformPlayer();
+</script>
+```
+
+Los picos son amplitudes normalizadas **suministradas por la aplicación**, por ejemplo desde el servidor o un proceso previo. El componente no descarga ni analiza el archivo para calcularlos. Acota amplitudes a 0…1 y muestra las primeras 256 barras; sin picos muestra barras neutras iguales. El progreso y la duración sí proceden del audio real. Usa un archivo o una URL compatible con el navegador.
+
+`createWaveformPlayer(root, options)` devuelve `play(): Promise<boolean>`, `pause()`, `seek(seconds)`, `update(partialOptions)`, `state`, `audio` y `destroy()`. `play` resuelve `false` cuando falla, se cancela o falta una fuente; los rechazos del navegador se capturan y se muestran en el estado. `seek` se acota a la duración; antes de metadatos o con duración infinita no hace nada. `audio` es el elemento real y pasa a `null` tras destruir. `state` es una copia: `{ status, currentTime, duration, playbackRate, error }`. El estado puede ser `idle`, `loading`, `ready`, `playing`, `paused`, `ended` o `error`; el siguiente play tras finalizar vuelve al inicio.
+
+Opciones: `src`, `peaks`, `label` (nombre accesible), `disabled`, `playbackRates` (por defecto `[1, 1.5, 2]`, `false` oculta el control; tasas válidas 0.25…4), `onStateChange`, `onTimeUpdate`, `onPlay`, `onPause`, `onEnded`, `onError`. Los callbacks reciben una copia del estado. `onStateChange` informa transiciones de estado; `onTimeUpdate` informa reproducción/búsqueda. Eventos DOM burbujeantes: `mk:audio-statechange`, `mk:audio-play`, `mk:audio-pause`, `mk:audio-ended`, `mk:audio-error`, `mk:audio-timeupdate`, con el estado en `detail`.
+
+React admite `instanceRef` y actualiza las opciones/callbacks sin recrear el audio. El custom element expone los mismos métodos, `state`, `audio` y `instance`; los atributos son reactivos (`playback-rates` y `peaks` son JSON). Cambiar solamente picos, etiquetas o callbacks conserva fuente, tiempo y reproducción. Cambiar `src` pausa, cancela solicitudes y reinicia tiempo/duración. `destroy()` detiene el audio, vacía la fuente, retira listeners/animaciones y conserva el DOM ajeno.
+
+El slider nativo conserva teclado (flechas, Home/End), toque y semántica accesible; su nombre incluye `label` y su valor se anuncia como tiempo. Carga, errores y finalización usan un estado discreto; los tiempos no se anuncian continuamente. El pequeño resorte GSAP del botón se omite con movimiento reducido. Comparte el lenguaje del equalizer: pista tonal, barras en píldora remuestreadas al ancho (media de los picos suministrados, sin inventar datos), cabezal recortado que crece al pasar el puntero y al arrastrar, y barras que rebotan al cruzar el cabezal. Tokens locales: `--mk-wave-color` (reproducido y cabezal, texto por defecto), `--mk-wave-track` (pendiente), `--mk-wave-surface` (pista); el resto usa los colores, tipografía y superficies del tema.
+
+Tipos: `WaveformPlayerOptions`, `WaveformPlayerInstance`, `WaveformPlayerState`, `WaveformPlayerStatus`, `WaveformPlayerProps`. El componente reproduce contenido provisto por la aplicación: agrega una transcripción cerca del reproductor cuando el audio contenga información hablada.

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

@@ -0,0 +1,21 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createWaveformPlayer, type WaveformPlayerInstance, type WaveformPlayerOptions } from './engine';
+
+export class MkWaveformPlayerElement extends MkElement<WaveformPlayerInstance> {
+  static options: Record<string, OptionType> = { src: 'string', peaks: 'json', label: 'string', disabled: 'boolean', playbackRates: 'json' };
+  protected create(options: Record<string, unknown>) { return createWaveformPlayer(this, options as WaveformPlayerOptions); }
+  play() { return this.instance?.play() ?? Promise.resolve(false); }
+  pause() { this.instance?.pause(); }
+  seek(seconds: number) { this.instance?.seek(seconds); }
+  update(options: Partial<WaveformPlayerOptions>) { this.instance?.update(options); }
+  get state() { return this.instance?.state; }
+  get audio() { return this.instance?.audio ?? null; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    if (!Object.hasOwn(MkWaveformPlayerElement.options, option)) return;
+    // Undefined resets only the removed option; imperative values for other options survive.
+    this.instance.update({ [option]: this.options[option] });
+  }
+}
+export const defineWaveformPlayer = () => defineElement('mk-waveform-player', MkWaveformPlayerElement);