@yewdiel21/motion-kit 0.9.1 → 0.10.0

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() };
+}

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

@@ -0,0 +1,46 @@
+# scroll-dock
+
+La navegación rápida de DOVV Studio: una cápsula invertida fija abajo y al centro. Aparece cuando el scroll pasa de 0.6 alturas de ventana y se esconde cuando el footer llega a 40 px del borde inferior. Sube desde `translateY(140%)` en 0.6 s `cubic-bezier(.32,1.25,.5,1)`, un resorte con un poco de rebote, y su opacidad cambia en 0.3 s.
+
+## Vanilla / Astro
+
+```html
+<nav class="mk-scroll-dock" data-mk="scroll-dock" data-mk-hide-when="footer" aria-label="Navegación rápida">
+  <a href="#proyectos">Proyectos</a>
+  <a href="#proceso">Cómo trabajamos</a>
+  <a href="#precios">Precios</a>
+  <a href="#contacto">Contacto</a>
+</nav>
+```
+
+Con `autoInit()` las opciones van como `data-mk-<opción>` (`data-mk-threshold`, `data-mk-hide-when`, `data-mk-hide-offset`). Sin `autoInit`: `createScrollDock(el, opciones)`, que devuelve `visible`, `update()` y `destroy()`. Cada cambio emite `mk:change` con `{ visible }`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+useScrollDock(ref, { hideWhen: 'footer' });
+return <nav ref={ref} className="mk-scroll-dock" aria-label="Navegación rápida">…</nav>;
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `threshold` | `0.6` | Scroll mínimo, en alturas de ventana |
+| `hideWhen` | — | Elemento o selector que la esconde al llegar abajo |
+| `hideOffset` | `40` | px antes del borde inferior |
+| `scroller` | `window` | Contenedor con scroll propio (elemento o selector, buscado desde la cápsula hacia arriba) |
+| `onChange(visible)` | — | Al aparecer o esconderse |
+
+Dentro de un contenedor con scroll propio, añade `.mk-scroll-dock--sticky` y pasa `scroller`. Así queda pegada al borde inferior del contenedor en vez de al de la ventana. Ponla como último hijo del contenido. No ocupa sitio: se superpone a la última sección, como la versión fija, así que no deja una franja vacía al final.
+
+## Variables CSS
+
+`--mk-scroll-dock-bottom` (24 px) y `--mk-scroll-dock-height` (58 px, 64 px en móvil; sólo la usa `--sticky`; cámbiala si cambias el alto de los botones).
+
+En pantallas de 680 px o menos los botones pasan a pestañas (icono sobre etiqueta, 11 px), así caben cuatro o cinco en un teléfono. Si aun así no caben, la cápsula se desplaza por dentro y nunca desborda la página.
+
+## Accesibilidad
+
+Los enlaces siguen en el orden de tabulación. Si reciben foco con la cápsula escondida, `:focus-within` la muestra. Con movimiento reducido sólo cambia la opacidad.

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

@@ -0,0 +1,72 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+/*
+ * Scroll dock (DOVV Studio quick navigation): a floating capsule that rises
+ * once the page is scrolled past `threshold` viewports and sinks again when
+ * `hideWhen` (the footer) comes within `hideOffset` px of the bottom edge.
+ * The rise is CSS: translateY 140 % → 0 in .6 s cubic-bezier(.32,1.25,.5,1),
+ * opacity .3 s. Keyboard focus inside shows it whatever the scroll.
+ */
+
+export interface ScrollDockOptions {
+  /** Scroll distance before it shows, in viewport heights. */
+  threshold?: number;
+  /** Element (or selector) that sends it away when it reaches the viewport bottom. */
+  hideWhen?: Element | string | null;
+  /** px above the bottom edge at which `hideWhen` counts as reached. */
+  hideOffset?: number;
+  /** Scrolling element (or selector, looked up from the dock outwards); the window by default. */
+  scroller?: HTMLElement | string | null;
+  onChange?: (visible: boolean) => void;
+}
+
+export interface ScrollDockInstance extends Instance {
+  readonly visible: boolean;
+  /** Re-read the scroll position (after layout changes). */
+  update(): void;
+}
+
+export function createScrollDock(root: HTMLElement | null, options: ScrollDockOptions = {}): ScrollDockInstance {
+  if (!root) return inert({ visible: false, update() {} });
+  const scope = createScope();
+  const threshold = Number.isFinite(options.threshold) ? Math.max(0, options.threshold!) : 0.6;
+  const hideOffset = Number.isFinite(options.hideOffset) ? options.hideOffset! : 40;
+  const scroller = typeof options.scroller === 'string'
+    ? root.closest<HTMLElement>(options.scroller) ?? document.querySelector<HTMLElement>(options.scroller)
+    : options.scroller ?? null;
+  const hideTarget = () => (typeof options.hideWhen === 'string' ? document.querySelector(options.hideWhen) : options.hideWhen ?? null);
+  let visible = false;
+  let queued = false;
+  scope.attr(root, 'data-mk-ready', '');
+
+  const update = () => {
+    queued = false;
+    if (scope.disposed) return;
+    const offset = scroller ? scroller.scrollTop : window.scrollY;
+    const viewport = scroller ? scroller.clientHeight : window.innerHeight;
+    const bottom = scroller ? scroller.getBoundingClientRect().bottom : window.innerHeight;
+    const end = hideTarget();
+    const reachedEnd = end ? end.getBoundingClientRect().top < bottom - hideOffset : false;
+    const next = offset > viewport * threshold && !reachedEnd;
+    if (next === visible) return;
+    visible = next;
+    scope.attr(root, 'data-mk-visible', next ? '' : null);
+    options.onChange?.(next);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { visible: next } }));
+  };
+  const queue = () => {
+    if (queued) return;
+    queued = true;
+    requestAnimationFrame(update);
+  };
+  scope.on(scroller ?? window, 'scroll', queue, { passive: true });
+  scope.on(window, 'resize', queue, { passive: true });
+  update();
+
+  return {
+    get visible() { return visible; },
+    update,
+    destroy: () => scope.dispose(),
+  };
+}

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

