@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/magnetize-button/README.md

@@ -0,0 +1,26 @@
+# Magnetize button
+
+Partículas discretas reposan alrededor de un botón tonal. Hover o foco las atrae hacia el perímetro; al salir se separan y vuelven a reposar. Es un efecto de atracción de partículas, con el botón estable. Las transiciones usan `EASE.swatch` y se pueden interrumpir. No usa RAF ni un ticker propio en reposo.
+
+```ts
+import { createMagnetizeButton } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/magnetize-button';
+const magnet = createMagnetizeButton(document.querySelector('#gather'), {
+  onAction: () => groupSelectedIdeas(),
+});
+// magnet.attract(); magnet.release(); magnet.destroy();
+```
+
+`MagnetizeButtonOptions`: `label` (Reunir ideas, solo si falta contenido), `count` (14, limitado a 4–24), `reach` (42px, limitado a 16–90), `onAction`. `MagnetizeButtonInstance`: `attract()`, `release()`, `attracted`, `destroy()`. Emite `mk:action` en clic nativo, incluido teclado y tacto. El factory acepta un botón, un host con botón o crea uno si falta. Su `type` predeterminado es `button`.
+
+```tsx
+<MagnetizeButton label="Reunir ideas" onAction={groupSelectedIdeas} instanceRef={magnetRef} />
+```
+
+`MagnetizeButtonProps` añade atributos nativos e `instanceRef`. El motor posee los hijos; se usa `label` y se filtran `children`/`dangerouslySetInnerHTML` en ejecución.
+
+```html
+<mk-magnetize-button count="14" reach="42"><button type="button">Reunir ideas</button></mk-magnetize-button>
+```
+
+`defineMagnetizeButton()` registra `MkMagnetizeButtonElement`; atributos `label`, `count`, `reach`. Teclado muestra la misma atracción y un anillo de foco. Movimiento reducido o disabled oculta partículas; la acción sigue siendo nativa. Reserva hasta `reach` de aire alrededor del botón para ver el efecto. `destroy()` desconecta observers, media listeners, eventos y animaciones, retira partículas y restaura nodos y estilos originales.

package/src/components/magnetize-button/element.ts

@@ -0,0 +1,13 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMagnetizeButton, type MagnetizeButtonInstance } from './engine';
+
+export class MkMagnetizeButtonElement extends MkElement<MagnetizeButtonInstance> {
+  static options: Record<string, OptionType> = { label: 'string', count: 'number', reach: 'number' };
+  protected create(options: Record<string, unknown>) { return createMagnetizeButton(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focused = this.contains(document.activeElement);
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) this.querySelector<HTMLButtonElement>('button')?.focus({ preventScroll: true });
+  }
+}
+export const defineMagnetizeButton = () => defineElement('mk-magnetize-button', MkMagnetizeButtonElement);

package/src/components/magnetize-button/engine.ts

