@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/tooltip/engine.ts

@@ -0,0 +1,288 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { requestFrame } from '../../core/frame';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { originOf, place, type Placement } from '../../core/position';
+
+/*
+ * Tooltip: a short description beside its trigger, shown when the pointer
+ * rests on it (400 ms), when keyboard focus reaches it (at once) or on a long
+ * press (500 ms, touch). It takes the preferred side, flips when that side has
+ * no room, stays inside the viewport and points an arrow at the trigger's
+ * centre; it lives in the top layer (popover API) so no overflow clips it.
+ * Motion (Melon Mind): it pops from the arrow (scale .85, 4 px toward the
+ * trigger, blur 4 → 0, .22 s, pop curve) and fades out in .12 s; moving to
+ * another tooltip within .4 s shows it at once with a plain fade (warm), and
+ * new text cross-fades. Escape hides it (WCAG 1.4.13); with `interactive` the
+ * pointer can move onto it. The trigger is described by it (aria-describedby).
+ */
+
+export interface TooltipOptions {
+  /** Text of the bubble (default: the trigger's title, which is removed so the browser's own does not show). */
+  content?: string;
+  /** Preferred side (default 'top'); 'auto' takes the roomiest. */
+  placement?: Placement;
+  /** Hover delay in ms (default 400). Focus shows it at once. */
+  openDelay?: number;
+  /** Delay before hiding when the pointer leaves, in ms (default 100). */
+  closeDelay?: number;
+  /** The pointer can move onto the bubble (links, selectable text). */
+  interactive?: boolean;
+  /** Arrow pointing at the trigger (default true). */
+  arrow?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface TooltipInstance extends Instance {
+  open(): void;
+  close(): void;
+  /** New text; an open tooltip cross-fades to it. Empty text hides it. */
+  setContent(text: string): void;
+  readonly isOpen: boolean;
+}
+
+const FOCUSABLE = 'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
+/** A tooltip shown within this long after another one hid skips the delay and the pop. */
+const WARM = 400;
+let sequence = 0;
+let current: { hide(instant: boolean): void } | null = null;
+let lastHidden = -Infinity;
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+export function createTooltip(root: HTMLElement | null, options: TooltipOptions = {}): TooltipInstance {
+  if (!root) return inert({ open() {}, close() {}, setContent() {}, isOpen: false });
+  registerMotion();
+  const scope = createScope();
+  const trigger = root.querySelector<HTMLElement>('[data-mk-tooltip-trigger]') ?? (root.matches(FOCUSABLE) ? root : root.querySelector<HTMLElement>(FOCUSABLE)) ?? root;
+  const title = trigger.getAttribute('title');
+  if (title !== null) scope.attr(trigger, 'title', null);
+  let text = options.content ?? title ?? '';
+  // Keyboard users must be able to reach what the tooltip describes.
+  if (!trigger.matches(FOCUSABLE)) scope.attr(trigger, 'tabindex', '0');
+  const openDelay = Number.isFinite(options.openDelay) ? Math.max(0, options.openDelay!) : 400;
+  const closeDelay = Number.isFinite(options.closeDelay) ? Math.max(0, options.closeDelay!) : 100;
+  const placement = options.placement ?? 'top';
+  const withArrow = options.arrow !== false;
+
+  const bubble = document.createElement('div');
+  bubble.dataset.mkTooltipBubble = '';
+  bubble.setAttribute('role', 'tooltip');
+  bubble.id = `mk-tooltip-${++sequence}`;
+  if (options.interactive) bubble.dataset.mkInteractive = '';
+  const label = document.createElement('span');
+  label.dataset.mkTooltipText = '';
+  label.textContent = text;
+  bubble.append(label);
+  if (withArrow) {
+    const arrow = document.createElement('span');
+    arrow.dataset.mkTooltipArrow = '';
+    arrow.setAttribute('aria-hidden', 'true');
+    bubble.append(arrow);
+  }
+  // The top layer (popover API) escapes every overflow; without it the bubble hangs from <body>.
+  const topLayer = typeof bubble.showPopover === 'function';
+  if (topLayer) {
+    bubble.setAttribute('popover', 'manual');
+    root.append(bubble);
+  } else {
+    bubble.hidden = true;
+    document.body.append(bubble);
+  }
+  scope.add(() => bubble.remove());
+  scope.attr(trigger, 'aria-describedby', [trigger.getAttribute('aria-describedby'), bubble.id].filter(Boolean).join(' '));
+  scope.attr(root, 'data-mk-open', null);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  let motion: gsap.core.Animation | null = null;
+  scope.add(() => {
+    motion?.kill();
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  let isOpen = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = () => {
+    clearTimeout(timer);
+    timer = undefined;
+  };
+  const later = (fn: () => void, ms: number) => {
+    cancel();
+    timer = setTimeout(fn, ms);
+  };
+  scope.add(cancel);
+
+  const shown = () => (topLayer ? bubble.matches(':popover-open') : !bubble.hidden);
+  const reveal = () => {
+    if (shown()) return;
+    if (topLayer) bubble.showPopover();
+    else bubble.hidden = false;
+  };
+  const conceal = () => {
+    if (!shown()) return;
+    if (topLayer) bubble.hidePopover();
+    else bubble.hidden = true;
+  };
+
+  const position = () => {
+    const anchor = trigger.getBoundingClientRect();
+    const box = bubble.getBoundingClientRect();
+    const placed = place(anchor, { width: box.width, height: box.height }, { placement, gap: withArrow ? 10 : 6 });
+    bubble.style.left = `${placed.x}px`;
+    bubble.style.top = `${placed.y}px`;
+    bubble.dataset.mkSide = placed.side;
+    bubble.style.setProperty('--mk-tooltip-arrow', `${placed.arrow}px`);
+    return placed;
+  };
+  let pending: (() => void) | null = null;
+  const follow = () => {
+    if (!isOpen || pending) return;
+    pending = requestFrame(() => {
+      pending = null;
+      if (isOpen) position();
+    });
+  };
+  scope.add(() => pending?.());
+
+  const announce = (open: boolean) => {
+    if (open) root.setAttribute('data-mk-open', '');
+    else root.removeAttribute('data-mk-open');
+    options.onOpenChange?.(open);
+    root.dispatchEvent(new CustomEvent('mk:open-change', { bubbles: true, detail: { open } }));
+  };
+
+  const controller = {
+    hide: (instant: boolean) => hide(instant),
+  };
+
+  const show = () => {
+    cancel();
+    if (isOpen || scope.disposed || !text) return;
+    const warm = current !== null || now() - lastHidden < WARM;
+    if (current && current !== controller) current.hide(true);
+    current = controller;
+    isOpen = true;
+    motion?.kill();
+    reveal();
+    const placed = position();
+    if (!reduced()) {
+      if (warm) motion = gsap.fromTo(bubble, { opacity: 0 }, { opacity: 1, duration: 0.1, ease: 'power1.out', clearProps: 'opacity' });
+      else {
+        const toward = 4;
+        const offset = placed.side === 'top' ? { x: 0, y: toward } : placed.side === 'bottom' ? { x: 0, y: -toward } : placed.side === 'left' ? { x: toward, y: 0 } : { x: -toward, y: 0 };
+        gsap.set(bubble, { transformOrigin: originOf(placed) });
+        motion = gsap.fromTo(
+          bubble,
+          { opacity: 0, scale: 0.85, filter: 'blur(4px)', ...offset },
+          { opacity: 1, scale: 1, filter: 'blur(0px)', x: 0, y: 0, duration: 0.22, ease: EASE.pop, clearProps: 'opacity,scale,filter,transform,transformOrigin' },
+        );
+      }
+    }
+    announce(true);
+  };
+
+  const hide = (instant = false) => {
+    cancel();
+    if (!isOpen) return;
+    isOpen = false;
+    if (current === controller) current = null;
+    lastHidden = now();
+    motion?.kill();
+    const finish = () => {
+      conceal();
+      gsap.set(bubble, { clearProps: 'opacity,scale,filter,transform,transformOrigin' });
+    };
+    if (instant || reduced()) finish();
+    else motion = gsap.to(bubble, { opacity: 0, scale: 0.96, duration: 0.12, ease: 'power2.in', onComplete: finish });
+    announce(false);
+  };
+  scope.add(() => {
+    if (current === controller) current = null;
+  });
+
+  /** The last input: focus after a click is not keyboard focus. */
+  let pointerInput = false;
+  scope.on(document, 'pointerdown', () => (pointerInput = true), true);
+  scope.on(document, 'keydown', () => (pointerInput = false), true);
+
+  scope.on(trigger, 'pointerenter', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') return;
+    later(show, current || now() - lastHidden < WARM ? 0 : openDelay);
+  });
+  scope.on(trigger, 'pointerleave', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') return;
+    later(() => hide(), closeDelay);
+  });
+  // Touch: a long press shows it for a moment.
+  scope.on(trigger, 'pointerdown', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') later(show, 500);
+  });
+  for (const type of ['pointerup', 'pointercancel']) {
+    scope.on(trigger, type, (event) => {
+      if ((event as PointerEvent).pointerType !== 'touch') return;
+      if (isOpen) later(() => hide(), 1500);
+      else cancel();
+    });
+  }
+  if (options.interactive) {
+    scope.on(bubble, 'pointerenter', cancel);
+    scope.on(bubble, 'pointerleave', () => later(() => hide(), closeDelay));
+  }
+  scope.on(trigger, 'focusin', () => {
+    if (!pointerInput) show();
+  });
+  scope.on(trigger, 'focusout', (event) => {
+    if (options.interactive && bubble.contains((event as FocusEvent).relatedTarget as Node | null)) return;
+    hide();
+  });
+  scope.on(document, 'keydown', (event) => {
+    if ((event as KeyboardEvent).key === 'Escape' && isOpen) hide();
+  });
+  scope.on(window, 'resize', follow);
+  scope.on(window, 'scroll', follow, { capture: true, passive: true });
+  scope.add(() => {
+    if (isOpen) conceal();
+  });
+
+  return {
+    open: show,
+    close: () => hide(),
+    setContent(next) {
+      if (scope.disposed) return;
+      text = next;
+      if (!text) {
+        label.textContent = '';
+        hide();
+        return;
+      }
+      if (!isOpen || reduced() || label.textContent === text) {
+        label.textContent = text;
+        if (isOpen) position();
+        return;
+      }
+      gsap.killTweensOf(label);
+      keep(
+        gsap
+          .timeline()
+          .to(label, { opacity: 0, filter: 'blur(3px)', duration: 0.1, ease: 'power1.in' })
+          .call(() => {
+            label.textContent = text;
+            if (isOpen) position();
+          })
+          .to(label, { opacity: 1, filter: 'blur(0px)', duration: 0.16, ease: 'power1.out', clearProps: 'opacity,filter' }),
+      );
+    },
+    get isOpen() {
+      return isOpen;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/tooltip/react.tsx

@@ -0,0 +1,30 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTooltip, type TooltipInstance, type TooltipOptions } from './engine';
+
+export interface TooltipProps extends HTMLAttributes<HTMLSpanElement>, TooltipOptions {}
+
+/** <Tooltip content="Copiar enlace"><button>…</button></Tooltip>: the first focusable child is the trigger. */
+export function Tooltip({ content, placement, openDelay, closeDelay, interactive, arrow, onOpenChange, className, children, ...props }: TooltipProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const instance = useRef<TooltipInstance | null>(null);
+  const change = useLatest(onOpenChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTooltip(ref.current, { content, placement, openDelay, closeDelay, interactive, arrow, onOpenChange: (open) => change.current?.(open) });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [placement, openDelay, closeDelay, interactive, arrow]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setContent(content ?? '');
+  }, [content]);
+  return (
+    <span {...props} ref={ref} className={['mk-tooltip', className].filter(Boolean).join(' ')}>
+      {children}
+    </span>
+  );
+}

package/src/components/tooltip/tooltip.css

@@ -0,0 +1,78 @@
+/* tooltip — Melon Mind's inverse glass in a compact 8 px bubble: .8125rem text, at most 18rem wide, a 12 × 6 px arrow
+   that points at the trigger's centre. It lives in the top layer, so the reset below undoes the popover UA styles. */
+.mk-tooltip,
+mk-tooltip {
+  display: inline-flex;
+}
+
+[data-mk-tooltip-bubble] {
+  --mk-tooltip-bg: var(--mk-glass-inverse, rgb(24 24 24 / 0.9));
+  position: fixed;
+  inset: auto;
+  z-index: 2147483000;
+  box-sizing: border-box;
+  width: max-content;
+  max-width: min(18rem, calc(100vw - 16px));
+  margin: 0;
+  padding: 0.4rem 0.65rem;
+  border: 0;
+  border-radius: 8px;
+  overflow: visible;
+  background: var(--mk-tooltip-bg);
+  color: var(--mk-on-glass-inverse, #fff);
+  box-shadow: 0 8px 24px -10px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  font: 500 0.8125rem/1.35 var(--mk-font, system-ui, sans-serif);
+  text-align: start;
+  overflow-wrap: anywhere;
+  pointer-events: none;
+  -webkit-backdrop-filter: blur(12px);
+  backdrop-filter: blur(12px);
+}
+
+[data-mk-tooltip-bubble][data-mk-interactive] {
+  pointer-events: auto;
+}
+
+[data-mk-tooltip-bubble][hidden] {
+  display: none;
+}
+
+/* A triangle outside the bubble's edge (no overlap, so the translucent glass is not doubled). */
+[data-mk-tooltip-arrow] {
+  position: absolute;
+  background: var(--mk-tooltip-bg);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='top'] > [data-mk-tooltip-arrow],
+[data-mk-tooltip-bubble][data-mk-side='bottom'] > [data-mk-tooltip-arrow] {
+  left: calc(var(--mk-tooltip-arrow, 50%) - 6px);
+  width: 12px;
+  height: 6px;
+}
+
+[data-mk-tooltip-bubble][data-mk-side='top'] > [data-mk-tooltip-arrow] {
+  top: 100%;
+  clip-path: polygon(0 0, 100% 0, 50% 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='bottom'] > [data-mk-tooltip-arrow] {
+  bottom: 100%;
+  clip-path: polygon(50% 0, 100% 100%, 0 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='left'] > [data-mk-tooltip-arrow],
+[data-mk-tooltip-bubble][data-mk-side='right'] > [data-mk-tooltip-arrow] {
+  top: calc(var(--mk-tooltip-arrow, 50%) - 6px);
+  width: 6px;
+  height: 12px;
+}
+
+[data-mk-tooltip-bubble][data-mk-side='left'] > [data-mk-tooltip-arrow] {
+  left: 100%;
+  clip-path: polygon(0 0, 100% 50%, 0 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='right'] > [data-mk-tooltip-arrow] {
+  right: 100%;
+  clip-path: polygon(100% 0, 100% 100%, 0 50%);
+}

package/src/components/trailer/README.md

@@ -0,0 +1,28 @@
+# trailer
+
+Modal de video que compone el motor `dialog`: top layer, bloqueo del fondo, Escape y retorno de foco. Medios escritos por el consumidor; no inyecta YouTube, rastreadores ni videos remotos.
+
+```html
+<button data-mk-open="preview">Ver trailer</button>
+<dialog class="mk-trailer" id="preview">
+  <header class="mk-trailer__header">
+    <h2 data-mk-part="title">Trailer</h2>
+    <button data-mk-part="close">Cerrar</button>
+  </header>
+  <video controls playsinline preload="metadata" src="/trailer.webm">
+    <track kind="captions" src="/captions.vtt" srclang="es" label="Español" />
+  </video>
+</dialog>
+```
+
+`createTrailer(dialog, { triggers:true, autoplay:false, closeOnBackdrop:true, onOpen, onClose })` devuelve `open(origin?)`, `close()`, `toggle(origin?)`, `play():Promise<boolean>`, `pause()`, `seek(seconds)`, `setVolume(0..1)`, `isOpen`, `destroy()`.
+
+React: `<Trailer id="preview" options={…}>…</Trailer>` o `useTrailer(ref, options, deps?)` sobre un `<dialog>`. Custom element: `<mk-trailer><dialog id="preview">…</dialog></mk-trailer>`, `defineTrailer()`. La estructura permanece en light DOM. Los callbacks/options de los hooks se leen al crear; usar `deps` cuando cambien.
+
+Controles opcionales: botones `data-mk-trailer-play`, `mute`, `fullscreen`, `captions`; inputs range `data-mk-trailer-seek` y `volume`; output `data-mk-trailer-time`; párrafo `data-mk-trailer-status`. Sólo oculta los controles nativos si existen Play/Mute/Seek y, cuando hay tracks, un botón CC. `aria-label`, `aria-pressed`, duración, posición y mensajes de error se sincronizan. Los sliders conservan teclado nativo; fuera de ellos Space/K alterna, flechas buscan±5s y M cambia mute. Los subtítulos usan el primer track. Pantalla completa depende del soporte del navegador y de un gesto del usuario.
+
+Autoplay está desactivado. Cerrar o destruir pausa el video y cancela solicitudes de play pendientes. `play()` absorbe rechazos del navegador y anuncia el error. `destroy()` devuelve los controles/atributos originales y retira listeners. La fuente puede fallar sin bloquear el cierre.
+
+Pantalla completa se solicita sobre `[data-mk-trailer-stage]` (un wrapper normal alrededor de video y controles), o sobre el video si falta ese wrapper. Nunca sobre `<dialog>`, que la API no admite. Cerrar/destruir sale de la pantalla completa que pertenece a esta instancia.
+
+El modal usa el morph accesible existente de motion-kit. **No copia** la apertura por bandas ni la disolución procedural de A24; el modelo de interacción y los controles se reconstruyeron para ser reutilizables. La demo usa SVG, captions y WebM silencioso originales de 6 s, sin assets de las referencias.

package/src/components/trailer/element.ts

@@ -0,0 +1,13 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTrailer, type TrailerInstance, type TrailerOptions } from './engine';
+
+/** Wrap a consumer-authored native <dialog> containing <video>. */
+export class MkTrailerElement extends MkElement<TrailerInstance> {
+  static options: Record<string, OptionType> = { autoplay: 'boolean', triggers: 'string', closeOnBackdrop: 'boolean' };
+  protected create(options: Record<string, unknown>) {
+    return createTrailer(this.querySelector('dialog'), options as TrailerOptions);
+  }
+  open(origin?: HTMLElement | null) { this.instance?.open(origin); }
+  close() { this.instance?.close(); }
+}
+export const defineTrailer = () => defineElement('mk-trailer', MkTrailerElement);

package/src/components/trailer/engine.ts

@@ -0,0 +1,189 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createDialog } from '../dialog/engine';
+
+export interface TrailerOptions {
+  triggers?: boolean | string;
+  autoplay?: boolean;
+  closeOnBackdrop?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+export interface TrailerInstance extends Instance {
+  open(origin?: HTMLElement | null): void;
+  close(): void;
+  toggle(origin?: HTMLElement | null): void;
+  play(): Promise<boolean>;
+  pause(): void;
+  seek(seconds: number): void;
+  setVolume(volume: number): void;
+  readonly isOpen: boolean;
+}
+const time = (value: number) => {
+  const seconds = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+  return `${Math.floor(seconds / 60).toString().padStart(2, '0')}:${(seconds % 60).toString().padStart(2, '0')}`;
+};
+
+/** Native modal + consumer-owned video, with optional accessible custom transport controls. */
+export function createTrailer(root: HTMLElement | null, options: TrailerOptions = {}): TrailerInstance {
+  const video = root?.querySelector<HTMLVideoElement>('video');
+  if (!root || !video || root.tagName !== 'DIALOG') return inert({ open() {}, close() {}, toggle() {}, play: async () => false, pause() {}, seek() {}, setVolume() {}, isOpen: false });
+  const scope = createScope();
+  const get = <T extends HTMLElement>(name: string) => root.querySelector<T>(`[data-mk-trailer-${name}]`);
+  const playButton = get<HTMLButtonElement>('play');
+  const muteButton = get<HTMLButtonElement>('mute');
+  const fullButton = get<HTMLButtonElement>('fullscreen');
+  // The Fullscreen API rejects HTMLDialogElement. A consumer can wrap media and
+  // transport in a stage; otherwise fullscreen just the native video element.
+  const fullTarget = get<HTMLElement>('stage') ?? video;
+  const captionsButton = get<HTMLButtonElement>('captions');
+  const seekInput = get<HTMLInputElement>('seek');
+  const volumeInput = get<HTMLInputElement>('volume');
+  const output = get<HTMLElement>('time');
+  const status = get<HTMLElement>('status');
+  const originalText = [output, status].filter((el): el is HTMLElement => !!el).map(el => [el, el.textContent] as const);
+  scope.add(() => originalText.forEach(([el, text]) => { el.textContent = text; }));
+  scope.attr(root, 'data-mk-trailer-ready', '');
+  scope.attr(root, 'data-mk-trailer-state', 'paused');
+  const controls = video.controls;
+  // Keep the browser's controls unless the consumer supplied a complete transport.
+  if (playButton && muteButton && seekInput && (!video.querySelector('track') || captionsButton)) video.controls = false;
+  scope.add(() => { video.controls = controls; });
+  for (const input of [seekInput, volumeInput]) {
+    if (!input) continue;
+    const initialValue = input.value;
+    scope.add(() => { input.value = initialValue; });
+    scope.attr(input, 'min', '0');
+    scope.attr(input, 'max', '1');
+    scope.attr(input, 'step', input === volumeInput ? '.01' : '.1');
+    scope.attr(input, 'aria-label', input.getAttribute('aria-label') ?? (input === volumeInput ? 'Volumen' : 'Posición del video'));
+  }
+  if (status) scope.attr(status, 'role', 'status');
+  const tell = (message: string) => { if (!scope.disposed && status) status.textContent = message; };
+  const sync = () => {
+    if (scope.disposed) return;
+    const duration = Number.isFinite(video.duration) ? Math.max(0, video.duration) : 0;
+    scope.attr(root, 'data-mk-trailer-state', video.ended ? 'ended' : video.paused ? 'paused' : 'playing');
+    if (playButton) {
+      scope.attr(playButton, 'aria-label', video.paused || video.ended ? 'Reproducir' : 'Pausar');
+      scope.attr(playButton, 'aria-pressed', String(!video.paused && !video.ended));
+    }
+    if (muteButton) {
+      scope.attr(muteButton, 'aria-label', video.muted ? 'Activar sonido' : 'Silenciar');
+      scope.attr(muteButton, 'aria-pressed', String(video.muted));
+    }
+    if (seekInput) {
+      scope.attr(seekInput, 'max', String(duration || 1));
+      scope.attr(seekInput, 'disabled', duration ? null : '');
+      scope.attr(seekInput, 'aria-valuetext', `${time(video.currentTime)} de ${time(duration)}`);
+      seekInput.value = String(Number.isFinite(video.currentTime) ? video.currentTime : 0);
+    }
+    if (volumeInput) volumeInput.value = String(video.muted ? 0 : video.volume);
+    if (captionsButton) {
+      scope.attr(captionsButton, 'disabled', video.textTracks.length ? null : '');
+      scope.attr(captionsButton, 'aria-pressed', String(video.textTracks[0]?.mode === 'showing'));
+    }
+    if (output) output.textContent = `${time(video.currentTime)} / ${time(duration)}`;
+  };
+  let playRequest = 0;
+  let wantsPlayback = false;
+  const pause = () => { if (!scope.disposed) { wantsPlayback = false; ++playRequest; video.pause(); sync(); } };
+  const play = async () => {
+    if (scope.disposed) return false;
+    wantsPlayback = true;
+    const request = ++playRequest;
+    try {
+      await video.play();
+      if (scope.disposed || request !== playRequest) {
+        // A stale request must not pause a newer play after a quick close/reopen.
+        if (scope.disposed || !wantsPlayback) video.pause();
+        return false;
+      }
+      tell('');
+      sync();
+      return true;
+    } catch {
+      if (scope.disposed || request !== playRequest) return false;
+      wantsPlayback = false;
+      tell('No se pudo reproducir el video. Revisa la fuente y vuelve a intentarlo.');
+      sync();
+      return false;
+    }
+  };
+  const seek = (seconds: number) => {
+    if (scope.disposed || !Number.isFinite(seconds) || !Number.isFinite(video.duration) || video.duration <= 0) return;
+    video.currentTime = Math.max(0, Math.min(video.duration, seconds));
+    sync();
+  };
+  const setVolume = (volume: number) => {
+    if (scope.disposed || !Number.isFinite(volume)) return;
+    video.volume = Math.max(0, Math.min(1, volume));
+    video.muted = volume <= 0;
+    sync();
+  };
+  const exitFullscreen = () => {
+    if (document.fullscreenElement !== fullTarget) return;
+    void document.exitFullscreen?.().catch(() => {});
+  };
+  const dialog = createDialog(root, {
+    triggers: options.triggers,
+    closeOnBackdrop: options.closeOnBackdrop ?? true,
+    drag: false,
+    autoResize: false,
+    animateContent: false,
+    onOpen: () => { sync(); if (options.autoplay) void play(); options.onOpen?.(); },
+    onClose: () => { ++playRequest; pause(); exitFullscreen(); options.onClose?.(); },
+  });
+  if (playButton) scope.on(playButton, 'click', () => video.paused || video.ended ? void play() : pause());
+  if (muteButton) scope.on(muteButton, 'click', () => { video.muted = !video.muted; sync(); });
+  if (seekInput) scope.on(seekInput, 'input', () => seek(Number(seekInput.value)));
+  if (volumeInput) scope.on(volumeInput, 'input', () => setVolume(Number(volumeInput.value)));
+  if (captionsButton) scope.on(captionsButton, 'click', () => {
+    const track = video.textTracks[0];
+    if (track) track.mode = track.mode === 'showing' ? 'hidden' : 'showing';
+    sync();
+  });
+  const fullscreen = async () => {
+    if (scope.disposed) return;
+    try {
+      if (document.fullscreenElement === fullTarget) await document.exitFullscreen?.();
+      else if (fullTarget.requestFullscreen) {
+        await fullTarget.requestFullscreen();
+        if (scope.disposed || !dialog.isOpen) exitFullscreen();
+      }
+      else tell('La pantalla completa no está disponible en este navegador.');
+    } catch { tell('No se pudo abrir la pantalla completa.'); }
+  };
+  if (fullButton) {
+    scope.attr(fullButton, 'aria-label', 'Pantalla completa');
+    scope.on(fullButton, 'click', () => { void fullscreen(); });
+    scope.on(document, 'fullscreenchange', () => {
+      scope.attr(fullButton, 'aria-label', document.fullscreenElement === fullTarget ? 'Salir de pantalla completa' : 'Pantalla completa');
+    });
+  }
+  for (const event of ['loadedmetadata', 'durationchange', 'timeupdate', 'play', 'pause', 'ended', 'volumechange']) scope.on(video, event, sync);
+  scope.on(video, 'error', () => { tell('El video no está disponible.'); scope.attr(root, 'data-mk-trailer-state', 'error'); });
+  scope.on(root, 'keydown', (event) => {
+    if (!dialog.isOpen || (event.target instanceof Element && event.target.closest('button, input, select, textarea, a, [contenteditable]'))) return;
+    if (event.key === ' ' || event.key.toLowerCase() === 'k') { event.preventDefault(); video.paused ? void play() : pause(); }
+    else if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') { event.preventDefault(); seek(video.currentTime + (event.key === 'ArrowRight' ? 5 : -5)); }
+    else if (event.key.toLowerCase() === 'm') { video.muted = !video.muted; sync(); }
+  });
+  sync();
+  return {
+    open: (origin) => { if (!scope.disposed) dialog.open(origin); },
+    close: () => { if (!scope.disposed) dialog.close(); },
+    toggle: (origin) => { if (!scope.disposed) dialog.toggle(origin); },
+    play, pause, seek, setVolume,
+    get isOpen() { return dialog.isOpen; },
+    destroy() {
+      if (scope.disposed) return;
+      wantsPlayback = false;
+      ++playRequest;
+      video.pause();
+      exitFullscreen();
+      dialog.destroy();
+      scope.dispose();
+    },
+  };
+}

package/src/components/trailer/react.tsx

@@ -0,0 +1,16 @@
+'use client';
+import { useRef, type DialogHTMLAttributes } from 'react';
+import { useRecipe } from '../../react/use-recipe';
+import { createTrailer, type TrailerOptions } from './engine';
+
+export interface TrailerProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, 'open' | 'onClose'> {
+  options?: TrailerOptions;
+}
+/** Consumer supplies <video>, optional controls and tracks; no remote media is injected. */
+export function Trailer({ options, className, children, ...props }: TrailerProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+  useRecipe(ref, createTrailer, options);
+  return <dialog {...props} ref={ref} className={['mk-trailer', className].filter(Boolean).join(' ')}>{children}</dialog>;
+}
+
+export { useTrailer } from '../../react/use-trailer';