@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/editable-table/react.tsx

@@ -0,0 +1,79 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes, type ReactElement, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import type { DataRow } from '../data-table/engine';
+import { createEditableTable, type EditableTableInstance, type EditableTableOptions } from './engine';
+
+export interface EditableTableProps<T extends DataRow> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'>, Omit<EditableTableOptions<T>, 'rows'> {
+  rows: T[];
+}
+
+export type EditableTableHandle<T extends DataRow = DataRow> = Pick<EditableTableInstance<T>, 'edit' | 'setValue' | 'addRow' | 'removeRows' | 'save' | 'discard'>;
+
+/**
+ * <EditableTable columns={columns} rows={rows} onSave={async (changes, rows) => { await api.save(changes); setRows(rows); }} />.
+ * New `rows` from the app replace the table's (pending edits go with them): hand them back after a save.
+ */
+function EditableTableInner<T extends DataRow>(
+  { columns, rows, rowKey, caption, pageSize, pageSizes, selectable, search, filters, columnsMenu, actions, bulkActions, sort, emptyTitle, emptyDescription, locale, onSave, onChange, newRow, onAction, onBulkAction, onSelectionChange, className, ...props }: EditableTableProps<T>,
+  handle: Ref<EditableTableHandle<T>>,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<EditableTableInstance<T> | null>(null);
+  const shown = useRef(rows);
+  const callbacks = useLatest({ onSave, onChange, newRow, onAction, onBulkAction, onSelectionChange });
+  useImperativeHandle(
+    handle,
+    () => ({
+      edit: (id, key) => instance.current?.edit(id, key),
+      setValue: (id, key, value) => instance.current?.setValue(id, key, value) ?? false,
+      addRow: (values) => instance.current?.addRow(values) ?? '',
+      removeRows: (ids) => instance.current?.removeRows(ids),
+      save: () => instance.current?.save() ?? Promise.resolve(false),
+      discard: () => instance.current?.discard(),
+    }),
+    [],
+  );
+  const columnsKey = JSON.stringify((columns ?? []).map(({ key, label, type, editable, editor, required, min, max, hidden, options: choices }) => [key, label, type, editable, editor, required, min, max, hidden, choices]));
+  const setupKey = JSON.stringify([columnsKey, rowKey, caption, pageSize, pageSizes, selectable, search, filters, columnsMenu, actions, bulkActions, emptyTitle, emptyDescription, locale, Boolean(newRow)]);
+  useIsomorphicLayoutEffect(() => {
+    const created = createEditableTable<T>(ref.current, {
+      columns,
+      rows: shown.current,
+      rowKey,
+      caption,
+      pageSize,
+      pageSizes,
+      selectable,
+      search,
+      filters,
+      columnsMenu,
+      actions,
+      bulkActions,
+      sort,
+      emptyTitle,
+      emptyDescription,
+      locale,
+      onSave: (changes, next) => callbacks.current.onSave?.(changes, next),
+      onChange: (changes) => callbacks.current.onChange?.(changes),
+      newRow: newRow ? () => callbacks.current.newRow?.() ?? {} : undefined,
+      onAction: (action, row) => callbacks.current.onAction?.(action, row),
+      onBulkAction: (action, chosen) => callbacks.current.onBulkAction?.(action, chosen),
+      onSelectionChange: (ids, chosen) => callbacks.current.onSelectionChange?.(ids, chosen),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [setupKey]);
+  useIsomorphicLayoutEffect(() => {
+    if (shown.current === rows) return;
+    shown.current = rows;
+    instance.current?.setRows(rows);
+  }, [rows]);
+  return <div {...props} ref={ref} className={['mk-data-table', 'mk-editable-table', className].filter(Boolean).join(' ')} />;
+}
+
+export const EditableTable = forwardRef(EditableTableInner) as <T extends DataRow>(props: EditableTableProps<T> & { ref?: Ref<EditableTableHandle<T>> }) => ReactElement;

package/src/components/empty-state/README.md

@@ -0,0 +1,41 @@
+# empty-state
+
+Estado vacío: ilustración, título, una línea de ayuda y acciones, para un sitio que aún no tiene nada (sin resultados, bandeja vacía, error, tarea terminada). Las ilustraciones son SVG en línea con los colores del tema.
+
+Cuando entra en pantalla, la ilustración aparece con un pop (escala .85, blur 12 → 0, .6 s) y el texto y las acciones entran después (12 px y blur 8, 60 ms entre piezas). Luego queda un movimiento suave en reposo: el sobre flota, la lupa da vueltas, la hoja asoma de la carpeta, el aviso respira y los destellos parpadean. Se pausa cuando sale de pantalla. `update()` cambia el contenido con un fundido con blur.
+
+## HTML / Astro
+
+```html
+<mk-empty-state class="mk-empty-state" illustration="search" title="Sin resultados"
+  description="Prueba con otras palabras o quita algún filtro."
+  actions='[{"id":"clear","label":"Quitar filtros"},{"id":"new","label":"Crear tarea"}]'></mk-empty-state>
+```
+
+Sin `title` ni `description`, conserva el contenido que escribas dentro y solo añade la ilustración delante.
+
+## React
+
+```tsx
+<EmptyState illustration="inbox" title="Bandeja vacía" description="Aquí verás los mensajes nuevos."
+  actions={[{ id: 'compose', label: 'Escribir mensaje' }]} onAction={(id) => id === 'compose' && openComposer()} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `illustration` | `illustration` | `'inbox'` | `inbox`, `search`, `folder`, `error`, `success` o `none`. |
+| `title` | `title` | — | Título (h3). |
+| `description` | `description` | — | Texto de ayuda. |
+| `actions` | `actions` (JSON) | — | `{ id, label, variant?, href? }[]`; la primera es primaria y las demás tonales. |
+| `loop` | `loop` | `true` | Movimiento suave en reposo. |
+| `onAction(id, event)` | — | — | Al pulsar una acción. |
+
+## API y eventos
+
+`update({ illustration, title, description, actions })`, `destroy()`. Evento `mk:action` con `{ id }`.
+
+## Estilo
+
+Columna centrada de 28rem como máximo. Variables para recolorear la ilustración: `--mk-empty-ink`, `--mk-empty-fill`, `--mk-empty-card`, `--mk-empty-accent`, `--mk-empty-soft`, `--mk-empty-alert`. Con movimiento reducido no hay entrada ni movimiento en reposo.

package/src/components/empty-state/element.ts

@@ -0,0 +1,23 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createEmptyState, type EmptyStateInstance } from './engine';
+
+/**
+ * <mk-empty-state class="mk-empty-state" illustration="search" title="Sin resultados"
+ *   description="Prueba con otras palabras." actions='[{"id":"clear","label":"Borrar filtros"}]'></mk-empty-state>
+ * Emits mk:action ({id}).
+ */
+export class MkEmptyStateElement extends MkElement<EmptyStateInstance> {
+  static options: Record<string, OptionType> = { illustration: 'string', title: 'string', description: 'string', actions: 'json', loop: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createEmptyState(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'loop') return super.attributeChangedCallback(name, previous, next);
+    this.instance.update(this.options);
+  }
+}
+
+export const defineEmptyState = () => defineElement('mk-empty-state', MkEmptyStateElement);

package/src/components/empty-state/empty-state.css

@@ -0,0 +1,60 @@
+/* empty-state — centred column: a 160 × 120 illustration on the theme's colours, a 1.125rem title, a muted line of
+   help (36ch) and the actions (kit buttons). The illustration's colours are variables, so a theme or a card can
+   recolour it. */
+.mk-empty-state,
+mk-empty-state {
+  --mk-empty-ink: var(--mk-muted);
+  --mk-empty-fill: var(--mk-surface-3);
+  --mk-empty-card: var(--mk-surface-1);
+  --mk-empty-accent: var(--mk-accent);
+  --mk-empty-soft: var(--mk-accent-soft);
+  --mk-empty-shadow: color-mix(in srgb, var(--mk-text) 9%, transparent);
+  --mk-empty-fill-ink: color-mix(in srgb, var(--mk-muted) 35%, transparent);
+  --mk-empty-alert: var(--mk-error);
+  --mk-empty-alert-soft: var(--mk-error-soft);
+  display: grid;
+  justify-items: center;
+  gap: 0.75rem;
+  box-sizing: border-box;
+  max-width: 28rem;
+  margin-inline: auto;
+  padding: 2rem 1.25rem;
+  text-align: center;
+}
+
+[data-mk-empty-illustration] svg {
+  display: block;
+  width: min(160px, 50vw);
+  height: auto;
+  overflow: visible;
+}
+
+[data-mk-empty-title] {
+  margin: 0.25rem 0 0;
+  color: var(--mk-text);
+  font-size: 1.125rem;
+  font-weight: 600;
+  line-height: 1.3;
+  text-wrap: balance;
+}
+
+[data-mk-empty-description] {
+  max-width: 36ch;
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.9375rem;
+  line-height: 1.5;
+  text-wrap: pretty;
+}
+
+[data-mk-empty-actions] {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+}
+
+:is(.mk-empty-state, mk-empty-state) [hidden] {
+  display: none;
+}

package/src/components/empty-state/engine.ts

@@ -0,0 +1,232 @@
+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';
+
+/*
+ * Empty state: an illustration, a title, a line of help and actions for a
+ * place with nothing in it yet (no results, an empty inbox, an error). The
+ * illustrations are inline SVG on the theme's colours. When it scrolls into
+ * view the illustration pops in (scale .85, blur 12 → 0, .6 s, pop curve) and
+ * the text and actions flow in after it (12 px, blur 8, 60 ms apart); then a
+ * gentle idle motion runs (the envelope floats, the magnifier circles, the page
+ * peeks out of the folder, the warning breathes, the sparkles twinkle), paused
+ * while it is off screen. update() swaps the content with a blur cross-fade.
+ * Authored content is kept; the illustration is added before it.
+ */
+
+export type EmptyIllustration = 'inbox' | 'search' | 'folder' | 'error' | 'success' | 'none';
+
+export interface EmptyAction {
+  id: string;
+  label: string;
+  /** primary (default for the first) or secondary. */
+  variant?: 'primary' | 'secondary';
+  /** A link instead of a button. */
+  href?: string;
+}
+
+export interface EmptyStateOptions {
+  illustration?: EmptyIllustration;
+  title?: string;
+  description?: string;
+  actions?: EmptyAction[];
+  /** The illustration's idle motion (default true). */
+  loop?: boolean;
+  onAction?: (id: string, event: MouseEvent) => void;
+}
+
+export interface EmptyStateInstance extends Instance {
+  update(next: Pick<EmptyStateOptions, 'illustration' | 'title' | 'description' | 'actions'>): void;
+}
+
+const INK = 'stroke="var(--mk-empty-ink)" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"';
+
+const ART: Record<Exclude<EmptyIllustration, 'none'>, string> = {
+  inbox: `<ellipse data-mk-part="shadow" cx="80" cy="108" rx="40" ry="5" fill="var(--mk-empty-shadow)"/>
+<path d="M36 66h22l6 10h32l6-10h22v24a8 8 0 0 1-8 8H44a8 8 0 0 1-8-8z" fill="var(--mk-empty-fill)" ${INK}/>
+<g data-mk-part="float"><rect x="55" y="22" width="50" height="36" rx="7" fill="var(--mk-empty-card)" ${INK}/><path d="M58 27l22 16 22-16" fill="none" stroke="var(--mk-empty-accent)" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/></g>
+<g data-mk-part="twinkle" fill="var(--mk-empty-accent)"><path d="M122 20l2 5 5 2-5 2-2 5-2-5-5-2 5-2z"/><circle cx="38" cy="40" r="3"/><circle cx="128" cy="52" r="2"/></g>`,
+  search: `<ellipse data-mk-part="shadow" cx="80" cy="108" rx="40" ry="5" fill="var(--mk-empty-shadow)"/>
+<rect x="44" y="18" width="62" height="80" rx="9" fill="var(--mk-empty-card)" ${INK}/>
+<path d="M56 36h38M56 48h30M56 60h34M56 72h22" fill="none" stroke="var(--mk-empty-fill-ink)" stroke-width="4" stroke-linecap="round"/>
+<g data-mk-part="orbit"><circle cx="100" cy="66" r="15" fill="var(--mk-empty-soft)" ${INK}/><path d="M111 77l13 13" fill="none" ${INK} stroke-width="5"/></g>
+<g data-mk-part="twinkle" fill="var(--mk-empty-accent)"><path d="M30 30l2 5 5 2-5 2-2 5-2-5-5-2 5-2z"/><circle cx="130" cy="34" r="2.5"/></g>`,
+  folder: `<ellipse data-mk-part="shadow" cx="80" cy="108" rx="44" ry="5" fill="var(--mk-empty-shadow)"/>
+<path d="M34 40a8 8 0 0 1 8-8h22l8 8h46a8 8 0 0 1 8 8v42a8 8 0 0 1-8 8H42a8 8 0 0 1-8-8z" fill="var(--mk-empty-fill)" ${INK}/>
+<g data-mk-part="peek"><rect x="52" y="30" width="56" height="44" rx="5" fill="var(--mk-empty-card)" ${INK}/><path d="M62 44h30M62 54h20" fill="none" stroke="var(--mk-empty-accent)" stroke-width="3" stroke-linecap="round"/></g>
+<path d="M34 58h92v32a8 8 0 0 1-8 8H42a8 8 0 0 1-8-8z" fill="var(--mk-empty-soft)" ${INK}/>
+<g data-mk-part="twinkle" fill="var(--mk-empty-accent)"><path d="M130 24l2 5 5 2-5 2-2 5-2-5-5-2 5-2z"/><circle cx="28" cy="30" r="2.5"/></g>`,
+  error: `<ellipse data-mk-part="shadow" cx="80" cy="108" rx="40" ry="5" fill="var(--mk-empty-shadow)"/>
+<path d="M50 30h40l18 18v42a8 8 0 0 1-8 8H50a8 8 0 0 1-8-8V38a8 8 0 0 1 8-8z" fill="var(--mk-empty-card)" ${INK}/>
+<path d="M90 30v12a6 6 0 0 0 6 6h12" fill="none" ${INK}/>
+<g data-mk-part="pulse"><circle cx="76" cy="70" r="16" fill="var(--mk-empty-alert-soft)" stroke="var(--mk-empty-alert)" stroke-width="2.5"/><path d="M76 62v9M76 78v.5" fill="none" stroke="var(--mk-empty-alert)" stroke-width="3.5" stroke-linecap="round"/></g>`,
+  success: `<ellipse data-mk-part="shadow" cx="80" cy="108" rx="36" ry="5" fill="var(--mk-empty-shadow)"/>
+<circle cx="80" cy="60" r="34" fill="var(--mk-empty-soft)" ${INK}/>
+<path data-mk-part="draw" d="M64 61l11 11 22-24" fill="none" stroke="var(--mk-empty-accent)" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+<g data-mk-part="twinkle" fill="var(--mk-empty-accent)"><path d="M126 26l2 5 5 2-5 2-2 5-2-5-5-2 5-2z"/><circle cx="34" cy="34" r="3"/><circle cx="130" cy="84" r="2.5"/><path d="M30 80l1.5 3.5 3.5 1.5-3.5 1.5-1.5 3.5-1.5-3.5-3.5-1.5 3.5-1.5z"/></g>`,
+};
+
+/** The idle motion of each moving part; repeat forever, back and forth. */
+function idle(svg: SVGSVGElement) {
+  const timeline = gsap.timeline({ repeat: -1, yoyo: true, defaults: { ease: 'sine.inOut' } });
+  const part = (name: string) => svg.querySelector<SVGGElement>(`[data-mk-part="${name}"]`);
+  const float = part('float');
+  if (float) timeline.to(float, { y: -6, duration: 1.8 }, 0).to(part('shadow'), { scaleX: 0.86, transformOrigin: '50% 50%', duration: 1.8 }, 0);
+  const orbit = part('orbit');
+  if (orbit) timeline.to(orbit, { keyframes: { x: [0, -8, -4, 0], y: [0, -4, -10, 0] }, duration: 3.2, ease: 'sine.inOut' }, 0);
+  const peek = part('peek');
+  if (peek) timeline.to(peek, { y: -7, duration: 1.6 }, 0);
+  const pulse = part('pulse');
+  if (pulse) timeline.to(pulse, { scale: 1.07, transformOrigin: '50% 50%', duration: 1.1 }, 0);
+  const twinkle = part('twinkle');
+  if (twinkle) timeline.to(twinkle.children, { opacity: 0.25, scale: 0.7, transformOrigin: '50% 50%', duration: 0.9, stagger: 0.3 }, 0);
+  return timeline;
+}
+
+export function createEmptyState(root: HTMLElement | null, options: EmptyStateOptions = {}): EmptyStateInstance {
+  if (!root) return inert({ update() {} });
+  registerMotion();
+  const scope = createScope();
+  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);
+  };
+  let loop: gsap.core.Timeline | null = null;
+  scope.add(() => {
+    loop?.kill();
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+  scope.attr(root, 'role', root.getAttribute('role') ?? 'status');
+  scope.attr(root, 'data-mk-ready', '');
+
+  const authored = root.childNodes.length > 0 && !options.title && !options.description;
+  // The entrance writes inline styles: authored children get theirs back on destroy.
+  for (const child of root.children) scope.attr(child, 'style', child.getAttribute('style'));
+  const made: Element[] = [];
+  scope.add(() => made.forEach((node) => node.remove()));
+
+  const art = document.createElement('div');
+  art.dataset.mkEmptyIllustration = '';
+  art.setAttribute('aria-hidden', 'true');
+  root.prepend(art);
+  made.push(art);
+  const drawArt = (name: EmptyIllustration | undefined) => {
+    loop?.kill();
+    loop = null;
+    const kind = name ?? 'inbox';
+    art.hidden = kind === 'none';
+    if (kind === 'none') return art.replaceChildren();
+    art.innerHTML = `<svg viewBox="0 0 160 120" width="160" height="120">${ART[kind]}</svg>`;
+  };
+
+  // Built content (or the authored one, kept as it is).
+  const title = document.createElement('h3');
+  title.dataset.mkEmptyTitle = '';
+  const description = document.createElement('p');
+  description.dataset.mkEmptyDescription = '';
+  const actions = document.createElement('div');
+  actions.dataset.mkEmptyActions = '';
+  const fill = (next: Pick<EmptyStateOptions, 'title' | 'description' | 'actions'>) => {
+    title.textContent = next.title ?? '';
+    title.hidden = !next.title;
+    description.textContent = next.description ?? '';
+    description.hidden = !next.description;
+    actions.replaceChildren(
+      ...(next.actions ?? []).map((action, i) => {
+        const element = document.createElement(action.href ? 'a' : 'button');
+        if (element instanceof HTMLAnchorElement) element.href = action.href!;
+        else element.type = 'button';
+        const variant = action.variant ?? (i === 0 ? 'primary' : 'secondary');
+        element.className = `mk-button ${variant === 'primary' ? 'mk-button--primary' : 'mk-button--tonal'}`;
+        element.dataset.mkAction = action.id;
+        element.textContent = action.label;
+        return element;
+      }),
+    );
+    actions.hidden = !next.actions?.length;
+  };
+  if (!authored) {
+    root.append(title, description, actions);
+    made.push(title, description, actions);
+    fill(options);
+  }
+  drawArt(options.illustration);
+
+  const parts = () => [...root.children].filter((child) => child !== art && !(child as HTMLElement).hidden) as HTMLElement[];
+
+  const startLoop = () => {
+    const svg = art.querySelector('svg');
+    if (!svg || options.loop === false || reduced() || loop) return;
+    loop = idle(svg);
+  };
+
+  /** The entrance: illustration first, then the text and the actions. */
+  const enter = () => {
+    const svg = art.querySelector('svg');
+    if (reduced()) return;
+    if (svg) {
+      keep(gsap.fromTo(art, { opacity: 0, scale: 0.85, filter: 'blur(12px)' }, { opacity: 1, scale: 1, filter: 'blur(0px)', duration: 0.6, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+      const draw = svg.querySelector<SVGGeometryElement>('[data-mk-part="draw"]');
+      if (draw) keep(gsap.fromTo(draw, { strokeDasharray: 60, strokeDashoffset: 60 }, { strokeDashoffset: 0, duration: 0.5, delay: 0.3, ease: EASE.wipe }));
+    }
+    keep(gsap.fromTo(parts(), { opacity: 0, y: 12, filter: 'blur(8px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.45, delay: svg ? 0.15 : 0, stagger: 0.06, ease: 'power2.out', clearProps: 'opacity,transform,filter' }));
+  };
+
+  let entered = false;
+  let visible = true;
+  if (typeof IntersectionObserver === 'function') {
+    // Before it is seen, everything waits hidden; afterwards the loop only runs on screen.
+    if (!reduced()) gsap.set([art, ...parts()], { opacity: 0 });
+    scope.observe(
+      new IntersectionObserver((entries) => {
+        visible = entries.some((entry) => entry.isIntersecting);
+        if (visible && !entered) {
+          entered = true;
+          enter();
+          startLoop();
+        }
+        if (visible) loop?.play();
+        else loop?.pause();
+      }),
+    ).observe(root);
+  } else {
+    entered = true;
+    enter();
+    startLoop();
+  }
+
+  scope.on(root, 'click', (event) => {
+    const action = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-action]');
+    if (!action || !root.contains(action)) return;
+    keep(press(action));
+    options.onAction?.(action.dataset.mkAction!, event as MouseEvent);
+    root.dispatchEvent(new CustomEvent('mk:action', { bubbles: true, detail: { id: action.dataset.mkAction } }));
+  });
+
+  return {
+    update(next) {
+      if (scope.disposed) return;
+      const swap = () => {
+        if (next.illustration !== undefined) {
+          options = { ...options, illustration: next.illustration };
+          drawArt(next.illustration);
+        }
+        if (!authored) fill({ title: next.title ?? options.title, description: next.description ?? options.description, actions: next.actions ?? options.actions });
+        options = { ...options, ...next };
+        if (entered) {
+          enter();
+          if (visible) startLoop();
+        }
+      };
+      if (reduced() || !entered) return swap();
+      keep(gsap.to([art, ...parts()], { opacity: 0, filter: 'blur(8px)', duration: 0.15, ease: 'power1.in', onComplete: swap }));
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/empty-state/react.tsx

@@ -0,0 +1,34 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createEmptyState, type EmptyStateInstance, type EmptyStateOptions } from './engine';
+
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'>, EmptyStateOptions {}
+
+/** <EmptyState illustration="search" title="Sin resultados" actions={[{ id: 'clear', label: 'Borrar filtros' }]} onAction={…} />. */
+export function EmptyState({ illustration, title, description, actions, loop, onAction, className, ...props }: EmptyStateProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<EmptyStateInstance | null>(null);
+  const action = useLatest(onAction);
+  const content = { illustration, title, description, actions };
+  const key = JSON.stringify(content);
+  useIsomorphicLayoutEffect(() => {
+    const created = createEmptyState(ref.current, { ...content, loop, onAction: (id, event) => action.current?.(id, event) });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [loop]);
+  const first = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    instance.current?.update(content);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+  return <div {...props} ref={ref} className={['mk-empty-state', className].filter(Boolean).join(' ')} />;
+}

package/src/components/file-explorer/README.md

@@ -0,0 +1,67 @@
+# file-explorer
+
+Explorador de carpetas y archivos: el árbol de carpetas a un lado, la ruta como *breadcrumb* y el contenido de la carpeta como lista (nombre, tamaño y fecha, ordenable) o como cuadrícula de iconos grandes. Los iconos son dibujos: las carpetas, en el color de acento; los archivos, una hoja teñida según su familia (imagen, PDF, documento, hoja de cálculo, presentación, código, comprimido, audio o video) con la extensión en una etiqueta.
+
+Al abrir una carpeta, el contenido se empuja: el anterior sale hacia un lado con blur y el nuevo entra por el otro (.34 s, curva signature); al volver, al revés. El árbol y la ruta lo siguen. Al cambiar entre lista y cuadrícula, cada icono vuela a su nuevo lugar (Flip, .5 s). Ordenar desliza los elementos a su nuevo orden (el resorte de layout del kit). Una carpeta nueva crece desde un blur y pide su nombre ahí mismo; un nombre repetido sacude el campo. Lo eliminado se encoge y lo demás cierra el hueco.
+
+Para mover, arrastra: se levanta una tarjeta con el número de elementos que sigue al puntero y se inclina con su velocidad. Una carpeta bajo ella (en el contenido, en el árbol o en la ruta) abre la tapa, y las ramas del árbol se abren tras un momento. Al soltar, la tarjeta vuela hacia la carpeta. En pantallas táctiles, el arrastre empieza con una pulsación larga.
+
+## HTML / Astro
+
+```html
+<mk-file-explorer class="mk-file-explorer" root-label="Mi unidad"
+  files='[{"id":"docs","name":"Documentos","children":[
+            {"id":"cv","name":"Currículum.pdf","size":184320,"modified":"2026-10-02"},
+            {"id":"facturas","name":"Facturas","children":[]}]},
+          {"id":"notas","name":"notas.txt","size":900}]'></mk-file-explorer>
+
+<script>
+  const explorer = document.querySelector('mk-file-explorer');
+  explorer.addEventListener('mk:open', (event) => abrir(event.detail.entry));
+  explorer.addEventListener('mk:change', (event) => guardar(event.detail.files, event.detail.change));
+</script>
+```
+
+## React
+
+```tsx
+const [files, setFiles] = useState(inicial);
+
+<FileExplorer files={files} onChange={setFiles} onOpen={(file) => preview(file)} rootLabel="Mi unidad" />;
+```
+
+Lo que devuelve `onChange` puede volver como `files` sin redibujar nada; unos `files` distintos que lleguen de la app reemplazan lo que se muestra.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `files` | `files` (JSON) | `[]` | Lo que contiene la carpeta superior: `{ id, name, kind?, children?, size?, modified? }[]`. Una entrada con `children` (o `kind: 'folder'`) es una carpeta. |
+| `rootLabel` | `root-label` | `'Inicio'` | Nombre de la carpeta superior. |
+| `folder` | `folder` | `'/'` | Carpeta abierta al empezar. |
+| `view` | `view` | `'list'` | `'list'` o `'grid'`. |
+| `tree` | `tree` | `true` | El árbol de carpetas (se oculta por debajo de 560 px). |
+| `readOnly` | `read-only` | `false` | Sin crear, renombrar, eliminar ni mover. |
+| `locale` | `locale` | el `lang` más cercano | Idioma de fechas, tamaños y orden. |
+| `label` | `label` | `'Explorador de archivos'` | Nombre accesible. |
+| `onOpen(file)` | — | — | Se abrió un archivo (doble clic o Intro). |
+| `onNavigate(folder)` | — | — | Se abrió una carpeta. |
+| `onSelectionChange(ids)` | — | — | Cambió la selección. |
+| `onViewChange(view)` | — | — | Cambió la vista (también desde su interruptor). |
+| `onChange(files, change)` | — | — | Tras crear, renombrar, eliminar o mover; `change` dice qué pasó (`{ type: 'create' \| 'rename' \| 'delete' \| 'move', … }`). |
+
+## API y eventos
+
+`open(id)` (una carpeta, o un archivo: abre su carpeta y llama a `onOpen`), `up()`, `setView(view)`, `select(ids)`, `createFolder(nombre?)`, `rename(id, nombre?)` (sin nombre, lo pide en su sitio), `remove(ids?)`, `move(ids, carpeta)`, `setFiles(files)`, `files`, `folder`, `selection`, `view`, `destroy()`. Eventos `mk:open` con `{ id, entry }`, `mk:navigate` con `{ id, folder }`, `mk:select` con `{ ids }` y `mk:change` con `{ files, change }`.
+
+## Teclado
+
+Flechas para moverse (en la cuadrícula, también ← →), Mayús para extender la selección, Ctrl/⌘ para mover el foco sin seleccionar y Ctrl/⌘ + Espacio para sumar, Ctrl/⌘ + A selecciona todo, Intro abre, Retroceso o Alt + ↑ suben, F2 renombra, Supr elimina, Ctrl/⌘ + X y Ctrl/⌘ + V mueven a otra carpeta, Escape limpia la selección y escribir salta a un nombre. Durante un arrastre, Escape lo cancela.
+
+## Variables CSS
+
+`--mk-fx-height` (alto, `26rem`), `--mk-fx-side` (ancho del árbol, `13rem`).
+
+## Accesibilidad
+
+Una región con nombre; el contenido es un `listbox` de selección múltiple con un solo elemento tabulable, y cada opción dice su nombre, su tipo, su tamaño y su fecha. El árbol sigue el patrón de árbol de WAI-ARIA y la ruta es un `nav`. Un estado discreto anuncia cada carpeta abierta, cada cambio y cada movimiento; el error de un nombre se lee desde el campo. Mover también se puede hacer sin arrastrar (Ctrl + X, Ctrl + V). Con movimiento reducido no hay deslizamientos, vuelos ni inclinación.

package/src/components/file-explorer/element.ts

@@ -0,0 +1,39 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createFileExplorer, type FileEntry, type FileExplorerInstance } from './engine';
+
+/**
+ * <mk-file-explorer class="mk-file-explorer" root-label="Mi unidad" view="grid"
+ *   files='[{"id":"docs","name":"Documentos","children":[{"id":"cv","name":"Currículum.pdf","size":184320}]}]'>
+ * </mk-file-explorer>. Emits mk:open ({id, entry}), mk:navigate ({id, folder}), mk:select ({ids}), mk:change ({files, change}).
+ */
+export class MkFileExplorerElement extends MkElement<FileExplorerInstance> {
+  static options: Record<string, OptionType> = {
+    files: 'json',
+    rootLabel: 'string',
+    folder: 'string',
+    view: 'string',
+    tree: 'boolean',
+    readOnly: 'boolean',
+    locale: 'string',
+    label: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createFileExplorer(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'files') {
+      try {
+        this.instance.setFiles(JSON.parse(next ?? '[]') as FileEntry[]);
+      } catch {
+        // Malformed JSON: keep the current files.
+      }
+    } else if (name === 'view') this.instance.setView(next === 'grid' ? 'grid' : 'list');
+    else if (name === 'folder') this.instance.open(next || '/');
+    else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineFileExplorer = () => defineElement('mk-file-explorer', MkFileExplorerElement);