@yewdiel21/motion-kit 0.14.0 → 0.15.0

package/src/components/nav/react.tsx

@@ -2,7 +2,7 @@
 
 import { useRef, type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
 import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
-import { revealShell, type NavStyle } from './engine';
+import { revealShell, toNavStyle, type NavStyle, type NavStyleAlias } from './engine';
 
 export interface NavItem {
   value: string;
@@ -19,7 +19,7 @@ export interface NavProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'>
   /** Value of the current page. */
   active?: string;
   onSelect?: (value: string, event: MouseEvent<HTMLElement>) => void;
-  navStyle?: NavStyle;
+  navStyle?: NavStyle | NavStyleAlias;
   accent?: boolean;
   /** Reveal the surrounding .mk-shell from the first button on mount. */
   reveal?: boolean;
@@ -34,7 +34,7 @@ export function Nav({
   items,
   active,
   onSelect,
-  navStyle = 'bonita',
+  navStyle = 'pills',
   accent = false,
   reveal = false,
   first,
@@ -50,7 +50,7 @@ export function Nav({
     // Only on mount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
-  const classes = ['mk-nav', `mk-nav--${navStyle}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');
+  const classes = ['mk-nav', `mk-nav--${toNavStyle(navStyle) ?? 'pills'}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');
   return (
     <nav ref={ref} aria-label="Principal" {...props} className={classes}>
       {first}

package/src/components/orbit-menu/README.md

@@ -0,0 +1,46 @@
+# orbit-menu
+
+Menú central que despliega acciones en cruz o círculo con giro, desenfoque y resorte.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { OrbitMenu } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add orbit-menu --react --elements
+```
+
+## React
+
+```tsx
+<OrbitMenu label="Acciones" items={[{ value: "add", label: "Crear", icon: "+" }, { value: "download", label: "Descargar", icon: "↓" }]} onSelect={run} />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-orbit-menu radius="88"><button data-mk-orbit-toggle aria-label="Acciones"></button><button data-mk-orbit-item data-mk-value="add" aria-label="Crear">+</button><button data-mk-orbit-item data-mk-value="download" aria-label="Descargar">↓</button></mk-orbit-menu>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-orbit-menu']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createOrbitMenu } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+radius: 96 px. start: 0 grados desde arriba. closeOnSelect: true. onToggle(open), onSelect(value). Reserva espacio alrededor del botón. Instancia: open(), close(), toggle(), isOpen.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-orbit-size, --mk-orbit-face, --mk-orbit-ink, --mk-orbit-shadow.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/orbit-menu/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createOrbitMenu, type OrbitMenuInstance } from './engine';
+
+/**
+ * <mk-orbit-menu class="mk-orbit-menu">
+ *   <button data-mk-orbit-toggle aria-label="Acciones"></button>
+ *   <button data-mk-orbit-item data-mk-value="nuevo" aria-label="Nuevo">…svg…</button> …
+ * </mk-orbit-menu>
+ * Options swirl out around the middle button. Emits mk:toggle ({open}) and mk:select ({value}).
+ */
+export class MkOrbitMenuElement extends MkElement<OrbitMenuInstance> {
+  static options: Record<string, OptionType> = { radius: 'number', start: 'number', closeOnSelect: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createOrbitMenu(this, options);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+}
+
+export const defineOrbitMenu = () => defineElement('mk-orbit-menu', MkOrbitMenuElement);

package/src/components/orbit-menu/engine.ts

@@ -0,0 +1,179 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+/*
+ * Orbit menu: a square button in the middle whose options come out around it
+ * (four make a cross: up, right, down, left; more share the circle). Opening,
+ * the button's lines turn into an ×, it goes glassy, and each option swirls out
+ * of it along an arc, its distance on the swatch curve (.38,.49,0,1.5) so it
+ * overshoots and settles, out of a blur, 45 ms after the one before; closing,
+ * they keep turning and are drawn back in (.3 s). Arrows pick the option on
+ * that side, Tab walks them, Escape or a click outside closes and gives focus
+ * back. Closed options are inert. Choosing one presses it and closes.
+ */
+
+export interface OrbitMenuOptions {
+  /** Distance of the options from the middle, px (default 96). */
+  radius?: number;
+  /** Where the first option sits, degrees clockwise from the top (default 0). */
+  start?: number;
+  /** Close after an option is chosen (default true). */
+  closeOnSelect?: boolean;
+  onToggle?: (open: boolean) => void;
+  /** An option was chosen: its data-mk-value, else its position. */
+  onSelect?: (value: string) => void;
+}
+
+export interface OrbitMenuInstance extends Instance {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  readonly isOpen: boolean;
+}
+
+export function createOrbitMenu(root: HTMLElement | null, options: OrbitMenuOptions = {}): OrbitMenuInstance {
+  const toggle = root?.querySelector<HTMLButtonElement>('[data-mk-orbit-toggle]') ?? null;
+  const items = root ? [...root.querySelectorAll<HTMLElement>('[data-mk-orbit-item]')] : [];
+  if (!root || !toggle || !items.length) {
+    if (root) warnOnce('orbit-menu: needs a [data-mk-orbit-toggle] and at least one [data-mk-orbit-item]');
+    return inert({ open() {}, close() {}, toggle() {}, isOpen: false });
+  }
+  registerMotion();
+  const scope = createScope();
+  const radius = Number.isFinite(options.radius) ? Math.max(24, options.radius!) : 96;
+  const start = ((Number.isFinite(options.start) ? options.start! : 0) * Math.PI) / 180;
+  const angles = items.map((_, i) => start + (i * Math.PI * 2) / items.length);
+  const valueOf = (item: HTMLElement) => item.dataset.mkValue ?? String(items.indexOf(item));
+
+  // The lines that turn into an ×, when the button brings no icon of its own.
+  if (!toggle.children.length && !toggle.textContent?.trim()) {
+    const burger = document.createElement('span');
+    burger.dataset.mkOrbitBurger = '';
+    burger.setAttribute('aria-hidden', 'true');
+    burger.append(document.createElement('i'), document.createElement('i'), document.createElement('i'));
+    toggle.append(burger);
+    scope.add(() => burger.remove());
+  }
+  scope.attr(toggle, 'aria-expanded', 'false');
+  scope.attr(toggle, 'aria-haspopup', 'true');
+  if (!toggle.getAttribute('aria-label') && !toggle.textContent?.trim()) scope.attr(toggle, 'aria-label', 'Menú');
+  for (const item of items) {
+    scope.attr(item, 'inert', '');
+    if (item instanceof HTMLButtonElement) scope.attr(item, 'type', item.getAttribute('type') ?? 'button');
+  }
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-state', 'closed');
+
+  const states = items.map((_, i) => ({ a: angles[i]!, r: 0 }));
+  const apply = (i: number) => {
+    const { a, r } = states[i]!;
+    gsap.set(items[i]!, { x: r * Math.sin(a), y: -r * Math.cos(a) });
+  };
+  let timeline: gsap.core.Timeline | null = null;
+  scope.add(() => {
+    timeline?.kill();
+    gsap.set(items, { clearProps: 'transform,opacity,filter,visibility' });
+  });
+  gsap.set(items, { opacity: 0, scale: 0.3, visibility: 'hidden' });
+
+  let open = false;
+  const set = (next: boolean, focus: 'first' | 'toggle' | false = false) => {
+    if (next === open) return;
+    open = next;
+    toggle.setAttribute('aria-expanded', String(open));
+    root.dataset.mkState = open ? 'open' : 'closed';
+    for (const item of items) item.toggleAttribute('inert', !open);
+    timeline?.kill();
+    if (reduced()) {
+      items.forEach((item, i) => {
+        states[i] = { a: angles[i]!, r: open ? radius : 0 };
+        apply(i);
+        gsap.set(item, { opacity: open ? 1 : 0, scale: open ? 1 : 0.3, filter: 'none', visibility: open ? 'visible' : 'hidden' });
+      });
+    } else if (open) {
+      timeline = gsap.timeline();
+      items.forEach((item, i) => {
+        const state = states[i]!;
+        // From a little behind its place, swirling out to it.
+        if (state.r < 1) state.a = angles[i]! - 0.7;
+        const at = i * 0.045;
+        gsap.set(item, { visibility: 'visible' });
+        timeline!.to(state, { r: radius, duration: 0.55, ease: EASE.swatch, onUpdate: () => apply(i) }, at);
+        timeline!.to(state, { a: angles[i]!, duration: 0.5, ease: 'power3.out', onUpdate: () => apply(i) }, at);
+        timeline!.fromTo(item, { filter: 'blur(8px)' }, { opacity: 1, scale: 1, filter: 'blur(0px)', duration: 0.35, ease: 'power2.out', clearProps: 'filter' }, at);
+      });
+    } else {
+      timeline = gsap.timeline();
+      [...items].reverse().forEach((item, k) => {
+        const i = items.length - 1 - k;
+        const state = states[i]!;
+        const at = k * 0.03;
+        timeline!.to(state, { r: 0, a: state.a + 0.6, duration: 0.3, ease: 'power2.in', onUpdate: () => apply(i) }, at);
+        timeline!.to(item, { opacity: 0, scale: 0.3, filter: 'blur(6px)', duration: 0.28, ease: 'power2.in', onComplete: () => {
+          gsap.set(item, { visibility: 'hidden', clearProps: 'filter' });
+        } }, at);
+      });
+    }
+    if (focus === 'first') items[0]!.focus();
+    if (focus === 'toggle') toggle.focus();
+    options.onToggle?.(open);
+    root.dispatchEvent(new CustomEvent('mk:toggle', { bubbles: true, detail: { open } }));
+  };
+
+  scope.on(toggle, 'click', (event) => {
+    press(toggle);
+    // A keyboard click (detail 0) opens onto the first option.
+    set(!open, !open && (event as MouseEvent).detail === 0 ? 'first' : false);
+  });
+  scope.on(root, 'click', (event) => {
+    const item = (event.target as Element).closest<HTMLElement>('[data-mk-orbit-item]');
+    if (!item || !items.includes(item) || !open) return;
+    press(item);
+    const value = valueOf(item);
+    options.onSelect?.(value);
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { value } }));
+    if (options.closeOnSelect !== false) set(false, 'toggle');
+  });
+  // Arrows: the option on that side (the nearest angle).
+  const sides: Record<string, number> = { ArrowUp: 0, ArrowRight: Math.PI / 2, ArrowDown: Math.PI, ArrowLeft: (Math.PI * 3) / 2 };
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if (key === 'Escape' && open) {
+      event.preventDefault();
+      set(false, 'toggle');
+      return;
+    }
+    if (!(key in sides)) return;
+    if (!open) {
+      if (document.activeElement !== toggle) return;
+      event.preventDefault();
+      set(true);
+    } else event.preventDefault();
+    const want = sides[key]!;
+    const gap = (a: number) => {
+      const d = Math.abs((((a - want) % (Math.PI * 2)) + Math.PI * 3) % (Math.PI * 2) - Math.PI);
+      return d;
+    };
+    let best = 0;
+    angles.forEach((a, i) => {
+      if (gap(a) < gap(angles[best]!)) best = i;
+    });
+    items[best]!.focus();
+  });
+  scope.on(document, 'pointerdown', (event) => {
+    if (open && !root.contains(event.target as Node)) set(false);
+  });
+
+  return {
+    open: () => set(true),
+    close: () => set(false),
+    toggle: () => set(!open),
+    get isOpen() {
+      return open;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/orbit-menu/orbit-menu.css

@@ -0,0 +1,129 @@
+/* orbit-menu — soft white squares (16 px corners, a wide low shadow) around a middle button whose lines turn into an ×.
+   The options sit on the middle and the engine moves them out; give the menu room around it. */
+.mk-orbit-menu,
+mk-orbit-menu {
+  --mk-orbit-size: 4rem;
+  --mk-orbit-face: var(--mk-surface-3);
+  --mk-orbit-ink: var(--mk-text);
+  --mk-orbit-shadow: 0 18px 36px -14px rgb(0 0 0 / 0.22), 0 2px 6px -2px rgb(0 0 0 / 0.08);
+  position: relative;
+  display: inline-grid;
+  place-items: center;
+  width: var(--mk-orbit-size);
+  height: var(--mk-orbit-size);
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu) :is([data-mk-orbit-toggle], [data-mk-orbit-item]) {
+  display: grid;
+  place-items: center;
+  width: var(--mk-orbit-size);
+  height: var(--mk-orbit-size);
+  padding: 0;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: var(--mk-radius-md);
+  background: var(--mk-orbit-face);
+  box-shadow: var(--mk-orbit-shadow);
+  color: var(--mk-orbit-ink);
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu) [data-mk-orbit-toggle] {
+  position: relative;
+  z-index: 2;
+  transition:
+    background-color 0.3s ease,
+    box-shadow 0.3s ease;
+}
+
+/* Open: the middle goes glassy, the options are the faces now. */
+:is(.mk-orbit-menu, mk-orbit-menu)[data-mk-state='open'] [data-mk-orbit-toggle] {
+  background: color-mix(in srgb, var(--mk-orbit-face) 55%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-orbit-ink) 8%, transparent);
+  backdrop-filter: blur(8px);
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu) [data-mk-orbit-item] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 1;
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu) :is([data-mk-orbit-toggle], [data-mk-orbit-item]) svg {
+  width: 1.75rem;
+  height: 1.75rem;
+  transition: transform 0.35s var(--mk-ease-swatch);
+}
+
+@media (hover: hover) {
+  :is(.mk-orbit-menu, mk-orbit-menu) [data-mk-orbit-item]:hover svg {
+    transform: scale(1.12);
+  }
+  :is(.mk-orbit-menu, mk-orbit-menu) [data-mk-orbit-item]:hover {
+    box-shadow: 0 22px 40px -14px rgb(0 0 0 / 0.28), 0 2px 6px -2px rgb(0 0 0 / 0.1);
+  }
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu) :is([data-mk-orbit-toggle], [data-mk-orbit-item]):focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+/* The three lines and their × . */
+[data-mk-orbit-burger] {
+  position: relative;
+  width: 1.5rem;
+  height: 1rem;
+}
+
+[data-mk-orbit-burger] i {
+  position: absolute;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  border-radius: 2px;
+  background: currentColor;
+  transition:
+    transform 0.4s var(--mk-ease-swatch),
+    opacity 0.2s ease;
+}
+
+[data-mk-orbit-burger] i:nth-child(1) {
+  top: 0;
+}
+
+[data-mk-orbit-burger] i:nth-child(2) {
+  top: calc(50% - 1px);
+}
+
+[data-mk-orbit-burger] i:nth-child(3) {
+  bottom: 0;
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu)[data-mk-state='open'] [data-mk-orbit-burger] i:nth-child(1) {
+  transform: translateY(calc(0.5rem - 1px)) rotate(45deg);
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu)[data-mk-state='open'] [data-mk-orbit-burger] i:nth-child(2) {
+  opacity: 0;
+  transform: scaleX(0.2);
+}
+
+:is(.mk-orbit-menu, mk-orbit-menu)[data-mk-state='open'] [data-mk-orbit-burger] i:nth-child(3) {
+  transform: translateY(calc(-0.5rem + 1px)) rotate(-45deg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-orbit-burger] i,
+  :is(.mk-orbit-menu, mk-orbit-menu) [data-mk-orbit-toggle],
+  :is(.mk-orbit-menu, mk-orbit-menu) svg {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  :is(.mk-orbit-menu, mk-orbit-menu) :is([data-mk-orbit-toggle], [data-mk-orbit-item]) {
+    border: 1px solid ButtonText;
+  }
+}

package/src/components/orbit-menu/react.tsx

@@ -0,0 +1,44 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createOrbitMenu, type OrbitMenuInstance, type OrbitMenuOptions } from './engine';
+
+export interface OrbitMenuItem {
+  value: string;
+  label: string;
+  icon: ReactNode;
+}
+
+export interface OrbitMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'onToggle'>, OrbitMenuOptions {
+  items: OrbitMenuItem[];
+  /** The middle button's name (default 'Menú'). */
+  label?: string;
+  instanceRef?: MutableRefObject<OrbitMenuInstance | null>;
+}
+
+/** <OrbitMenu label="Acciones" items={[{ value: 'nuevo', label: 'Nuevo', icon: <Plus /> }, …]} onSelect={run} /> */
+export function OrbitMenu({ items, label = 'Menú', radius, start, closeOnSelect, onToggle, onSelect, instanceRef, className, ...props }: OrbitMenuProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const toggled = useLatest(onToggle);
+  const selected = useLatest(onSelect);
+  const keys = items.map((item) => item.value).join('\u0000');
+  useIsomorphicLayoutEffect(() => {
+    const created = createOrbitMenu(ref.current, { radius, start, closeOnSelect, onToggle: (open) => toggled.current?.(open), onSelect: (value) => selected.current?.(value) });
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [keys, radius, start, closeOnSelect]);
+  return (
+    <div {...props} ref={ref} className={['mk-orbit-menu', className].filter(Boolean).join(' ')}>
+      <button type="button" data-mk-orbit-toggle="" aria-label={label} />
+      {items.map((item) => (
+        <button key={item.value} type="button" data-mk-orbit-item="" data-mk-value={item.value} aria-label={item.label}>
+          {item.icon}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/pagination/README.md

@@ -1,6 +1,6 @@
 # pagination
 
-Paginación con ventana acotada de números, extremos, elipsis y respuesta de elevación/presión.
+Paginación con ventana acotada de números, extremos y elipsis. Una píldora de acento se desliza bajo la página actual (.4 s, curva swing); cuando la ventana se mueve, los números que siguen se deslizan a su sitio nuevo y los nuevos entran con un pop desde un blur; las flechas hacen el press y se inclinan hacia su lado; al pasar, los botones se elevan.
 
 ```html
 <mk-pagination class="mk-pagination" total-pages="30" page="4" role="navigation" aria-label="Artículos">

package/src/components/pagination/engine.ts

@@ -1,5 +1,8 @@
+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 PaginationOptions {
   totalPages?: number;
@@ -17,20 +20,45 @@ export interface PaginationInstance extends Instance {
 // Reserve room for the page-window arithmetic so incrementing always progresses.
 const positive = (n: number | undefined, fallback: number) => Number.isFinite(n) ? Math.max(1, Math.min(Number.MAX_SAFE_INTEGER - 32, Math.floor(n!))) : fallback;
 
-/** Renders a bounded window of pages, even when totalPages is very large. */
+/**
+ * Renders a bounded window of pages, even when totalPages is very large. A pill
+ * ([data-mk-pagination-indicator]) glides under the current page on Melonmind's
+ * swing; when the window moves, the numbers that stay slide to their new place
+ * and the new ones pop in out of a blur; the arrows press and nudge their way.
+ */
 export function createPagination(root: HTMLElement | null, options: PaginationOptions = {}): PaginationInstance {
   const pages = root?.querySelector<HTMLElement>('[data-mk-pagination-pages]');
   if (!root || !pages) return inert({ setPage() {}, setTotalPages() {}, page: 1, totalPages: 1 });
+  registerMotion();
   const scope = createScope();
   const original = [...pages.childNodes];
+  const indicator = document.createElement('span');
+  indicator.dataset.mkPaginationIndicator = '';
+  indicator.setAttribute('aria-hidden', 'true');
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+  let placed = false;
   const previous = root.querySelector<HTMLButtonElement>('[data-mk-pagination-previous]');
   const next = root.querySelector<HTMLButtonElement>('[data-mk-pagination-next]');
   let total = positive(options.totalPages, 10);
   let page = Math.min(total, positive(options.page, 1));
   const siblings = Math.min(10, Math.max(0, Number.isFinite(options.siblings) ? Math.floor(options.siblings!) : 1));
   scope.attr(root, 'data-mk-ready', '');
-  const render = () => {
+  // The pill draws the current page (the buttons themselves stay clear).
+  scope.attr(root, 'data-mk-glide', '');
+  const render = (animate = false) => {
     const hadFocus = pages.contains(document.activeElement);
+    // Where each number was, to slide the ones that stay.
+    const before = new Map([...pages.querySelectorAll<HTMLElement>('[data-mk-page]')].map((button) => [button.dataset.mkPage!, button.offsetLeft]));
     const selected = new Set([1, total]);
     for (let n = Math.max(1, page - siblings); n <= Math.min(total, page + siblings); n++) selected.add(n);
     const fragment = document.createDocumentFragment();
@@ -52,8 +80,23 @@ export function createPagination(root: HTMLElement | null, options: PaginationOp
       fragment.append(button);
       last = n;
     }
-    pages.replaceChildren(fragment);
+    pages.replaceChildren(indicator, fragment);
     if (hadFocus) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+    const motion = animate && !reduced();
+    if (motion) {
+      for (const button of pages.querySelectorAll<HTMLElement>('[data-mk-page]')) {
+        const from = before.get(button.dataset.mkPage!);
+        if (from === undefined) keep(gsap.fromTo(button, { opacity: 0, scale: 0.6, filter: 'blur(4px)' }, { opacity: 1, scale: 1, filter: 'blur(0px)', duration: 0.3, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+        else if (from !== button.offsetLeft) keep(gsap.fromTo(button, { x: from - button.offsetLeft }, { x: 0, duration: 0.35, ease: EASE.swatch, clearProps: 'transform' }));
+      }
+    }
+    const current = pages.querySelector<HTMLElement>('[aria-current]');
+    if (current) {
+      const box = { x: current.offsetLeft, width: current.offsetWidth, height: current.offsetHeight };
+      if (motion && placed) keep(gsap.to(indicator, { ...box, duration: 0.4, ease: EASE.swatch }));
+      else gsap.set(indicator, box);
+      placed = true;
+    }
     if (previous) scope.attr(previous, 'disabled', page === 1 ? '' : null);
     if (next) scope.attr(next, 'disabled', page === total ? '' : null);
   };
@@ -63,7 +106,7 @@ export function createPagination(root: HTMLElement | null, options: PaginationOp
     if (candidate === page) return;
     const focused = pages.contains(document.activeElement);
     page = candidate;
-    render();
+    render(true);
     if (focused) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
     if (notify) {
       options.onChange?.(page);
@@ -73,6 +116,9 @@ export function createPagination(root: HTMLElement | null, options: PaginationOp
   scope.on(root, 'click', (event) => {
     const target = (event.target as Element).closest<HTMLButtonElement>('button');
     if (!target || target.disabled) return;
+    if (!reduced()) keep(press(target));
+    // The arrow leans the way it goes, then settles.
+    if ((target === previous || target === next) && !reduced()) keep(gsap.fromTo(target, { x: target === next ? 4 : -4 }, { x: 0, duration: 0.45, ease: EASE.click, clearProps: 'x' }));
     if (target === previous) setPage(page - 1);
     else if (target === next) setPage(page + 1);
     else if (target.dataset.mkPage) setPage(Number(target.dataset.mkPage));

package/src/components/pagination/pagination.css

@@ -1,10 +1,15 @@
+/* pagination — round page buttons on surface-2; a pill (accent) glides under the current page; numbers that stay slide
+   when the window moves and new ones pop in; hover lifts, press squeezes. */
 .mk-pagination, mk-pagination { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: .35rem; }
-.mk-pagination [data-mk-pagination-pages], mk-pagination [data-mk-pagination-pages] { display: flex; align-items: center; gap: .25rem; }
-.mk-pagination button, mk-pagination button { min-width: 2.5rem; height: 2.5rem; border: 0; border-radius: var(--mk-radius-full); background: var(--mk-surface-2); color: var(--mk-text); font: inherit; cursor: pointer; transition: transform .3s, background .3s, color .3s; }
+.mk-pagination [data-mk-pagination-pages], mk-pagination [data-mk-pagination-pages] { position: relative; display: flex; align-items: center; gap: .25rem; isolation: isolate; }
+.mk-pagination button, mk-pagination button { position: relative; min-width: 2.5rem; height: 2.5rem; border: 0; border-radius: var(--mk-radius-full); background: var(--mk-surface-2); color: var(--mk-text); font: inherit; font-variant-numeric: tabular-nums; cursor: pointer; transition: translate .3s cubic-bezier(.38,.49,0,1.5), background-color .25s, color .25s; }
 .mk-pagination button[aria-current], mk-pagination button[aria-current] { background: var(--mk-accent); color: var(--mk-on-accent); }
-.mk-pagination button:hover:not(:disabled), mk-pagination button:hover:not(:disabled) { transform: translateY(-3px); }
-.mk-pagination button:active:not(:disabled), mk-pagination button:active:not(:disabled) { transform: scale(.9); }
+/* With the engine, the pill paints the current page and its button stays clear. */
+:is(.mk-pagination, mk-pagination)[data-mk-glide] button[aria-current] { background: transparent; }
+:is(.mk-pagination, mk-pagination) [data-mk-pagination-indicator] { position: absolute; top: 0; left: 0; z-index: -1; border-radius: var(--mk-radius-full); background: var(--mk-accent); pointer-events: none; }
+.mk-pagination button:hover:not(:disabled), mk-pagination button:hover:not(:disabled) { translate: 0 -3px; }
+.mk-pagination button:hover:not(:disabled):not([aria-current]), mk-pagination button:hover:not(:disabled):not([aria-current]) { background: var(--mk-surface-3); }
 .mk-pagination button:focus-visible, mk-pagination button:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
 .mk-pagination button:disabled, mk-pagination button:disabled { opacity: .35; cursor: default; }
 .mk-pagination__gap { padding: 0 .15rem; color: var(--mk-muted); }
-@media (prefers-reduced-motion: reduce) { .mk-pagination button, mk-pagination button { transition: none; transform: none !important; } }
+@media (prefers-reduced-motion: reduce) { .mk-pagination button, mk-pagination button { transition: none; translate: none !important; } }

package/src/components/pie-chart/README.md

@@ -0,0 +1,48 @@
+# pie-chart
+
+Gráfica circular o donut con entrada de barrido, selección expansiva y total animado.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { PieChart } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add pie-chart --react --elements
+```
+
+## React
+
+```tsx
+<PieChart label="Ventas" data={[{ label: "Tienda", value: 60 }, { label: "Web", value: 40 }]} />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-pie-chart label="Ventas" data='[{"label":"Tienda","value":60},{"label":"Web","value":40}]'></mk-pie-chart>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-pie-chart']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createPieChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+data: {label, value, color?}[]. donut: 0.62 (0 para pie). gap: 1.5 grados. size: 240 px. totalLabel: Total. legend: true. Se omiten valores no finitos o no positivos.
+
+Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-chart-1…8, --mk-chart-surface.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.