@@ -0,0 +1,84 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+export interface MagnetizeButtonOptions {
+  label?: string;
+  /** Discrete particles, clamped to 4–24. No idle ticker. */
+  count?: number;
+  /** Distance outside the button where the particles rest, default 42px. */
+  reach?: number;
+  onAction?: () => void;
+}
+export interface MagnetizeButtonInstance extends Instance { attract(): void; release(): void; readonly attracted: boolean; }
+
+export function createMagnetizeButton(root: HTMLElement | null, options: MagnetizeButtonOptions = {}): MagnetizeButtonInstance {
+  if (!root) return inert({ attract() {}, release() {}, attracted: false });
+  registerMotion();
+  const scope = createScope();
+  let button = root.matches('button') ? root as HTMLButtonElement : root.querySelector<HTMLButtonElement>('button');
+  if (!button) { button = document.createElement('button'); root.append(button); const made = button; scope.add(() => made.remove()); }
+  const control = button;
+  if (!control.textContent?.trim() && !control.querySelector('[aria-label], svg, img')) {
+    const label = document.createElement('span'); label.textContent = options.label ?? 'Reunir ideas'; control.append(label); scope.add(() => label.remove());
+  }
+  const originalStyle = control.getAttribute('style');
+  const originalTransform = control.style.transform;
+  scope.add(() => { if (originalStyle === null) control.removeAttribute('style'); else control.setAttribute('style', originalStyle); });
+  scope.attr(control, 'type', control.getAttribute('type') ?? 'button');
+  scope.attr(control, 'data-mk-magnetize-button', '');
+  scope.attr(root, 'data-mk-ready', '');
+  const layer = document.createElement('span'); layer.dataset.mkMagnetParticles = ''; layer.setAttribute('aria-hidden', 'true'); control.append(layer); scope.add(() => layer.remove());
+  const count = Number.isFinite(options.count) ? Math.min(24, Math.max(4, Math.round(options.count!))) : 14;
+  const reach = Number.isFinite(options.reach) ? Math.min(90, Math.max(16, options.reach!)) : 42;
+  const dots: HTMLElement[] = [];
+  for (let i = 0; i < count; i++) { const dot = document.createElement('i'); layer.append(dot); dots.push(dot); }
+  let hovered = false;
+  let focused = false;
+  let attracted = false;
+  let tween: gsap.core.Timeline | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const disabled = () => control.disabled || control.getAttribute('aria-disabled') === 'true';
+  const positions = (near: boolean) => {
+    const w = control.offsetWidth || 160;
+    const h = control.offsetHeight || 48;
+    return dots.map((_, i) => {
+      const angle = i / count * Math.PI * 2 - Math.PI / 2;
+      // Intersect a ray with the rounded rectangle envelope; attraction lands at the perimeter.
+      const c = Math.cos(angle); const s = Math.sin(angle);
+      const boundary = Math.min((w / 2 + 4) / Math.max(.001, Math.abs(c)), (h / 2 + 4) / Math.max(.001, Math.abs(s)));
+      const radius = boundary + (near ? 0 : reach * (.72 + (i % 3) * .14));
+      return { x: c * radius, y: s * radius, opacity: near ? .88 : .25, scale: near ? 1 : .6 };
+    });
+  };
+  const paint = (near: boolean, animate: boolean) => {
+    tween?.kill(); tween = null;
+    layer.hidden = reduced() || disabled();
+    if (layer.hidden) { attracted = false; scope.attr(control, 'data-mk-attracted', null); return; }
+    attracted = near;
+    scope.attr(control, 'data-mk-attracted', near ? '' : null);
+    const targets = positions(near);
+    if (!animate) { dots.forEach((dot, i) => gsap.set(dot, targets[i]!)); return; }
+    tween = gsap.timeline();
+    dots.forEach((dot, i) => tween!.to(dot, { ...targets[i]!, duration: near ? .62 : .48, ease: near ? EASE.swatch : EASE.signature }, i * .008));
+  };
+  const sync = () => paint(hovered || focused, true);
+  scope.on(control, 'pointerenter', () => { hovered = true; sync(); });
+  scope.on(control, 'pointerleave', () => { hovered = false; sync(); });
+  scope.on(control, 'focus', () => { focused = true; sync(); });
+  scope.on(control, 'blur', () => { focused = false; sync(); });
+  scope.on(control, 'click', (event) => {
+    if (disabled()) { event.preventDefault(); return; }
+    pressing?.kill(); pressing = press(control);
+    pressing?.eventCallback('onComplete', () => { gsap.set(control, { clearProps: 'transform,scale' }); control.style.transform = originalTransform; if (!control.getAttribute('style')) control.removeAttribute('style'); });
+    options.onAction?.(); root.dispatchEvent(new CustomEvent('mk:action', { bubbles: true }));
+  });
+  if (typeof ResizeObserver !== 'undefined') scope.observe(new ResizeObserver(() => paint(attracted, false))).observe(control);
+  if (typeof MutationObserver !== 'undefined') scope.observe(new MutationObserver(() => paint(hovered || focused, false))).observe(control, { attributes: true, attributeFilter: ['disabled', 'aria-disabled'] });
+  if (typeof matchMedia === 'function') { const media = matchMedia('(prefers-reduced-motion: reduce)'); scope.on(media, 'change', () => paint(hovered || focused, false)); }
+  paint(false, false);
+  scope.add(() => { tween?.kill(); pressing?.kill(); gsap.killTweensOf(dots); });
+  return { attract: () => { if (!scope.disposed) paint(true, true); }, release: () => { if (!scope.disposed) paint(false, true); }, get attracted() { return attracted; }, destroy: () => scope.dispose() };
+}

package/src/components/magnetize-button/magnetize-button.css

@@ -0,0 +1,17 @@
+.mk-magnetize-button,
+mk-magnetize-button { display: inline-flex; overflow: visible; }
+[data-mk-magnetize-button] {
+  position: relative; display: inline-flex; align-items: center; justify-content: center; gap: .6rem; min-height: 48px;
+  padding: .8rem 1.5rem; border: 1px solid var(--mk-outline-soft); border-radius: 16px; background: var(--mk-surface-3);
+  color: var(--mk-text); font: 500 .9375rem var(--mk-font); cursor: pointer; overflow: visible;
+  transition: background 160ms, border-radius 350ms var(--mk-ease-swatch);
+}
+[data-mk-magnetize-button]:is(:hover, [data-mk-attracted]):not(:disabled) { border-radius: 24px; background: var(--mk-surface-4); }
+[data-mk-magnetize-button]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 8px; }
+[data-mk-magnetize-button]:disabled,
+[data-mk-magnetize-button][aria-disabled='true'] { opacity: .4; cursor: not-allowed; }
+[data-mk-magnet-particles] { position: absolute; inset: 0; pointer-events: none; }
+[data-mk-magnet-particles][hidden] { display: none; }
+[data-mk-magnet-particles] i { position: absolute; top: 50%; left: 50%; width: 4px; height: 4px; margin: -2px; border-radius: 999px; background: var(--mk-muted); }
+[data-mk-magnet-particles] i:nth-child(4n) { width: 5px; height: 5px; background: var(--mk-accent); }
+@media (prefers-reduced-motion: reduce) { [data-mk-magnet-particles] { display: none; } [data-mk-magnetize-button] { transition: none; } }

