@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/curved-carousel/curved-carousel.css

@@ -0,0 +1,50 @@
+/*
+ * curved-carousel — spencergabor.com (Carousel). Layout rules apply only while the
+ * recipe runs (`[data-mk-carousel]`); without JS the root keeps whatever fallback
+ * the page gives it (e.g. a horizontal scroll row).
+ */
+
+[data-mk-carousel] {
+  --mk-slide-w: min(30rem, 78vw);
+  position: relative;
+  display: block;
+  height: var(--mk-carousel-h, calc(var(--mk-slide-w) * 0.625 + 6.5rem));
+  overflow-x: clip;
+  overflow-y: visible;
+  column-gap: var(--mk-gap, 1rem);
+  touch-action: pan-y;
+  cursor: grab;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+[data-mk-carousel]:active {
+  cursor: grabbing;
+}
+
+[data-mk-carousel] [data-mk-slide] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--mk-slide-w);
+  transform-origin: 50% 70vw;
+  translate: calc(var(--mk-x, -9999) * 1px) calc(cos(var(--mk-t, 0) * 3.14 / 1000) * -3rem + 3rem);
+  rotate: calc(var(--mk-t, 0) * 0.03deg);
+  will-change: translate, rotate;
+}
+
+[data-mk-carousel] .mk-carousel__media {
+  display: block;
+  transition:
+    scale 1.4s var(--mk-ease-elastic),
+    translate 1.4s var(--mk-ease-elastic);
+  transition-delay: calc(sin(var(--mk-k, 0) * 1.5708) * 0.12s);
+}
+
+[data-mk-carousel] .mk-carousel__media img {
+  pointer-events: none;
+}
+
+[data-mk-carousel] .mk-carousel__title {
+  opacity: max(0, cos(var(--mk-t, 0) * 3.14 / 600));
+}

package/src/recipes/depth-grid/README.md

