@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/filter-builder/react.tsx

@@ -0,0 +1,36 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import type { FilterGroup } from '../../core/filter';
+import { createFilterBuilder, type FilterBuilderInstance, type FilterBuilderOptions } from './engine';
+
+export interface FilterBuilderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, FilterBuilderOptions {
+  /** Controlled filter; without it the builder keeps its own (defaultValue). */
+  value?: FilterGroup;
+  defaultValue?: FilterGroup;
+}
+
+/** <FilterBuilder fields={fields} value={filter} onChange={setFilter} />. */
+export function FilterBuilder({ fields, value, defaultValue, maxDepth, label, summary, onChange, className, ...props }: FilterBuilderProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<FilterBuilderInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef(value ?? defaultValue);
+  const fieldsKey = JSON.stringify(fields);
+  useIsomorphicLayoutEffect(() => {
+    const created = createFilterBuilder(ref.current, { fields, value: value ?? start.current, maxDepth, label, summary, onChange: (next) => change.current?.(next) });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fieldsKey, maxDepth, label, summary]);
+  const valueKey = JSON.stringify(value ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (value && instance.current && JSON.stringify(instance.current.value) !== valueKey) instance.current.setValue(value);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [valueKey]);
+  return <div {...props} ref={ref} className={['mk-filter-builder', className].filter(Boolean).join(' ')} />;
+}

package/src/components/hold-confirm/README.md

@@ -0,0 +1,13 @@
+# hold-confirm
+
+Confirmación por pulsación mantenida sobre el mismo botón: mientras se mantiene (puntero, Espacio o Enter) un relleno lo cruza durante `duration`, el botón se comprime un poco y la etiqueta cambia con blur. Soltar antes devuelve el relleno con resorte. Al completar: rebote de pulsación (curva click de Melonmind), un ✓ que se dibuja, partículas, `onConfirm` / `mk:confirm` y vuelta al inicio tras `resetAfter`.
+
+```html
+<mk-hold-confirm class="mk-hold-confirm"><button>Eliminar cuenta</button></mk-hold-confirm>
+```
+
+`defineElements()`, `createHoldConfirm(root, options)` (root es el botón o lo contiene) o `<HoldConfirm onConfirm={remove}>Eliminar cuenta</HoldConfirm>`.
+
+Opciones: `duration=1200` ms, `resetAfter=1800` ms (0 lo deja confirmado), `holdingLabel='Mantén pulsado…'`, `doneLabel='Confirmado'`, `hint='Mantén pulsado para confirmar'` (descripción accesible), `disabled`, `onConfirm()`. API: `reset()`, `confirmed`, `destroy()`. Un clic simple no envía formularios ni actúa. Un estado educado anuncia la confirmación.
+
+Variables: `--mk-hold-bg`, `--mk-hold-fg`, `--mk-hold-fill`, `--mk-hold-on-fill` (tonos de error por defecto; `.mk-hold-confirm--neutral` usa superficie y texto). Movimiento reducido: el relleno salta y no hay partículas; la confirmación sigue llegando a su tiempo.

package/src/components/hold-confirm/element.ts

@@ -0,0 +1,24 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createHoldConfirm, type HoldConfirmInstance } from './engine';
+
+/**
+ * <mk-hold-confirm class="mk-hold-confirm" duration="1200"><button>Eliminar cuenta</button></mk-hold-confirm>
+ * Hold the button (pointer, Space or Enter) to confirm. Emits mk:confirm.
+ */
+export class MkHoldConfirmElement extends MkElement<HoldConfirmInstance> {
+  static options: Record<string, OptionType> = { duration: 'number', resetAfter: 'number', holdingLabel: 'string', doneLabel: 'string', hint: 'string', disabled: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createHoldConfirm(this, options);
+  }
+
+  reset() {
+    this.instance?.reset();
+  }
+
+  get confirmed() {
+    return this.instance?.confirmed ?? false;
+  }
+}
+
+export const defineHoldConfirm = () => defineElement('mk-hold-confirm', MkHoldConfirmElement);

package/src/components/hold-confirm/engine.ts

