@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/pop/README.md

@@ -0,0 +1,36 @@
+# pop
+
+Un elemento entra escalando de .7 a 1 con rebote.
+
+Origen: spencergabor.com — imágenes de proyecto.
+
+## Vanilla / Astro
+
+```html
+<img data-mk="pop" src="photo.jpg" alt="Retrato">
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createPop(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLImageElement>(null);
+usePop(ref, { scale: .8 });
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `scale` | `.7` | Escala inicial |
+| `duration` | `1.1` | Segundos |
+| `delay` | `0` | Segundos |
+| `trigger` | `'scroll'` | 'scroll', 'load' o 'manual' |
+| `start` | `'top 85%'` | Inicio del ScrollTrigger |
+
+## Controles
+
+`play()`, `destroy()`
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/pop/create-pop.ts

@@ -0,0 +1,52 @@
+import { gsap, ELASTIC, ScrollTrigger, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/* Elastic scale-in for a single element (spencergabor.com project images, scale .7 → 1). */
+
+export interface PopOptions {
+  scale?: number;
+  duration?: number;
+  delay?: number;
+  trigger?: 'scroll' | 'load' | 'manual';
+  start?: string;
+}
+
+export interface PopInstance extends Instance {
+  play(): void;
+}
+
+export function createPop(el: HTMLElement | null, options: PopOptions = {}): PopInstance {
+  if (!el) {
+    warnOnce('pop: missing element');
+    return inert({ play() {} });
+  }
+  registerMotion();
+  const { scale = 0.7, duration = 1.1, delay = 0, trigger = 'scroll', start = 'top 85%' } = options;
+  const animate = entrances();
+  const ctx = gsap.context(() => {});
+  let played = !animate;
+
+  const play = () => {
+    if (played) return;
+    played = true;
+    ctx.add(() => gsap.to(el, { scale: 1, autoAlpha: 1, duration, delay, ease: ELASTIC }));
+  };
+
+  if (animate) {
+    ctx.add(() => {
+      gsap.set(el, { scale, autoAlpha: 0 });
+      if (trigger === 'load') play();
+      else if (trigger !== 'manual') ScrollTrigger.create({ trigger: el, start, end: 'max', once: true, onEnter: play });
+    });
+  }
+  el.dataset.mkReady = '';
+
+  return {
+    play,
+    destroy() {
+      ctx.revert();
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/radial-menu/README.md

@@ -0,0 +1,44 @@
+# radial-menu
+
+Un botón redondo cuyas opciones salen en arco con rebote; cerrado, las opciones quedan `inert`. Cierra con Escape y al pulsar fuera.
+
+Origen: spencergabor.com — selector de color.
+
+## Vanilla / Astro
+
+```html
+<div data-mk="radial-menu" class="settings">
+  <button data-mk-item aria-label="Modo oscuro">☾</button>
+  <button data-mk-item aria-label="Idioma">ES</button>
+  <button data-mk-toggle aria-label="Ajustes">◐</button>
+</div>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createRadialMenu(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const menu = useRadialMenu(ref, { onToggle: setOpen });
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `radius` | `'3.6rem'` | Distancia de las opciones |
+| `startAngle` | `1.5708` | Ángulo de la primera opción (rad; π/2 = izquierda) |
+| `spacing` | `.9` | Ángulo entre opciones (rad) |
+| `closeOnOutside` | `true` | Cerrar al pulsar fuera |
+| `onToggle(open)` | — | Callback |
+
+## Controles
+
+`open()`, `close()`, `toggle()`, `isOpen`, `destroy()`
+
+## CSS
+
+El toggle y las opciones son hijos directos del root (rejilla de una celda). Las posiciones salen de `--mk-i`, `--mk-radius`, `--mk-start` y `--mk-spacing`.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/radial-menu/create-radial-menu.ts

@@ -0,0 +1,96 @@
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * spencergabor.com colour picker, generalised: options fan out in an arc from a
+ * round toggle (CSS trig on --mk-i), elastic, 50 ms apart. Closed options are
+ * `inert`, so they are skipped by Tab and screen readers.
+ */
+
+export interface RadialMenuOptions {
+  /** Distance of the options from the toggle (any CSS length). */
+  radius?: string;
+  /** Angle of the first option, radians (π/2 → left, 0 → down). */
+  startAngle?: number;
+  /** Angle between options, radians. */
+  spacing?: number;
+  closeOnOutside?: boolean;
+  onToggle?: (open: boolean) => void;
+}
+
+export interface RadialMenuInstance extends Instance {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  readonly isOpen: boolean;
+}
+
+const noop = { open() {}, close() {}, toggle() {}, isOpen: false };
+
+export function createRadialMenu(root: HTMLElement | null, options: RadialMenuOptions = {}): RadialMenuInstance {
+  const toggleEl = root?.querySelector<HTMLElement>('[data-mk-toggle]');
+  const items = root ? [...root.querySelectorAll<HTMLElement>('[data-mk-item]')] : [];
+  if (!root || !toggleEl || !items.length) {
+    warnOnce('radial-menu: needs a [data-mk-toggle] and at least one [data-mk-item]');
+    return inert(noop);
+  }
+  const scope = createScope();
+
+  // Remember what we overwrite so destroy() can put it back.
+  const expandedBefore = toggleEl.getAttribute('aria-expanded');
+  const inertBefore = items.map((item) => item.hasAttribute('inert'));
+  const vars: Array<[string, string | undefined]> = [
+    ['--mk-radius', options.radius],
+    ['--mk-start', options.startAngle?.toString()],
+    ['--mk-spacing', options.spacing?.toString()],
+  ];
+  vars.forEach(([name, value]) => value !== undefined && root.style.setProperty(name, value));
+  items.forEach((item, i) => item.style.setProperty('--mk-i', String(i)));
+
+  let open = false;
+  const set = (next: boolean) => {
+    open = next;
+    root.toggleAttribute('data-mk-open', open);
+    toggleEl.setAttribute('aria-expanded', String(open));
+    items.forEach((item) => (item.inert = !open));
+    options.onToggle?.(open);
+  };
+  set(false);
+
+  scope.on(toggleEl, 'click', () => set(!open));
+  scope.on(root, 'keydown', (e: KeyboardEvent) => {
+    if (e.key !== 'Escape' || !open) return;
+    set(false);
+    toggleEl.focus();
+  });
+  if (options.closeOnOutside ?? true) {
+    scope.on(document, 'pointerdown', (e: PointerEvent) => {
+      if (open && !root.contains(e.target as Node)) set(false);
+    });
+  }
+  root.dataset.mkReady = '';
+
+  scope.add(() => {
+    root.removeAttribute('data-mk-open');
+    delete root.dataset.mkReady;
+    if (expandedBefore === null) toggleEl.removeAttribute('aria-expanded');
+    else toggleEl.setAttribute('aria-expanded', expandedBefore);
+    items.forEach((item, i) => {
+      item.inert = inertBefore[i]!;
+      item.style.removeProperty('--mk-i');
+      if (!item.getAttribute('style')) item.removeAttribute('style');
+    });
+    vars.forEach(([name]) => root.style.removeProperty(name));
+    if (!root.getAttribute('style')) root.removeAttribute('style');
+  });
+
+  return {
+    open: () => set(true),
+    close: () => set(false),
+    toggle: () => set(!open),
+    get isOpen() {
+      return open;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/recipes/radial-menu/radial-menu.css

@@ -0,0 +1,45 @@
+/* radial-menu — spencergabor.com colour picker, generalised. Scoped to its root:
+   [data-mk-item] and [data-mk-open] are also used by other recipes and components. */
+
+[data-mk~="radial-menu"],
+.mk-radial {
+  display: grid;
+  place-items: center;
+  --mk-radius: 3.6rem;
+  --mk-start: 1.5708;
+  --mk-spacing: 0.9;
+}
+
+:is([data-mk~="radial-menu"], .mk-radial) > * {
+  grid-area: 1 / 1;
+}
+
+:is([data-mk~="radial-menu"], .mk-radial) [data-mk-toggle] {
+  position: relative;
+  z-index: 1;
+  transition: scale 0.8s var(--mk-ease-elastic);
+}
+
+:is([data-mk~="radial-menu"], .mk-radial) [data-mk-toggle]:active {
+  scale: 0.9;
+}
+
+:is([data-mk~="radial-menu"], .mk-radial) [data-mk-item] {
+  opacity: 0;
+  scale: 0.5;
+  transition:
+    translate 0.15s cubic-bezier(0.55, 0.055, 0.675, 0.19),
+    scale 0.15s cubic-bezier(0.55, 0.055, 0.675, 0.19),
+    opacity 0.15s;
+}
+
+:is([data-mk~="radial-menu"], .mk-radial)[data-mk-open] [data-mk-item] {
+  opacity: 1;
+  scale: 1;
+  translate:
+    calc(sin(var(--mk-i, 0) * var(--mk-spacing) + var(--mk-start)) * var(--mk-radius) * -1)
+    calc(cos(var(--mk-i, 0) * var(--mk-spacing) + var(--mk-start)) * var(--mk-radius));
+  transition-duration: 0.5s;
+  transition-timing-function: var(--mk-ease-elastic);
+  transition-delay: calc(var(--mk-i, 0) * 0.05s);
+}

package/src/recipes/reflow/README.md

@@ -0,0 +1,47 @@
+# reflow
+
+Cuando una lista cambia (ordenar, filtrar, añadir), los elementos viajan a su nuevo lugar con un resorte (0.62 s, razón .52) y los nuevos crecen desde 94 %.
+
+Origen: Stepbro — task-layout (`layoutReflow`, `FA(.52)` en el kit).
+
+## Vanilla / Astro
+
+```html
+<ul data-mk="reflow">
+  <li data-mk-item data-flip-id="t1">…</li>
+  <li data-mk-item data-flip-id="t2">…</li>
+</ul>
+```
+
+```js
+const reflow = createReflow(lista);
+reflow.capture();      // antes de cambiar el DOM
+reordenar(lista);      // tu cambio
+reflow.play();         // después
+```
+
+`data-flip-id` estable empareja cada elemento con su posición anterior. No pongas los elementos en `position: absolute`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLUListElement>(null);
+const reflow = useReflow(ref);
+const sort = () => { reflow.current?.capture(); setItems(sorted); };
+useLayoutEffect(() => reflow.current?.play(), [items]);
+```
+
+O `<FlipGroup>`, que hace la captura y la animación por ti.
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `selector` | `'[data-mk-item]'` | Elementos de la lista |
+| `duration` | `.62` | Segundos del viaje |
+
+## Controles
+
+`capture()`, `play()`, `destroy()`
+
+Con movimiento reducido los elementos cambian de sitio sin viajar.

package/src/recipes/reflow/create-reflow.ts

@@ -0,0 +1,49 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { TIMING } from '../../core/timing';
+import { captureLayout, reflowLayout, type CapturedLayout } from '../../motion/layout';
+
+/*
+ * Stepbro's layout reflow on a list: call `capture()` before changing the DOM
+ * and `play()` after it; moved items travel on a spring and new ones grow in.
+ * Give items a stable `data-flip-id` so moves pair up.
+ */
+
+export interface ReflowOptions {
+  selector?: string;
+  duration?: number;
+}
+
+export interface ReflowInstance extends Instance {
+  capture(): void;
+  play(): void;
+}
+
+export function createReflow(root: HTMLElement | null, options: ReflowOptions = {}): ReflowInstance {
+  if (!root) {
+    warnOnce('reflow: missing root');
+    return inert({ capture() {}, play() {} });
+  }
+  registerMotion();
+  const { selector = '[data-mk-item]', duration = TIMING.layoutTravel } = options;
+  const ctx = gsap.context(() => {});
+  let captured: CapturedLayout | null = null;
+  root.dataset.mkReady = '';
+
+  return {
+    capture() {
+      captured = captureLayout(root, selector);
+    },
+    play() {
+      if (!captured) return;
+      const state = captured;
+      captured = null;
+      ctx.add(() => reflowLayout(root, selector, state, { duration }));
+    },
+    destroy() {
+      ctx.revert();
+      captured = null;
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/repel-bento/README.md

@@ -0,0 +1,21 @@
+# repel-bento
+
+Bento con entrada spring y repulsión de tarjetas vecinas (Dousan).
+
+```html
+<div class="mk-repel-bento" data-mk="repel-bento"><article>Uno</article><article>Dos</article></div>
+```
+
+```ts
+import { createRepelBento } from '@yewdiel21/motion-kit';
+import { useRepelBento } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createRepelBento(root);
+instance.destroy();
+```
+
+`distance` máximo 30 px; `breakpoint` 1024. Entrada con spring 60/15 y desfase .006 s; repulsión de vecinos min(5000/distancia,30) con spring 300/25. `play()` repite la entrada; `reset()` vuelve al reposo. Bajo el breakpoint, puntero grueso y movimiento reducido no hay repulsión. Origen: Dousan `desktop-card-enter` y `neighbor-card-repulsion`.
+
+Vanilla declarativo: `autoInit(root)`. React: `useRepelBento(ref, options, deps)` devuelve una ref a la instancia; se destruye al desmontar. Con movimiento reducido no se ejecuta movimiento decorativo. `destroy()` restaura atributos y estilos y quita listeners, observers y nodos generados.
+
+Desde 0.8.0. Parámetros investigados en `REA - Dousan OFFFICE Siena/`; implementación propia, sin código ni assets de esos sitios.

package/src/recipes/repel-bento/create-repel-bento.ts

@@ -0,0 +1,65 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { motionSpring } from '../../core/physics-spring';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { clearStyles } from '../../core/styles';
+import { inert, type Instance } from '../../core/types';
+
+export interface RepelBentoOptions { distance?: number; breakpoint?: number; }
+export interface RepelBentoInstance extends Instance { play(): void; reset(): void; }
+
+export function createRepelBento(root: HTMLElement | null, options: RepelBentoOptions = {}): RepelBentoInstance {
+  if (!root || reduced()) return inert({ play() {}, reset() {} });
+  registerMotion();
+  const scope = createScope();
+  const items = [...root.children] as HTMLElement[];
+  const animations = new Map<HTMLElement, gsap.core.Tween>();
+  const defaults = TIMING.repelBento;
+  const enabled = () => innerWidth >= (options.breakpoint ?? defaults.breakpoint) && !matchMedia('(pointer: coarse)').matches;
+  items.forEach((item) => scope.attr(item, 'style', item.getAttribute('style')));
+  const animate = (item: HTMLElement, vars: gsap.TweenVars) => {
+    animations.get(item)?.kill();
+    animations.set(item, gsap.to(item, { ...vars, overwrite: true }));
+  };
+  const reset = () => {
+    if (scope.disposed) return;
+    items.forEach((item) => animate(item, { x: 0, y: 0, scale: 1, opacity: 1, ...motionSpring(...TIMING.springs.bentoRepel) }));
+  };
+  const play = () => {
+    if (scope.disposed || !enabled()) return;
+    items.forEach((item, index) => {
+      const rect = item.getBoundingClientRect();
+      gsap.set(item, { x: (rect.left + rect.width / 2 - innerWidth / 2) * defaults.offset, y: (rect.top + rect.height / 2 - innerHeight / 2) * defaults.offset, opacity: 0 });
+      animate(item, { x: 0, y: 0, opacity: 1, delay: index * defaults.stagger, ...motionSpring(...TIMING.springs.bentoEnter) });
+    });
+  };
+  items.forEach((hovered) => scope.on(hovered, 'pointerenter', () => {
+    if (!enabled()) return;
+    const origin = hovered.getBoundingClientRect();
+    items.forEach((item) => {
+      if (item === hovered) { animate(item, { x: 0, y: 0, scale: 1.02, opacity: 1, ...motionSpring(...TIMING.springs.bentoRepel) }); return; }
+      const rect = item.getBoundingClientRect();
+      const deltaX = rect.left + rect.width / 2 - origin.left - origin.width / 2;
+      const deltaY = rect.top + rect.height / 2 - origin.top - origin.height / 2;
+      const distance = Math.hypot(deltaX, deltaY);
+      const magnitude = distance > 0 ? Math.min(defaults.strength / distance, options.distance ?? defaults.distance) : 0;
+      animate(item, { x: distance ? deltaX / distance * magnitude : 0, y: distance ? deltaY / distance * magnitude : 0, scale: 1, opacity: 1, ...motionSpring(...TIMING.springs.bentoRepel) });
+    });
+  }));
+  scope.on(root, 'pointerleave', reset);
+  scope.on(window, 'resize', reset);
+  scope.add(() => {
+    animations.forEach((animation) => animation.kill());
+    clearStyles(items, ['transform', 'translate', 'rotate', 'scale', 'opacity']);
+  });
+  if (typeof IntersectionObserver === 'function') {
+    const observer = scope.observe(new IntersectionObserver(([entry]) => {
+      if (!entry?.isIntersecting) return;
+      play();
+      observer.disconnect();
+    }, { threshold: 0.15 }));
+    observer.observe(root);
+  } else play();
+  return { play, reset, destroy: () => scope.dispose() };
+}

package/src/recipes/repel-bento/repel-bento.css

@@ -0,0 +1,3 @@
+.mk-repel-bento { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; overflow: clip; overflow-clip-margin: 30px; }
+.mk-repel-bento > * { min-width: 0; border-radius: 32px; }
+@media (max-width: 680px) { .mk-repel-bento { grid-template-columns: 1fr; } }

package/src/recipes/reveal/README.md

@@ -0,0 +1,36 @@
+# reveal
+
+Un velo del color de la superficie la cubre y se abre como una onda desde un punto; luego se desvanece. El sobrepaso de 2 hace que la apertura pase la esquina más lejana a mitad de camino, y el final queda suave.
+
+Origen: Stepbro — reveal (`reveal-wipe` en el kit; usado en la navegación, el calendario y la hora). Velocidades `fast` 0.5/0.25 s, `normal` 0.7/0.35, `slow` 1.05/0.5, `slower` 1.6/0.75 (recorrido/fundido), `power2.out` y fundido `power1.out`.
+
+## Vanilla / Astro
+
+```html
+<div data-mk="reveal" data-mk-trigger="load" data-mk-origin="#abrir-calendario">…</div>
+```
+
+Sin `autoInit`: `createReveal(el, opciones)`. Para un uso suelto: `revealFrom(el, { origin: boton, speed: 'slow' })`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const reveal = useReveal(ref);
+// al abrir: reveal.current?.play(botonRef.current!)
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `speed` | `'normal'` | `'fast'`, `'normal'`, `'slow'`, `'slower'` |
+| `origin` | — | Selector del elemento desde cuyo centro sale la onda. Sin él: último puntero o el centro |
+| `delay` | `0` | Segundos |
+| `trigger` | `'manual'` | `'load'` la reproduce al crearse |
+
+## Controles
+
+`play(origen?)`, `destroy()`
+
+Con movimiento reducido no se reproduce.

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

@@ -0,0 +1,48 @@
+import { entrances } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { revealFrom, type RevealHandle, type RevealSpeed } from '../../motion/reveal';
+
+/*
+ * Stepbro's reveal on an element: a veil in its own colour opens like a wave
+ * from the origin (an element, else the last pointer position, else the centre).
+ */
+
+export interface RevealRecipeOptions {
+  speed?: RevealSpeed;
+  /** CSS selector of the origin element (searched in the document). */
+  origin?: string;
+  delay?: number;
+  trigger?: 'manual' | 'load';
+}
+
+export interface RevealInstance extends Instance {
+  /** Play the wave, optionally from another origin. */
+  play(origin?: Element | { x: number; y: number }): void;
+}
+
+export function createReveal(el: HTMLElement | null, options: RevealRecipeOptions = {}): RevealInstance {
+  if (!el) {
+    warnOnce('reveal: missing element');
+    return inert({ play() {} });
+  }
+  const { speed = 'normal', delay = 0, trigger = 'manual' } = options;
+  let handle: RevealHandle | null = null;
+
+  const play = (origin?: Element | { x: number; y: number }) => {
+    handle?.cancel();
+    const from = origin ?? (options.origin ? document.querySelector(options.origin) : undefined);
+    handle = revealFrom(el, { speed, delay, origin: from });
+  };
+
+  if (trigger === 'load' && entrances()) play();
+  el.dataset.mkReady = '';
+
+  return {
+    play,
+    destroy() {
+      handle?.cancel();
+      handle = null;
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/rotator/README.md

@@ -0,0 +1,21 @@
+# rotator
+
+Rotador de testimonios con autoplay, pausa al enfocar y controles manuales (Dousan).
+
+```html
+<div class="mk-rotator" data-mk="rotator"><blockquote>Uno</blockquote><blockquote>Dos</blockquote></div>
+```
+
+```ts
+import { createRotator } from '@yewdiel21/motion-kit';
+import { useRotator } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createRotator(root);
+instance.destroy();
+```
+
+`interval` 8000 ms, `autoplay` true, `index` 0, `onChange(index)`. `select(index)`, `next()`, `previous()`, `index`. Pausa al señalar, enfocar o esconder la pestaña; los controles reinician el intervalo. Solo la pieza activa es visible y accesible. Entrada opacity/y 5 a 0, .25 s. Origen: testimonios de Dousan.
+
+Vanilla declarativo: `autoInit(root)`. React: `useRotator(ref, options, deps)` devuelve una ref a la instancia; se destruye al desmontar. Con movimiento reducido no se ejecuta movimiento decorativo. `destroy()` restaura atributos y estilos y quita listeners, observers y nodos generados.
+
+Desde 0.8.0. Parámetros investigados en `REA - Dousan OFFFICE Siena/`; implementación propia, sin código ni assets de esos sitios.

package/src/recipes/rotator/create-rotator.ts

@@ -0,0 +1,66 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { wrap } from '../../core/math';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { clearStyles } from '../../core/styles';
+import { inert, type Instance } from '../../core/types';
+
+export interface RotatorOptions {
+  interval?: number;
+  autoplay?: boolean;
+  index?: number;
+  onChange?: (index: number) => void;
+}
+export interface RotatorInstance extends Instance {
+  select(index: number): void;
+  next(): void;
+  previous(): void;
+  readonly index: number;
+}
+
+export function createRotator(root: HTMLElement | null, options: RotatorOptions = {}): RotatorInstance {
+  const items = root ? [...root.children] as HTMLElement[] : [];
+  if (!root || !items.length) return inert({ select() {}, next() {}, previous() {}, index: 0 });
+  registerMotion();
+  const scope = createScope();
+  const still = reduced();
+  let index = 0;
+  let hovered = false;
+  let focused = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let animation: gsap.core.Tween | undefined;
+  for (const item of items) scope.attr(item, 'style', item.getAttribute('style'));
+  const select = (next: number, notify = true) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    index = wrap(Math.round(next), items.length);
+    animation?.kill();
+    for (const [position, item] of items.entries()) {
+      scope.attr(item, 'hidden', position === index ? null : '');
+      scope.attr(item, 'inert', position === index ? null : '');
+    }
+    if (!still) animation = gsap.fromTo(items[index]!, { opacity: 0, y: TIMING.rotator.y }, { opacity: 1, y: 0, duration: TIMING.rotator.duration, overwrite: true });
+    if (notify) {
+      options.onChange?.(index);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { index } }));
+    }
+  };
+  const restart = () => {
+    clearInterval(timer);
+    if (scope.disposed || still || options.autoplay === false || hovered || focused || document.hidden || items.length < 2) return;
+    timer = setInterval(() => select(index + 1), Math.max(100, options.interval ?? TIMING.rotator.interval));
+  };
+  const move = (next: number) => { select(next); restart(); };
+  scope.on(root, 'pointerenter', () => { hovered = true; restart(); });
+  scope.on(root, 'pointerleave', () => { hovered = false; restart(); });
+  scope.on(root, 'focusin', () => { focused = true; restart(); });
+  scope.on(root, 'focusout', (event) => {
+    focused = root.contains(event.relatedTarget as Node | null);
+    restart();
+  });
+  scope.on(document, 'visibilitychange', restart);
+  scope.add(() => { clearInterval(timer); animation?.kill(); clearStyles(items, ['transform', 'translate', 'rotate', 'scale', 'opacity']); });
+  select(options.index ?? 0, false);
+  restart();
+  return { select: move, next: () => move(index + 1), previous: () => move(index - 1), get index() { return index; }, destroy: () => scope.dispose() };
+}

package/src/recipes/rotator/rotator.css

@@ -0,0 +1,3 @@
+.mk-rotator { min-height: 12rem; }
+.mk-rotator > [hidden] { display: none !important; }
+.mk-rotator > :not([hidden]) { margin: 0; }