@@ -0,0 +1,30 @@
+# depth-grid
+
+Un grid de imágenes que llega desde la profundidad: cada imagen parte empujada hacia fuera del centro (900 px), hundida en la pantalla (hasta −3000 px), girada (hasta 160°), casi transparente (.05) y pequeña (.4), y se coloca en su sitio mientras el grid baja desde que su borde superior toca el centro de la pantalla hasta que su borde inferior toca el borde inferior. Primero las del centro; 0.15 s repartidos hacia los bordes. Sigue al scroll sin retraso (`lerp: .1` para suavizarlo).
+
+Origen: Siena Film Foundation, página About (`Rv`, `Un`). Siena busca el timeline en segundos y las del borde se quedan al 85 %; aquí se usa el progreso y el grid termina montado.
+
+## HTML / Astro
+
+```html
+<div data-mk="depth-grid" class="grid">
+  <img src="1.jpg" alt=""> <img src="2.jpg" alt=""> …
+</div>
+```
+
+Dale espacio de scroll alrededor: el recorrido va de `top center` a `bottom bottom`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useDepthGrid(ref);
+```
+
+## API
+
+`createDepthGrid(root, { start, end, lerp, scroll })` → `{ seek(p), destroy }`.
+
+## Accesibilidad
+
+Con movimiento reducido el grid aparece montado. Las imágenes no cambian de orden en el DOM.

package/src/recipes/depth-grid/create-depth-grid.ts

@@ -0,0 +1,120 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { trackScroll, type ScrollTrack } from '../../core/scroll-track';
+import { clearStyles } from '../../core/styles';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * Siena's About grid: the pictures come from far away — pushed out from the
+ * grid's centre (900 px), deep into the screen (up to −3000 px), tilted (up to
+ * 160°), nearly transparent (.05) and small (.4) — and gather into their places
+ * as the grid scrolls from its top at the screen's centre to its bottom at the
+ * screen's bottom (eased .1 a frame). Centre first, 0.15 s spread to the edges.
+ * Siena seeks the timeline in seconds (edges stop at 85 %); this uses its
+ * progress, so the grid ends fully assembled.
+ */
+
+export interface DepthGridOptions {
+  start?: string;
+  end?: string;
+  lerp?: number;
+  /** Follow the scroll (default). Off: only seek() moves it. */
+  scroll?: boolean;
+}
+
+export interface DepthGridInstance extends Instance {
+  seek(progress: number): void;
+}
+
+const STYLES = ['transform', 'translate', 'rotate', 'scale', 'opacity', 'visibility'];
+
+/** Siena's Un(): where a child starts, from its centre relative to the grid's. */
+function origin(child: Element, box: DOMRect) {
+  const t = TIMING.depthGrid;
+  const own = child.getBoundingClientRect();
+  const centre = { x: box.width / 2, y: box.height / 2 };
+  const point = { x: own.left - box.left + own.width / 2, y: own.top - box.top + own.height / 2 };
+  const angle = Math.atan2(Math.abs(centre.y - point.y), Math.abs(centre.x - point.x));
+  const cos = Math.abs(Math.cos(angle));
+  const sin = Math.abs(Math.sin(angle));
+  const reach = Math.hypot(centre.x, centre.y) || 1;
+  const h = Math.hypot(centre.x - point.x, centre.y - point.y) / reach;
+  const left = point.x < centre.x;
+  const above = point.y < centre.y;
+  return {
+    x: (left ? -1 : 1) * cos * t.distance,
+    y: (above ? -1 : 1) * sin * t.distance,
+    z: t.depth * h,
+    rotateX: (above ? -1 : 1) * sin * t.rotate * h,
+    rotateY: (left ? 1 : -1) * cos * t.rotate * h,
+  };
+}
+
+export function createDepthGrid(root: HTMLElement | null, options: DepthGridOptions = {}): DepthGridInstance {
+  const items = root ? ([...root.children] as HTMLElement[]) : [];
+  if (!root || !items.length) {
+    warnOnce('depth-grid: needs a grid with children');
+    return inert({ seek() {} });
+  }
+  const t = TIMING.depthGrid;
+  const { start = 'top center', end = 'bottom bottom', lerp = t.lerp, scroll = true } = options;
+  if (!entrances()) {
+    root.dataset.mkReady = '';
+    return {
+      seek() {},
+      destroy() {
+        delete root.dataset.mkReady;
+      },
+    };
+  }
+  registerMotion();
+  const perspective = root.style.perspective;
+  root.style.perspective = `${t.perspective}px`;
+  const box = root.getBoundingClientRect();
+  const starts = items.map((item) => origin(item, box));
+  const timeline = gsap.timeline({ paused: true, defaults: { ease: 'none' } });
+  timeline.fromTo(
+    items,
+    {
+      x: (i: number) => starts[i]!.x,
+      y: (i: number) => starts[i]!.y,
+      z: (i: number) => starts[i]!.z,
+      rotateX: (i: number) => starts[i]!.rotateX,
+      rotateY: (i: number) => starts[i]!.rotateY,
+      autoAlpha: t.opacity,
+      scale: t.scale,
+    },
+    {
+      x: 0,
+      y: 0,
+      z: 0,
+      rotateX: 0,
+      rotateY: 0,
+      autoAlpha: 1,
+      scale: 1,
+      duration: 1,
+      stagger: { amount: t.stagger, from: 'center', grid: 'auto' },
+    },
+  );
+  const render = (progress: number) => timeline.progress(progress);
+  let track: ScrollTrack | null = null;
+  if (scroll) track = trackScroll(root, { start, end, lerp, onUpdate: render });
+  else render(0);
+  root.dataset.mkReady = '';
+
+  return {
+    seek(progress: number) {
+      if (track) track.set(progress);
+      else render(progress);
+    },
+    destroy() {
+      track?.destroy();
+      timeline.kill();
+      clearStyles(items, STYLES);
+      root.style.perspective = perspective;
+      if (root.getAttribute('style') === '') root.removeAttribute('style');
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/details/README.md

@@ -0,0 +1,31 @@
+# details
+
+Los `<details>` crecen hasta la altura de su contenido mientras este aparece, y se pliegan de vuelta (0.32 s, curva signature). Un `[data-mk-chevron]` dentro del `<summary>` gira 180° en 0.25 s.
+
+Origen: Stepbro — PrettyDetails (`details` en el kit).
+
+## Vanilla / Astro
+
+```html
+<section data-mk="details">
+  <details>
+    <summary>¿Qué incluye? <span data-mk-chevron class="mk-icon">expand_more</span></summary>
+    <p>…</p>
+  </details>
+</section>
+```
+
+Un solo listener en el contenedor anima todos sus `<details>`. Los controles dentro del `<summary>` conservan su clic. `data-mk-motion="none"` en un `<details>` lo excluye. Sin `autoInit`: `createDetails(el)`; para todo el documento, `installDetailsMotion()`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+useDetails(ref);
+```
+
+## Controles
+
+`destroy()`
+
+Con movimiento reducido se abren y cierran al instante.

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

