@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/recipes/editorial-reveal/create-editorial-reveal.ts

@@ -0,0 +1,91 @@
+import { gsap, CustomEase, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createMaskText } from '../mask-text/create-mask-text';
+import { createCascade } from '../cascade/create-cascade';
+import { createParallax } from '../parallax/create-parallax';
+import { createContrast } from '../contrast/create-contrast';
+
+export interface EditorialRevealOptions {
+  trigger?: 'scroll' | 'load' | 'manual';
+  /** Title and staged groups, seconds. Reference default 1.2. */
+  duration?: number;
+  stagger?: number;
+  /** Title pieces' start offset, percent. Reference default 110. */
+  y?: number;
+  ease?: string;
+  hoverDuration?: number;
+  /** Duplicate label/arrow content moves by this many em. */
+  buttonShift?: number;
+  imageScale?: number;
+  parallax?: boolean;
+}
+export interface EditorialRevealInstance extends Instance { play(): void; reset(): void; }
+let nextScope = 0;
+
+/** Editorial composition: masked headings, staged contact groups, restrained image/card motion and keyboard-equivalent buttons. */
+export function createEditorialReveal(root: HTMLElement | null, options: EditorialRevealOptions = {}): EditorialRevealInstance {
+  if (!root) return inert({ play() {}, reset() {} });
+  registerMotion();
+  const scope = createScope();
+  const context = gsap.context(() => {}, root);
+  const trigger = options.trigger ?? 'scroll';
+  const duration = options.duration ?? 1.2;
+  const stagger = options.stagger ?? .03;
+  const hoverDuration = options.hoverDuration ?? .5;
+  const ease = options.ease ?? 'mk-editorial-reference';
+  CustomEase.create('mk-editorial-reference', 'M0,0 C0.6,0 0,1 1,1');
+  // Helpers restore their own nodes; these snapshots also preserve caller inline styles/readiness.
+  const preserve = (el: HTMLElement) => ['style', 'data-mk-ready', 'aria-label'].forEach(name => scope.attr(el, name, el.getAttribute(name)));
+  preserve(root);
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-title],[data-mk-editorial-group],[data-mk-cascade],[data-mk-editorial-image],[data-mk-parallax-target],[data-mk-editorial-header],[data-mk-editorial-card-image],[data-mk-editorial-button-content]').forEach(preserve);
+  const titles = [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-title]')].map(el => createMaskText(el, { by: 'lines', trigger, once: true, y: options.y ?? 110, duration, stagger, ease, delay: 0 }));
+  const groups = [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-group]')].map(el => createCascade(el, { trigger, duration, step: stagger, once: true }));
+  const images = options.parallax === false ? [] : [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-image]')].map(el => createParallax(el, { amount: .25 }));
+  const header = root.querySelector<HTMLElement>('[data-mk-editorial-header]');
+  const sections = [...root.querySelectorAll<HTMLElement>('[data-mk-tone]')];
+  const scopeId = String(++nextScope);
+  sections.forEach(el => scope.attr(el, 'data-mk-editorial-scope', scopeId));
+  const contrast = header ? createContrast(header, { sections: `[data-mk-editorial-scope="${scopeId}"]` }) : null;
+  scope.add(() => { titles.forEach(instance => instance.destroy()); groups.forEach(instance => instance.destroy()); images.forEach(instance => instance.destroy()); contrast?.destroy(); context.revert(); });
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-button]').forEach(button => {
+    const content = button.querySelector<HTMLElement>('[data-mk-editorial-button-content]');
+    if (!content) return;
+    let pointerInside = false;
+    const render = () => {
+      const active = pointerInside || button.contains(root.ownerDocument.activeElement);
+      context.add(() => gsap.to(content, { x: active && !reduced() ? `${options.buttonShift ?? 2.25}em` : '0em', duration: reduced() ? 0 : hoverDuration, ease, overwrite: true }));
+    };
+    scope.on(button, 'pointerenter', () => { pointerInside = true; render(); });
+    scope.on(button, 'pointerleave', () => { pointerInside = false; render(); });
+    scope.on(button, 'focusin', render);
+    scope.on(button, 'focusout', () => { scope.timeout(render, 0); });
+  });
+  const cursor = root.querySelector<HTMLElement>('[data-mk-editorial-cursor]');
+  if (cursor) { preserve(cursor); scope.attr(cursor, 'aria-hidden', 'true'); scope.attr(cursor, 'hidden', ''); }
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-card]').forEach(card => {
+    const image = card.querySelector<HTMLElement>('[data-mk-editorial-card-image]');
+    let pointerInside = false;
+    const render = () => {
+      const active = pointerInside || card.contains(root.ownerDocument.activeElement);
+      scope.attr(card, 'data-mk-editorial-active', active ? '' : null);
+      if (image) context.add(() => gsap.to(image, { scale: active && !reduced() ? options.imageScale ?? 1.04 : 1, duration: reduced() ? 0 : hoverDuration, ease, overwrite: true }));
+    };
+    scope.on(card, 'pointerenter', event => { pointerInside = true; render(); if (cursor && !reduced() && event.pointerType !== 'touch') scope.attr(cursor, 'hidden', null); });
+    scope.on(card, 'pointerleave', () => { pointerInside = false; render(); if (cursor) scope.attr(cursor, 'hidden', ''); });
+    scope.on(card, 'pointermove', event => {
+      if (!cursor || reduced() || event.pointerType === 'touch') return;
+      const rect = root.getBoundingClientRect();
+      cursor.style.transform = `translate(${event.clientX - rect.left + 16}px, ${event.clientY - rect.top + 16}px)`;
+    });
+    scope.on(card, 'focusin', render);
+    scope.on(card, 'focusout', () => { scope.timeout(render, 0); });
+  });
+  scope.attr(root, 'data-mk-ready', '');
+  return {
+    play() { if (!scope.disposed) { titles.forEach(instance => instance.play()); groups.forEach(instance => instance.play()); } },
+    reset() { if (!scope.disposed) { titles.forEach(instance => instance.hide()); groups.forEach(instance => instance.reset()); } },
+    destroy() { scope.dispose(); },
+  };
+}