package/src/components/magnetize-button/react.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createMagnetizeButton, type MagnetizeButtonInstance, type MagnetizeButtonOptions } from './engine';
+
+export interface MagnetizeButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'dangerouslySetInnerHTML'>, MagnetizeButtonOptions { instanceRef?: Ref<MagnetizeButtonInstance>; }
+export function MagnetizeButton({ label = 'Reunir ideas', count, reach, onAction, instanceRef, type = 'button', className, ...props }: MagnetizeButtonProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as ButtonHTMLAttributes<HTMLButtonElement>;
+  const root = useRef<HTMLButtonElement>(null);
+  const instance = useRef<MagnetizeButtonInstance | null>(null);
+  const action = useLatest(onAction);
+  useIsomorphicLayoutEffect(() => {
+    const created = createMagnetizeButton(root.current, { label, count, reach, onAction: () => action.current?.() });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [label, count, reach]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, label, count, reach]);
+  return <button {...safe} type={type} ref={root} className={['mk-magnetize-button', className].filter(Boolean).join(' ')} />;
+}

package/src/components/morphing-page-dots/README.md

@@ -0,0 +1,28 @@
+# Morphing page dots
+
+Indicador de páginas: una píldora se estira hacia el nuevo índice y su cola alcanza el destino con `EASE.swatch`. Los puntos siguen siendo botones nativos de 44px con foco visible y `aria-current="page"`. No inicia reproducción automática ni crea diapositivas.
+
+```ts
+import { createMorphingPageDots } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/morphing-page-dots';
+const dots = createMorphingPageDots(document.querySelector('#pages'), {
+  count: 4, value: 0, pageIds: ['slide-a', 'slide-b', 'slide-c', 'slide-d'],
+  onChange: (index) => showSlide(index),
+});
+dots.setValue(2, true);
+// dots.destroy();
+```
+
+`MorphingPageDotsOptions`: `count` (5, entre 1–20), `value` (índice desde 0), `label` (Páginas), `labels` (nombres de cada página), `pageIds` (aria-controls opcional), `disabled`, `onChange(index)`. `MorphingPageDotsInstance`: `setValue(index, notify = false)`, `value`, `destroy()`. Emite `mk:change` con `{value}` al notificar. Flechas izquierda/derecha recorren y seleccionan con wrapping; Home/End van a los extremos. Respeta RTL. La app debe mantener las diapositivas y su contenido accesible sincronizados.
+
+```tsx
+<MorphingPageDots count={slides.length} value={index} onChange={setIndex} />
+```
+
+React admite `value` controlado o `defaultValue`, `instanceRef` y atributos de div. El estado controlado sigue siendo la autoridad si se rechaza el cambio. El motor posee todos los hijos; `children` y `dangerouslySetInnerHTML` se filtran también en ejecución.
+
+```html
+<mk-morphing-page-dots count="4" value="0" labels='["Sierra","Lago","Pinar","Dunas"]'></mk-morphing-page-dots>
+```
+
+`defineMorphingPageDots()` registra `MkMorphingPageDotsElement`; atributos `count`, `value`, `label`, `labels` (JSON), `page-ids` (JSON), `disabled`. Conserva la selección al cambiar presentación o reconectar; un cambio del atributo `value` la reemplaza. Movimiento reducido coloca la píldora directamente. `destroy()` elimina observers, animaciones, eventos y devuelve los nodos/atributos originales.

package/src/components/morphing-page-dots/element.ts

