@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/react/use-parallax.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createParallax, type ParallaxOptions } from '../recipes/parallax/create-parallax';
+
+/** Siena's photo parallax inside its frame. */
+export const useParallax = (ref: RefObject<HTMLElement | null>, options?: ParallaxOptions, deps?: DependencyList) =>
+  useRecipe(ref, createParallax, options, deps);

package/src/react/use-particle-hero.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createParticleHero, type ParticleHeroOptions } from '../gl/particle-hero/create-particle-hero';
+
+/** iyo.ai's particle hero (WebGL2, Canvas2D fallback). The canvas joins the ref's element. */
+export const useParticleHero = (ref: RefObject<HTMLElement | null>, options?: ParticleHeroOptions, deps?: DependencyList) =>
+  useRecipe(ref, createParticleHero, options, deps);

package/src/react/use-pile.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createPile, type PileOptions } from '../recipes/pile/create-pile';
+
+export const usePile = (ref: RefObject<HTMLElement | null>, options?: PileOptions, deps?: DependencyList) =>
+  useRecipe(ref, createPile, options, deps);

package/src/react/use-pop.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createPop, type PopOptions } from '../recipes/pop/create-pop';
+
+export const usePop = (ref: RefObject<HTMLElement | null>, options?: PopOptions, deps?: DependencyList) =>
+  useRecipe(ref, createPop, options, deps);

package/src/react/use-radial-menu.ts

@@ -0,0 +1,10 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useLatest, useRecipe } from './use-recipe';
+import { createRadialMenu, type RadialMenuOptions } from '../recipes/radial-menu/create-radial-menu';
+
+export function useRadialMenu(ref: RefObject<HTMLElement | null>, options: RadialMenuOptions = {}, deps?: DependencyList) {
+  const onToggle = useLatest(options.onToggle);
+  return useRecipe(ref, createRadialMenu, { ...options, onToggle: (open) => onToggle.current?.(open) }, deps);
+}

package/src/react/use-recipe.ts

@@ -0,0 +1,38 @@
+'use client';
+
+import { useEffect, useLayoutEffect, useRef, type DependencyList, type RefObject } from 'react';
+import type { Instance } from '../core/types';
+
+/** useLayoutEffect in the browser (no flash), useEffect during SSR (no warning). */
+export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+/**
+ * Create a recipe on `ref.current` after mount and destroy it on unmount or when
+ * `deps` change. Returns a ref holding the live instance (controls like `next()`).
+ */
+export function useRecipe<I extends Instance, O>(
+  ref: RefObject<HTMLElement | null>,
+  factory: (el: HTMLElement | null, options?: O) => I,
+  options?: O,
+  deps: DependencyList = [],
+): RefObject<I | null> {
+  const instance = useRef<I | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = factory(ref.current, options);
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // Options are read once per creation; pass `deps` to recreate when they change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+  return instance;
+}
+
+/** Keep the latest callback in a ref so recipes do not restart on every render. */
+export function useLatest<T>(value: T) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}

package/src/react/use-reflow.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createReflow, type ReflowOptions } from '../recipes/reflow/create-reflow';
+
+/** Call `.current.capture()` before the state change and `.current.play()` in a layout effect after it. */
+export const useReflow = (ref: RefObject<HTMLElement | null>, options?: ReflowOptions, deps?: DependencyList) =>
+  useRecipe(ref, createReflow, options, deps);

package/src/react/use-repel-bento.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createRepelBento, type RepelBentoOptions } from '../recipes/repel-bento/create-repel-bento';
+
+export const useRepelBento = (ref: RefObject<HTMLElement | null>, options?: RepelBentoOptions, deps?: DependencyList) =>
+  useRecipe(ref, createRepelBento, options, deps);

package/src/react/use-reveal.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createReveal, type RevealRecipeOptions } from '../recipes/reveal/create-reveal';
+
+export const useReveal = (ref: RefObject<HTMLElement | null>, options?: RevealRecipeOptions, deps?: DependencyList) =>
+  useRecipe(ref, createReveal, options, deps);

package/src/react/use-rotator.ts