package/src/recipes/editorial-reveal/editorial-reveal.css

@@ -0,0 +1,17 @@
+.mk-editorial-reveal { position: relative; isolation: isolate; color: var(--mk-text); }
+.mk-editorial-reveal [data-mk-editorial-image], .mk-editorial-reveal [data-mk-editorial-card] { overflow: clip; border-radius: 12px; }
+.mk-editorial-reveal [data-mk-editorial-image] > :is(img,video,picture) { display: block; width: 100%; height: 100%; object-fit: cover; }
+.mk-editorial-reveal [data-mk-editorial-card] { display: grid; gap: 20px; padding: 24px; background: var(--mk-surface-2); color: inherit; text-decoration: none; transition: background-color .5s cubic-bezier(.6, 0, 0, 1), color .5s cubic-bezier(.6, 0, 0, 1); }
+.mk-editorial-reveal [data-mk-editorial-card][data-mk-editorial-active] { background: var(--mk-accent); color: var(--mk-on-accent); }
+.mk-editorial-reveal [data-mk-editorial-card-image] { width: 100%; aspect-ratio: 4 / 3; object-fit: cover; border-radius: 8px; }
+.mk-editorial-reveal [data-mk-editorial-button] { display: inline-flex; overflow: clip; align-items: center; padding: 12px 18px; border: 1px solid var(--mk-outline-soft); border-radius: 8px; background: var(--mk-text); color: var(--mk-surface); text-decoration: none; font: inherit; cursor: pointer; }
+.mk-editorial-reveal [data-mk-editorial-button-content] { position: relative; display: flex; align-items: center; gap: 1em; padding-inline-end: 2.25em; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::before, .mk-editorial-reveal [data-mk-editorial-button-content]::after { content: '↗'; position: absolute; inset-block-start: 0; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::before { inset-inline-start: -2.25em; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::after { inset-inline-end: 0; }
+.mk-editorial-reveal [data-mk-editorial-cursor] { pointer-events: none; position: absolute; z-index: 3; inset: 0 auto auto 0; width: max-content; height: max-content; padding: 10px 14px; border-radius: 30px; background: var(--mk-text); color: var(--mk-surface); font-size: .75rem; }
+.mk-editorial-reveal [hidden] { display: none !important; }
+.mk-editorial-reveal [data-mk-editorial-header][data-mk-on='dark'] { color: var(--mk-surface); }
+.mk-editorial-reveal :is(a,button,input,textarea):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+.mk-editorial-reveal [data-mk-editorial-group] [data-mk-cascade='rise'] { position: relative; }
+@media (prefers-reduced-motion: reduce) { .mk-editorial-reveal *, .mk-editorial-reveal *::after, .mk-editorial-reveal *::before { animation: none !important; transition: none !important; } }

package/src/recipes/film-hero/README.md

@@ -0,0 +1,23 @@
+# film-hero
+
+Hero editorial de cine: líneas ascendentes, reglas que se trazan, imagen/video con escala y parallax dentro del contenedor de scroll. Componer con `action-button`, `details` y `trailer` para una ficha completa. La demo incluye créditos, premios, un selector de siguiente producción y medios locales originales.
+
+```html
+<section class="mk-film-hero" data-mk="film-hero">
+  <h1 class="mk-film-hero__title">
+    <span class="mk-film-hero__mask"><span data-mk-film-line>Una historia</span></span>
+  </h1>
+  <span data-mk-film-rule></span>
+  <div class="mk-film-hero__visual">
+    <img class="mk-film-hero__media" src="/mi-imagen.jpg" alt="…" />
+  </div>
+</section>
+```
+
+`createFilmHero(root, { duration:.7, stagger:.08, parallax:.12, scale:1.08, edge:'organic', scroller })` → `replay()`, `refresh()`, `destroy()`. React: `useFilmHero(ref, options, deps?)`. Para demos/paneles con scroll, marcar el contenedor `data-mk-scroll-root` o pasar `scroller`; no requiere scroll global ni Lenis. `edge:'straight'` conserva el recorte rectangular.
+
+Las líneas se marcan explícitamente; no cambia el HTML del título ni duplica su nombre accesible. Reduced-motion deja visibles texto/reglas y desactiva parallax. Sin JavaScript el contenido sigue visible. El observer, rAF pendiente, listeners, GSAP y estilos se revierten con `destroy()`.
+
+El borde `organic` es un polígono CSS estático **aproximado**. El A24 original usa un algoritmo procedural con ruido, respuesta al cursor y disolución al scroll, además de un disco Three para la siguiente producción. Esta receta no incluye ese algoritmo ni afirma equivalencia. El disco CSS de la demo es otra aproximación decorativa. Las duraciones .7/.9s y stagger proceden de las fuentes inspeccionadas; `power3.out` reemplaza la curva custom del original. No incluye assets ni tipografías de A24.
+
+Tokens: `--mk-film-ink`, `--mk-film-paper`, `--mk-film-font`; el motor escribe y restaura `--mk-film-shift`/`--mk-film-scale`.

package/src/recipes/film-hero/create-film-hero.ts

@@ -0,0 +1,65 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { entrances, reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface FilmHeroOptions {
+  duration?: number;
+  stagger?: number;
+  /** Media travel as a fraction of the hero height. 0 disables parallax. */
+  parallax?: number;
+  scale?: number;
+  edge?: 'organic' | 'straight';
+  /** Scrollable demo panels and nested page shells can supply their own scroll root. */
+  scroller?: HTMLElement | Window;
+}
+export interface FilmHeroInstance extends Instance { replay(): void; refresh(): void; }
+
+/** Editorial line reveals with scoped, scroll-driven media. Organic edge is an approximation. */
+export function createFilmHero(root: HTMLElement | null, options: FilmHeroOptions = {}): FilmHeroInstance {
+  if (!root) return inert({ replay() {}, refresh() {} });
+  const scope = createScope();
+  scope.attr(root, 'data-mk-film-ready', '');
+  scope.attr(root, 'data-mk-film-edge', options.edge ?? 'organic');
+  scope.attr(root, 'style', root.getAttribute('style'));
+  const still = reduced();
+  const lines = [...root.querySelectorAll<HTMLElement>('[data-mk-film-line]')];
+  const rules = [...root.querySelectorAll<HTMLElement>('[data-mk-film-rule]')];
+  [...lines, ...rules].forEach(element => scope.attr(element, 'style', element.getAttribute('style')));
+  let timeline: gsap.core.Timeline | null = null;
+  const context = gsap.context(() => {}, root);
+  const replay = () => {
+    if (scope.disposed || !entrances()) return;
+    registerMotion();
+    context.add(() => {
+      timeline?.kill();
+      timeline = gsap.timeline();
+      if (lines.length) timeline.fromTo(lines, { yPercent: 120 }, { yPercent: 0, duration: options.duration ?? .7, stagger: options.stagger ?? .08, ease: 'power3.out' }, 0);
+      if (rules.length) timeline.fromTo(rules, { scaleX: 0, transformOrigin: 'left center' }, { scaleX: 1, duration: .9, stagger: .06, ease: 'power3.out' }, .08);
+    });
+  };
+  replay();
+  const scroller = options.scroller ?? root.closest<HTMLElement>('[data-mk-scroll-root]') ?? window;
+  let frame = 0;
+  const refresh = () => {
+    if (scope.disposed || still) return;
+    const rect = root.getBoundingClientRect();
+    const view = scroller instanceof HTMLElement ? scroller.getBoundingClientRect() : { top: 0, height: window.innerHeight };
+    const progress = Math.max(0, Math.min(1, (view.top - rect.top) / Math.max(1, rect.height)));
+    root.style.setProperty('--mk-film-shift', `${(progress * rect.height * (options.parallax ?? .12)).toFixed(2)}px`);
+    root.style.setProperty('--mk-film-scale', String((options.scale ?? 1.08) - progress * Math.max(0, (options.scale ?? 1.08) - 1)));
+  };
+  if (!still) {
+    const schedule = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => { frame = 0; refresh(); });
+    };
+    scope.on(scroller, 'scroll', schedule, { passive: true });
+    scope.on(window, 'resize', schedule, { passive: true });
+    if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(schedule)).observe(root);
+    scope.add(() => cancelAnimationFrame(frame));
+    refresh();
+  }
+  scope.add(() => { timeline?.kill(); context.revert(); });
+  return { replay, refresh, destroy: () => scope.dispose() };
+}

package/src/recipes/film-hero/film-hero.css

@@ -0,0 +1,29 @@
+.mk-film-hero {
+  --mk-film-ink: var(--mk-text, #191b18);
+  --mk-film-paper: var(--mk-surface, #f4f1e8);
+  --mk-film-font: Georgia, 'Times New Roman', serif;
+  position: relative;
+  isolation: isolate;
+  color: var(--mk-film-ink);
+  background: var(--mk-film-paper);
+  overflow: clip;
+}
+.mk-film-hero__credits { padding: clamp(20px, 5cqw, 64px); text-align: center; }
+.mk-film-hero__eyebrow { font: 500 .65rem/1.5 var(--mk-font-mono, monospace); text-transform: uppercase; letter-spacing: .18em; }
+.mk-film-hero__title { margin: .2em 0 .35em; font: 400 clamp(3.5rem, 10cqw, 8rem)/.82 var(--mk-film-font); letter-spacing: -.065em; text-transform: uppercase; }
+.mk-film-hero__mask { display: block; overflow: clip; padding-bottom: .08em; margin-bottom: -.08em; }
+[data-mk-film-line] { display: block; }
+[data-mk-film-rule] { display: block; height: 1px; border: 0; background: currentColor; margin: 16px 0; }
+.mk-film-hero__metadata { display: grid; gap: 0; margin: 24px 0 0; font: .8rem/1.5 var(--mk-font, sans-serif); }
+.mk-film-hero__metadata > div { display: flex; align-items: baseline; justify-content: space-between; gap: 20px; padding: 8px 0; border-top: 1px solid currentColor; }
+.mk-film-hero__metadata dt { font: .6rem/1.5 var(--mk-font-mono, monospace); text-transform: uppercase; letter-spacing: .14em; }
+.mk-film-hero__metadata dd { margin: 0; text-align: right; }
+.mk-film-hero__visual { position: relative; min-height: clamp(260px, 45cqw, 540px); display: grid; place-items: center; overflow: clip; color: #fffdf1; background: #243c36; }
+.mk-film-hero__media { position: absolute; inset: -8% 0; width: 100%; height: 116%; object-fit: cover; transform: translateY(var(--mk-film-shift, 0px)) scale(var(--mk-film-scale, 1)); transform-origin: center; }
+.mk-film-hero__visual::after { content: ''; position: absolute; inset: 0; pointer-events: none; background: linear-gradient(transparent, #00120c66); }
+.mk-film-hero__caption { position: relative; z-index: 1; padding: 48px 24px; text-align: center; }
+.mk-film-hero__caption blockquote { font: 400 clamp(2.25rem, 6cqw, 5.5rem)/.95 var(--mk-film-font); letter-spacing: -.04em; margin: 0 0 24px; text-transform: uppercase; }
+.mk-film-hero[data-mk-film-edge="organic"] .mk-film-hero__visual {
+  clip-path: polygon(0 7%, 9% 8%, 20% 5%, 32% 2%, 43% 0, 54% 2%, 68% 6%, 82% 8%, 93% 6%, 100% 4%, 100% 100%, 0 100%);
+}
+@media (prefers-reduced-motion: reduce) { .mk-film-hero__media { transform: none; } }

package/src/recipes/font-cycle/README.md

@@ -0,0 +1,11 @@
+# font-cycle
+
+Caras tipográficas alternadas por carácter, con copia enmascarada que entra al hover y al foco. Adaptación de la tipografía de Mat Voyce; el original también superpone GIFs. No incluye fuentes ni ilustraciones del sitio.
+
+```html
+<button class="mk-font-cycle" data-mk="font-cycle" data-mk-font-alternate="Georgia, serif">Explore</button>
+```
+
+`createFontCycle(root, { faces, text, duration: .6, stagger: .035, overlaySrc })` devuelve `play()`, `reset()`, `active`, `destroy()`. Duraciones en segundos, ease `power3.out`. `faces` es una tupla de `{ family?, axes?: { wght: 500, wdth: 75 }, weight?, style? }`; cada carácter alterna las dos caras. Los ejes que no admita la fuente no tienen efecto. `overlaySrc` (o `data-mk-font-overlay`) es una imagen decorativa propia, opcional.
+
+React: `useFontCycle(ref, options, deps)`. La receta administra los hijos del elemento mientras está montada; no cambies sus hijos durante ese intervalo. Una copia accesible conserva el texto sin duplicar letras. El foco activa el mismo efecto que hover; con movimiento reducido el cambio es inmediato y no se muestra la imagen animada. `destroy()` restaura los nodos y atributos originales.

package/src/recipes/font-cycle/create-font-cycle.ts

@@ -0,0 +1,126 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { splitGraphemes } from '../../core/split';
+import { inert, type Instance } from '../../core/types';
+
+export interface FontCycleFace {
+  /** A font supplied by the application. No font files are downloaded by this recipe. */
+  family?: string;
+  axes?: Readonly<Record<string, number>>;
+  weight?: number;
+  style?: 'normal' | 'italic' | 'oblique';
+}
+
+export interface FontCycleOptions {
+  text?: string;
+  /** Alternated per character; the second face rolls in on hover or focus. */
+  faces?: readonly [FontCycleFace, FontCycleFace];
+  /** Seconds per character. */
+  duration?: number;
+  /** Seconds between characters. */
+  stagger?: number;
+  /** Optional decorative artwork owned by the consumer. Hidden with reduced motion. */
+  overlaySrc?: string;
+}
+
+export interface FontCycleInstance extends Instance {
+  play(): void;
+  reset(): void;
+  readonly active: boolean;
+}
+
+function applyFace(element: HTMLElement, face: FontCycleFace) {
+  if (face.family) element.style.fontFamily = face.family;
+  if (face.weight !== undefined) element.style.fontWeight = String(face.weight);
+  if (face.style) element.style.fontStyle = face.style;
+  const axes = Object.entries(face.axes ?? {}).filter(([tag, value]) => /^[\w ]{4}$/.test(tag) && Number.isFinite(value));
+  if (axes.length) element.style.fontVariationSettings = axes.map(([tag, value]) => `"${tag}" ${value}`).join(', ');
+}
+
+/** Alternating variable-font faces in a masked, reversible character roll. */
+export function createFontCycle(root: HTMLElement | null, options: FontCycleOptions = {}): FontCycleInstance {
+  if (!root || typeof document === 'undefined') return inert({ play() {}, reset() {}, active: false });
+  registerMotion();
+  const scope = createScope();
+  const original = [...root.childNodes];
+  const text = options.text ?? root.textContent ?? '';
+  const faces = options.faces ?? [
+    { weight: 500, axes: { wght: 500, wdth: 75 } },
+    { family: root.dataset.mkFontAlternate, weight: 900, axes: { wght: 900, wdth: 125 } },
+  ];
+  const duration = Math.max(0, options.duration ?? 0.6);
+  const stagger = Math.max(0, options.stagger ?? 0.035);
+  const tracks: HTMLElement[] = [];
+  let animation: gsap.core.Tween | undefined;
+  let active = false;
+  let hovered = false;
+  let focused = false;
+
+  const copy = document.createElement('span');
+  copy.className = 'mk-font-cycle__accessible';
+  copy.textContent = text;
+  const visual = document.createElement('span');
+  visual.className = 'mk-font-cycle__visual';
+  visual.setAttribute('aria-hidden', 'true');
+  for (const [index, letter] of splitGraphemes(text, Number.MAX_SAFE_INTEGER).entries()) {
+    const character = document.createElement('span');
+    character.className = 'mk-font-cycle__char';
+    const track = document.createElement('span');
+    track.className = 'mk-font-cycle__track';
+    for (let side = 0; side < 2; side++) {
+      const face = document.createElement('span');
+      face.className = 'mk-font-cycle__face';
+      face.textContent = letter === ' ' ? '\u00a0' : letter;
+      applyFace(face, faces[(index + side) % 2]!);
+      const sizer = face.cloneNode(true) as HTMLElement;
+      sizer.className = 'mk-font-cycle__sizer';
+      character.append(sizer);
+      track.append(face);
+    }
+    character.append(track);
+    visual.append(character);
+    tracks.push(track);
+  }
+  root.replaceChildren(copy, visual);
+  const overlaySrc = options.overlaySrc ?? root.dataset.mkFontOverlay;
+  if (overlaySrc) {
+    const overlay = document.createElement('img');
+    overlay.className = 'mk-font-cycle__overlay';
+    overlay.alt = '';
+    overlay.setAttribute('aria-hidden', 'true');
+    scope.attr(root, 'data-mk-font-overlay-ready', null);
+    const loaded = () => {
+      if (!scope.disposed) scope.attr(root, 'data-mk-font-overlay-ready', overlay.naturalWidth > 0 ? '' : null);
+    };
+    scope.on(overlay, 'load', loaded);
+    scope.on(overlay, 'error', () => {
+      if (!scope.disposed) scope.attr(root, 'data-mk-font-overlay-ready', null);
+    });
+    overlay.src = overlaySrc;
+    root.append(overlay);
+    if (overlay.complete) loaded();
+  }
+  scope.add(() => root.replaceChildren(...original));
+  scope.attr(root, 'class', `${root.className} mk-font-cycle`.trim());
+  scope.attr(root, 'data-mk-ready', '');
+
+  const setActive = (next: boolean) => {
+    if (scope.disposed || next === active) return;
+    active = next;
+    scope.attr(root, 'data-mk-active', next ? '' : null);
+    animation?.kill();
+    if (reduced() || duration === 0) gsap.set(tracks, { yPercent: next ? -50 : 0 });
+    else animation = gsap.to(tracks, { yPercent: next ? -50 : 0, duration, stagger, ease: 'power3.out', overwrite: true });
+  };
+  scope.on(root, 'mouseenter', () => { hovered = true; setActive(true); });
+  scope.on(root, 'mouseleave', () => { hovered = false; setActive(focused); });
+  scope.on(root, 'focusin', () => { focused = true; setActive(true); });
+  scope.on(root, 'focusout', (event) => {
+    if (event.relatedTarget instanceof Node && root.contains(event.relatedTarget)) return;
+    focused = false;
+    setActive(hovered);
+  });
+  scope.add(() => animation?.kill());
+  return { play: () => setActive(true), reset: () => setActive(false), get active() { return active; }, destroy: () => scope.dispose() };
+}

package/src/recipes/font-cycle/font-cycle.css

@@ -0,0 +1,36 @@
+.mk-font-cycle {
+  position: relative;
+  display: inline-block;
+  color: inherit;
+  font-family: var(--mk-font, sans-serif);
+  isolation: isolate;
+}
+.mk-font-cycle__accessible {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.mk-font-cycle__visual { display: inline-flex; white-space: pre; }
+.mk-font-cycle__char {
+  position: relative;
+  display: inline-grid;
+  overflow: hidden;
+  line-height: 1.12;
+  vertical-align: bottom;
+}
+.mk-font-cycle__sizer { grid-area: 1 / 1; visibility: hidden; padding-inline: .035em; }
+.mk-font-cycle__track { position: absolute; inset: 0 0 auto; display: flex; flex-direction: column; will-change: transform; }
+.mk-font-cycle__face { display: block; flex: none; text-align: center; padding-inline: .035em; }
+.mk-font-cycle__overlay { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; pointer-events: none; opacity: 0; }
+.mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__overlay { opacity: 1; }
+.mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__visual { opacity: 0; }
+.mk-font-cycle:focus-visible { outline: 2px solid var(--mk-accent, currentColor); outline-offset: .15em; }
+@media (prefers-reduced-motion: reduce) {
+  .mk-font-cycle__track { will-change: auto; }
+  .mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__visual { opacity: 1; }
+  .mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__overlay { display: none; }
+}

package/src/recipes/image-zoom/README.md

@@ -0,0 +1,16 @@
+# image-zoom
+
+Contrazoom inspirado en las categorías de [Bernice](https://bernicebakery.com/collections/cakes). Marco 1→1.1 e imagen 1.2→1 en 1 s con cubic-bezier(.28,.71,0,.98).
+
+```html
+<a class="mk-image-zoom" data-mk="image-zoom" href="/collection">
+  <span data-mk-zoom-frame style="border-radius:50%;width:10rem;height:10rem">
+    <img src="/image.jpg" width="400" height="400" alt="Descripción" />
+  </span>
+  <strong>Colección</strong>
+</a>
+```
+
+`createImageZoom(root,{duration:1,frameScale:1.1,imageScale:1.2})`, `autoInit()`, `useImageZoom(ref,options,deps)`. API `open(boolean)`, `active`, `destroy()`.
+
+Hover/focus revelan el mismo efecto. Root puede contener imagen, video o picture dentro de frame. Para marcado distinto usar `data-mk-zoom-image` en el elemento que escala (evitar marcar también su padre). Variables: `--mk-zoom-duration`, `--mk-zoom-frame-scale`, `--mk-zoom-image-scale`, `--mk-zoom-ease`. Sin transformaciones bajo movimiento reducido; las imágenes siguen accesibles.

package/src/recipes/image-zoom/create-image-zoom.ts

@@ -0,0 +1,27 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface ImageZoomOptions { duration?: number; frameScale?: number; imageScale?: number; }
+export interface ImageZoomInstance extends Instance { open(active: boolean): void; readonly active: boolean; }
+
+/** Counter-zoom: the clipped frame grows as the picture inside settles to 1×. */
+export function createImageZoom(root: HTMLElement | null, options: ImageZoomOptions = {}): ImageZoomInstance {
+  if (!root) return inert({ open() {}, active: false });
+  const scope = createScope();
+  let active = false;
+  let pointer = false;
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  const setVariable = (name: string, value: number | undefined, suffix = '') => {
+    if (Number.isFinite(value)) root.style.setProperty(name, `${Math.max(0, value!)}${suffix}`);
+  };
+  setVariable('--mk-zoom-duration', options.duration, 's');
+  setVariable('--mk-zoom-frame-scale', options.frameScale);
+  setVariable('--mk-zoom-image-scale', options.imageScale);
+  const set = (on: boolean) => { if (!scope.disposed) { active = on; scope.attr(root, 'data-mk-active', on ? '' : null); } };
+  scope.on(root, 'pointerenter', () => { pointer = true; set(true); });
+  scope.on(root, 'pointerleave', () => { pointer = false; if (!root.contains(document.activeElement)) set(false); });
+  scope.on(root, 'focusin', () => set(true));
+  scope.on(root, 'focusout', (event) => { if (!pointer && !root.contains((event as FocusEvent).relatedTarget as Node | null)) set(false); });
+  return { open: set, get active() { return active; }, destroy: () => scope.dispose() };
+}

package/src/recipes/image-zoom/image-zoom.css

@@ -0,0 +1,7 @@
+.mk-image-zoom { --mk-zoom-duration: 1s; --mk-zoom-frame-scale: 1.1; --mk-zoom-image-scale: 1.2; --mk-zoom-ease: cubic-bezier(.28,.71,0,.98); color: inherit; text-decoration: none; }
+.mk-image-zoom [data-mk-zoom-frame] { display: block; overflow: hidden; border-radius: inherit; transition: transform var(--mk-zoom-duration) var(--mk-zoom-ease); }
+.mk-image-zoom [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom [data-mk-zoom-image] { display: block; width: 100%; height: 100%; object-fit: cover; transform: scale(var(--mk-zoom-image-scale)); transition: transform var(--mk-zoom-duration) var(--mk-zoom-ease); }
+.mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-frame] { transform: scale(var(--mk-zoom-frame-scale)); }
+.mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-image] { transform: scale(1); }
+.mk-image-zoom:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 5px; }
+@media (prefers-reduced-motion: reduce) { .mk-image-zoom [data-mk-zoom-frame], .mk-image-zoom [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom [data-mk-zoom-image] { transform: none !important; transition: none; } }

package/src/recipes/joined-cta/README.md

@@ -0,0 +1,13 @@
+# joined-cta
+
+CTA inspirado en [Silvia Sguotti](https://silviasguotti.design/): tres cápsulas que se desplazan, giran y se unen. El CSS público declara .5 s ease-in-out.
+
+```html
+<button type="button" class="mk-joined-cta" data-mk="joined-cta" aria-label="Keep in touch">
+  <span>KEEP</span><span>IN</span><span>TOUCH</span>
+</button>
+```
+
+`createJoinedCta(root,{duration:.5})`, `autoInit()`, o `useJoinedCta(ref,options,deps)`. Se puede usar un enlace real en lugar del botón. API `expand()`, `collapse()`, `expanded`, `destroy()`.
+
+Hover y foco equivalentes. En touch o pantallas <=420px se presenta una cápsula legible sin giro. Movimiento reducido conserva el cambio de estado instantáneo. Variables: `--mk-joined-duration`, `--mk-joined-bg`, `--mk-joined-color`. El contenido debe tener exactamente tres spans. No incluye navegación ni envío de correo.

package/src/recipes/joined-cta/create-joined-cta.ts

@@ -0,0 +1,22 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface JoinedCtaOptions { duration?: number; }
+export interface JoinedCtaInstance extends Instance { expand(): void; collapse(): void; readonly expanded: boolean; }
+
+/** Silvia's three contact capsules joining into one. Motion is entirely CSS. */
+export function createJoinedCta(root: HTMLElement | null, options: JoinedCtaOptions = {}): JoinedCtaInstance {
+  if (!root) return inert({ expand() {}, collapse() {}, expanded: false });
+  const scope = createScope();
+  let expanded = false;
+  let pointer = false;
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  if (Number.isFinite(options.duration)) root.style.setProperty('--mk-joined-duration', `${Math.max(0, options.duration!)}s`);
+  const set = (value: boolean) => { if (!scope.disposed) { expanded = value; scope.attr(root, 'data-mk-expanded', value ? '' : null); } };
+  scope.on(root, 'pointerenter', () => { pointer = true; set(true); });
+  scope.on(root, 'pointerleave', () => { pointer = false; if (!root.contains(document.activeElement)) set(false); });
+  scope.on(root, 'focusin', () => set(true));
+  scope.on(root, 'focusout', (event) => { if (!pointer && !root.contains((event as FocusEvent).relatedTarget as Node | null)) set(false); });
+  return { expand: () => set(true), collapse: () => set(false), get expanded() { return expanded; }, destroy: () => scope.dispose() };
+}

package/src/recipes/joined-cta/joined-cta.css

@@ -0,0 +1,17 @@
+.mk-joined-cta { --mk-joined-duration: .5s; --mk-joined-bg: var(--mk-text); --mk-joined-color: var(--mk-bg); position: relative; display: inline-flex; align-items: center; justify-content: center; width: 17.7rem; height: 5.9rem; max-width: 100%; border: 0; padding: 0; background: transparent; text-decoration: none; color: var(--mk-joined-color); cursor: pointer; font: inherit; isolation: isolate; border-radius: var(--mk-radius-full); }
+.mk-joined-cta::before { content: ''; position: absolute; left: 0; width: 7.3rem; height: 5.9rem; border-radius: 100px; background: var(--mk-joined-bg); z-index: -1; transition: width var(--mk-joined-duration) ease-in-out; }
+.mk-joined-cta > span { position: relative; display: grid; place-items: center; flex-shrink: 0; background: var(--mk-joined-bg); border-radius: 100px; height: 5.9rem; transition: left var(--mk-joined-duration) ease-in-out, height var(--mk-joined-duration) ease-in-out, transform var(--mk-joined-duration) ease-in-out, background var(--mk-joined-duration); }
+.mk-joined-cta > span:nth-child(1) { width: 7.3rem; left: 0; }
+.mk-joined-cta > span:nth-child(2) { width: 4.5rem; left: 0; z-index: 2; }
+.mk-joined-cta > span:nth-child(3) { width: 5.9rem; height: 3.05rem; left: -1.45rem; transform: rotate(-90deg); }
+.mk-joined-cta:is(:hover,:focus-visible,[data-mk-expanded])::before { width: 17.7rem; }
+.mk-joined-cta:is(:hover,:focus-visible,[data-mk-expanded]) > span:nth-child(1) { left: 3.2rem; }
+.mk-joined-cta:is(:hover,:focus-visible,[data-mk-expanded]) > span:nth-child(2) { left: -.75rem; background: transparent; }
+.mk-joined-cta:is(:hover,:focus-visible,[data-mk-expanded]) > span:nth-child(3) { left: -3.65rem; height: 5.9rem; transform: rotate(0); }
+.mk-joined-cta:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 5px; }
+@media (hover: none), (max-width: 420px) {
+  .mk-joined-cta { width: auto; height: auto; padding: 1.25rem 2rem; gap: .3em; background: var(--mk-joined-bg); }
+  .mk-joined-cta::before { display: none; }
+  .mk-joined-cta > span:nth-child(n) { width: auto; height: auto; left: 0; transform: none; background: transparent; }
+}
+@media (prefers-reduced-motion: reduce) { .mk-joined-cta::before, .mk-joined-cta > span { transition: none; } }

package/src/recipes/local-clock/README.md

@@ -0,0 +1,31 @@
+# local-clock
+
+La hora de otra zona en vivo, como el «20:48 local time» del contacto de DOVV Studio. Se actualiza justo al cambiar el minuto (o el segundo, con `seconds`). En un `<time>` también mantiene el atributo `datetime`.
+
+## Vanilla / Astro
+
+```html
+<p><span class="mk-status__dot"></span> <time data-mk="local-clock" data-mk-time-zone="America/Mexico_City">--:--</time> hora local</p>
+```
+
+Con `autoInit()` las opciones van como `data-mk-<opción>`. Sin `autoInit`: `createLocalClock(el, opciones)`, que devuelve `text` y `destroy()`. El contenido inicial (por ejemplo `--:--`) se ve sin JavaScript y vuelve con `destroy()`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLTimeElement>(null);
+useLocalClock(ref, { timeZone: 'America/Argentina/Buenos_Aires' });
+return <time ref={ref}>--:--</time>;
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `timeZone` | la del visitante | Zona IANA |
+| `locale` | `'es'` | Idioma del formato |
+| `hour12` | `false` | 12 h con a. m./p. m. |
+| `seconds` | `false` | Mostrar y actualizar segundos |
+| `format` | — | `Intl.DateTimeFormatOptions` completo |
+
+Una zona o un idioma desconocidos usan los del visitante en lugar de fallar. No anuncia cada cambio a lectores de pantalla.

package/src/recipes/local-clock/create-local-clock.ts

@@ -0,0 +1,61 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+/*
+ * Local clock (DOVV Studio contact: "20:48 local time"): the time in a given
+ * zone, refreshed on the minute (or the second). A <time> element also gets
+ * its datetime attribute. The text node is replaced; destroy() puts it back.
+ */
+
+export interface LocalClockOptions {
+  /** IANA zone, e.g. "America/Mexico_City". The visitor's zone by default. */
+  timeZone?: string;
+  locale?: string;
+  hour12?: boolean;
+  seconds?: boolean;
+  /** Full control over the format (overrides hour12/seconds). */
+  format?: Intl.DateTimeFormatOptions;
+}
+
+export interface LocalClockInstance extends Instance {
+  /** Text currently shown. */
+  readonly text: string;
+}
+
+export function createLocalClock(root: HTMLElement | null, options: LocalClockOptions = {}): LocalClockInstance {
+  if (!root) return inert({ text: '' });
+  const scope = createScope();
+  const original = [...root.childNodes];
+  scope.add(() => root.replaceChildren(...original));
+  scope.attr(root, 'data-mk-ready', '');
+  let formatter: Intl.DateTimeFormat;
+  try {
+    formatter = new Intl.DateTimeFormat(options.locale ?? 'es', options.format ?? {
+      hour: '2-digit',
+      minute: '2-digit',
+      ...(options.seconds ? { second: '2-digit' } : {}),
+      hour12: options.hour12 ?? false,
+      timeZone: options.timeZone,
+    });
+  } catch {
+    // Unknown zone or locale: the visitor's own.
+    formatter = new Intl.DateTimeFormat(undefined, { hour: '2-digit', minute: '2-digit', hour12: options.hour12 ?? false });
+  }
+  let text = '';
+  const isTime = root instanceof HTMLTimeElement;
+  const render = () => {
+    const now = new Date();
+    text = formatter.format(now);
+    if (root.textContent !== text) root.textContent = text;
+    if (isTime) scope.attr(root, 'datetime', now.toISOString());
+  };
+  const step = options.seconds || options.format?.second ? 1000 : 60000;
+  const schedule = () => {
+    // Land just after the next boundary so the minute flips with the system clock.
+    const wait = step - (Date.now() % step) + 20;
+    scope.timeout(() => { if (!scope.disposed) { render(); schedule(); } }, wait);
+  };
+  render();
+  schedule();
+  return { get text() { return text; }, destroy: () => scope.dispose() };
+}