@@ -0,0 +1,16 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMorphingPageDots, type MorphingPageDotsInstance } from './engine';
+
+export class MkMorphingPageDotsElement extends MkElement<MorphingPageDotsInstance> {
+  static options: Record<string, OptionType> = { count: 'number', value: 'number', label: 'string', labels: 'json', pageIds: 'json', disabled: 'boolean' };
+  private retained: number | undefined;
+  protected create(options: Record<string, unknown>) { return createMorphingPageDots(this, { ...options, ...(this.retained === undefined ? {} : { value: this.retained }) }); }
+  disconnectedCallback() { this.retained = this.instance?.value ?? this.retained; super.disconnectedCallback(); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focusIndex = [...this.querySelectorAll('button')].findIndex((button) => button === document.activeElement);
+    if (previous !== next) this.retained = name === 'value' ? undefined : this.instance?.value ?? this.retained;
+    super.attributeChangedCallback(name, previous, next);
+    if (focusIndex >= 0) { const buttons = this.querySelectorAll('button'); buttons[Math.min(focusIndex, buttons.length - 1)]?.focus({ preventScroll: true }); }
+  }
+}
+export const defineMorphingPageDots = () => defineElement('mk-morphing-page-dots', MkMorphingPageDotsElement);

package/src/components/morphing-page-dots/engine.ts

@@ -0,0 +1,89 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+export interface MorphingPageDotsOptions {
+  count?: number;
+  value?: number;
+  label?: string;
+  /** Accessible page names; by default "Página 1 de 5". */
+  labels?: string[];
+  /** Optional ids of the real carousel slides controlled by each dot. */
+  pageIds?: string[];
+  disabled?: boolean;
+  onChange?: (index: number) => void;
+}
+export interface MorphingPageDotsInstance extends Instance {
+  setValue(index: number, notify?: boolean): void;
+  readonly value: number;
+}
+export function createMorphingPageDots(root: HTMLElement | null, options: MorphingPageDotsOptions = {}): MorphingPageDotsInstance {
+  if (!root) return inert({ setValue() {}, value: 0 });
+  registerMotion();
+  const scope = createScope();
+  const count = Number.isFinite(options.count) ? Math.min(20, Math.max(1, Math.round(options.count!))) : 5;
+  const normalize = (index: number) => Math.min(count - 1, Math.max(0, Math.round(index)));
+  let value = normalize(Number.isFinite(options.value) ? options.value! : 0);
+  const authored = [...root.childNodes];
+  const rail = document.createElement('span'); rail.dataset.mkPageRail = '';
+  const blob = document.createElement('i'); blob.dataset.mkPageBlob = ''; blob.setAttribute('aria-hidden', 'true'); rail.append(blob);
+  const buttons: HTMLButtonElement[] = [];
+  for (let i = 0; i < count; i++) {
+    const button = document.createElement('button'); button.type = 'button'; button.dataset.mkPageDot = '';
+    button.setAttribute('aria-label', options.labels?.[i] ?? `Página ${i + 1} de ${count}`);
+    if (options.pageIds?.[i]) button.setAttribute('aria-controls', options.pageIds[i]!);
+    button.disabled = Boolean(options.disabled);
+    const dot = document.createElement('i'); dot.setAttribute('aria-hidden', 'true'); button.append(dot); rail.append(button); buttons.push(button);
+  }
+  root.replaceChildren(rail);
+  scope.add(() => { rail.remove(); root.append(...authored); });
+  scope.attr(root, 'role', 'group');
+  scope.attr(root, 'aria-label', options.label ?? 'Páginas');
+  scope.attr(root, 'data-mk-morphing-page-dots', '');
+  scope.attr(root, 'data-mk-ready', '');
+  let moving: gsap.core.Timeline | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const at = (index: number) => {
+    const button = buttons[index]!;
+    const size = button.offsetWidth || 44;
+    return (button.offsetLeft || index * size) + size / 2 - 12;
+  };
+  const place = () => { moving?.kill(); moving = null; gsap.set(blob, { left: at(value), width: 24, scaleY: 1 }); };
+  const paint = () => buttons.forEach((button, i) => { button.setAttribute('aria-current', i === value ? 'page' : 'false'); button.tabIndex = i === value ? 0 : -1; });
+  const setValue = (index: number, notify = false) => {
+    if (scope.disposed || !Number.isFinite(index)) return;
+    const next = normalize(index);
+    if (value === next) return;
+    const start = at(value); const end = at(next);
+    value = next;
+    paint();
+    moving?.kill();
+    if (reduced()) place();
+    else {
+      // Stretch the leading edge, then let the tail catch up on the shared swatch curve.
+      const current = Number(gsap.getProperty(blob, 'left')) || start;
+      moving = gsap.timeline()
+        .to(blob, { left: Math.min(current, end), width: Math.abs(end - current) + 24, scaleY: .68, duration: .18, ease: EASE.wipe })
+        .to(blob, { left: end, width: 24, scaleY: 1, duration: .48, ease: EASE.swatch }, .13);
+    }
+    if (notify) { options.onChange?.(value); root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } })); }
+  };
+  buttons.forEach((button, i) => {
+    scope.on(button, 'click', () => { if (button.disabled) return; pressing?.kill(); pressing = press(button); setValue(i, true); });
+    scope.on(button, 'keydown', (event) => {
+      if (button.disabled) return;
+      const key = event.key;
+      if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(key)) return;
+      event.preventDefault();
+      const rtl = getComputedStyle(root).direction === 'rtl';
+      let next = key === 'Home' ? 0 : key === 'End' ? count - 1 : (value + ((key === 'ArrowRight') !== rtl ? 1 : -1) + count) % count;
+      setValue(next, true); buttons[next]!.focus();
+    });
+  });
+  if (typeof ResizeObserver !== 'undefined') scope.observe(new ResizeObserver(place)).observe(rail);
+  paint(); place();
+  scope.add(() => { moving?.kill(); pressing?.kill(); });
+  return { setValue, get value() { return value; }, destroy: () => scope.dispose() };
+}