@@ -0,0 +1,10 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useLatest, useRecipe } from './use-recipe';
+import { createRotator, type RotatorOptions } from '../recipes/rotator/create-rotator';
+
+export function useRotator(ref: RefObject<HTMLElement | null>, options: RotatorOptions = {}, deps?: DependencyList) {
+  const callback = useLatest(options.onChange);
+  return useRecipe(ref, createRotator, { ...options, onChange: (index) => callback.current?.(index) }, deps);
+}

package/src/react/use-shader-blur.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createShaderBlur, type ShaderBlurOptions } from '../gl/shader-blur/create-shader-blur';
+
+export const useShaderBlur = (ref: RefObject<HTMLElement | null>, options?: ShaderBlurOptions, deps?: DependencyList) =>
+  useRecipe(ref, createShaderBlur, options, deps);

package/src/react/use-shader-grain.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createShaderGrain, type ShaderGrainOptions } from '../gl/shader-grain/create-shader-grain';
+
+export const useShaderGrain = (ref: RefObject<HTMLElement | null>, options?: ShaderGrainOptions, deps?: DependencyList) =>
+  useRecipe(ref, createShaderGrain, options, deps);

package/src/react/use-slot-text.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import type { RefObject } from 'react';
+import { useIsomorphicLayoutEffect, useRecipe } from './use-recipe';
+import { createSlotText, type SlotTextOptions } from '../recipes/slot-text/create-slot-text';
+
+/**
+ * Rolls `text` into `ref` whenever it changes. The element must render no
+ * children of its own: the recipe writes the letters (see `<SlotText>`).
+ */
+export function useSlotText(ref: RefObject<HTMLElement | null>, text: string, options: Omit<SlotTextOptions, 'text'> = {}) {
+  const instance = useRecipe(ref, createSlotText, { ...options, text });
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.set(text);
+  }, [text]);
+  return instance;
+}

package/src/react/use-snap-strip.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createSnapStrip, type SnapStripOptions } from '../recipes/snap-strip/create-snap-strip';
+
+/** iyo.ai's phone cards: an autoplaying scroll-snap strip. */
+export const useSnapStrip = (ref: RefObject<HTMLElement | null>, options?: SnapStripOptions, deps?: DependencyList) =>
+  useRecipe(ref, createSnapStrip, options, deps);

package/src/react/use-sortable.ts

@@ -0,0 +1,14 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useLatest, useRecipe } from './use-recipe';
+import { createSortable, type SortableOptions } from '../recipes/sortable/create-sortable';
+
+/**
+ * Drag to reorder a list React renders: answer `onReorder` by updating your state
+ * (React moves the DOM; the engine waits for it and lands the item). `mutate` is off.
+ */
+export function useSortable(ref: RefObject<HTMLElement | null>, options: SortableOptions = {}, deps?: DependencyList) {
+  const onReorder = useLatest(options.onReorder);
+  return useRecipe(ref, createSortable, { mutate: false, ...options, onReorder: (detail) => onReorder.current?.(detail) }, deps);
+}

package/src/react/use-spring-cards.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createSpringCards, type SpringCardsOptions } from '../recipes/spring-cards/create-spring-cards';
+
+export const useSpringCards = (ref: RefObject<HTMLElement | null>, options?: SpringCardsOptions, deps?: DependencyList) =>
+  useRecipe(ref, createSpringCards, options, deps);

package/src/react/use-stretch-footer.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createStretchFooter, type StretchFooterOptions } from '../recipes/stretch-footer/create-stretch-footer';
+
+export interface UseStretchFooterOptions extends Omit<StretchFooterOptions, 'phantom' | 'title'> {
+  phantomRef?: RefObject<HTMLElement | null>;
+  titleRef?: RefObject<HTMLElement | null>;
+}
+
+export function useStretchFooter(ref: RefObject<HTMLElement | null>, options: UseStretchFooterOptions = {}, deps?: DependencyList) {
+  const { phantomRef, titleRef, ...rest } = options;
+  return useRecipe(
+    ref,
+    (el) => createStretchFooter(el, { ...rest, phantom: phantomRef?.current ?? undefined, title: titleRef?.current ?? undefined }),
+    undefined,
+    deps,
+  );
+}

