@yewdiel21/motion-kit 0.9.1 → 0.14.0

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.