package/src/components/morphing-page-dots/morphing-page-dots.css

@@ -0,0 +1,12 @@
+.mk-morphing-page-dots,
+mk-morphing-page-dots { display: inline-flex; max-width: 100%; color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-page-rail] { position: relative; display: inline-flex; max-width: 100%; border-radius: 999px; background: var(--mk-surface-2); padding: 0; overflow-x: auto; }
+[data-mk-page-dot] { position: relative; flex: 0 0 44px; width: 44px; height: 44px; display: grid; place-items: center; padding: 0; background: transparent; border: 0; border-radius: 999px; cursor: pointer; }
+[data-mk-page-dot] > i { width: 8px; height: 8px; border-radius: 999px; background: var(--mk-muted); opacity: .45; transition: opacity 150ms; }
+[data-mk-page-dot]:hover > i { opacity: .85; }
+[data-mk-page-dot][aria-current='page'] > i { opacity: 0; }
+[data-mk-page-dot]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: -3px; }
+[data-mk-page-dot]:disabled { cursor: not-allowed; opacity: .4; }
+[data-mk-page-blob] { position: absolute; top: 18px; left: 10px; width: 24px; height: 8px; background: var(--mk-text); border-radius: 999px; pointer-events: none; }
+[data-mk-morphing-page-dots]:has(button:disabled) [data-mk-page-blob] { opacity: .4; }
+@media (prefers-reduced-motion: reduce) { [data-mk-page-dot] > i { transition: none; } }

package/src/components/morphing-page-dots/react.tsx

@@ -0,0 +1,32 @@
+'use client';
+import { useRef, type HTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createMorphingPageDots, type MorphingPageDotsInstance, type MorphingPageDotsOptions } from './engine';
+
+export interface MorphingPageDotsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'onChange'>, MorphingPageDotsOptions {
+  defaultValue?: number;
+  instanceRef?: Ref<MorphingPageDotsInstance>;
+}
+export function MorphingPageDots({ count, value, defaultValue = 0, label, labels, pageIds, disabled, onChange, instanceRef, className, ...props }: MorphingPageDotsProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<MorphingPageDotsInstance | null>(null);
+  const current = useLatest({ value, onChange });
+  const retained = useRef(defaultValue);
+  const labelsKey = JSON.stringify(labels); const pagesKey = JSON.stringify(pageIds);
+  useIsomorphicLayoutEffect(() => {
+    let created: MorphingPageDotsInstance;
+    created = createMorphingPageDots(root.current, {
+      count, value: current.current.value ?? retained.current, label, labels, pageIds, disabled,
+      onChange: (next) => { current.current.onChange?.(next); if (current.current.value !== undefined) created.setValue(current.current.value); },
+    });
+    instance.current = created;
+    return () => { retained.current = created.value; created.destroy(); instance.current = null; };
+  }, [count, label, labelsKey, pagesKey, disabled]);
+  useIsomorphicLayoutEffect(() => { if (value !== undefined) instance.current?.setValue(value); }, [value]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, count, label, labelsKey, pagesKey, disabled]);
+  return <div {...safe} ref={root} className={['mk-morphing-page-dots', className].filter(Boolean).join(' ')} />;
+}

package/src/components/not-found/README.md

