@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/heatmap-chart/heatmap-chart.css

@@ -0,0 +1,93 @@
+/* heatmap-chart — a week per column of 3 px rounded days, deepening from the track to the accent; needs chart.css.
+   The day under the pointer lifts with a ring; the "less … more" scale sits under it, to the right. */
+.mk-heatmap-chart,
+mk-heatmap-chart {
+  --mk-heatmap-color: var(--mk-accent);
+  --mk-heatmap-empty: var(--mk-surface-2);
+  display: grid;
+  gap: 0.6rem;
+  min-width: 0;
+}
+
+[data-mk-heatmap-scroll] {
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding-block: 4px;
+  scrollbar-width: thin;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-chart-svg] {
+  width: var(--mk-heatmap-width, auto);
+  max-width: none;
+  overflow: visible;
+  cursor: pointer;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition:
+    fill 0.35s ease,
+    opacity 0.2s ease,
+    transform 0.3s var(--mk-ease-swatch);
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect[data-mk-on] {
+  stroke: var(--mk-text);
+  stroke-width: 1.5;
+  transform: scale(1.3);
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect[data-mk-dim] {
+  opacity: 0.25;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='months'] text,
+[data-mk-chart-type='heatmap'] [data-mk-part='weekdays'] text {
+  font-size: 10px;
+}
+
+[data-mk-heatmap-scale] {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 3px;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+[data-mk-heatmap-scale][hidden] {
+  display: none;
+}
+
+[data-mk-heatmap-scale] span {
+  margin-inline: 0.35rem;
+}
+
+[data-mk-heatmap-scale] i {
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  cursor: pointer;
+  transition: transform 0.25s var(--mk-ease-swatch);
+}
+
+@media (hover: hover) {
+  [data-mk-heatmap-scale] i:hover {
+    transform: scale(1.25);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect,
+  [data-mk-heatmap-scale] i {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect {
+    stroke: CanvasText;
+    stroke-width: 0.5;
+  }
+}

package/src/components/heatmap-chart/react.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import type { HTMLAttributes } from 'react';
+import { useChart } from '../chart/use-chart';
+import { createHeatmapChart, type HeatmapChartInstance, type HeatmapChartOptions } from './engine';
+
+export interface HeatmapChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, HeatmapChartOptions {
+  instanceRef?: { current: HeatmapChartInstance | null };
+}
+
+export function HeatmapChart({ data, end, weeks, firstDay, locale, levels, color, unit, label, legend, formatValue, emptyLabel, onSelect, instanceRef, className, ...props }: HeatmapChartProps) {
+  const ref = useChart(createHeatmapChart, { data, end, weeks, firstDay, locale, levels, color, unit, label, legend, emptyLabel }, { formatValue, onSelect }, instanceRef);
+  return <div {...props} ref={ref} className={['mk-heatmap-chart', 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

@@ -11,6 +11,10 @@ Vista previa no modal, accesible al señalar, enfocar o tocar. Los enlaces/boton
 
 `defineElements()`, `createHoverCard(root, options)`, o `<HoverCard trigger="Ver estudio" placement="bottom">Contenido</HoverCard>`.
 
-Opciones: `openDelay=120` ms, `closeDelay=140` ms, `placement='top'|'bottom'`, `onOpenChange(boolean)`. API `open()`, `close()`, `isOpen`, `destroy()`. Evento `mk:open-change` con `{open}`.
+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 panel se posiciona respecto al root: mantener un ancestro que permita overflow; no crea portal. No atrapa el foco. Entrada .28 s, instantánea bajo movimiento reducido. Limpia timers y restaura todos los atributos.
+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/engine.ts

@@ -1,61 +1,144 @@
+import { requestFrame } from '../../core/frame';
+import { reduced } from '../../core/reduced';
 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;
+/** Longest fold back into the trigger (the CSS one is .22 s); then it hides anyway. */
+const FOLD_MS = 400;
 
-/** Nonmodal preview: pointer, keyboard focus and tap all reveal the same panel. */
+/**
+ * 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.
+ * It grows out of the trigger's centre (--mk-hover-origin-x) and, when the
+ * pointer leaves, folds back into it (data-mk-closing, .22 s) before hiding.
+ */
 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() {}, isOpen: false });
+  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', options.placement ?? 'top');
+  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`);
+    // The panel grows from (and folds back into) the trigger's centre.
+    const target = trigger.getBoundingClientRect();
+    root.style.setProperty('--mk-hover-origin-x', `${Math.round(target.left + target.width / 2 - (left + 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; };
+  // The fold back into the trigger: the panel stays until its animation ends (or FOLD_MS passes).
+  let folding: ReturnType<typeof setTimeout> | undefined;
+  const settleFold = () => {
+    clearTimeout(folding);
+    folding = undefined;
+    panel.removeEventListener('animationend', settleFold);
+    if (scope.disposed) return;
+    scope.attr(root, 'data-mk-closing', null);
+    if (!opened) scope.attr(panel, 'hidden', '');
+  };
+  scope.add(() => {
+    clearTimeout(folding);
+    panel.removeEventListener('animationend', settleFold);
+  });
   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 : '');
+    if (value) {
+      if (folding !== undefined) settleFold();
+      scope.attr(panel, 'hidden', null);
+    } else if (changed && !reduced() && root.dataset.mkInput !== 'keyboard' && !panel.hidden) {
+      scope.attr(root, 'data-mk-closing', '');
+      panel.addEventListener('animationend', settleFold);
+      folding = setTimeout(settleFold, FOLD_MS);
+    } else if (folding === undefined) scope.attr(panel, 'hidden', '');
     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; schedule(true, openDelay); });
+  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', () => set(true));
+  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;
@@ -63,7 +146,15 @@ export function createHoverCard(root: HTMLElement | null, options: HoverCardOpti
     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), get isOpen() { return opened; }, destroy: () => scope.dispose() };
+  return {
+    open: () => set(true),
+    close: () => set(false),
+    reposition: place,
+    get isOpen() { return opened; },
+    destroy: () => scope.dispose(),
+  };
 }