@@ -0,0 +1,27 @@
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { installDetailsMotion } from '../../motion/details';
+
+/*
+ * Stepbro's PrettyDetails for every <details> under `root` (or `root` itself):
+ * height and content fade in 0.32 s on the signature curve, chevron 180° in 0.25 s.
+ */
+
+export type DetailsInstance = Instance;
+
+export function createDetails(root: HTMLElement | null): DetailsInstance {
+  if (!root) {
+    warnOnce('details: missing root');
+    return inert();
+  }
+  const uninstall = installDetailsMotion(root);
+  root.dataset.mkReady = '';
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      uninstall();
+      delete root.dataset.mkReady;
+    },
+  };
+}

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

@@ -0,0 +1,23 @@
+# dock-pill
+
+Indicador spring que sigue la opción activa de un dock (Dousan).
+
+```html
+<nav class="mk-dock-pill" data-mk="dock-pill" aria-label="Secciones">
+  <button data-mk-dock-item>Inicio</button><button data-mk-dock-item>Archivo</button>
+</nav>
+```
+
+```ts
+import { createDockPill } from '@yewdiel21/motion-kit';
+import { useDockPill } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createDockPill(root);
+instance.destroy();
+```
+
+`index` (o aria-current="page" existente), `onSelect(index,item)`. `select(index)`, `index`; evento `mk:select`. Medición de la opción activa con ResizeObserver, indicador spring 380/30. Flechas, Home/End; evita opciones deshabilitadas. Conserva los enlaces y la navegación del consumidor. Origen: `activeTabPill` del dock móvil de Dousan.
+
+Vanilla declarativo: `autoInit(root)`. React: `useDockPill(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/dock-pill/create-dock-pill.ts

@@ -0,0 +1,68 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { motionSpring } from '../../core/physics-spring';
+import { reduced } from '../../core/reduced';
+import { wrap } from '../../core/math';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, type Instance } from '../../core/types';
+
+export interface DockPillOptions { index?: number; onSelect?: (index: number, item: HTMLElement) => void; }
+export interface DockPillInstance extends Instance { select(index: number): void; readonly index: number; }
+
+export function createDockPill(root: HTMLElement | null, options: DockPillOptions = {}): DockPillInstance {
+  const items = root ? [...root.querySelectorAll<HTMLElement>('[data-mk-dock-item]')] : [];
+  if (!root || !items.length) return inert({ select() {}, index: 0 });
+  registerMotion();
+  const scope = createScope();
+  const indicator = document.createElement('span');
+  indicator.className = 'mk-dock-pill__indicator';
+  indicator.setAttribute('aria-hidden', 'true');
+  root.prepend(indicator);
+  scope.add(() => indicator.remove());
+  let index = Math.max(0, items.findIndex((item) => item.getAttribute('aria-current') === 'page'));
+  let animation: gsap.core.Tween | undefined;
+  const measure = (animate = true) => {
+    if (scope.disposed) return;
+    const item = items[index]!;
+    const target = { x: item.offsetLeft, y: item.offsetTop, width: item.offsetWidth, height: item.offsetHeight };
+    animation?.kill();
+    if (animate && !reduced()) animation = gsap.to(indicator, { ...target, ...motionSpring(...TIMING.springs.dockPill), overwrite: true });
+    else gsap.set(indicator, target);
+  };
+  const select = (next: number, notify = true) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    const candidate = wrap(Math.round(next), items.length);
+    if (items[candidate]!.matches(':disabled, [aria-disabled="true"]')) return;
+    index = candidate;
+    items.forEach((item, position) => scope.attr(item, 'aria-current', position === index ? 'page' : null));
+    measure(notify);
+    if (notify) {
+      options.onSelect?.(index, items[index]!);
+      root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { index, item: items[index] } }));
+    }
+  };
+  scope.on(root, 'click', (event) => {
+    const item = (event.target as Element).closest<HTMLElement>('[data-mk-dock-item]');
+    if (item && items.includes(item)) select(items.indexOf(item));
+  });
+  scope.on(root, 'keydown', (event) => {
+    const current = items.indexOf(document.activeElement as HTMLElement);
+    if (current < 0) return;
+    const direction = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
+    if (!direction && event.key !== 'Home' && event.key !== 'End') return;
+    event.preventDefault();
+    let next = event.key === 'Home' ? 0 : event.key === 'End' ? items.length - 1 : wrap(current + direction, items.length);
+    for (let tries = 0; tries < items.length && items[next]!.matches(':disabled, [aria-disabled="true"]'); tries++) next = wrap(next + (direction || 1), items.length);
+    select(next);
+    items[index]!.focus();
+  });
+  if (typeof ResizeObserver === 'function') {
+    const observer = scope.observe(new ResizeObserver(() => measure(false)));
+    observer.observe(root);
+    items.forEach((item) => observer.observe(item));
+  }
+  scope.on(window, 'resize', () => measure(false));
+  scope.add(() => animation?.kill());
+  select(options.index ?? index, false);
+  return { select, get index() { return index; }, destroy: () => scope.dispose() };
+}

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

@@ -0,0 +1,5 @@
+.mk-dock-pill { position: relative; isolation: isolate; display: inline-flex; gap: 4px; padding: 8px; border-radius: 64px; background: var(--mk-surface-2); }
+.mk-dock-pill [data-mk-dock-item] { position: relative; display: grid; place-items: center; min-width: 48px; min-height: 48px; padding: 10px 16px; border: 0; border-radius: 48px; background: transparent; color: inherit; font: inherit; text-decoration: none; cursor: pointer; }
+.mk-dock-pill [aria-current='page'] { color: var(--mk-on-accent); }
+.mk-dock-pill [data-mk-dock-item]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+.mk-dock-pill__indicator { position: absolute; top: 0; left: 0; z-index: -1; border-radius: 48px; background: var(--mk-accent); pointer-events: none; }

package/src/recipes/drag-ruler/README.md

@@ -0,0 +1,21 @@
+# drag-ruler
+
+Regla numérica arrastrable de 60 px por unidad, paso y teclado (Dousan).
+
+```html
+<div class="mk-drag-ruler" data-mk="drag-ruler" aria-label="Años de experiencia" data-mk-value="8"></div>
+```
+
+```ts
+import { createDragRuler } from '@yewdiel21/motion-kit';
+import { useDragRuler } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createDragRuler(root);
+instance.destroy();
+```
+
+`min` 0, `max` 8, `step` .1, `value` max, `pixelsPerUnit` 60, `onChange(value)`. `set(value)`, `value`; evento `mk:change` con detail.value. Role slider, aria-valuemin/max/now y nombre accesible provisto por el consumidor. Flechas, Home/End y PageUp/PageDown. Drag usa pointer capture, respeta pointercancel. Origen: regla de años de Dousan; marcas generadas según el rango, sin su formulario.
+
+Vanilla declarativo: `autoInit(root)`. React: `useDragRuler(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/drag-ruler/create-drag-ruler.ts

@@ -0,0 +1,95 @@
+import { clamp } from '../../core/math';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, type Instance } from '../../core/types';
+
+export interface DragRulerOptions {
+  min?: number;
+  max?: number;
+  step?: number;
+  value?: number;
+  pixelsPerUnit?: number;
+  onChange?: (value: number) => void;
+}
+
+export interface DragRulerInstance extends Instance {
+  set(value: number): void;
+  readonly value: number;
+}
+
+export function createDragRuler(root: HTMLElement | null, options: DragRulerOptions = {}): DragRulerInstance {
+  if (!root) return inert({ set() {}, value: 0 });
+  const scope = createScope();
+  const defaults = TIMING.dragRuler;
+  const min = Number.isFinite(options.min) ? options.min! : defaults.min;
+  const max = Math.max(min, Number.isFinite(options.max) ? options.max! : defaults.max);
+  const step = Number.isFinite(options.step) && options.step! > 0 ? options.step! : defaults.step;
+  const pixels = Number.isFinite(options.pixelsPerUnit) && options.pixelsPerUnit! > 0 ? options.pixelsPerUnit! : defaults.pixelsPerUnit;
+  let value = min;
+  let drag: { x: number; value: number; id: number } | null = null;
+  const track = document.createElement('span');
+  track.className = 'mk-drag-ruler__track';
+  track.setAttribute('aria-hidden', 'true');
+  const count = Math.min(500, Math.ceil((max - min) / step));
+  for (let index = 0; index <= count; index++) {
+    const tick = document.createElement('span');
+    const tickValue = min + index * ((max - min) / Math.max(1, count));
+    tick.className = 'mk-drag-ruler__tick';
+    tick.style.left = `${(tickValue - min) * pixels}px`;
+    if (index % 10 === 0) tick.textContent = String(Number(tickValue.toFixed(2)));
+    track.append(tick);
+  }
+  root.append(track);
+  scope.add(() => track.remove());
+  scope.attr(root, 'role', 'slider');
+  scope.attr(root, 'tabindex', root.getAttribute('tabindex') ?? '0');
+  scope.attr(root, 'aria-orientation', 'horizontal');
+  scope.attr(root, 'aria-valuemin', String(min));
+  scope.attr(root, 'aria-valuemax', String(max));
+  const set = (next: number, notify = true) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    const snapped = clamp(Number((min + Math.round((next - min) / step) * step).toFixed(8)), min, max);
+    const changed = snapped !== value;
+    value = snapped;
+    scope.attr(root, 'aria-valuenow', String(value));
+    track.style.transform = `translateX(${-(value - min) * pixels - 3}px)`;
+    if (changed && notify) {
+      options.onChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+    }
+  };
+  scope.on(root, 'keydown', (event) => {
+    const keys: Record<string, number> = {
+      ArrowLeft: value - step, ArrowDown: value - step, ArrowRight: value + step, ArrowUp: value + step,
+      PageDown: value - step * 10, PageUp: value + step * 10, Home: min, End: max,
+    };
+    if (!(event.key in keys)) return;
+    event.preventDefault();
+    set(keys[event.key]!);
+  });
+  scope.on(root, 'pointerdown', (event) => {
+    if (event.button !== 0 || drag) return;
+    drag = { x: event.clientX, value, id: event.pointerId };
+    root.setPointerCapture?.(event.pointerId);
+    scope.attr(root, 'data-mk-dragging', '');
+    root.focus({ preventScroll: true });
+  });
+  scope.on(window, 'pointermove', (event) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    set(drag.value - (event.clientX - drag.x) / pixels);
+  });
+  const release = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    if (root.hasPointerCapture?.(drag.id)) root.releasePointerCapture(drag.id);
+    drag = null;
+    scope.attr(root, 'data-mk-dragging', null);
+  };
+  scope.on(window, 'pointerup', release);
+  scope.on(window, 'pointercancel', release);
+  scope.on(root, 'lostpointercapture', release);
+  scope.add(() => {
+    if (drag && root.hasPointerCapture?.(drag.id)) root.releasePointerCapture(drag.id);
+  });
+  set(options.value ?? max, false);
+  return { set, get value() { return value; }, destroy: () => scope.dispose() };
+}