@@ -0,0 +1,216 @@
+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 { burst, press } from '../../motion/micro';
+
+/*
+ * Hold to confirm: the same button is held (pointer, Space or Enter) while a
+ * fill runs across it for `duration`; the button presses in a little and its
+ * label changes with a blur. Letting go early springs the fill back. Holding
+ * to the end confirms: a press bounce, a check that draws itself, a ring of
+ * particles, onConfirm / mk:confirm, and the button returns after `resetAfter`.
+ * The hint ("Mantén pulsado para confirmar") is the button's description.
+ */
+
+export interface HoldConfirmOptions {
+  /** Hold time in ms (default 1200). */
+  duration?: number;
+  /** Back to the start after confirming, in ms (default 1800; 0 keeps it confirmed). */
+  resetAfter?: number;
+  holdingLabel?: string;
+  doneLabel?: string;
+  hint?: string;
+  disabled?: boolean;
+  onConfirm?: () => void;
+}
+
+export interface HoldConfirmInstance extends Instance {
+  reset(): void;
+  readonly confirmed: boolean;
+}
+
+const CHECK = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12.5l4.5 4.5L19 7.5" pathLength="1"/></svg>';
+let sequence = 0;
+
+export function createHoldConfirm(root: HTMLElement | null, options: HoldConfirmOptions = {}): HoldConfirmInstance {
+  const button = root ? ((root.matches('button') ? root : root.querySelector('button')) as HTMLButtonElement | null) : null;
+  if (!root || !button) return inert({ reset() {}, confirmed: false });
+  registerMotion();
+  const scope = createScope();
+  const duration = Number.isFinite(options.duration) && options.duration! > 0 ? options.duration! : 1200;
+  const resetAfter = Number.isFinite(options.resetAfter) ? Math.max(0, options.resetAfter!) : 1800;
+  const made: Element[] = [];
+  const add = <T extends Element>(parent: Element, element: T, first = false) => {
+    if (first) parent.prepend(element);
+    else parent.append(element);
+    made.push(element);
+    return element;
+  };
+  scope.add(() => made.forEach((element) => element.remove()));
+
+  // The label: the authored text, kept in a span that swaps with a blur.
+  const authored = [...button.childNodes];
+  const label = document.createElement('span');
+  label.dataset.mkHoldLabel = '';
+  label.append(...authored);
+  button.append(label);
+  scope.add(() => {
+    label.remove();
+    button.append(...authored);
+  });
+  const fill = add(button, document.createElement('span'), true);
+  fill.dataset.mkHoldFill = '';
+  fill.setAttribute('aria-hidden', 'true');
+  const check = add(button, document.createElement('span'));
+  check.dataset.mkHoldCheck = '';
+  check.innerHTML = CHECK;
+  const hint = add(root === button ? button : root, document.createElement('span'));
+  hint.className = 'mk-sr-only';
+  hint.id = `mk-hold-${++sequence}`;
+  hint.textContent = options.hint ?? 'Mantén pulsado para confirmar';
+  const live = add(root === button ? button : root, document.createElement('span'));
+  live.className = 'mk-sr-only';
+  live.setAttribute('role', 'status');
+
+  scope.attr(button, 'type', button.getAttribute('type') ?? 'button');
+  scope.attr(button, 'aria-describedby', [button.getAttribute('aria-describedby'), hint.id].filter(Boolean).join(' '));
+  scope.attr(button, 'data-mk-hold', '');
+  scope.attr(button, 'style', button.getAttribute('style'));
+  if (options.disabled) scope.attr(button, 'disabled', '');
+  scope.attr(root, 'data-mk-ready', '');
+
+  let holding = false;
+  let confirmed = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let back: ReturnType<typeof setTimeout> | undefined;
+  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);
+  };
+  scope.add(() => {
+    clearTimeout(timer);
+    clearTimeout(back);
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([fill, button, label, check]);
+  });
+
+  /** Show `text`, or the authored content again with null. */
+  let showing: string | null = null;
+  const write = (text: string | null) => {
+    showing = text;
+    if (text === null) label.replaceChildren(...authored);
+    else label.textContent = text;
+  };
+  const swap = (text: string | null) => {
+    if (showing === text) return;
+    if (reduced()) {
+      write(text);
+      return;
+    }
+    gsap.killTweensOf(label);
+    keep(
+      gsap
+        .timeline()
+        .to(label, { opacity: 0, filter: 'blur(6px)', y: -4, duration: 0.12, ease: 'power2.in' })
+        .call(() => write(text))
+        .fromTo(label, { opacity: 0, filter: 'blur(6px)', y: 4 }, { opacity: 1, filter: 'blur(0px)', y: 0, duration: 0.25, ease: EASE.pop, clearProps: 'all' }),
+    );
+  };
+
+  const setProgress = (value: number, seconds: number, ease: string) => {
+    gsap.killTweensOf(fill, 'scaleX');
+    if (reduced() || seconds === 0) gsap.set(fill, { scaleX: value });
+    else keep(gsap.to(fill, { scaleX: value, duration: seconds, ease }));
+  };
+
+  const start = () => {
+    if (holding || confirmed || button.disabled || scope.disposed) return;
+    holding = true;
+    scope.attr(button, 'data-mk-holding', '');
+    swap(options.holdingLabel ?? 'Mantén pulsado…');
+    setProgress(1, duration / 1000, 'power1.in');
+    if (!reduced()) keep(gsap.to(button, { scale: 0.96, duration: duration / 1000, ease: 'power1.out' }));
+    clearTimeout(timer);
+    timer = setTimeout(confirm, duration);
+  };
+
+  const cancel = () => {
+    if (!holding) return;
+    holding = false;
+    clearTimeout(timer);
+    scope.attr(button, 'data-mk-holding', null);
+    swap(null);
+    setProgress(0, 0.5, EASE.swatch);
+    if (!reduced()) keep(gsap.to(button, { scale: 1, duration: 0.5, ease: EASE.click, clearProps: 'scale,transform' }));
+  };
+
+  const reset = () => {
+    if (scope.disposed) return;
+    clearTimeout(back);
+    confirmed = false;
+    holding = false;
+    scope.attr(button, 'data-mk-confirmed', null);
+    scope.attr(button, 'data-mk-holding', null);
+    swap(null);
+    setProgress(0, 0.4, 'power2.out');
+  };
+
+  function confirm() {
+    if (!holding || scope.disposed) return;
+    holding = false;
+    confirmed = true;
+    scope.attr(button!, 'data-mk-holding', null);
+    scope.attr(button!, 'data-mk-confirmed', '');
+    setProgress(1, 0, 'none');
+    gsap.killTweensOf(button, 'scale');
+    gsap.set(button, { clearProps: 'scale,transform' });
+    keep(press(button));
+    swap(options.doneLabel ?? 'Confirmado');
+    const path = check.querySelector('path');
+    if (path && !reduced()) keep(gsap.fromTo(path, { strokeDasharray: 1, strokeDashoffset: 1 }, { strokeDashoffset: 0, duration: 0.45, delay: 0.1, ease: 'power2.out' }));
+    keep(burst(button, { count: 8, distance: 34, colors: ['currentColor'] }));
+    live.textContent = options.doneLabel ?? 'Confirmado';
+    options.onConfirm?.();
+    root!.dispatchEvent(new CustomEvent('mk:confirm', { bubbles: true }));
+    if (resetAfter) back = setTimeout(reset, resetAfter);
+  }
+
+  scope.on(button, 'pointerdown', (event) => {
+    const pointer = event as PointerEvent;
+    if (pointer.button !== 0) return;
+    pointer.preventDefault();
+    button.focus({ preventScroll: true });
+    start();
+  });
+  for (const type of ['pointerup', 'pointerleave', 'pointercancel']) scope.on(button, type, cancel);
+  scope.on(button, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    if (key.key !== ' ' && key.key !== 'Enter') return;
+    key.preventDefault();
+    if (!key.repeat) start();
+  });
+  scope.on(button, 'keyup', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if (key === ' ' || key === 'Enter') cancel();
+  });
+  scope.on(button, 'blur', cancel);
+  // A plain click (no hold) must not submit a form or act.
+  scope.on(button, 'click', (event) => event.preventDefault());
+  scope.on(button, 'contextmenu', (event) => {
+    if (holding) event.preventDefault();
+  });
+  gsap.set(fill, { scaleX: 0 });
+
+  return {
+    reset,
+    get confirmed() {
+      return confirmed;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/hold-confirm/hold-confirm.css

@@ -0,0 +1,86 @@
+/* hold-confirm — Melonmind button (64 px pill, surface tones); while held a darker fill runs from the left,
+   the button presses in, the label changes; confirmed, a check draws itself. */
+.mk-hold-confirm,
+mk-hold-confirm {
+  display: inline-flex;
+}
+
+[data-mk-hold] {
+  --mk-hold-bg: var(--mk-error-soft);
+  --mk-hold-fg: var(--mk-on-error-soft);
+  --mk-hold-fill: var(--mk-error);
+  --mk-hold-on-fill: var(--mk-on-error);
+  position: relative;
+  isolation: isolate;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  min-height: 3rem;
+  min-width: 12rem;
+  padding: 0 1.75rem;
+  overflow: hidden;
+  border: 0;
+  border-radius: 64px;
+  background: var(--mk-hold-bg);
+  color: var(--mk-hold-fg);
+  font: inherit;
+  font-weight: 500;
+  cursor: pointer;
+  user-select: none;
+  -webkit-user-select: none;
+  touch-action: manipulation;
+  -webkit-touch-callout: none;
+  transition: color 0.2s ease;
+}
+
+[data-mk-hold]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+[data-mk-hold]:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+[data-mk-hold] [data-mk-hold-fill] {
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background: var(--mk-hold-fill);
+  transform-origin: left center;
+}
+
+[data-mk-hold]:is([data-mk-holding], [data-mk-confirmed]) {
+  color: var(--mk-hold-on-fill);
+}
+
+[data-mk-hold] [data-mk-hold-label] {
+  display: inline-block;
+}
+
+[data-mk-hold] [data-mk-hold-check] {
+  display: none;
+}
+
+[data-mk-hold][data-mk-confirmed] [data-mk-hold-check] {
+  display: inline-grid;
+  order: -1;
+}
+
+/* The neutral variant (Melonmind tonal). */
+.mk-hold-confirm--neutral [data-mk-hold],
+[data-mk-hold].mk-hold-confirm--neutral {
+  --mk-hold-bg: var(--mk-surface-3);
+  --mk-hold-fg: var(--mk-text);
+  --mk-hold-fill: var(--mk-text);
+  --mk-hold-on-fill: var(--mk-bg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-hold] {
+    transition: none;
+  }
+}

package/src/components/hold-confirm/react.tsx

@@ -0,0 +1,28 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createHoldConfirm, type HoldConfirmOptions } from './engine';
+
+export interface HoldConfirmProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onClick'>, HoldConfirmOptions {
+  children?: ReactNode;
+}
+
+/**
+ * <HoldConfirm onConfirm={removeAccount}>Eliminar cuenta</HoldConfirm>: hold the button to confirm.
+ * The engine moves the label into its own span, so pass plain text or inline content.
+ */
+export function HoldConfirm({ duration, resetAfter, holdingLabel, doneLabel, hint, disabled, onConfirm, className, children, ...props }: HoldConfirmProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const confirm = useLatest(onConfirm);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createHoldConfirm(ref.current, { duration, resetAfter, holdingLabel, doneLabel, hint, disabled, onConfirm: () => confirm.current?.() });
+    return () => instance.destroy();
+  }, [duration, resetAfter, holdingLabel, doneLabel, hint, disabled]);
+  return (
+    <span ref={ref} className={['mk-hold-confirm', className].filter(Boolean).join(' ')}>
+      <button type="button" {...props}>
+        <span data-mk-hold-text="">{children}</span>
+      </button>
+    </span>
+  );
+}