@@ -0,0 +1,26 @@
+# Not found
+
+Estado 404 con ilustración vectorial original: dos cuatros y un pequeño portal en lugar del cero. Su entrada combina blur escalonado y un asentamiento `swatch`; permanece quieto después. Usa superficies del tema y reserva el acento para la brújula.
+
+```ts
+import { createNotFound } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/not-found';
+const missing = createNotFound(document.querySelector('#missing'), {
+  brand: 'Mi biblioteca', homeHref: '/library',
+});
+// missing.replay(); missing.destroy();
+```
+
+`NotFoundOptions`: `brand` (Motion Kit), `title`, `description`, `homeHref` (/), `homeLabel`, `backLabel`, `showBack` (true), `onBack`. El enlace Home navega a su href real. Back llama `history.back()`; se desactiva cuando no hay entrada previa. `onBack` permite que un router posea la acción. `NotFoundInstance`: `replay()`, `destroy()`. Todo el contenido configurable se inserta como texto, no como HTML.
+
+```tsx
+<NotFound brand="Mi biblioteca" homeHref="/library" instanceRef={missingRef} />
+```
+
+`NotFoundProps` añade atributos de div e `instanceRef`; el motor posee todos los hijos, por lo que filtra `children` y `dangerouslySetInnerHTML` en ejecución. Cambiar copy o destinos actualiza la instancia. Movimiento reducido conserva toda la navegación y muestra el estado completo inmediatamente.
+
+```html
+<mk-not-found brand="Mi biblioteca" home-href="/library" title="No encontramos esa lectura."></mk-not-found>
+```
+
+`defineNotFound()` registra `MkNotFoundElement`; atributos `brand`, `title`, `description`, `home-href`, `home-label`, `back-label`, `show-back`. El contenido usa heading h2 para poder incrustarlo en un layout; la página anfitriona determina su h1 y su código HTTP. `destroy()` detiene la entrada y devuelve los nodos y atributos originales.

package/src/components/not-found/element.ts

@@ -0,0 +1,15 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createNotFound, type NotFoundInstance } from './engine';
+
+export class MkNotFoundElement extends MkElement<NotFoundInstance> {
+  static options: Record<string, OptionType> = { brand: 'string', title: 'string', description: 'string', homeHref: 'string', homeLabel: 'string', backLabel: 'string', showBack: 'boolean' };
+  protected create(options: Record<string, unknown>) { return createNotFound(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const active = document.activeElement;
+    const focused = this.contains(active);
+    const back = active?.tagName === 'BUTTON';
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) (this.querySelector<HTMLElement>(back ? 'button:not(:disabled)' : 'a') ?? this.querySelector<HTMLElement>('a'))?.focus({ preventScroll: true });
+  }
+}
+export const defineNotFound = () => defineElement('mk-not-found', MkNotFoundElement);

package/src/components/not-found/engine.ts

@@ -0,0 +1,57 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press } from '../../motion/micro';
+
+export interface NotFoundOptions {
+  brand?: string;
+  title?: string;
+  description?: string;
+  homeHref?: string;
+  homeLabel?: string;
+  backLabel?: string;
+  showBack?: boolean;
+  /** A router may own Back. Without this callback it calls history.back(). */
+  onBack?: () => void;
+}
+export interface NotFoundInstance extends Instance { replay(): void; }
+const ILLUSTRATION = '<svg viewBox="0 0 320 140" fill="none" aria-hidden="true"><path data-mk-lost-track d="M20 115H100Q118 115 118 95V72Q118 53 138 53H185Q205 53 205 73V95Q205 115 224 115H300"/><g data-mk-lost-four><path d="M72 23L35 79H84M77 23V107"/><path d="M263 23L226 79H275M268 23V107"/></g><g data-mk-lost-portal><rect x="124" y="18" width="72" height="96" rx="32"/><ellipse cx="160" cy="66" rx="17" ry="29"/><path d="M145 66h30M160 51v30"/></g><path data-mk-lost-star d="M211 13v12m-6-6h12M105 118v8m-4-4h8"/></svg>';
+export function createNotFound(root: HTMLElement | null, options: NotFoundOptions = {}): NotFoundInstance {
+  if (!root) return inert({ replay() {} });
+  registerMotion();
+  const scope = createScope();
+  const authored = [...root.childNodes];
+  const content = document.createElement('div'); content.dataset.mkNotFoundContent = '';
+  const art = document.createElement('div'); art.dataset.mkNotFoundArt = ''; art.innerHTML = ILLUSTRATION;
+  const eyebrow = document.createElement('p'); eyebrow.dataset.mkNotFoundCode = ''; eyebrow.textContent = `404 · ${options.brand ?? 'Motion Kit'}`;
+  const heading = document.createElement('h2'); heading.textContent = options.title ?? 'Este camino se perdió.';
+  const description = document.createElement('p'); description.dataset.mkNotFoundDescription = ''; description.textContent = options.description ?? 'La página que buscas no está aquí. Volvamos a un lugar conocido.';
+  const actions = document.createElement('div'); actions.dataset.mkNotFoundActions = '';
+  const home = document.createElement('a'); home.href = options.homeHref ?? '/'; home.textContent = options.homeLabel ?? 'Volver al inicio';
+  actions.append(home);
+  const back = document.createElement('button'); back.type = 'button'; back.textContent = options.backLabel ?? 'Ir atrás';
+  back.disabled = !options.onBack && history.length <= 1;
+  if (options.showBack !== false) actions.append(back);
+  content.append(art, eyebrow, heading, description, actions);
+  root.replaceChildren(content);
+  scope.add(() => { content.remove(); root.append(...authored); });
+  scope.attr(root, 'data-mk-not-found', '');
+  scope.attr(root, 'data-mk-ready', '');
+  let entering: gsap.core.Animation | null = null;
+  let drawing: gsap.core.Animation | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const portal = art.querySelector('[data-mk-lost-portal]');
+  const replay = () => {
+    if (scope.disposed) return;
+    entering?.kill(); drawing?.kill();
+    if (reduced()) { gsap.set([art, eyebrow, heading, description, actions], { clearProps: 'all' }); return; }
+    entering = blurIn([art, eyebrow, heading, description, actions], { from: 'soft', duration: .5, stagger: .055 });
+    drawing = gsap.fromTo(portal, { rotation: -12, scale: .82, transformOrigin: '50% 50%' }, { rotation: 0, scale: 1, duration: .8, ease: EASE.swatch });
+  };
+  scope.on(back, 'click', () => { if (!back.disabled) { pressing?.kill(); pressing = press(back); if (options.onBack) options.onBack(); else history.back(); } });
+  scope.on(home, 'click', () => { pressing?.kill(); pressing = press(home); });
+  replay();
+  scope.add(() => { entering?.kill(); drawing?.kill(); pressing?.kill(); });
+  return { replay, destroy: () => scope.dispose() };
+}