package/src/recipes/drag-ruler/drag-ruler.css

@@ -0,0 +1,16 @@
+.mk-drag-ruler {
+  position: relative;
+  height: 100px;
+  overflow: hidden;
+  cursor: ew-resize;
+  touch-action: pan-y;
+  user-select: none;
+  border-block: 1px solid var(--mk-outline-soft);
+}
+.mk-drag-ruler:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+.mk-drag-ruler::after { content: ''; position: absolute; left: 50%; top: 8px; width: 3px; height: 58px; background: var(--mk-accent); }
+.mk-drag-ruler__track { position: absolute; left: 50%; top: 20px; transition: transform .15s ease-out; }
+.mk-drag-ruler[data-mk-dragging] .mk-drag-ruler__track { transition: none; }
+.mk-drag-ruler__tick { position: absolute; border-left: 1px solid var(--mk-muted); height: 16px; padding-top: 28px; font: 11px monospace; }
+.mk-drag-ruler__tick:not(:empty) { height: 26px; }
+@media (prefers-reduced-motion: reduce) { .mk-drag-ruler__track { transition: none; } }

package/src/recipes/fill-text/README.md

@@ -0,0 +1,27 @@
+# fill-text
+
+Un texto cuyas letras empiezan al 20 % y se rellenan una tras otra ligadas al scroll: desde que el borde superior del texto llega al 90 % de la pantalla hasta que su centro llega al 40 % (cada letra 0.5 s de una línea de tiempo lineal, 0.1 s entre letras).
+
+Origen: iyo.ai, módulo `fill-text` (`GM`): SplitText `words, chars`, `autoAlpha .2 → 1`, `stagger .1`, `ease: linear`, ScrollTrigger con `scrub` de `top 90%` a `center 40%`. Aquí sigue al scroll con `trackScroll` y lee el texto completo a los lectores de pantalla (iyo usaba `aria: none`).
+
+## HTML / Astro
+
+```html
+<p data-mk="fill-text" class="statement">Diseñamos objetos que escuchan.</p>
+<h2 data-mk="fill-text" data-mk-start="top 80%" data-mk-end="center center">…</h2>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLParagraphElement>(null);
+useFillText(ref);
+```
+
+## API
+
+`createFillText(el, { from, start, end, scroll })` → `{ seek(p), progress, destroy }`. Clases: `.mk-fill-word`, `.mk-fill-char`.
+
+## Accesibilidad
+
+El texto entero queda en `aria-label` y las letras ocultas a los lectores. No es una entrada (no esconde el texto, lo atenúa), así que solo lo detiene el movimiento reducido: el texto queda entero y sin partir.