package/src/components/hover-card/README.md

@@ -0,0 +1,20 @@
+# hover-card
+
+Vista previa no modal, accesible al señalar, enfocar o tocar. Los enlaces/botones del panel pueden recibir foco.
+
+```html
+<mk-hover-card class="mk-hover-card" placement="bottom">
+  <button type="button" data-mk-hover-trigger>Ver estudio</button>
+  <div data-mk-hover-panel hidden role="region" aria-label="Vista previa">Contenido</div>
+</mk-hover-card>
+```
+
+`defineElements()`, `createHoverCard(root, options)`, o `<HoverCard trigger="Ver estudio" placement="bottom">Contenido</HoverCard>`.
+
+Opciones: `openDelay=120` ms, `closeDelay=140` ms, `placement='top'|'bottom'` (lado preferido), `onOpenChange(boolean)`. API `open()`, `close()`, `reposition()`, `isOpen`, `destroy()`. Evento `mk:open-change` con `{open}`.
+
+Escape cierra y retorna al disparador; salir con foco y puntero fuera o tocar fuera cierra. El puntero puede pasar del disparador al panel sin cerrarlo y el panel admite foco en su contenido. No atrapa el foco.
+
+El panel se posiciona respecto al root (sin portal: mantener un ancestro que permita overflow) y no se sale del viewport: si su lado no tiene sitio pasa al otro (`data-mk-side`) y se desplaza en horizontal lejos de los bordes (`--mk-hover-shift`); vuelve a colocarse con scroll y resize mientras está abierto. El panel es cristal inverso (`--mk-glass-inverse`, radio de 24px) y entra con un pop de .3 s desde el blur al señalar o tocar; abierto desde teclado (`data-mk-input="keyboard"`) aparece sin entrada, igual que con movimiento reducido. Limpia timers, listeners y frames y restaura todos los atributos.
+
+[link-preview](../link-preview/README.md) lo compone para previsualizar enlaces.