package/src/components/not-found/not-found.css

@@ -0,0 +1,21 @@
+.mk-not-found,
+mk-not-found { display: block; max-width: 34rem; color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-not-found-content] { display: grid; justify-items: center; text-align: center; gap: .75rem; padding: .75rem 1rem; }
+[data-mk-not-found-art] { width: min(100%, 320px); }
+[data-mk-not-found-art] svg { display: block; width: 100%; overflow: visible; }
+[data-mk-lost-track] { stroke: var(--mk-outline); stroke-width: 1.5; stroke-dasharray: 3 5; }
+[data-mk-lost-four] { stroke: var(--mk-text); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; }
+[data-mk-lost-portal] rect { fill: var(--mk-surface-3); stroke: var(--mk-outline-soft); }
+[data-mk-lost-portal] ellipse { fill: var(--mk-surface-1); stroke: var(--mk-outline); stroke-width: 1.5; }
+[data-mk-lost-portal] path,
+[data-mk-lost-star] { stroke: var(--mk-accent); stroke-width: 2; stroke-linecap: round; }
+[data-mk-not-found-code] { margin: 0; color: var(--mk-muted); font-size: .6875rem; letter-spacing: .1em; text-transform: uppercase; }
+[data-mk-not-found-content] h2 { margin: 0; font-size: clamp(1.5rem, 4vw, 2rem); font-weight: 550; line-height: 1.15; letter-spacing: -.045em; }
+[data-mk-not-found-description] { max-width: 34ch; margin: 0; color: var(--mk-muted); font-size: .875rem; line-height: 1.55; }
+[data-mk-not-found-actions] { display: flex; flex-wrap: wrap; justify-content: center; gap: .5rem; margin-top: .5rem; }
+[data-mk-not-found-actions] :is(a, button) { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: .7rem 1rem; border: 0; border-radius: 16px; background: var(--mk-surface-3); color: var(--mk-text); font: 500 .875rem var(--mk-font); text-decoration: none; cursor: pointer; transition: background 160ms, border-radius 320ms var(--mk-ease-swatch); }
+[data-mk-not-found-actions] a { background: var(--mk-text); color: var(--mk-bg); }
+[data-mk-not-found-actions] :is(a, button):hover { border-radius: 24px; }
+[data-mk-not-found-actions] :is(a, button):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-not-found-actions] button:disabled { opacity: .4; cursor: not-allowed; }
+@media (prefers-reduced-motion: reduce) { [data-mk-not-found-actions] :is(a, button) { transition: none; } }

package/src/components/not-found/react.tsx

@@ -0,0 +1,23 @@
+'use client';
+import { useRef, type HTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createNotFound, type NotFoundInstance, type NotFoundOptions } from './engine';
+
+export interface NotFoundProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'title'>, NotFoundOptions { instanceRef?: Ref<NotFoundInstance>; }
+export function NotFound({ brand, title, description, homeHref, homeLabel, backLabel, showBack, onBack, instanceRef, className, ...props }: NotFoundProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<NotFoundInstance | null>(null);
+  const current = useLatest(onBack);
+  const hasBack = Boolean(onBack);
+  useIsomorphicLayoutEffect(() => {
+    const created = createNotFound(root.current, { brand, title, description, homeHref, homeLabel, backLabel, showBack, onBack: hasBack ? () => current.current?.() : undefined });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [brand, title, description, homeHref, homeLabel, backLabel, showBack, hasBack]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, brand, title, description, homeHref, homeLabel, backLabel, showBack, hasBack]);
+  return <div {...safe} ref={root} className={['mk-not-found', className].filter(Boolean).join(' ')} />;
+}