package/src/react/use-tabs.ts

@@ -0,0 +1,10 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useLatest, useRecipe } from './use-recipe';
+import { createTabs, type TabsOptions } from '../recipes/tabs/create-tabs';
+
+export function useTabs(ref: RefObject<HTMLElement | null>, options: TabsOptions = {}, deps?: DependencyList) {
+  const onSelect = useLatest(options.onSelect);
+  return useRecipe(ref, createTabs, { ...options, onSelect: (index, tab) => onSelect.current?.(index, tab) }, deps);
+}

package/src/react/use-text-roll.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createTextRoll, type TextRollOptions } from '../recipes/text-roll/create-text-roll';
+
+/** Siena's slot title. `.current.play()` spins it. */
+export const useTextRoll = (ref: RefObject<HTMLElement | null>, options?: TextRollOptions, deps?: DependencyList) =>
+  useRecipe(ref, createTextRoll, options, deps);

package/src/react/use-ticket-menu.ts

@@ -0,0 +1,15 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useLatest, useRecipe } from './use-recipe';
+import { createTicketMenu, type TicketMenuOptions } from '../recipes/ticket-menu/create-ticket-menu';
+
+export function useTicketMenu(ref: RefObject<HTMLElement | null>, options: TicketMenuOptions = {}, deps?: DependencyList) {
+  const latest = useLatest(options);
+  return useRecipe(ref, createTicketMenu, {
+    ...options,
+    onSelect: (value, item) => latest.current.onSelect?.(value, item),
+    onOpen: () => latest.current.onOpen?.(),
+    onClose: () => latest.current.onClose?.(),
+  }, deps);
+}

package/src/react/use-words.ts

@@ -0,0 +1,8 @@
+'use client';
+
+import type { DependencyList, RefObject } from 'react';
+import { useRecipe } from './use-recipe';
+import { createWords, type WordsOptions } from '../recipes/words/create-words';
+
+export const useWords = (ref: RefObject<HTMLElement | null>, options?: WordsOptions, deps?: DependencyList) =>
+  useRecipe(ref, createWords, options, deps);

package/src/recipes/card-dock/README.md