package/src/components/hover-card/element.ts

@@ -0,0 +1,8 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createHoverCard, type HoverCardInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkHoverCardElement extends MkElement<HoverCardInstance> {
+  static options: Record<string, OptionType> = { openDelay: 'number', closeDelay: 'number', placement: 'string' };
+  protected create(options: Record<string, unknown>) { return createHoverCard(this, options); }
+}
+export const defineHoverCard = () => defineElement('mk-hover-card', MkHoverCardElement);

package/src/components/hover-card/engine.ts

@@ -0,0 +1,131 @@
+import { requestFrame } from '../../core/frame';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface HoverCardOptions {
+  openDelay?: number;
+  closeDelay?: number;
+  /** Preferred side; it flips when the viewport has no room there. */
+  placement?: 'top' | 'bottom';
+  onOpenChange?: (open: boolean) => void;
+}
+export interface HoverCardInstance extends Instance {
+  open(): void;
+  close(): void;
+  /** Place the open panel again (after its content changed size). */
+  reposition(): void;
+  readonly isOpen: boolean;
+}
+let sequence = 0;
+/** Distance kept from the viewport edges. */
+const EDGE = 12;
+const GAP = 12;
+
+/**
+ * Nonmodal preview: pointer, keyboard focus and tap all reveal the same panel.
+ * The panel stays inside the viewport: it flips to the other side when its own
+ * has no room and shifts sideways (--mk-hover-shift) away from the edges, again
+ * on scroll and resize. Opened from the keyboard it appears without the entrance.
+ */
+export function createHoverCard(root: HTMLElement | null, options: HoverCardOptions = {}): HoverCardInstance {
+  const trigger = root?.querySelector<HTMLElement>('[data-mk-hover-trigger]');
+  const panel = root?.querySelector<HTMLElement>('[data-mk-hover-panel]');
+  if (!root || !trigger || !panel) return inert({ open() {}, close() {}, reposition() {}, isOpen: false });
+  const scope = createScope();
+  const openDelay = Number.isFinite(options.openDelay) ? Math.max(0, options.openDelay!) : 120;
+  const closeDelay = Number.isFinite(options.closeDelay) ? Math.max(0, options.closeDelay!) : 140;
+  const preferred = options.placement ?? 'top';
+  let opened = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pointerInside = false;
+  /** The last input was a pointer (focus that follows a click is not keyboard). */
+  let pointerInput = false;
+  let id = panel.id;
+  if (!id) { do { id = `mk-hover-${++sequence}`; } while (document.getElementById(id)); }
+  scope.attr(panel, 'id', id);
+  scope.attr(trigger, 'aria-controls', id);
+  scope.attr(root, 'data-mk-placement', preferred);
+  scope.attr(root, 'data-mk-side', preferred);
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+
+  const place = () => {
+    if (!opened || scope.disposed) return;
+    root.style.removeProperty('--mk-hover-shift');
+    const anchor = root.getBoundingClientRect();
+    const box = panel.getBoundingClientRect();
+    const view = { width: innerWidth, height: innerHeight };
+    const need = box.height + GAP + EDGE;
+    const above = anchor.top;
+    const below = view.height - anchor.bottom;
+    let side = preferred;
+    if (preferred === 'top' && above < need && below > above) side = 'bottom';
+    if (preferred === 'bottom' && below < need && above > below) side = 'top';
+    scope.attr(root, 'data-mk-side', side);
+    // The panel starts at the root's left edge; move it back inside the viewport.
+    const left = anchor.left;
+    let shift = 0;
+    if (left + box.width > view.width - EDGE) shift = view.width - EDGE - box.width - left;
+    if (left + shift < EDGE) shift = EDGE - left;
+    if (shift) root.style.setProperty('--mk-hover-shift', `${Math.round(shift)}px`);
+  };
+  let pending: (() => void) | null = null;
+  const schedulePlace = () => {
+    if (!opened || pending) return;
+    pending = requestFrame(() => {
+      pending = null;
+      place();
+    });
+  };
+  scope.add(() => pending?.());
+
+  const cancel = () => { clearTimeout(timer); timer = undefined; };
+  const set = (value: boolean) => {
+    cancel();
+    if (scope.disposed) return;
+    const changed = value !== opened;
+    opened = value;
+    scope.attr(trigger, 'aria-expanded', String(value));
+    scope.attr(panel, 'hidden', value ? null : '');
+    scope.attr(root, 'data-mk-open', value ? '' : null);
+    if (value && changed) {
+      scope.attr(root, 'data-mk-input', pointerInput ? 'pointer' : 'keyboard');
+      place();
+    }
+    if (changed) {
+      options.onOpenChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:open-change', { bubbles: true, detail: { open: value } }));
+    }
+  };
+  const schedule = (value: boolean, delay: number) => { cancel(); timer = setTimeout(() => set(value), delay); };
+  scope.on(root, 'pointerenter', () => { pointerInside = true; pointerInput = true; schedule(true, openDelay); });
+  scope.on(root, 'pointerleave', () => {
+    pointerInside = false;
+    if (!root.contains(document.activeElement)) schedule(false, closeDelay);
+  });
+  scope.on(root, 'pointerdown', () => { pointerInput = true; });
+  scope.on(document, 'keydown', () => { pointerInput = false; }, true);
+  scope.on(root, 'focusin', () => set(true));
+  scope.on(root, 'focusout', (event) => {
+    if (!pointerInside && !root.contains((event as FocusEvent).relatedTarget as Node | null)) schedule(false, closeDelay);
+  });
+  scope.on(trigger, 'click', () => { pointerInput = true; set(true); });
+  scope.on(document, 'pointerdown', (event) => { if (!root.contains(event.target as Node)) set(false); });
+  scope.on(root, 'keydown', (event) => {
+    if (event.key !== 'Escape' || !opened) return;
+    event.preventDefault();
+    trigger.focus();
+    set(false);
+  });
+  scope.on(window, 'resize', schedulePlace);
+  scope.on(window, 'scroll', schedulePlace, { capture: true, passive: true });
+  scope.add(cancel);
+  set(false);
+  return {
+    open: () => set(true),
+    close: () => set(false),
+    reposition: place,
+    get isOpen() { return opened; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/hover-card/hover-card.css

@@ -0,0 +1,19 @@
+.mk-hover-card, mk-hover-card { position: relative; display: inline-flex; }
+.mk-hover-card [data-mk-hover-panel], mk-hover-card [data-mk-hover-panel] {
+  transform-origin: 50% 100%;
+  position: absolute; z-index: 10; bottom: calc(100% + .75rem); left: var(--mk-hover-shift, 0);
+  width: min(19rem, calc(100vw - 1.5rem)); padding: 1.25rem; border-radius: var(--mk-radius-lg);
+  color: var(--mk-on-glass-inverse); background: var(--mk-glass-inverse); border: 0; border-radius: var(--mk-radius-lg, 24px);
+  box-shadow: var(--mk-glass-bevel); backdrop-filter: blur(16px);
+  /* Melonmind animation-general-in-2: blur 32 → 0, scale .7 → 1, 300 ms. */
+  animation: mk-hover-card-in .3s cubic-bezier(.1,.8,0,1.1) both;
+}
+/* Bridge over the gap so the pointer can travel into the panel. */
+.mk-hover-card [data-mk-hover-panel]::after, mk-hover-card [data-mk-hover-panel]::after { content: ''; position: absolute; inset: -1rem 0; z-index: -1; }
+:is(.mk-hover-card, mk-hover-card)[data-mk-side=bottom] [data-mk-hover-panel] { top: calc(100% + .75rem); bottom: auto; transform-origin: 50% 0; animation-name: mk-hover-card-down; }
+/* Opened from the keyboard: no entrance. */
+:is(.mk-hover-card, mk-hover-card)[data-mk-input=keyboard] [data-mk-hover-panel] { animation: none; }
+.mk-hover-card [hidden], mk-hover-card [hidden] { display: none !important; }
+@keyframes mk-hover-card-in { from { opacity: 0; filter: blur(32px); transform: translateY(8px) scale(.7); } to { opacity: 1; filter: none; transform: none; } }
+@keyframes mk-hover-card-down { from { opacity: 0; filter: blur(32px); transform: translateY(-8px) scale(.7); } to { opacity: 1; filter: none; transform: none; } }
+@media (prefers-reduced-motion: reduce) { .mk-hover-card [data-mk-hover-panel], mk-hover-card [data-mk-hover-panel] { animation: none; } }

package/src/components/hover-card/react.tsx

@@ -0,0 +1,19 @@
+'use client';
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createHoverCard, type HoverCardOptions } from './engine';
+export interface HoverCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, HoverCardOptions {
+  trigger: ReactNode; children: ReactNode; triggerLabel?: string; panelLabel?: string;
+}
+export function HoverCard({ trigger, children, triggerLabel, panelLabel = 'Vista previa', openDelay, closeDelay, placement, onOpenChange, className, ...props }: HoverCardProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const change = useLatest(onOpenChange);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createHoverCard(ref.current, { openDelay, closeDelay, placement, onOpenChange: (n) => change.current?.(n) });
+    return () => instance.destroy();
+  }, [openDelay, closeDelay, placement]);
+  return <div {...props} ref={ref} className={['mk-hover-card', className].filter(Boolean).join(' ')}>
+    <button type="button" className="mk-button mk-button--tonal" data-mk-hover-trigger aria-label={triggerLabel} aria-expanded="false">{trigger}</button>
+    <div data-mk-hover-panel role="region" aria-label={panelLabel} hidden>{children}</div>
+  </div>;
+}