@@ -0,0 +1,70 @@
+/* scroll-dock — inverted capsule at the bottom centre; rises with a soft overshoot. */
+.mk-scroll-dock {
+  position: fixed;
+  left: 50%;
+  bottom: var(--mk-scroll-dock-bottom, 24px);
+  z-index: 20;
+  display: flex;
+  gap: 4px;
+  max-width: calc(100vw - 32px);
+  padding: 6px;
+  /* Too many items for the width: scroll inside the capsule, never overflow the page. */
+  overflow-x: auto;
+  scrollbar-width: none;
+  border-radius: 100px;
+  background: var(--mk-text);
+  color: var(--mk-bg);
+  box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--mk-bg) 20%, transparent), 0 12px 30px -10px rgb(0 0 0 / 0.5);
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, 140%);
+  transition: transform 0.6s cubic-bezier(0.32, 1.25, 0.5, 1), opacity 0.3s;
+}
+.mk-scroll-dock[data-mk-visible],
+.mk-scroll-dock:focus-within {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translate(-50%, 0);
+}
+/* Inside a scrolling container: sticks to its bottom edge instead of the viewport's.
+   Scrollable overflow counts the un-stuck box plus its transform, so the negative
+   margin lifts that box by its height + bottom gap and the hide offset equals the
+   gap: nothing reaches past the last section, no empty band at the end. */
+.mk-scroll-dock--sticky {
+  position: sticky;
+  left: auto;
+  width: max-content;
+  max-width: calc(100% - 16px);
+  margin: calc(-1 * (var(--mk-scroll-dock-height, 58px) + var(--mk-scroll-dock-bottom, 24px))) auto 0;
+  transform: translateY(var(--mk-scroll-dock-bottom, 24px)) scale(0.96);
+}
+.mk-scroll-dock--sticky:is([data-mk-visible], :focus-within) { transform: none; }
+.mk-scroll-dock > :is(a, button) {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 46px;
+  padding: 0 18px;
+  border: 0;
+  border-radius: 100px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 15px;
+  font-weight: 500;
+  white-space: nowrap;
+  text-decoration: none;
+  cursor: pointer;
+  transition: background 0.25s;
+}
+.mk-scroll-dock > :is(a, button):hover { background: color-mix(in srgb, var(--mk-bg) 15%, transparent); }
+.mk-scroll-dock > :is(a, button):focus-visible { outline: 2px solid var(--mk-bg); outline-offset: -2px; }
+.mk-scroll-dock::-webkit-scrollbar { display: none; }
+/* Phones: a tab bar, icon over label, so four or five items fit in 360 px. */
+@media (max-width: 680px) {
+  .mk-scroll-dock > :is(a, button) { flex-direction: column; justify-content: center; gap: 2px; height: 52px; padding: 0 12px; border-radius: 26px; font-size: 11px; }
+  .mk-scroll-dock--sticky { margin-top: calc(-1 * (var(--mk-scroll-dock-height, 64px) + var(--mk-scroll-dock-bottom, 24px))); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .mk-scroll-dock { transition: opacity 0.2s; }
+}

package/src/recipes/sticker/README.md

@@ -0,0 +1,59 @@
+# sticker
+
+Un sticker troquelado y holográfico, como los del hero y el contacto de DOVV Studio:
+
+- **Entrada:** pasa de escala .4 y opacidad 0 a su tamaño en 0.7 s con la curva `slot` (`.34,1.56,.64,1`). Para escalonarlos, usa `--mk-sticker-delay` (0.15 s entre uno y otro en la referencia).
+- **Hover:** la rotación pasa a `--mk-sticker-rot × −0.6` y la escala a 1.08, en 0.4 s con la misma curva.
+- **Holograma:** el foil y el brillo siguen al ratón sobre el sticker (lerp .08). Sin ratón, o en táctil, derivan solos. Sólo se anima mientras el sticker es visible.
+- **Despegar:** al presionar, el borde más cercano se levanta un poco y el sticker conserva la pose que tenía, sin saltos aunque estuviera en hover. Al arrastrar en cualquier dirección (también hacia fuera, como al jalarlo), el pliegue avanza con la distancia y deja ver un dorso de papel con sombra. Si lo sueltas pronto, se vuelve a pegar en 380 ms. Pasado el 30 % del área, o tras arrastrar la mitad de su lado largo (80 px como mínimo), se suelta: sigue al puntero (lerp .22), crece un 8 % y se inclina con la velocidad (±16°). Al soltarlo cae con gravedad (1600 px/s²) y giro, y a los 2.5 s vuelve a su sitio con la entrada.
+
+El pliegue es propio: el frente se recorta con `clip-path` a un lado de la línea de pliegue y el dorso es una copia reflejada sobre ella. No usa Peel.js ni dependencias. Respecto a la referencia, el kit añade cuatro cosas: congela la pose al presionar, despega también al jalar hacia fuera, limita el estiramiento (la esquina no se aleja de la arista opuesta más que su distancia original) y sombrea el dorso. Así no levanta de golpe toda una píldora larga.
+
+## Vanilla / Astro
+
+```html
+<div class="hero" style="position: relative">
+  <div class="mk-sticker" data-mk="sticker" aria-hidden="true"
+       style="position: absolute; left: -4%; top: -12%; --mk-sticker-rot: -9deg; --mk-sticker-delay: .9s">
+    <span class="mk-sticker__pill">Framer expert</span>
+  </div>
+  <div class="mk-sticker mk-sticker--lime" data-mk="sticker" aria-hidden="true" style="position: absolute; right: 0; bottom: 0; --mk-sticker-rot: 7deg">
+    <span class="mk-sticker__badge">4.9 ★</span>
+  </div>
+</div>
+```
+
+El arte puede ser `.mk-sticker__pill` (cápsula), `.mk-sticker__badge` (círculo, `--mk-sticker-size`) o cualquier elemento con `.mk-sticker__art` (`--mk-sticker-radius`). Paletas: por defecto naranja, `--pink`, `--blue`, `--lime` y `--gold`. Para una propia, define `--mk-sticker-foil` (un gradiente) y `--mk-sticker-ink`.
+
+Sin `autoInit`: `createSticker(el, opciones)`. Devuelve `state` (`idle | peeling | carried | falling | away`) y `destroy()`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useSticker(ref, { returnDelay: 2500 });
+return <div ref={ref} className="mk-sticker mk-sticker--blue" aria-hidden="true"><span className="mk-sticker__pill">hey!</span></div>;
+```
+
+Mientras está despegado, el elemento se mueve a `document.body` con `position: fixed` (así no lo recortan los contenedores) y después vuelve a su padre. No desmontes el sticker en ese intervalo; si lo haces, `destroy()` lo devuelve a su sitio.
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `peel` | `true` | Permite despegarlo arrastrando |
+| `holo` | `true` | Foil y brillo que siguen al puntero |
+| `detachAt` | `0.3` | Fracción del área levantada a partir de la cual se suelta |
+| `detachDistance` | mitad del lado largo, mín. 80 | px de arrastre (sin escala) a partir de los cuales se suelta |
+| `returnDelay` | `2500` | ms oculto después de caer |
+| `onPeel`, `onReturn` | — | Al soltarse y al volver |
+
+## Variables CSS
+
+`--mk-sticker-rot`, `--mk-sticker-delay`, `--mk-sticker-scale` (la referencia usa .8 bajo 1200 px y .6 bajo 810 px), `--mk-sticker-foil`, `--mk-sticker-ink`, `--mk-sticker-size` y `--mk-sticker-radius`.
+
+El dorso de papel cubre `.mk-sticker__pill`, `__badge` y `__art`. Si el arte es una forma libre (un `<img>` o `<svg>` con transparencia), añade `data-mk-sticker-back="silhouette"` al sticker y el dorso será su silueta blanca.
+
+## Accesibilidad
+
+Es decoración: márcalo con `aria-hidden="true"` y deja el texto importante en el contenido. Si el sticker transmite información, usa `peel: false`. Con movimiento reducido no hay entrada, hover ni holograma animado; despegar sigue funcionando porque lo hace el usuario, pero sin caída: se oculta y vuelve.