@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/components/island/react.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createIsland, type IslandInstance, type IslandOptions } from './engine';
+
+export interface IslandPanel {
+  name: string;
+  /** Accessible name of its button. */
+  label: string;
+  /** Button content; the menu's nine dots by default. */
+  icon?: ReactNode;
+  /** Light button (iyo's cart). */
+  light?: boolean;
+  content: ReactNode;
+}
+
+export interface IslandProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'>, Omit<IslandOptions, 'onChange'> {
+  brand?: ReactNode;
+  /** The call to action that fades out while a panel is open. */
+  cta?: { href: string; label: ReactNode };
+  panels: IslandPanel[];
+  /** Keep it (and its backdrop) inside a positioned parent instead of fixed over the page. */
+  contained?: boolean;
+  onChange?: (active: string | null) => void;
+  /** Receives the live instance (open, close, toggle, ready). */
+  instanceRef?: { current: IslandInstance | null };
+}
+
+/** The nine static dots of iyo's menu button. */
+export function IslandDots() {
+  return (
+    <span className="mk-island__dots" aria-hidden="true">
+      {Array.from({ length: 9 }, (_, i) => (
+        <i key={i} />
+      ))}
+    </span>
+  );
+}
+
+/** iyo.ai's floating navbar. */
+export function Island({
+  brand,
+  cta,
+  panels,
+  contained = false,
+  entrance,
+  closeOnScroll,
+  closeOnNavigate,
+  focusOnOpen,
+  onChange,
+  instanceRef,
+  className,
+  ...props
+}: IslandProps) {
+  const ref = useRef<HTMLElement>(null);
+  const change = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createIsland(ref.current, {
+      entrance,
+      closeOnScroll,
+      closeOnNavigate,
+      focusOnOpen,
+      onChange: (active) => change.current?.(active),
+    });
+    if (instanceRef) instanceRef.current = instance;
+    return () => {
+      instance.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // The panels' names define the markup the engine reads.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [panels.map((panel) => panel.name).join(), entrance, closeOnScroll, closeOnNavigate, focusOnOpen]);
+  const classes = ['mk-island', contained && 'mk-island--contained', className].filter(Boolean).join(' ');
+  return (
+    <nav ref={ref} aria-label="Principal" {...props} className={classes}>
+      <button type="button" className="mk-island__backdrop" data-mk-island-close tabIndex={-1} aria-label="Cerrar" />
+      <div className="mk-island__shell">
+        <div className="mk-island__glass" aria-hidden="true" />
+        <div className="mk-island__header">
+          {brand ? <span className="mk-island__brand">{brand}</span> : <span />}
+          <div className="mk-island__actions">
+            {cta ? (
+              <a className="mk-island__cta" href={cta.href}>
+                {cta.label}
+              </a>
+            ) : null}
+            {panels.map((panel, i) => (
+              <span key={panel.name} style={{ display: 'contents' }}>
+                {i > 0 ? <span className="mk-island__separator" aria-hidden="true" /> : null}
+                <button
+                  type="button"
+                  className={panel.light ? 'mk-island__button mk-island__button--light' : 'mk-island__button'}
+                  data-mk-island-toggle={panel.name}
+                  aria-label={panel.label}
+                >
+                  {panel.icon ?? <IslandDots />}
+                </button>
+              </span>
+            ))}
+          </div>
+        </div>
+        <div className="mk-island__content">
+          <div>
+            {panels.map((panel) => (
+              <section key={panel.name} className="mk-island__panel" data-mk-island-panel={panel.name} aria-label={panel.label}>
+                {panel.content}
+              </section>
+            ))}
+          </div>
+        </div>
+      </div>
+    </nav>
+  );
+}

package/src/components/menu/README.md

@@ -0,0 +1,67 @@
+# menu
+
+El menú "Opciones" de Stepbro: un panel translúcido que crece desde su botón (el mismo motor del diálogo, anclado y sin velo) y cuyas opciones entran escalonadas desde 90 % con blur 4 px, de la última a la primera, 0.35 s, 40 ms entre opciones, tras 0.1 s. Un clic fuera o Escape lo cierra; flechas, Inicio y Fin mueven el foco.
+
+Origen: Stepbro NavMenu (abre con ModalHost `absolute`, sin backdrop, superficie translúcida; `nav-menu-enter` en el kit). Su código usa el mismo plegado de 0.5 s que los diálogos; el screencast en vivo de Stepbro midió menos (abre 175 → 364 ms, cierra 66 → 182 ms) que `pnpm timings` aquí (≈ 585 / 510 ms); lo más probable es que su comparación de frames no registrara la cascada pequeña de las opciones ni la cola del plegado.
+
+## HTML / Astro
+
+```html
+<button class="mk-button mk-button--icon" data-mk-open="opciones" aria-label="Opciones">
+  <span class="mk-icon">more_vert</span>
+</button>
+
+<mk-menu id="opciones" label="Opciones">
+  <button data-mk-item data-mk-value="apariencia"><span class="mk-icon">palette</span>Apariencia</button>
+  <button data-mk-item data-mk-value="ajustes"><span class="mk-icon">settings</span>Ajustes</button>
+  <hr data-mk-separator />
+  <button data-mk-item data-mk-value="salir"><span class="mk-icon">logout</span>Cerrar sesión</button>
+</mk-menu>
+
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-menu']);
+  document.addEventListener('mk:select', (event) => console.log(event.detail.value));
+</script>
+```
+
+Sobre tu propio `<dialog class="mk-dialog mk-menu">`: `createMenu(dialog, opciones)`.
+
+## React
+
+```tsx
+<Menu.Root onSelect={(value) => run(value)}>
+  <Menu.Trigger className="mk-button mk-button--icon" aria-label="Opciones">⋮</Menu.Trigger>
+  <Menu.Content aria-label="Opciones">
+    <Menu.Item value="apariencia">Apariencia</Menu.Item>
+    <Menu.Separator />
+    <Menu.Item value="salir">Cerrar sesión</Menu.Item>
+  </Menu.Content>
+</Menu.Root>
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `closeOnSelect` | `keep-open` | `true` | Cerrar al elegir |
+| `onSelect` | evento `mk:select` | — | `(value, item)`; `value` = `data-mk-value` o el texto |
+| `variant` | `variant` | `'morph'` | `'liquid'` |
+| `labels`, `triggers`, `onOpen`, `onClose` | | | Como en `dialog` |
+
+## Partes
+
+`[data-mk-item]` (opción), `[data-mk-separator]` (línea), `[data-mk-label]` (título de grupo).
+
+## Variables CSS
+
+`--mk-menu-bg` (surface-3 al 78 %), `--mk-menu-radius` (28px), `--mk-menu-item-radius` (20px).
+
+## Accesibilidad
+
+`role="menu"` y `role="menuitem"`; foco en la primera opción al abrir y de vuelta al botón al cerrar. Con movimiento reducido aparece sin animar.
+
+## Presentación boleto (v0.8)
+
+`createMenu(dialog, { ticket: true })`, `createTicketMenu(dialog)`, `<mk-menu ticket>` o `<Menu.Root ticket>` aplican la presentación de Siena. El motor conserva foco, teclado, Escape y selección. Apertura recortada .9 s; contenido desde 150%, 1.1 s con stagger .02. El kit adapta los paneles globales con grid rows a un diálogo local. La receta `ticket-menu` tiene su propia página en el playground.
+

package/src/components/menu/element.ts

@@ -0,0 +1,55 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import type { Instance } from '../../core/types';
+import type { DialogVariant } from '../dialog/engine';
+import { createMenu, type MenuInstance } from './engine';
+
+/**
+ * <mk-menu id="opciones" [variant="liquid"] [keep-open]>
+ *   <button data-mk-item data-mk-value="ajustes">Ajustes</button> …
+ * </mk-menu>
+ * Any [data-mk-open="opciones"] opens it from that button; choosing an option
+ * emits `mk:select` (detail.value, detail.item).
+ */
+export class MkMenuElement extends MkElement<Instance> {
+  static options: Record<string, OptionType> = { variant: 'string', keepOpen: 'boolean', label: 'string', ticket: 'boolean' };
+
+  menu: MenuInstance | null = null;
+
+  protected create(options: Record<string, unknown>): Instance {
+    const original = [...this.childNodes];
+    const dialog = document.createElement('dialog');
+    dialog.className = 'mk-dialog mk-menu';
+    if (options.label) dialog.setAttribute('aria-label', options.label as string);
+    dialog.append(...original);
+    this.append(dialog);
+    const menu = createMenu(dialog, {
+      ticket: Boolean(options.ticket),
+      variant: (options.variant as DialogVariant) ?? 'morph',
+      closeOnSelect: !options.keepOpen,
+      triggers: this.id || false,
+    });
+    this.menu = menu;
+    return {
+      destroy: () => {
+        menu.destroy();
+        this.append(...original);
+        dialog.remove();
+        this.menu = null;
+      },
+    };
+  }
+
+  open(origin?: HTMLElement | null) {
+    this.menu?.open(origin);
+  }
+
+  close() {
+    this.menu?.close();
+  }
+
+  get isOpen() {
+    return this.menu?.isOpen ?? false;
+  }
+}
+
+export const defineMenu = () => defineElement('mk-menu', MkMenuElement);

package/src/components/menu/engine.ts

@@ -0,0 +1,142 @@
+import { createScope } from '../../core/scope';
+import { gsap } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce } from '../../core/types';
+import { flowInMenu } from '../../motion/entrances';
+import { createDialog, type DialogInstance, type DialogOptions } from '../dialog/engine';
+
+/*
+ * Stepbro's NavMenu "Opciones": the same ModalHost as a dialog, anchored to its
+ * button, without a tinted backdrop, on a translucent surface that grows out of
+ * the button; its options flow in from 90 % out of a 4 px blur, last first,
+ * 40 ms apart, after 0.1 s. Arrow keys, Home and End move between options.
+ */
+
+export interface MenuOptions extends Omit<DialogOptions, 'placement' | 'backdrop' | 'drag' | 'autoResize' | 'animateContent'> {
+  ticket?: boolean;
+  /** Close after an option is chosen (default). */
+  closeOnSelect?: boolean;
+  onSelect?: (value: string, item: HTMLElement) => void;
+}
+
+export interface MenuInstance extends DialogInstance {
+  readonly items: HTMLElement[];
+}
+
+const ITEM = '[data-mk-item]';
+
+export function createMenu(dialog: HTMLElement | null, options: MenuOptions = {}): MenuInstance {
+  if (!dialog) {
+    warnOnce('menu: missing <dialog> element');
+    return inert({
+      open() {},
+      close() {},
+      toggle() {},
+      float() {},
+      dock() {},
+      isOpen: false,
+      isFloating: false,
+      element: null as unknown as HTMLElement,
+      items: [],
+    });
+  }
+  const { closeOnSelect = true } = options;
+  const scope = createScope();
+  let ticketAnimation: gsap.core.Timeline | undefined;
+  if (options.ticket) {
+    scope.attr(dialog, 'data-mk-ticket', '');
+    scope.attr(dialog, 'style', dialog.getAttribute('style'));
+    for (const item of dialog.querySelectorAll<HTMLElement>(ITEM)) scope.attr(item, 'style', item.getAttribute('style'));
+    scope.add(() => ticketAnimation?.kill());
+  }
+  const items = () => [...dialog.querySelectorAll<HTMLElement>(ITEM)].filter((item) => !item.hasAttribute('disabled') && item.getAttribute('aria-disabled') !== 'true');
+
+  scope.attr(dialog, 'role', 'menu');
+  // Options can come and go (frameworks): roles are applied now and on every open.
+  const markItems = () => {
+    for (const item of dialog.querySelectorAll<HTMLElement>(ITEM)) {
+      scope.attr(item, 'role', 'menuitem');
+      scope.attr(item, 'tabindex', '-1');
+    }
+  };
+  markItems();
+
+  const surface = createDialog(dialog, {
+    ...options,
+    placement: 'anchor',
+    backdrop: false,
+    drag: false,
+    autoResize: false,
+    animateContent: false,
+    onOpen: () => {
+      markItems();
+      const list = items();
+      if (options.ticket && !reduced()) {
+        ticketAnimation?.kill();
+        ticketAnimation = gsap.timeline()
+          .fromTo(dialog, { clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0% 0)', duration: TIMING.ticketMenu.open, ease: 'expo.out' })
+          .fromTo(list, { yPercent: TIMING.ticketMenu.from }, { yPercent: 0, duration: TIMING.ticketMenu.content, stagger: TIMING.ticketMenu.stagger, ease: 'expo.out' }, 0);
+      } else flowInMenu(list);
+      list[0]?.focus({ preventScroll: true });
+      options.onOpen?.();
+    },
+  });
+
+  const select = (item: HTMLElement) => {
+    const value = item.dataset.mkValue ?? item.textContent?.trim() ?? '';
+    dialog.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { value, item } }));
+    options.onSelect?.(value, item);
+    if (closeOnSelect) surface.close();
+  };
+
+  scope.on(dialog, 'click', (event) => {
+    const item = (event.target as Element | null)?.closest<HTMLElement>(ITEM);
+    if (item && dialog.contains(item) && items().includes(item)) select(item);
+  });
+  scope.on(dialog, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const list = items();
+    if (!list.length) return;
+    const at = list.indexOf(document.activeElement as HTMLElement);
+    const moves: Record<string, number> = {
+      ArrowDown: at < 0 ? 0 : (at + 1) % list.length,
+      ArrowUp: at < 0 ? list.length - 1 : (at - 1 + list.length) % list.length,
+      Home: 0,
+      End: list.length - 1,
+    };
+    if (key in moves) {
+      event.preventDefault();
+      list[moves[key]]?.focus();
+      return;
+    }
+    // Buttons and links activate themselves; other items need Enter and Space.
+    const target = event.target as HTMLElement;
+    if ((key === 'Enter' || key === ' ') && list.includes(target) && !target.matches('button, a[href]')) {
+      event.preventDefault();
+      select(target);
+    }
+  });
+
+  return {
+    open: surface.open,
+    close: surface.close,
+    toggle: surface.toggle,
+    float: surface.float,
+    dock: surface.dock,
+    get isOpen() {
+      return surface.isOpen;
+    },
+    get isFloating() {
+      return surface.isFloating;
+    },
+    get items() {
+      return items();
+    },
+    element: dialog,
+    destroy() {
+      surface.destroy();
+      scope.dispose();
+    },
+  };
+}

package/src/components/menu/menu.css

@@ -0,0 +1,104 @@
+/* menu — Stepbro's translucent options panel that grows out of its button (an anchored .mk-dialog). */
+.mk-menu {
+  --mk-menu-bg: color-mix(in srgb, var(--mk-surface-3) 78%, transparent);
+  --mk-menu-radius: 28px;
+  --mk-menu-item-radius: 20px;
+  --mk-dialog-bg: var(--mk-menu-bg);
+  --mk-dialog-radius: var(--mk-menu-radius);
+  --mk-dialog-shadow: 0 16px 48px -12px rgb(0 0 0 / 0.35);
+  width: max-content;
+  min-width: 220px;
+  max-width: min(320px, calc(100vw - 32px));
+  padding: 8px;
+  backdrop-filter: blur(24px) saturate(1.6);
+  -webkit-backdrop-filter: blur(24px) saturate(1.6);
+}
+
+.mk-menu[open] {
+  gap: 2px;
+}
+
+.mk-menu [data-mk-item] {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  min-height: 48px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: var(--mk-menu-item-radius);
+  background: transparent;
+  color: var(--mk-text);
+  font-family: var(--md-sys-typescale-body-large-font);
+  font-size: var(--md-sys-typescale-label-large-size);
+  font-weight: var(--md-sys-typescale-label-large-weight);
+  letter-spacing: var(--md-sys-typescale-label-large-tracking);
+  text-align: left;
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+  outline: none;
+  transition: background-color 0.15s linear;
+}
+
+.mk-menu [data-mk-item]:hover,
+.mk-menu [data-mk-item]:focus-visible {
+  background: color-mix(in srgb, var(--mk-text) 8%, transparent);
+}
+
+.mk-menu [data-mk-item]:focus-visible {
+  box-shadow: inset 0 0 0 2px var(--mk-accent);
+}
+
+.mk-menu [data-mk-item][aria-disabled='true'],
+.mk-menu [data-mk-item]:disabled {
+  opacity: 0.38;
+  cursor: default;
+}
+
+.mk-menu [data-mk-item] .mk-icon,
+.mk-menu [data-mk-item] svg {
+  flex: none;
+  color: var(--mk-muted);
+  font-size: 20px;
+}
+
+.mk-menu [data-mk-separator] {
+  height: 1px;
+  margin: 6px 12px;
+  border: 0;
+  background: var(--mk-outline-soft);
+}
+
+.mk-menu [data-mk-label] {
+  padding: 8px 16px 4px;
+  color: var(--mk-muted);
+  font-size: var(--md-sys-typescale-label-medium-size);
+  font-weight: var(--md-sys-typescale-label-medium-weight);
+}
+
+mk-menu {
+  display: contents;
+}
+
+.mk-menu[data-mk-ticket] {
+  --mk-menu-radius: 2px;
+  --mk-menu-item-radius: 0px;
+  --mk-menu-bg: var(--mk-surface-1);
+  padding: 20px;
+  min-width: 280px;
+  border-block: 6px dotted var(--mk-outline-soft);
+  backdrop-filter: none;
+}
+.mk-menu[data-mk-ticket] [data-mk-item] { border-bottom: 1px dashed var(--mk-outline-soft); min-height: 64px; font-size: 20px; }
+
+mk-menu:not(:defined) {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mk-menu [data-mk-item] {
+    transition: none;
+  }
+}

package/src/components/menu/react.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { createContext, useContext, useRef, type ButtonHTMLAttributes, type DialogHTMLAttributes, type MutableRefObject, type ReactNode } from 'react';
+import { useLatest } from '../../react/use-recipe';
+import { useSurfaceEngine, useSurfaceRoot, type SurfaceContextValue, type SurfaceRootProps } from '../dialog/react';
+import { createMenu, type MenuInstance } from './engine';
+
+interface MenuContextValue extends SurfaceContextValue<MenuInstance> {
+  ticket: boolean;
+  onSelect: MutableRefObject<((value: string, item: HTMLElement) => void) | undefined>;
+  closeOnSelect: boolean;
+}
+
+const MenuContext = createContext<MenuContextValue | null>(null);
+
+function useMenuContext(part: string) {
+  const value = useContext(MenuContext);
+  if (!value) throw new Error(`<Menu.${part}> must be inside <Menu.Root>`);
+  return value;
+}
+
+export interface MenuRootProps extends Omit<SurfaceRootProps, 'placement' | 'backdrop' | 'drag' | 'autoResize'> {
+  ticket?: boolean;
+  onSelect?: (value: string, item: HTMLElement) => void;
+  closeOnSelect?: boolean;
+  children?: ReactNode;
+}
+
+function Root({ onSelect, closeOnSelect = true, ticket = false, children, ...props }: MenuRootProps) {
+  const surface = useSurfaceRoot<MenuInstance>(props);
+  const select = useLatest(onSelect);
+  return <MenuContext.Provider value={{ ...surface, onSelect: select, closeOnSelect, ticket }}>{children}</MenuContext.Provider>;
+}
+
+function Trigger({ onClick, children, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) {
+  const context = useMenuContext('Trigger');
+  return (
+    <button
+      type="button"
+      aria-haspopup="menu"
+      aria-expanded={context.open}
+      {...props}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        context.origin.current = event.currentTarget;
+        context.setOpen(!context.open);
+      }}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Content({ className, children, ...props }: Omit<DialogHTMLAttributes<HTMLDialogElement>, 'open'>) {
+  const context = useMenuContext('Content');
+  const closeOnSelect = useRef(context.closeOnSelect);
+  closeOnSelect.current = context.closeOnSelect;
+  const ref = useSurfaceEngine(context, (dialog, options) =>
+    createMenu(dialog, { ...options, ticket: context.ticket, closeOnSelect: closeOnSelect.current, onSelect: (value, item) => context.onSelect.current?.(value, item) }),
+  );
+  return (
+    <dialog ref={ref} className={['mk-dialog mk-menu', className].filter(Boolean).join(' ')} {...props}>
+      {children}
+    </dialog>
+  );
+}
+
+function Item({ value, children, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & { value?: string }) {
+  return (
+    <button type="button" data-mk-item="" data-mk-value={value} {...props}>
+      {children}
+    </button>
+  );
+}
+
+function Separator() {
+  return <hr data-mk-separator="" />;
+}
+
+/** Stepbro's options menu: <Menu.Root onSelect><Menu.Trigger/><Menu.Content><Menu.Item value/>…</Menu.Content></Menu.Root>. */
+export const Menu = { Root, Trigger, Content, Item, Separator };

package/src/components/nav/README.md

@@ -0,0 +1,85 @@
+# nav
+
+La navegación de Stepbro (Money y Tasks): siete estilos de escritorio y una sola barra de cristal en el móvil (< 680 px), dentro de una cáscara de app (`.mk-shell`).
+
+| Estilo | Stepbro | Cómo se ve |
+|---|---|---|
+| `clasica` | style-1 | Barra lateral con borde; la página actual en una píldora rellena |
+| `bonita` | style-2 (por defecto en Money) | Píldoras de texto centradas que se ensanchan al pasar y al estar activas (padding con resorte, 0.3 s `cubic(.38,.49,0,1.5)`) |
+| `dock` | style-3 | Barra flotante de cristal centrada abajo; el botón activo se ensancha a 80 px |
+| `guapa` | style-4 | La vista es una tarjeta sobre la cáscara tintada; la página actual es un chip blanco |
+| `tasks` | style-5 | Riel de botones redondos de 56 px; el activo se cuadra (radio 0.3 s `cubic(.38,.49,0,2)`) |
+| `melon` | style-6 | Barra lateral suave con un lavado primario en la página actual |
+| `tunnel` | style-7 | Palabras grandes; la que tiene el ratón y sus vecinas crecen como un dock (1.2 / 1.09 / 1.03) |
+
+`accent` (variant-1 de Stepbro) pinta la página actual en primary-container. Al cambiar de página el icono se rellena (`mk-nav-icon`, 125 ms, `FILL 0 → 1`, para fuentes de iconos como Material Symbols). Con `reveal`, al arrancar la cáscara se descubre desde el primer botón (`revealFrom`, como el `Nav` de Stepbro).
+
+Origen: Stepbro `navigation-styles.css`, `navigation.json`, componente `Nav` (Tasks).
+
+## HTML / Astro
+
+```html
+<div class="mk-shell" style="height: 100dvh">
+  <main class="mk-shell__view">
+    <header class="mk-shell__header"><h1 class="mk-shell__title">Inicio</h1></header>
+    …
+  </main>
+  <mk-nav class="mk-nav mk-nav--bonita" nav-style="bonita" storage-key="mi-app-nav">
+    <div class="mk-nav__buttons">
+      <a class="mk-nav__button" href="/" aria-current="page"><svg class="mk-nav__icon">…</svg><span class="mk-nav__name">Inicio</span></a>
+      <a class="mk-nav__button" href="/movimientos"><svg class="mk-nav__icon">…</svg><span class="mk-nav__name">Movimientos</span></a>
+    </div>
+    <div class="mk-nav__actions">
+      <button class="mk-nav__button mk-nav__button--action" type="button"><svg class="mk-nav__icon">…</svg><span class="mk-nav__name">Opciones</span></button>
+    </div>
+  </mk-nav>
+</div>
+
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-nav']);
+  document.querySelector('mk-nav').setStyle('dock');
+</script>
+```
+
+Escribe la clase `mk-nav--<estilo>` en el marcado para que se vea bien antes de que cargue el JS. Sin custom element: `createNav(document.querySelector('.mk-nav'), opciones)` sobre un `<nav>`.
+
+Partes: `.mk-nav__button--first` (botón de arriba: cuenta, espacio de trabajo), `.mk-nav__buttons`, `.mk-nav__actions` (`.mk-nav__button--action`), `.mk-nav__options` + `.mk-nav__label` (bloque extra que solo muestran clásica, guapa, melon y tunnel), `.mk-nav__icon`, `.mk-nav__name`, `data-mk-hide-mobile` (se esconde en el móvil). Vista: `.mk-shell__view`, `.mk-shell__header`, `.mk-shell__title`, `.mk-shell__content` (cada estilo ajusta su cabecera).
+
+## React
+
+```tsx
+const [page, setPage] = useState('home');
+
+<div className="mk-shell" style={{ height: '100dvh' }}>
+  <main className="mk-shell__view">…</main>
+  <Nav
+    navStyle="tasks"
+    items={[
+      { value: 'home', label: 'Inicio', icon: <HomeIcon /> },
+      { value: 'movements', label: 'Movimientos', icon: <RowsIcon /> },
+    ]}
+    active={page}
+    onSelect={(value) => setPage(value)}
+  />
+</div>
+```
+
+`first` y `actions` aceptan tus botones (`className="mk-nav__button mk-nav__button--first"` / `--action`). Con `href` el item es un enlace.
+
+## API
+
+`createNav(root, { style, accent, reveal, storageKey, labels: { nav }, onSelect })` → `{ select(índice | valor), setStyle(nombre), setAccent(on), index, style, items, destroy }`.
+
+- Al hacer clic se emite `mk:navigate` (cancelable; `detail`: `index`, `value`, `item`, `originalEvent`). Para una SPA, llama `event.detail.originalEvent.preventDefault()` y navega con tu router.
+- `select()` solo marca la página actual (sin evento): úsalo para seguir a tu router.
+- `storageKey` guarda el estilo elegido en `localStorage` (Stepbro: `money-nav`).
+- `NAV_STYLES` lista los siete nombres.
+
+## Variables CSS
+
+`--mk-nav-icon-size` (24px; 16px en guapa y melon con acento). Colores de los roles Material (`surface-container-*`, `primary-container`, `tertiary-container`…).
+
+## Accesibilidad
+
+Un `<nav>` con `aria-label` ("Principal" por defecto); la página actual lleva `aria-current="page"`. Cuando un estilo esconde el texto (dock, tasks, móvil) solo lo oculta a la vista: el botón conserva su nombre para lectores de pantalla. Foco visible en cada botón. Con movimiento reducido no hay transiciones ni revelado.