package/src/components/image-preview/README.md

@@ -0,0 +1,16 @@
+# image-preview
+
+Visor de imágenes tipo diálogo: las miniaturas `[data-mk-image]` abren un `<dialog>` modal donde la imagen crece desde su miniatura (0.7 s, curva firma; el radio de la miniatura pasa a 24 px) sobre un fondo oscuro desenfocado. Anterior/siguiente (botones, flechas o deslizar) entran con desplazamiento y blur, y el contador rueda. Doble clic o doble toque hace zoom ×2 donde apuntas y arrastrar lo mueve. Arrastrar hacia abajo, Escape o cerrar devuelven la imagen a su miniatura y el foco a ella.
+
+```html
+<mk-image-preview class="mk-image-preview">
+  <button data-mk-image data-mk-src="/big/1.jpg" data-mk-caption="Atardecer"><img src="/thumb/1.jpg" alt="Atardecer en la sierra"></button>
+  <button data-mk-image data-mk-src="/big/2.jpg"><img src="/thumb/2.jpg" alt="Lago"></button>
+</mk-image-preview>
+```
+
+`defineElements()`, `createImagePreview(root, options)` o `<ImagePreview images={[{ src, thumb, alt, caption }]} />`. La imagen grande sale de `data-mk-src`, el `href` o el `src` de la miniatura; el pie, de `data-mk-caption`.
+
+Opciones: `labels {close, prev, next, dialog}`, `loop=true`, `onChange(index)`, `onOpenChange(open)`. API: `open(index)`, `close()`, `next()`, `prev()`, `isOpen`, `index`, `destroy()`. Eventos `mk:open`, `mk:change` `{index, previous}` y `mk:close`. Miniaturas que no son botones reciben `tabindex` y `role="button"` (Enter o Espacio abren).
+
+Movimiento reducido: abre, cambia y cierra sin crecimiento ni deslizamientos.

package/src/components/image-preview/element.ts

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createImagePreview, type ImagePreviewInstance } from './engine';
+
+/**
+ * <mk-image-preview class="mk-image-preview">
+ *   <button data-mk-image data-mk-src="/big/1.jpg" data-mk-caption="Atardecer"><img src="/thumb/1.jpg" alt="Atardecer en la sierra"></button>
+ * </mk-image-preview>
+ * Emits mk:open, mk:change ({index, previous}) and mk:close.
+ */
+export class MkImagePreviewElement extends MkElement<ImagePreviewInstance> {
+  static options: Record<string, OptionType> = { loop: 'boolean', labels: 'json' };
+
+  protected create(options: Record<string, unknown>) {
+    return createImagePreview(this, options);
+  }
+
+  open(index?: number) {
+    this.instance?.open(index);
+  }
+
+  close() {
+    this.instance?.close();
+  }
+}
+
+export const defineImagePreview = () => defineElement('mk-image-preview', MkImagePreviewElement);