package/src/recipes/fill-text/create-fill-text.ts

@@ -0,0 +1,93 @@
+import { gsap, SplitText, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { trackScroll, type ScrollTrack } from '../../core/scroll-track';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * iyo.ai's fill-text: the letters start at 20 % and fill in one after another,
+ * tied to the scroll, from when the text's top reaches 90 % of the screen until
+ * its centre reaches 40 % (each letter 0.5 s of a linear timeline, 0.1 s apart).
+ */
+
+export interface FillTextOptions {
+  /** Opacity the letters start at. */
+  from?: number;
+  /** ScrollTrigger-style positions, as in trackScroll. */
+  start?: string;
+  end?: string;
+  /** Follow the scroll (default). Off: only seek() moves it. */
+  scroll?: boolean;
+}
+
+export interface FillTextInstance extends Instance {
+  /** Show the state at progress 0…1. */
+  seek(progress: number): void;
+  readonly progress: number;
+}
+
+export function createFillText(el: HTMLElement | null, options: FillTextOptions = {}): FillTextInstance {
+  if (!el) {
+    warnOnce('fill-text: missing element');
+    return inert({ seek() {}, progress: 1 });
+  }
+  const t = TIMING.fillText;
+  const { from = t.from, start = t.start, end = t.end, scroll = true } = options;
+  registerMotion();
+  // Not an entrance: the text stays readable, so only reduced motion stills it.
+  if (reduced()) {
+    el.dataset.mkReady = '';
+    return {
+      seek() {},
+      progress: 1,
+      destroy() {
+        delete el.dataset.mkReady;
+      },
+    };
+  }
+
+  let timeline: gsap.core.Timeline | null = null;
+  let progress = 0;
+  const build = (chars: Element[]) => {
+    timeline?.kill();
+    timeline = gsap
+      .timeline({ paused: true })
+      .fromTo(chars, { opacity: from }, { opacity: 1, ease: 'none', duration: t.duration, stagger: t.stagger });
+    timeline.progress(progress);
+  };
+  const split = SplitText.create(el, {
+    type: 'words,chars',
+    aria: 'auto',
+    autoSplit: true,
+    wordsClass: 'mk-fill-word',
+    charsClass: 'mk-fill-char',
+    // A new split (resize, fonts) keeps the place it was at.
+    onSplit: (self: SplitText) => build(self.chars),
+  });
+  if (!timeline) build(split.chars);
+
+  const render = (value: number) => {
+    progress = value;
+    timeline?.progress(value);
+  };
+  let track: ScrollTrack | null = scroll ? trackScroll(el, { start, end, onUpdate: render }) : null;
+  if (!track) render(0);
+  el.dataset.mkReady = '';
+
+  return {
+    seek(value: number) {
+      if (track) track.set(value);
+      else render(Math.min(1, Math.max(0, value)));
+    },
+    get progress() {
+      return progress;
+    },
+    destroy() {
+      track?.destroy();
+      track = null;
+      timeline?.kill();
+      split.revert();
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/fit-text/README.md

@@ -0,0 +1,37 @@
+# fit-text
+
+Ajusta el tamaño de una línea de texto para que ocupe exactamente el ancho de contenido de su padre; se reajusta al cambiar el ancho.
+
+Origen: portfolio — "Portfolio" y "Contacto" a ancho completo.
+
+## Vanilla / Astro
+
+```html
+<h1><span data-mk="fit-text">Portfolio</span></h1>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createFitText(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLSpanElement>(null);
+const fit = useFitText(ref);
+// tras cambiar el texto: fit.current?.refit()
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `safety` | `.995` | Fracción del ancho disponible (margen para el ojo de las letras) |
+
+## Controles
+
+`refit()`, `destroy()`
+
+## CSS
+
+El elemento es `inline-block` y `nowrap`. Con `autoInit`, espera a las fuentes web antes de medir.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.