@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/credit-card/engine.ts

@@ -0,0 +1,410 @@
+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, shake } from '../../motion/micro';
+import { BRAND_LABELS, cardGroups, cardLength, cvcLength, detectBrand, formatNumber, luhn, parseExpiry, type CardBrand } from './card';
+
+/*
+ * Credit card: native fields (cc-number, cc-name, cc-exp, cc-csc autocomplete)
+ * beside a dark card that fills in as you type. Each new character rolls into
+ * its slot (y 100 % → 0 out of a blur); a frame glides to the part of the card
+ * being edited; the brand appears by prefix (as text, no logos); the CVC field
+ * turns the card around in 3D (0.8 s, Melonmind's swing) and leaving it turns it
+ * back. A fine pointer tilts the card a little. Fields validate on blur (Luhn,
+ * a future expiry, CVC length) and shake when wrong. Nothing is charged: the
+ * app reads the form. Events carry no card data: mk:change {brand, complete, valid}, mk:complete.
+ */
+
+export type CreditCardField = 'number' | 'name' | 'expiry' | 'cvc';
+
+export interface CreditCardLabels {
+  number?: string;
+  name?: string;
+  expiry?: string;
+  cvc?: string;
+  namePlaceholder?: string;
+  invalidNumber?: string;
+  invalidExpiry?: string;
+  invalidCvc?: string;
+}
+
+export interface CreditCardOptions {
+  labels?: CreditCardLabels;
+  /** Form names of the fields (default cc-number, cc-name, cc-exp, cc-csc). */
+  names?: Partial<Record<CreditCardField, string>>;
+  /** Tilt the card with a fine pointer (default true). */
+  tilt?: boolean;
+  onChange?: (state: { brand: CardBrand; complete: boolean; valid: boolean }) => void;
+  onComplete?: () => void;
+}
+
+export interface CreditCardValues {
+  number: string;
+  name: string;
+  expiry: string;
+  cvc: string;
+}
+
+export interface CreditCardInstance extends Instance {
+  readonly values: CreditCardValues;
+  readonly brand: CardBrand;
+  readonly valid: boolean;
+  focus(field: CreditCardField): void;
+  /** Turn the card (true: the back). */
+  flip(back?: boolean): void;
+}
+
+const LABELS: Required<CreditCardLabels> = {
+  number: 'Número de tarjeta',
+  name: 'Titular',
+  expiry: 'Caducidad',
+  cvc: 'CVC',
+  namePlaceholder: 'NOMBRE APELLIDO',
+  invalidNumber: 'Revisa el número de la tarjeta.',
+  invalidExpiry: 'La fecha de caducidad no es válida.',
+  invalidCvc: 'El CVC está incompleto.',
+};
+
+const FIELDS: CreditCardField[] = ['number', 'name', 'expiry', 'cvc'];
+const NAMES: Record<CreditCardField, string> = { number: 'cc-number', name: 'cc-name', expiry: 'cc-exp', cvc: 'cc-csc' };
+let sequence = 0;
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string> = {}, text?: string) => {
+  const element = document.createElement(tag);
+  for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, value);
+  if (text !== undefined) element.textContent = text;
+  return element;
+};
+
+export function createCreditCard(root: HTMLElement | null, options: CreditCardOptions = {}): CreditCardInstance {
+  if (!root) return inert({ values: { number: '', name: '', expiry: '', cvc: '' }, brand: 'unknown', valid: false, focus() {}, flip() {} });
+  registerMotion();
+  const scope = createScope();
+  const labels = { ...LABELS, ...options.labels };
+  const uid = `mk-card-${++sequence}`;
+  const made: HTMLElement[] = [];
+  const own = <T extends HTMLElement>(element: T) => {
+    made.push(element);
+    return element;
+  };
+  scope.add(() => made.forEach((element) => element.remove()));
+
+  // The card (decorative: the fields are the accessible control).
+  const visual = own(el('div', { 'data-mk-card-visual': '', 'aria-hidden': 'true' }));
+  const inner = el('div', { 'data-mk-card-inner': '' });
+  const front = el('div', { 'data-mk-card-face': 'front' });
+  const back = el('div', { 'data-mk-card-face': 'back' });
+  const chip = el('span', { 'data-mk-card-chip': '' });
+  const brand = el('span', { 'data-mk-card-brand': '' });
+  const number = el('span', { 'data-mk-card-number': '' });
+  const name = el('span', { 'data-mk-card-name': '' });
+  const expiry = el('span', { 'data-mk-card-expiry': '' });
+  const holderLabel = el('span', { 'data-mk-card-caption': '' }, labels.name);
+  const expiryLabel = el('span', { 'data-mk-card-caption': '' }, labels.expiry);
+  const holder = el('span', { 'data-mk-card-region': 'name' });
+  holder.append(holderLabel, name);
+  const valid = el('span', { 'data-mk-card-region': 'expiry' });
+  valid.append(expiryLabel, expiry);
+  const frame = el('span', { 'data-mk-card-frame': '' });
+  const numberRegion = el('span', { 'data-mk-card-region': 'number' });
+  numberRegion.append(number);
+  front.append(chip, brand, numberRegion, holder, valid, frame);
+  const stripe = el('span', { 'data-mk-card-stripe': '' });
+  const signature = el('span', { 'data-mk-card-signature': '' });
+  const cvc = el('span', { 'data-mk-card-cvc': '' });
+  signature.append(cvc);
+  const backBrand = el('span', { 'data-mk-card-brand': '' });
+  back.append(stripe, signature, backBrand);
+  inner.append(front, back);
+  visual.append(inner);
+
+  // The fields: authored ones are used as they are; missing ones are made.
+  const fields = {} as Record<CreditCardField, HTMLInputElement>;
+  const errors = {} as Record<CreditCardField, HTMLElement | null>;
+  let grid = root.querySelector<HTMLElement>('[data-mk-card-fields]');
+  if (!grid) grid = own(el('div', { 'data-mk-card-fields': '' }));
+  for (const field of FIELDS) {
+    let input = root.querySelector<HTMLInputElement>(`input[data-mk-card-field="${field}"]`);
+    if (!input) {
+      const label = el('label', { 'data-mk-card-label': field });
+      label.append(el('span', {}, labels[field]));
+      input = el('input', { 'data-mk-card-field': field });
+      label.append(input);
+      const error = el('span', { 'data-mk-card-error': '', id: `${uid}-${field}-error` });
+      label.append(error);
+      grid.append(label);
+    }
+    fields[field] = input;
+    errors[field] = input.closest('label')?.querySelector<HTMLElement>('[data-mk-card-error]') ?? null;
+  }
+  root.prepend(visual);
+  if (!grid.isConnected) root.append(grid);
+
+  const attrs: Record<CreditCardField, Record<string, string>> = {
+    number: { inputmode: 'numeric', autocomplete: 'cc-number', placeholder: '0000 0000 0000 0000' },
+    name: { autocomplete: 'cc-name', placeholder: labels.namePlaceholder, autocapitalize: 'characters', spellcheck: 'false' },
+    expiry: { inputmode: 'numeric', autocomplete: 'cc-exp', placeholder: 'MM/AA', maxlength: '5' },
+    cvc: { inputmode: 'numeric', autocomplete: 'cc-csc', placeholder: '•••', maxlength: '4' },
+  };
+  for (const field of FIELDS) {
+    const input = fields[field];
+    scope.attr(input, 'type', 'text');
+    for (const [key, value] of Object.entries(attrs[field])) if (!input.hasAttribute(key)) scope.attr(input, key, value);
+    if (!input.name) scope.attr(input, 'name', options.names?.[field] ?? NAMES[field]);
+    if (errors[field]?.id) scope.attr(input, 'aria-describedby', errors[field]!.id);
+  }
+  scope.attr(root, 'data-mk-ready', '');
+
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null | undefined) => {
+    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();
+    gsap.killTweensOf([inner, visual, frame]);
+  });
+
+  /** Write text into `target` one span per character; changed characters roll in. */
+  const chars = (target: HTMLElement, text: string, placeholder: string) => {
+    const shown = text || placeholder;
+    const empty = !text;
+    target.toggleAttribute('data-mk-empty', empty);
+    const current = [...target.children] as HTMLElement[];
+    for (let i = 0; i < Math.max(current.length, shown.length); i++) {
+      const char = shown[i];
+      const span = current[i];
+      if (char === undefined) {
+        span?.remove();
+        continue;
+      }
+      if (span && span.textContent === char && span.hasAttribute('data-mk-placeholder') === (empty || char === '•')) continue;
+      const next = el('span', {}, char);
+      next.toggleAttribute('data-mk-placeholder', empty || char === '•');
+      if (char === ' ') next.dataset.mkSpace = '';
+      if (span) span.replaceWith(next);
+      else target.append(next);
+      if (!empty && char !== '•' && char !== ' ' && !reduced()) keep(gsap.fromTo(next, { yPercent: 70, opacity: 0, filter: 'blur(4px)' }, { yPercent: 0, opacity: 1, filter: 'blur(0px)', duration: 0.35, ease: EASE.signature, clearProps: 'all' }));
+    }
+  };
+
+  const state = { number: '', name: '', expiry: '', cvc: '', brand: 'unknown' as CardBrand };
+  let flipped = false;
+  let lastComplete = false;
+  let lastSignature = '';
+
+  const numberMask = (brand: CardBrand, digits: string) => {
+    const groups = cardGroups(brand);
+    const parts: string[] = [];
+    let at = 0;
+    for (const size of groups) {
+      parts.push(Array.from({ length: size }, (_, i) => digits[at + i] ?? '•').join(''));
+      at += size;
+    }
+    return parts.join(' ');
+  };
+
+  const checks = () => {
+    const expiryState = parseExpiry(state.expiry);
+    return {
+      number: state.number.length === cardLength(state.brand) && luhn(state.number),
+      name: state.name.trim().length > 1,
+      expiry: expiryState.valid,
+      cvc: state.cvc.length === cvcLength(state.brand),
+    };
+  };
+
+  const render = () => {
+    chars(number, numberMask(state.brand, state.number), '');
+    number.toggleAttribute('data-mk-empty', !state.number);
+    chars(name, state.name.toUpperCase(), labels.namePlaceholder);
+    chars(expiry, state.expiry, 'MM/AA');
+    chars(cvc, state.cvc, '•'.repeat(cvcLength(state.brand)));
+    const label = BRAND_LABELS[state.brand];
+    if (brand.textContent !== label) {
+      brand.textContent = label;
+      backBrand.textContent = label;
+      keep(blurIn(label ? [brand] : null, { from: 'pop' }));
+    }
+    scope.attr(root, 'data-mk-brand', state.brand);
+    fields.cvc.maxLength = cvcLength(state.brand);
+  };
+
+  const emit = () => {
+    const ok = checks();
+    const complete = FIELDS.every((field) => (field === 'number' ? state.number.length === cardLength(state.brand) : field === 'expiry' ? state.expiry.length === 5 : field === 'cvc' ? state.cvc.length === cvcLength(state.brand) : state.name.trim().length > 0));
+    const allValid = Object.values(ok).every(Boolean);
+    const signature = `${state.brand}|${complete}|${allValid}`;
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      const detail = { brand: state.brand, complete, valid: allValid };
+      options.onChange?.(detail);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail }));
+    }
+    if (allValid && !lastComplete) {
+      options.onComplete?.();
+      root.dispatchEvent(new CustomEvent('mk:complete', { bubbles: true }));
+    }
+    lastComplete = allValid;
+  };
+
+  const setInvalid = (field: CreditCardField, message: string | null) => {
+    scope.attr(fields[field], 'aria-invalid', message ? 'true' : null);
+    if (errors[field]) errors[field]!.textContent = message ?? '';
+  };
+
+  const flip = (toBack = !flipped) => {
+    if (scope.disposed || toBack === flipped) return;
+    flipped = toBack;
+    scope.attr(root, 'data-mk-flipped', flipped ? '' : null);
+    gsap.killTweensOf(inner, 'rotationY');
+    if (reduced()) gsap.set(inner, { rotationY: flipped ? 180 : 0 });
+    else keep(gsap.to(inner, { rotationY: flipped ? 180 : 0, duration: 0.8, ease: EASE.swatch }));
+  };
+
+  /** The frame glides to the region of the card being edited. */
+  const regions: Record<CreditCardField, HTMLElement | null> = { number: numberRegion, name: holder, expiry: valid, cvc: null };
+  const moveFrame = (field: CreditCardField | null) => {
+    const target = field ? regions[field] : null;
+    if (!target) {
+      keep(gsap.to(frame, { opacity: 0, duration: 0.2, overwrite: 'auto' }));
+      return;
+    }
+    const box = { x: target.offsetLeft - 8, y: target.offsetTop - 6, width: target.offsetWidth + 16, height: target.offsetHeight + 12 };
+    const visible = Number(gsap.getProperty(frame, 'opacity')) > 0.5;
+    if (!visible || reduced()) gsap.set(frame, { ...box, opacity: reduced() ? 1 : 0 });
+    if (!reduced()) keep(gsap.to(frame, { ...box, opacity: 1, duration: 0.5, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+
+  // Typing: keep the field formatted and the caret after the same digits.
+  const caretDigits = (input: HTMLInputElement) => (input.value.slice(0, input.selectionStart ?? input.value.length).match(/\d/g) ?? []).length;
+  const placeCaret = (input: HTMLInputElement, digits: number) => {
+    let seen = 0;
+    let at = 0;
+    while (at < input.value.length && seen < digits) {
+      if (/\d/.test(input.value[at]!)) seen += 1;
+      at += 1;
+    }
+    if (document.activeElement === input) input.setSelectionRange(at, at);
+  };
+
+  const read = (field: CreditCardField, fromInput: boolean) => {
+    const input = fields[field];
+    if (field === 'number') {
+      const caret = caretDigits(input);
+      const digits = input.value.replace(/\D/g, '');
+      state.brand = detectBrand(digits);
+      state.number = digits.slice(0, cardLength(state.brand));
+      input.value = formatNumber(state.number, state.brand);
+      if (fromInput) placeCaret(input, caret);
+    } else if (field === 'expiry') {
+      const parsed = parseExpiry(input.value);
+      state.expiry = parsed.text;
+      // Deleting the slash deletes the month digit before it.
+      input.value = parsed.text;
+    } else if (field === 'cvc') {
+      state.cvc = input.value.replace(/\D/g, '').slice(0, cvcLength(state.brand));
+      input.value = state.cvc;
+    } else state.name = input.value.replace(/\s+/g, ' ').trimStart().slice(0, 26);
+  };
+
+  const validate = (field: CreditCardField) => {
+    const ok = checks();
+    const filled = field === 'number' ? state.number : field === 'expiry' ? state.expiry : field === 'cvc' ? state.cvc : state.name;
+    const message = !filled || ok[field] ? null : field === 'number' ? labels.invalidNumber : field === 'expiry' ? labels.invalidExpiry : field === 'cvc' ? labels.invalidCvc : null;
+    setInvalid(field, message);
+    if (message) {
+      keep(shake(fields[field].closest('label') ?? fields[field]));
+      keep(shake(visual, 6));
+    }
+  };
+
+  let leaving: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => clearTimeout(leaving));
+  for (const field of FIELDS) {
+    const input = fields[field];
+    read(field, false);
+    scope.on(input, 'input', () => {
+      read(field, true);
+      if (fields[field].getAttribute('aria-invalid') === 'true' && checks()[field]) setInvalid(field, null);
+      render();
+      emit();
+    });
+    scope.on(input, 'focus', () => {
+      root.dataset.mkActive = field;
+      if (field === 'cvc') flip(true);
+      else flip(false);
+      moveFrame(field);
+    });
+    scope.on(input, 'blur', () => {
+      validate(field);
+      // Leaving the form: the card faces front again.
+      clearTimeout(leaving);
+      leaving = setTimeout(() => {
+        if (scope.disposed) return;
+        const active = document.activeElement;
+        if (!FIELDS.some((name) => fields[name] === active)) {
+          delete root.dataset.mkActive;
+          flip(false);
+          moveFrame(null);
+        }
+      }, 0);
+    });
+  }
+  scope.add(() => delete root.dataset.mkActive);
+  // Expiry: a backspace right after the slash also removes the month's second digit.
+  scope.on(fields.expiry, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const input = fields.expiry;
+    if (key.key === 'Backspace' && input.selectionStart === input.value.length && input.value.endsWith('/')) {
+      key.preventDefault();
+      input.value = input.value.slice(0, 1);
+      read('expiry', true);
+      render();
+      emit();
+    }
+  });
+
+  // A fine pointer tilts the card.
+  if (options.tilt !== false && typeof matchMedia === 'function' && matchMedia('(pointer: fine)').matches) {
+    scope.on(visual, 'pointermove', (event) => {
+      if (reduced()) return;
+      const box = visual.getBoundingClientRect();
+      const x = ((event as PointerEvent).clientX - box.left) / box.width - 0.5;
+      const y = ((event as PointerEvent).clientY - box.top) / box.height - 0.5;
+      gsap.to(visual, { rotationY: x * 12, rotationX: -y * 10, duration: 0.5, ease: 'power3.out', overwrite: 'auto' });
+    });
+    scope.on(visual, 'pointerleave', () => {
+      gsap.to(visual, { rotationY: 0, rotationX: 0, duration: 0.7, ease: EASE.swatch, overwrite: 'auto' });
+    });
+  }
+  // A click on the card focuses its part.
+  scope.on(visual, 'click', (event) => {
+    const region = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-card-region]')?.dataset.mkCardRegion as CreditCardField | undefined;
+    fields[flipped ? 'cvc' : region ?? 'number'].focus();
+  });
+  render();
+  lastSignature = '';
+  lastComplete = Object.values(checks()).every(Boolean);
+
+  return {
+    get values() {
+      return { number: state.number, name: state.name, expiry: state.expiry, cvc: state.cvc };
+    },
+    get brand() {
+      return state.brand;
+    },
+    get valid() {
+      return Object.values(checks()).every(Boolean);
+    },
+    focus(field) {
+      fields[field]?.focus();
+    },
+    flip: (toBack) => flip(toBack ?? !flipped),
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/credit-card/react.tsx

@@ -0,0 +1,36 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createCreditCard, type CreditCardInstance, type CreditCardOptions } from './engine';
+
+export interface CreditCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'>, CreditCardOptions {
+  instanceRef?: MutableRefObject<CreditCardInstance | null>;
+}
+
+/**
+ * <CreditCard onComplete={() => setReady(true)} /> inside a <form>: the engine makes the card and the
+ * native cc-* fields; the app reads the form when it submits. Callbacks carry no card data.
+ */
+export function CreditCard({ labels, names, tilt, onChange, onComplete, instanceRef, className, ...props }: CreditCardProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const change = useLatest(onChange);
+  const complete = useLatest(onComplete);
+  const key = JSON.stringify([labels ?? {}, names ?? {}]);
+  useIsomorphicLayoutEffect(() => {
+    const created = createCreditCard(ref.current, {
+      labels,
+      names,
+      tilt,
+      onChange: (state) => change.current?.(state),
+      onComplete: () => complete.current?.(),
+    });
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // labels and names are compared by content.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, tilt]);
+  return <div {...props} ref={ref} className={['mk-credit-card', className].filter(Boolean).join(' ')} />;
+}

package/src/components/data-table/README.md

@@ -0,0 +1,83 @@
+# data-table
+
+Tabla avanzada con ordenamiento, búsqueda, filtros, selección, paginación, acciones por fila y columnas configurables. Al ordenar, las filas se deslizan a su nuevo lugar (el resorte de layout del kit, .62 s) y la flecha del encabezado gira. La búsqueda resalta lo que coincide (sin importar tildes ni mayúsculas) y las filas que quedan se reacomodan juntas. Los filtros usan `filter-builder` dentro de un panel que crece desde su botón: la tabla responde mientras editas y una frase dice qué está filtrado («Estado es Enviado y Monto mayor que 500»).
+
+Las casillas se dibujan solas y hacen pop; la del encabezado queda a medias cuando solo hay algunas filas elegidas. Una fila elegida se tiñe apenas y lleva un borde de acento a la izquierda, sin tapar sus datos. Al elegir filas, la barra con el conteo (que rueda) y las acciones masivas aparece con un blur en el lugar de la barra de herramientas, así nunca cubre filas, y ofrece elegir todos los resultados cuando la página entera está marcada. Al cambiar de página, las filas entran por el lado hacia el que vas; si la tabla cabe en su panel, el desborde se oculta mientras viajan para que no parpadee una barra de desplazamiento (si ya es más ancha, aparecen con un fundido). Las filas eliminadas salen deslizándose y las demás cierran el hueco. Mientras carga hay *skeletons* que brillan, y sin nada que mostrar aparece un estado vacío que explica por qué y ofrece limpiar los filtros.
+
+## HTML / Astro
+
+```html
+<mk-data-table class="mk-data-table" selectable page-size="10" sort="monto:desc" caption="Pedidos"
+  columns='[{"key":"cliente","label":"Cliente"},
+            {"key":"monto","label":"Monto","type":"number"},
+            {"key":"fecha","label":"Fecha","type":"date"},
+            {"key":"estado","label":"Estado","type":"select","options":[{"value":"nuevo","label":"Nuevo"},{"value":"enviado","label":"Enviado"}]}]'
+  rows='[{"id":1,"cliente":"Ana Gómez","monto":1240,"fecha":"2026-10-28","estado":"nuevo"}]'
+  actions='[{"id":"ver","label":"Ver pedido"},{"id":"cancelar","label":"Cancelar","danger":true}]'
+  bulk-actions='[{"id":"exportar","label":"Exportar"}]'></mk-data-table>
+
+<script>
+  const table = document.querySelector('mk-data-table');
+  table.addEventListener('mk:action', (event) => console.log(event.detail.action, event.detail.row));
+</script>
+```
+
+Con JavaScript, `createDataTable(root, opciones)` acepta además `format` y `render` en cada columna.
+
+## React
+
+```tsx
+const table = useRef<DataTableHandle<Pedido>>(null);
+
+<DataTable
+  ref={table}
+  columns={columnas}
+  rows={pedidos}
+  selectable
+  actions={[{ id: 'cancelar', label: 'Cancelar', danger: true }]}
+  onAction={(accion, pedido) => accion === 'cancelar' && table.current?.removeRows([pedido.id])}
+  bulkActions={[{ id: 'exportar', label: 'Exportar' }]}
+  onBulkAction={(accion, filas) => exportar(filas)}
+/>;
+```
+
+Unas `rows` nuevas entran en su sitio y se conservan el orden, los filtros y la selección. Las celdas son texto (`format`) o se dibujan con `render(valor, fila, celda)`.
+
+## Columnas
+
+`{ key, label, type?, options?, sortable?, filterable?, searchable?, hidden?, hideable?, align?, width?, format?, render?, value? }`. `type`: `text`, `number`, `date`, `boolean` o `select` (decide cómo se ordena, se filtra y se escribe: números y fechas en el idioma de la página, «Sí»/«No», la etiqueta de la opción). Los números se alinean a la derecha.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `columns` | `columns` (JSON) | `[]` | Las columnas. |
+| `rows` | `rows` (JSON) | `[]` | Las filas. |
+| `rowKey` | `row-key` | `'id'` | Clave (o función) del id de cada fila. |
+| `caption` | `caption` | `'Tabla'` | Nombre accesible. |
+| `pageSize` | `page-size` | `10` | Filas por página (`0`: todas). |
+| `pageSizes` | `page-sizes` (JSON) | `[10, 25, 50]` | Opciones del menú «Filas» (un botón que abre un menú como Filtros y Columnas, con la opción actual marcada). |
+| `selectable` | `selectable` | `false` | Casillas para elegir filas. |
+| `search` | `search` | `true` | Campo de búsqueda (un texto es su marcador). |
+| `filters` | `filters` | `true` | Botón «Filtros» con `filter-builder`. |
+| `filter` | — | vacío | Filtro inicial. |
+| `columnsMenu` | `columns-menu` | `true` | Botón «Columnas» para mostrar y ocultar. |
+| `actions` | `actions` (JSON) | — | Menú de cada fila: `{ id, label, danger? }[]`. |
+| `bulkActions` | `bulk-actions` (JSON) | — | Botones de la barra de selección. |
+| `sort` | `sort` (`clave` o `clave:desc`) | sin orden | Orden inicial. |
+| `loading` | `loading` | `false` | *Skeletons* mientras carga. |
+| `emptyTitle` / `emptyDescription` | `empty-title` / `empty-description` | — | Textos sin filas. |
+| `onSortChange`, `onSelectionChange(ids, filas)`, `onAction(accion, fila)`, `onBulkAction(accion, filas)`, `onPageChange(pagina)`, `onFilterChange(filtro, busqueda)` | — | — | Cada cambio. |
+| `onRender(tbody)` | — | — | Después de dibujar las filas (lo usa `editable-table`). |
+
+## API y eventos
+
+`setRows`, `updateRow(id, cambios)`, `removeRows(ids)`, `setLoading`, `sortBy(clave | null, direccion)`, `setPage`, `setPageSize`, `setQuery`, `setFilter`, `setColumnVisible(clave, visible)`, `select(ids)`, `rowOf(id)`, `cellOf(id, clave)`, `refresh()`, `idOf(fila)`, y `rows`, `results`, `page`, `pageCount`, `selection`, `sort`, `query`, `filter`, `columns`, `body`, `destroy()`. Eventos `mk:sort`, `mk:select`, `mk:action`, `mk:bulk-action`, `mk:page` y `mk:filter`.
+
+## Variables CSS
+
+`--mk-dt-max-height` (alto máximo antes de desplazarse dentro, con el encabezado fijo).
+
+## Accesibilidad
+
+Una tabla real con `caption`, encabezados `th scope="col"` con `aria-sort` y botones para ordenar; casillas con etiqueta («Seleccionar Ana Gómez»); el botón de acciones dice de qué fila es y abre un menú de WAI-ARIA; «Filas» es un botón con `aria-haspopup="menu"` y sus opciones son `menuitemradio` con `aria-checked`; la barra de selección es un `toolbar` con nombre. Si la tabla es más ancha que su contenedor, se desplaza de lado dentro de una región enfocable. Un estado discreto anuncia el orden, los resultados, la página y la selección. Con movimiento reducido los cambios son inmediatos.