@@ -0,0 +1,36 @@
+# card-dock
+
+Un dock de tarjetas de cristal apiladas: las que están detrás de la del frente bajan 90 % / 180 % / 270 % (360 % la quinta) y encogen a .93 / .87 / .8 (.73). Al pasar el puntero o enfocar se despliegan hacia arriba (0.8 s `cubic-bezier(.48,.01,0,1.08)`, con un pequeño rebote), la tarjeta bajo el puntero crece de 4rem a 4.5rem (0.6 s) y su nombre sale hacia la izquierda; al salir se apilan de nuevo (0.64 s). Al cargar se ven desplegadas 1.6 s y luego se apilan y aparece el CTA.
+
+Origen: iyo.ai, dock fijo de productos de la home (`product-cards`, `PM`): cristal `blur(19px)` sobre `#38383899` (`#555555b0` al pasar), borde `#8a8a8a1a`, radio .9rem, nombres a .7rem con tracking .07em. El movimiento es CSS; la receta añade la presentación de carga, el primer toque en tabletas táctiles (768–1024 px sin hover: abre en vez de navegar), Escape y clic fuera.
+
+## HTML / Astro
+
+```html
+<div data-mk="card-dock" class="mk-card-dock mk-card-dock--fixed" role="list" aria-label="Productos">
+  <div class="mk-card-dock__item" role="listitem">
+    <a class="mk-card-dock__card" href="/producto-a" aria-label="Producto A"><img src="/a.avif" alt="" /></a>
+    <span class="mk-card-dock__title" aria-hidden="true">Producto A</span>
+  </div>
+  <!-- … hasta cinco; la última es la del frente -->
+  <span class="mk-card-dock__cta" aria-hidden="true">Shop now</span>
+</div>
+```
+
+`mk-card-dock--fixed` lo fija abajo a la derecha (3rem / 2rem); sin ella queda en el flujo, creciendo hacia arriba desde su sitio.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const dock = useCardDock(ref, { intro: 1600 });
+// dock.current?.expand() / collapse()
+```
+
+## API
+
+`createCardDock(root, { intro })` → `{ expand(), collapse(), expanded, destroy }`. `intro`: milisegundos desplegado al cargar (0 lo omite). Estados en la raíz: `data-mk-spread`, `data-mk-settled`, `data-mk-expanded`. Variables: `--mk-card-dock-size(-hover)`, `--mk-card-dock-surface(-hover)`, `--mk-card-dock-border`, `--mk-card-dock-fg`, `--mk-card-dock-height`, `--mk-ease-dock`, `--mk-ease-dock-size`, `--mk-ease-dock-fade`.
+
+## Accesibilidad
+
+El foco despliega la pila y muestra los nombres, así que el teclado ve lo mismo que el puntero; pon el nombre accesible en el enlace (`aria-label`) y deja el título visible `aria-hidden`. Con movimiento reducido la pila queda desplegada con sus nombres y sin transiciones.

package/src/recipes/card-dock/card-dock.css

@@ -0,0 +1,178 @@
+/*
+ * iyo.ai's product dock. Cards are .mk-card-dock__item children (the last one
+ * is the front card); the optional .mk-card-dock__cta shows next to the stack
+ * once it has settled. Without JavaScript the stack still opens on hover/focus.
+ */
+.mk-card-dock {
+  --mk-card-dock-size: 4rem;
+  --mk-card-dock-size-hover: 4.5rem;
+  --mk-card-dock-surface: #38383899;
+  --mk-card-dock-surface-hover: #555555b0;
+  --mk-card-dock-border: #8a8a8a1a;
+  --mk-card-dock-fg: #f1f0ed;
+  --mk-card-dock-height: 7.2vw;
+  --mk-ease-dock: cubic-bezier(0.48, 0.01, 0, 1.08);
+  --mk-ease-dock-size: cubic-bezier(0.77, 0, 0.175, 1);
+  --mk-ease-dock-fade: cubic-bezier(0.65, 0, 0.35, 1);
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  justify-content: flex-end;
+  width: var(--mk-card-dock-size-hover);
+  height: var(--mk-card-dock-height);
+  isolation: isolate;
+  color: var(--mk-card-dock-fg);
+}
+.mk-card-dock--fixed {
+  position: fixed;
+  z-index: 3;
+  right: 3rem;
+  bottom: 2rem;
+}
+.mk-card-dock__item {
+  position: relative;
+  flex: none;
+  padding: 0.18rem;
+  transition: transform 0.64s var(--mk-ease-dock);
+}
+.mk-card-dock__item:nth-last-child(2 of .mk-card-dock__item) {
+  transform: translateY(90%) scale(0.93);
+}
+.mk-card-dock__item:nth-last-child(3 of .mk-card-dock__item) {
+  transform: translateY(180%) scale(0.87);
+}
+.mk-card-dock__item:nth-last-child(4 of .mk-card-dock__item) {
+  transform: translateY(270%) scale(0.8);
+}
+.mk-card-dock__item:nth-last-child(5 of .mk-card-dock__item) {
+  transform: translateY(360%) scale(0.73);
+}
+.mk-card-dock__card {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  box-sizing: border-box;
+  width: var(--mk-card-dock-size);
+  height: var(--mk-card-dock-size);
+  padding: 0.25rem 0.25rem 0.23rem;
+  border: 1px solid var(--mk-card-dock-border);
+  border-radius: 0.9rem;
+  background: var(--mk-card-dock-surface);
+  color: inherit;
+  -webkit-backdrop-filter: blur(19px);
+  backdrop-filter: blur(19px);
+  transition:
+    width 0.6s var(--mk-ease-dock-size),
+    height 0.6s var(--mk-ease-dock-size),
+    background-color 0.3s var(--mk-ease-dock-fade);
+}
+.mk-card-dock__card :is(img, video, svg) {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.mk-card-dock__title {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  font-size: 0.7rem;
+  letter-spacing: 0.07em;
+  line-height: 1.1rem;
+  text-transform: uppercase;
+  white-space: nowrap;
+  pointer-events: none;
+  opacity: 0;
+  transform: translateX(-15%);
+  transition:
+    opacity 0.5s var(--mk-ease-dock-fade),
+    transform 0.4s var(--mk-ease-dock-fade);
+}
+.mk-card-dock__cta {
+  position: absolute;
+  right: 0;
+  bottom: 0.18rem;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 9.3rem;
+  height: var(--mk-card-dock-size);
+  padding-right: calc(var(--mk-card-dock-size) + 1rem);
+  box-sizing: border-box;
+  font-size: 0.7rem;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+  white-space: nowrap;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.5s var(--mk-ease-dock-fade);
+}
+.mk-card-dock[data-mk-settled] .mk-card-dock__cta {
+  opacity: 1;
+}
+
+/* Spread: the load presentation, the tap on tablets, keyboard focus. */
+.mk-card-dock:is([data-mk-spread], [data-mk-expanded], :focus-within) {
+  height: auto;
+}
+.mk-card-dock:is([data-mk-spread], [data-mk-expanded], :focus-within) > .mk-card-dock__item {
+  transform: none;
+  transition-duration: 0.8s;
+}
+.mk-card-dock:is([data-mk-expanded], :focus-within) .mk-card-dock__title {
+  opacity: 1;
+  transform: translateX(-120%);
+}
+.mk-card-dock:is([data-mk-spread], [data-mk-expanded], :focus-within) .mk-card-dock__cta {
+  opacity: 0;
+}
+@media (hover: hover) {
+  .mk-card-dock:hover {
+    height: auto;
+  }
+  .mk-card-dock:hover > .mk-card-dock__item {
+    transform: none;
+    transition-duration: 0.8s;
+  }
+  .mk-card-dock:hover .mk-card-dock__cta {
+    opacity: 0;
+  }
+  .mk-card-dock__item:is(:hover, :focus-within) .mk-card-dock__card {
+    width: var(--mk-card-dock-size-hover);
+    height: var(--mk-card-dock-size-hover);
+    background-color: var(--mk-card-dock-surface-hover);
+  }
+  .mk-card-dock__item:is(:hover, :focus-within) .mk-card-dock__title {
+    opacity: 1;
+    transform: translateX(-120%);
+  }
+}
+@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+  .mk-card-dock {
+    --mk-card-dock-surface: #383838e6;
+    --mk-card-dock-surface-hover: #555555f0;
+  }
+}
+/* Still: the stack stays open with its names. */
+@media (prefers-reduced-motion: reduce) {
+  .mk-card-dock {
+    height: auto;
+  }
+  /* As specific as the stacked rules (:nth-last-child(n of …)), and later. */
+  .mk-card-dock > .mk-card-dock__item:nth-last-child(n of .mk-card-dock__item) {
+    transform: none;
+  }
+  .mk-card-dock .mk-card-dock__title {
+    opacity: 1;
+    transform: translateX(-120%);
+  }
+  .mk-card-dock .mk-card-dock__cta {
+    display: none;
+  }
+  .mk-card-dock,
+  .mk-card-dock * {
+    transition: none !important;
+  }
+}

package/src/recipes/card-dock/create-card-dock.ts

@@ -0,0 +1,97 @@
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * iyo.ai's product dock: a stack of glass cards where the ones behind the front
+ * card drop 90 % / 180 % / 270 % and shrink to .93 / .87 / .8. Hover or focus
+ * spreads them out (0.8 s, cubic-bezier(.48,.01,0,1.08)), the card under the
+ * pointer grows and its name slides out; leaving stacks them again (0.64 s).
+ * The motion is CSS (card-dock.css); this adds the 1.6 s spread on load, the
+ * first tap on touch tablets, Escape / outside click and manual control.
+ */
+
+export interface CardDockOptions {
+  /** Milliseconds the cards stay spread out on load before stacking (iyo: 1600; 0 skips it). */
+  intro?: number;
+}
+
+export interface CardDockInstance extends Instance {
+  expand(): void;
+  collapse(): void;
+  readonly expanded: boolean;
+}
+
+const TABLET_TOUCH = '(min-width: 768px) and (max-width: 1024px) and (hover: none)';
+
+export function createCardDock(root: HTMLElement | null, options: CardDockOptions = {}): CardDockInstance {
+  if (!root) {
+    warnOnce('card-dock: missing element');
+    return inert({ expand() {}, collapse() {}, expanded: false });
+  }
+  const t = TIMING.cardDock;
+  const intro = Math.max(0, options.intro ?? t.intro);
+  const scope = createScope();
+  let expanded = false;
+  let resizeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const set = (name: string, on: boolean) => scope.attr(root, name, on ? '' : null);
+  const expand = () => {
+    if (scope.disposed) return;
+    expanded = true;
+    set('data-mk-expanded', true);
+  };
+  const collapse = () => {
+    if (scope.disposed) return;
+    expanded = false;
+    set('data-mk-expanded', false);
+  };
+  const settle = () => {
+    set('data-mk-spread', false);
+    set('data-mk-settled', true);
+  };
+  // Checked on each tap, so a window resized into the tablet range works too.
+  const tablet = () => typeof matchMedia === 'function' && matchMedia(TABLET_TOUCH).matches;
+
+  if (intro > 0 && !reduced()) {
+    set('data-mk-spread', true);
+    scope.timeout(settle, intro);
+  } else settle();
+
+  // Touch tablets have no hover: the first tap opens the stack, the next one follows the link.
+  scope.on(
+    root,
+    'click',
+    (event) => {
+      if (expanded || !tablet()) return;
+      event.preventDefault();
+      event.stopPropagation();
+      expand();
+    },
+    true,
+  );
+  scope.on(document, 'click', (event) => {
+    if (expanded && !root.contains(event.target as Node)) collapse();
+  });
+  scope.on(document, 'keydown', (event) => {
+    if (expanded && (event as KeyboardEvent).key === 'Escape') collapse();
+  });
+  scope.on(window, 'resize', () => {
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(() => {
+      if (!tablet()) collapse();
+    }, t.resizeDebounce);
+  });
+  scope.add(() => clearTimeout(resizeTimer));
+  scope.attr(root, 'data-mk-ready', '');
+
+  return {
+    expand,
+    collapse,
+    get expanded() {
+      return expanded;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/recipes/cascade/README.md

@@ -0,0 +1,33 @@
+# cascade
+
+Un bloque que entra pieza a pieza: rayas que crecen desde un lado (alternando izquierda y derecha), textos que aparecen y líneas que suben desde su recorte. 1.2 s `expo.out`, 30 ms entre piezas, cuando el 30 % del bloque se ve (o el 30 % de la pantalla si el bloque es más alto). Al salir de la pantalla todo vuelve a su estado inicial, así que entra de nuevo al volver (salvo `once`), como el `isOut` de Siena.
+
+Origen: Siena Film Foundation, grupos `[data-a]` (`line`, `alpha`, `item`); el `fade` es también el `alpha` de OFFFICE.
+
+## HTML / Astro
+
+```html
+<section data-mk="cascade" data-mk-delay="0.2">
+  <hr data-mk-cascade="rule">
+  <p data-mk-cascade="fade">Director</p>
+  <span style="overflow: hidden; display: block"><span data-mk-cascade="rise" style="display: block">Limor Pinhasov</span></span>
+  <hr data-mk-cascade="rule">
+</section>
+```
+
+Los `rise` necesitan un padre que recorte (`overflow: hidden`).
+
+## React
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+useCascade(ref, { once: true });
+```
+
+## API
+
+`createCascade(root, { delay, duration, step, once, trigger })` → `{ play(), reset(), destroy }`. `delay` también se lee de `data-mk-delay`. `reset()` devuelve todas las piezas a su estado inicial.
+
+## Accesibilidad
+
+Solo transforma y hace aparecer contenido que ya está en el DOM. Con movimiento reducido todo queda visible.