package/src/components/notification-stack/README.md

@@ -0,0 +1,24 @@
+# Notification stack
+
+A local notification deck with overlapping tonal cards, explicit expand/collapse, actions, dismissal and pausable durations. It is independent of the global `toast` store, so several decks can coexist.
+
+```ts
+import { createNotificationStack } from '@yewdiel21/motion-kit';
+const stack = createNotificationStack(document.querySelector('#notifications'), {
+  items: [{ id: 'saved', title: 'Cambios guardados', tone: 'success', duration: 0 }],
+});
+stack.push({ id: 'review', title: 'Versión lista', duration: 6000, action: { label: 'Revisar', onClick: openReview } });
+stack.expand();
+// On unmount:
+stack.destroy();
+```
+
+Exports: `createNotificationStack`, `NotificationStackItem`, `NotificationStackOptions`, `NotificationStackInstance`; React `NotificationStack`, `NotificationStackProps`; elements `MkNotificationStackElement`, `defineNotificationStack` (`mk-notification-stack`). CSS: `notification-stack.css` plus the kit tokens/theme/fonts.
+
+Options: `items`, `expanded`, `direction` (`down` default, `up` or `side`), `duration` (milliseconds, default 6000, zero persists), `disabled`, `label`, `labels` (`expand`, `collapse`, `dismiss`, `empty`), `onDismiss(id)`, `onAction(id)`, `onExpandedChange(expanded)`. Items have `id`, `title`, optional `description`, `tone`, `duration`, `dismissible`, `action: {label,onClick?}`. IDs are unique; pushing an existing ID is ignored. `items` lists oldest first. `setOptions({items})` replaces data while preserving the remaining lifetime of matching IDs.
+
+`direction: 'up'` rests the cards on the deck's floor and grows above the front card (anchor its container to the bottom, for example with `flex-direction: column-reverse`); `'side'` peeks at the right edge and opens into a strip that scrolls sideways. A click on a closed deck opens it, and hovering spreads its peeks to invite that click; the toggle remains the keyboard path. Opening fans the cards out one by one as their blur clears.
+
+Instance: `push(item)`, `dismiss(id)`, `clear()`, `expand()`, `collapse()`, `toggle()`, `setOptions(partial)`, readonly `items`/`expanded`, `destroy()`. Events: `mk:dismiss` `{id}` and `mk:change` `{expanded}`. Hover, focus, document visibility and disabled state pause timers. Covered cards are inert until expanded. Dismissal moves focus to a surviving control or the region. Reduced motion applies the same state immediately.
+
+React owns an empty host; pass `items`, never children or HTML. `instanceRef` exposes the engine for `push`. An element accepts JSON `items`/`labels` and the other scalar options as attributes; `push`, `items` and `setOptions` also work as properties/methods. Attribute updates retain the live engine.

package/src/components/notification-stack/element.ts

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createNotificationStack, type NotificationStackInstance, type NotificationStackOptions, type NotificationStackItem } from './engine';
+
+export class MkNotificationStackElement extends MkElement<NotificationStackInstance> {
+  static options: Record<string, OptionType> = {"items":"json","expanded":"boolean","direction":"string","duration":"number","disabled":"boolean","label":"string","labels":"json"};
+  protected create(options: Record<string, unknown>) { return createNotificationStack(this, options); }
+  setOptions(options: Partial<NotificationStackOptions>) { this.instance?.setOptions(options); }
+
+  push(item: NotificationStackItem) { this.instance?.push(item); }
+  dismiss(id: string) { this.instance?.dismiss(id); }
+  clear() { this.instance?.clear(); }
+  expand() { this.instance?.expand(); }
+  collapse() { this.instance?.collapse(); }
+  toggle() { this.instance?.toggle(); }
+  get expanded() { return this.instance?.expanded ?? false; }
+  set expanded(value: boolean) { this.instance?.setOptions({ expanded: value }); }
+  get items() { return [...(this.instance?.items ?? [])]; }
+  set items(value: NotificationStackItem[]) { this.instance?.setOptions({ items: value }); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    const defaults: Record<string, unknown> = {"items":[],"expanded":false,"direction":"down","duration":6000,"disabled":false,"label":"Notificaciones","labels":{}};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineNotificationStack = () => defineElement('mk-notification-stack', MkNotificationStackElement);