@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/data-table/engine.ts

@@ -0,0 +1,1059 @@
+import { gsap, EASE, Flip, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, type Instance } from '../../core/types';
+import { fromJson, safeFormat } from '../../core/dates';
+import { toTime } from '../../core/relative-time';
+import { foldText, markText } from '../../core/mark';
+import { cloneFilter, describeFilter, emptyFilter, hasConditions, matchesFilter, type FilterField, type FilterGroup } from '../../core/filter';
+import { flowInMenu } from '../../motion/entrances';
+import { press, rollDigits } from '../../motion/micro';
+import { createDialog } from '../dialog/engine';
+import { createMenu } from '../menu/engine';
+import { createEmptyState } from '../empty-state/engine';
+import { createFilterBuilder } from '../filter-builder/engine';
+
+/*
+ * Data table: rows and columns with sorting, a search, filters, selection,
+ * pagination, row actions and columns to show or hide. Sorting glides the rows
+ * to their new order (layout reflow, .62 s) while the header's arrow turns;
+ * the search marks what matches and the rows that stay glide together; filters
+ * come from filter-builder in a panel that grows out of its button (the table
+ * follows live, a sentence says what is filtered). Checks draw themselves and
+ * pop; the header box goes mixed; a bar with the count (rolling) and the bulk
+ * actions slides up out of a blur when something is chosen. A page change
+ * slides the rows in from the side it goes to. Rows taken away slide out and
+ * the rest close the gap. While loading, shimmering bones stand in; with
+ * nothing to show, an empty state says why and offers to clear the filters.
+ */
+
+export type DataColumnType = 'text' | 'number' | 'date' | 'boolean' | 'select';
+export type DataRow = Record<string, unknown>;
+export type RowId = string | number;
+export type SortDirection = 'asc' | 'desc';
+
+export interface DataSort {
+  key: string;
+  direction: SortDirection;
+}
+
+export interface DataColumn<T extends DataRow = DataRow> {
+  key: string;
+  label: string;
+  /** For sorting, filtering and the default text (default 'text'). */
+  type?: DataColumnType;
+  /** The choices of a 'select' column (its text and its filter). */
+  options?: Array<{ value: string; label: string }>;
+  sortable?: boolean;
+  filterable?: boolean;
+  searchable?: boolean;
+  /** Starts hidden (it can be shown from "Columnas"). */
+  hidden?: boolean;
+  /** Can be hidden from "Columnas" (default true). */
+  hideable?: boolean;
+  align?: 'start' | 'center' | 'end';
+  width?: string;
+  /** The cell's text (default: numbers and dates in the page's language, Sí/No, the choice's label). */
+  format?: (value: unknown, row: T) => string;
+  /** Draw the cell yourself (vanilla). */
+  render?: (value: unknown, row: T, cell: HTMLTableCellElement) => void;
+  /** The value to sort, filter and search by (default row[key]). */
+  value?: (row: T) => unknown;
+}
+
+export interface DataAction {
+  id: string;
+  label: string;
+  danger?: boolean;
+}
+
+export interface DataTableOptions<T extends DataRow = DataRow> {
+  columns?: DataColumn<T>[];
+  rows?: T[];
+  /** The rows' id: a key (default 'id') or a function. */
+  rowKey?: string | ((row: T) => RowId);
+  /** Accessible name (default 'Tabla'). */
+  caption?: string;
+  /** Rows a page (default 10; 0: all of them). */
+  pageSize?: number;
+  pageSizes?: number[];
+  selectable?: boolean;
+  /** A search field: true, or its placeholder (default true). */
+  search?: boolean | string;
+  /** A "Filtros" button with filter-builder (default true). */
+  filters?: boolean;
+  filter?: FilterGroup;
+  /** A "Columnas" button to show and hide columns (default true). */
+  columnsMenu?: boolean;
+  /** A menu on each row. */
+  actions?: DataAction[];
+  /** Buttons in the bar of the chosen rows. */
+  bulkActions?: DataAction[];
+  sort?: DataSort | null;
+  loading?: boolean;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  locale?: string;
+  onSortChange?: (sort: DataSort | null) => void;
+  onSelectionChange?: (ids: RowId[], rows: T[]) => void;
+  onAction?: (action: string, row: T) => void;
+  onBulkAction?: (action: string, rows: T[]) => void;
+  onPageChange?: (page: number) => void;
+  onFilterChange?: (filter: FilterGroup, query: string) => void;
+  /** After the rows are drawn (editable-table decorates them). */
+  onRender?: (body: HTMLTableSectionElement) => void;
+}
+
+export interface DataTableInstance<T extends DataRow = DataRow> extends Instance {
+  setRows(rows: T[]): void;
+  updateRow(id: RowId, patch: Partial<T>): void;
+  /** Rows slide out and the rest close the gap. */
+  removeRows(ids: RowId[]): void;
+  setLoading(loading: boolean): void;
+  sortBy(key: string | null, direction?: SortDirection): void;
+  setPage(page: number): void;
+  setPageSize(size: number): void;
+  setQuery(query: string): void;
+  setFilter(filter: FilterGroup): void;
+  setColumnVisible(key: string, visible: boolean): void;
+  select(ids: RowId[]): void;
+  rowOf(id: RowId): HTMLTableRowElement | null;
+  cellOf(id: RowId, key: string): HTMLTableCellElement | null;
+  /** Draw the rows again (after changing them in place). */
+  refresh(): void;
+  idOf(row: T): RowId;
+  readonly rows: T[];
+  /** The rows the search and the filters leave, in order. */
+  readonly results: T[];
+  readonly page: number;
+  readonly pageCount: number;
+  readonly selection: RowId[];
+  readonly sort: DataSort | null;
+  readonly query: string;
+  readonly filter: FilterGroup;
+  readonly columns: DataColumn<T>[];
+  readonly body: HTMLTableSectionElement;
+}
+
+const SVG = (paths: string, size = 16) =>
+  `<svg aria-hidden="true" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${paths}</svg>`;
+const ICONS = {
+  search: SVG('<circle cx="11" cy="11" r="6.5"/><path d="M20 20l-4.2-4.2"/>'),
+  filter: SVG('<path d="M4 6h16M7 12h10M10 18h4"/>'),
+  columns: SVG('<rect x="3.5" y="4.5" width="17" height="15" rx="2.5"/><path d="M9.5 4.5v15M14.5 4.5v15"/>'),
+  more: SVG('<circle cx="5.5" cy="12" r="1.2" fill="currentColor"/><circle cx="12" cy="12" r="1.2" fill="currentColor"/><circle cx="18.5" cy="12" r="1.2" fill="currentColor"/>', 18),
+  previous: SVG('<path d="M15 6l-6 6 6 6"/>'),
+  next: SVG('<path d="M9 6l6 6-6 6"/>'),
+  close: SVG('<path d="M7 7l10 10M17 7L7 17"/>', 14),
+  arrow: SVG('<path d="M12 19V5M6 11l6-6 6 6"/>', 12),
+};
+const CHECK =
+  '<svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path data-mk-dt-tick d="M5 12.5l4.5 4.5L19 7.5" pathLength="1"/><path data-mk-dt-dash d="M6 12h12"/></svg>';
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+let sequence = 0;
+
+export function createDataTable<T extends DataRow = DataRow>(root: HTMLElement | null, options: DataTableOptions<T> = {}): DataTableInstance<T> {
+  if (!root) {
+    return inert({
+      setRows() {}, updateRow() {}, removeRows() {}, setLoading() {}, sortBy() {}, setPage() {}, setPageSize() {}, setQuery() {}, setFilter() {}, setColumnVisible() {}, select() {},
+      rowOf: () => null, cellOf: () => null, refresh() {}, idOf: () => '',
+      rows: [], results: [], page: 0, pageCount: 0, selection: [], sort: null, query: '', filter: emptyFilter(), columns: [], body: null as unknown as HTMLTableSectionElement,
+    });
+  }
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-dt-${++sequence}`;
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  // JSON text too (data-mk-* through autoInit).
+  const columns: DataColumn<T>[] = (fromJson(options.columns) ?? []).map((column) => ({ ...column }));
+  let rows: T[] = [...(fromJson(options.rows) ?? [])];
+  const hidden = new Set(columns.filter((column) => column.hidden).map((column) => column.key));
+  let sort: DataSort | null = options.sort ?? null;
+  let query = '';
+  let filter: FilterGroup = options.filter ? cloneFilter(options.filter) : emptyFilter();
+  let pageSize = Number.isFinite(options.pageSize) ? Math.max(0, Math.floor(options.pageSize!)) : 10;
+  const pageSizes = options.pageSizes ?? [10, 25, 50];
+  let page = 0;
+  let selection = new Set<RowId>();
+  let anchor: RowId | null = null;
+  let loading = Boolean(options.loading);
+  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);
+  };
+
+  // ── Rows and values ──────────────────────────────────────────────────────
+  const generated = new WeakMap<object, string>();
+  let made = 0;
+  const idOf = (row: T): RowId => {
+    if (typeof options.rowKey === 'function') return options.rowKey(row);
+    const id = row[options.rowKey ?? 'id'];
+    if (typeof id === 'string' || typeof id === 'number') return id;
+    let given = generated.get(row);
+    if (!given) generated.set(row, (given = `${uid}-row-${++made}`));
+    return given;
+  };
+  const visibleColumns = () => columns.filter((column) => !hidden.has(column.key));
+  const valueOf = (row: T, column: DataColumn<T>) => (column.value ? column.value(row) : row[column.key]);
+  let number: Intl.NumberFormat;
+  try {
+    number = new Intl.NumberFormat(locale);
+  } catch {
+    number = new Intl.NumberFormat();
+  }
+  const dateFormat = safeFormat(locale, { day: 'numeric', month: 'short', year: 'numeric' });
+  const textOf = (row: T, column: DataColumn<T>): string => {
+    const value = valueOf(row, column);
+    if (column.format) return column.format(value, row);
+    if (value === null || value === undefined || value === '') return '';
+    switch (column.type) {
+      case 'number':
+        return typeof value === 'number' ? number.format(value) : String(value);
+      case 'date': {
+        const date = toTime(value as string | number | Date);
+        return date ? dateFormat.format(date) : String(value);
+      }
+      case 'boolean':
+        return value ? 'Sí' : 'No';
+      case 'select':
+        return column.options?.find((option) => option.value === String(value))?.label ?? String(value);
+      default:
+        return String(value);
+    }
+  };
+  let collator: Intl.Collator;
+  try {
+    collator = new Intl.Collator(locale, { numeric: true, sensitivity: 'base' });
+  } catch {
+    collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+  }
+  const compare = (a: unknown, b: unknown, column: DataColumn<T>) => {
+    const empty = (value: unknown) => value === null || value === undefined || value === '';
+    // Empty cells go last whichever way.
+    if (empty(a) || empty(b)) return empty(a) === empty(b) ? 0 : empty(a) ? 1 : -1;
+    if (column.type === 'number') return Number(a) - Number(b);
+    if (column.type === 'date') return (toTime(a as string)?.getTime() ?? 0) - (toTime(b as string)?.getTime() ?? 0);
+    if (column.type === 'boolean') return Number(Boolean(a)) - Number(Boolean(b));
+    return collator.compare(String(a), String(b));
+  };
+  const fields = (): FilterField[] =>
+    columns
+      .filter((column) => column.filterable !== false)
+      .map((column) => ({ key: column.key, label: column.label, type: column.type ?? 'text', options: column.options }));
+  const results = (): T[] => {
+    const needle = foldText(query.trim());
+    const known = fields();
+    const filtering = hasConditions(filter, known);
+    let list = rows.filter((row) => {
+      if (filtering) {
+        const record: Record<string, unknown> = {};
+        for (const column of columns) record[column.key] = valueOf(row, column);
+        if (!matchesFilter(record, filter, known)) return false;
+      }
+      return !needle || visibleColumns().some((column) => column.searchable !== false && foldText(textOf(row, column)).includes(needle));
+    });
+    const column = sort ? columns.find((each) => each.key === sort!.key) : undefined;
+    if (sort && column) {
+      const direction = sort.direction === 'asc' ? 1 : -1;
+      const empty = (value: unknown) => value === null || value === undefined || value === '';
+      list = [...list].sort((a, b) => {
+        const va = valueOf(a, column);
+        const vb = valueOf(b, column);
+        // Empty cells stay at the end in both directions.
+        if (empty(va) || empty(vb)) return compare(va, vb, column);
+        return compare(va, vb, column) * direction;
+      });
+    }
+    return list;
+  };
+  let shown: T[] = [];
+  const pageCount = (count: number) => (pageSize ? Math.max(1, Math.ceil(count / pageSize)) : 1);
+
+  // ── The parts ────────────────────────────────────────────────────────────
+  const el = <K extends keyof HTMLElementTagNameMap>(tag: K, data?: string, text?: string) => {
+    const element = document.createElement(tag);
+    if (data) element.setAttribute(data, '');
+    if (text !== undefined) element.textContent = text;
+    return element;
+  };
+  const toolButton = (data: string, label: string, icon: string, text?: string) => {
+    const button = el('button', data);
+    button.type = 'button';
+    button.dataset.mkDtTool = '';
+    button.innerHTML = icon;
+    if (text) {
+      const span = el('span', undefined, text);
+      button.append(span);
+    } else button.setAttribute('aria-label', label);
+    return button;
+  };
+
+  const bar = el('div', 'data-mk-dt-bar');
+  let searchInput: HTMLInputElement | null = null;
+  if (options.search !== false) {
+    const field = el('label', 'data-mk-dt-search');
+    field.insertAdjacentHTML('beforeend', ICONS.search);
+    searchInput = el('input');
+    searchInput.type = 'search';
+    searchInput.placeholder = typeof options.search === 'string' ? options.search : 'Buscar…';
+    searchInput.setAttribute('aria-label', 'Buscar en la tabla');
+    field.append(searchInput);
+    bar.append(field);
+  }
+  const tools = el('div', 'data-mk-dt-tools');
+  const filtersButton = options.filters !== false && fields().length ? toolButton('data-mk-dt-filters', 'Filtros', ICONS.filter, 'Filtros') : null;
+  const filterCount = el('span', 'data-mk-dt-count');
+  filterCount.hidden = true;
+  filtersButton?.append(filterCount);
+  const columnsButton = options.columnsMenu !== false && columns.some((column) => column.hideable !== false) ? toolButton('data-mk-dt-columns', 'Columnas', ICONS.columns, 'Columnas') : null;
+  for (const button of [filtersButton, columnsButton]) if (button) tools.append(button);
+  bar.append(tools);
+
+  const active = el('div', 'data-mk-dt-active');
+  active.hidden = true;
+  const activeText = el('span');
+  const clearButton = el('button', 'data-mk-dt-clear');
+  clearButton.type = 'button';
+  clearButton.innerHTML = ICONS.close;
+  clearButton.append(el('span', undefined, 'Quitar filtros'));
+  active.append(activeText, clearButton);
+
+  const scroll = el('div', 'data-mk-dt-scroll');
+  const table = el('table', 'data-mk-dt-table');
+  table.id = `${uid}-table`;
+  const caption = el('caption', undefined, options.caption ?? 'Tabla');
+  caption.className = 'mk-sr-only';
+  const head = el('thead');
+  const headRow = el('tr');
+  head.append(headRow);
+  const body = el('tbody');
+  table.append(caption, head, body);
+  scroll.append(table);
+  // A region the keyboard can scroll when the table is wider than it.
+  scroll.setAttribute('role', 'region');
+  scroll.setAttribute('aria-label', `${options.caption ?? 'Tabla'} (desplazable)`);
+  scroll.tabIndex = 0;
+  const emptyHost = el('div', 'data-mk-dt-empty');
+  emptyHost.className = 'mk-empty-state';
+  emptyHost.hidden = true;
+
+  const foot = el('div', 'data-mk-dt-foot');
+  const range = el('span', 'data-mk-dt-range');
+  const sizeField = el('label', 'data-mk-dt-size');
+  sizeField.append(el('span', undefined, 'Filas'));
+  const sizeSelect = el('select');
+  for (const size of pageSizes) {
+    const option = el('option', undefined, String(size));
+    option.value = String(size);
+    sizeSelect.append(option);
+  }
+  if (!pageSizes.includes(pageSize) && pageSize) {
+    const option = el('option', undefined, String(pageSize));
+    option.value = String(pageSize);
+    sizeSelect.prepend(option);
+  }
+  sizeSelect.value = String(pageSize);
+  sizeField.append(sizeSelect);
+  const pager = el('nav', 'data-mk-dt-pager');
+  pager.setAttribute('aria-label', 'Páginas');
+  const previous = el('button', 'data-mk-dt-previous');
+  previous.type = 'button';
+  previous.innerHTML = ICONS.previous;
+  previous.setAttribute('aria-label', 'Página anterior');
+  const pageLabel = el('span', 'data-mk-dt-page');
+  const next = el('button', 'data-mk-dt-next');
+  next.type = 'button';
+  next.innerHTML = ICONS.next;
+  next.setAttribute('aria-label', 'Página siguiente');
+  pager.append(previous, pageLabel, next);
+  foot.append(range, sizeField, pager);
+
+  const bulk = el('div', 'data-mk-dt-bulk');
+  bulk.setAttribute('role', 'toolbar');
+  bulk.setAttribute('aria-label', 'Acciones de la selección');
+  bulk.hidden = true;
+  const bulkCount = el('span', 'data-mk-dt-bulk-count');
+  const bulkText = el('span');
+  const bulkAll = el('button', 'data-mk-dt-select-all');
+  bulkAll.type = 'button';
+  bulkAll.hidden = true;
+  const bulkActions = el('div', 'data-mk-dt-bulk-actions');
+  for (const action of options.bulkActions ?? []) {
+    const button = el('button', undefined, action.label);
+    button.type = 'button';
+    button.dataset.action = action.id;
+    if (action.danger) button.dataset.danger = '';
+    bulkActions.append(button);
+  }
+  const bulkClose = el('button', 'data-mk-dt-bulk-close');
+  bulkClose.type = 'button';
+  bulkClose.innerHTML = ICONS.close;
+  bulkClose.setAttribute('aria-label', 'Quitar la selección');
+  const bulkLabel = el('span', 'data-mk-dt-bulk-label');
+  bulkLabel.append(bulkCount, bulkText);
+  bulk.append(bulkLabel, bulkAll, bulkActions, bulkClose);
+
+  const status = el('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(bar, active, scroll, emptyHost, foot, bulk, status);
+  scope.attr(root, 'data-mk-ready', '');
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    for (const part of [bar, active, scroll, emptyHost, foot, bulk, status]) part.remove();
+  });
+
+  // ── Checkboxes that draw themselves ──────────────────────────────────────
+  const checkbox = (label: string) => {
+    const box = el('span', 'data-mk-dt-check');
+    const input = el('input');
+    input.type = 'checkbox';
+    input.setAttribute('aria-label', label);
+    box.append(input);
+    box.insertAdjacentHTML('beforeend', CHECK);
+    return { box, input };
+  };
+  const paintCheck = (box: HTMLElement, state: 'true' | 'false' | 'mixed', animate: boolean) => {
+    const input = box.querySelector('input')!;
+    const before = box.dataset.state;
+    box.dataset.state = state;
+    input.checked = state === 'true';
+    input.indeterminate = state === 'mixed';
+    if (!animate || before === state || state === 'false' || reduced()) return;
+    keep(gsap.fromTo(box, { scale: 0.8 }, { scale: 1, duration: 0.35, ease: EASE.click, clearProps: 'transform' }));
+    const path = box.querySelector<SVGPathElement>(state === 'true' ? '[data-mk-dt-tick]' : '[data-mk-dt-dash]');
+    if (path) keep(gsap.fromTo(path, { strokeDasharray: state === 'true' ? 1 : 12, strokeDashoffset: state === 'true' ? 1 : 12 }, { strokeDashoffset: 0, duration: 0.3, ease: EASE.wipe, clearProps: 'strokeDasharray,strokeDashoffset' }));
+  };
+
+  // ── The header ───────────────────────────────────────────────────────────
+  let headCheck: HTMLElement | null = null;
+  const buildHead = () => {
+    headRow.replaceChildren();
+    headCheck = null;
+    if (options.selectable) {
+      const th = el('th', 'data-mk-dt-select');
+      th.scope = 'col';
+      const { box } = checkbox('Seleccionar la página');
+      headCheck = box;
+      th.append(box);
+      headRow.append(th);
+    }
+    for (const column of visibleColumns()) {
+      const th = el('th');
+      th.scope = 'col';
+      th.dataset.key = column.key;
+      th.dataset.align = column.align ?? (column.type === 'number' ? 'end' : 'start');
+      if (column.width) th.style.width = column.width;
+      if (column.sortable !== false) {
+        const button = el('button', 'data-mk-dt-sort');
+        button.type = 'button';
+        button.append(el('span', undefined, column.label));
+        button.insertAdjacentHTML('beforeend', ICONS.arrow);
+        th.append(button);
+      } else th.textContent = column.label;
+      headRow.append(th);
+    }
+    if (options.actions?.length) {
+      const th = el('th', 'data-mk-dt-actions');
+      th.scope = 'col';
+      th.append(Object.assign(el('span', undefined, 'Acciones'), { className: 'mk-sr-only' }));
+      headRow.append(th);
+    }
+    paintHead();
+  };
+  const paintHead = () => {
+    for (const th of headRow.querySelectorAll<HTMLElement>('th[data-key]')) {
+      const key = th.dataset.key!;
+      const on = sort?.key === key;
+      if (th.querySelector('[data-mk-dt-sort]')) th.setAttribute('aria-sort', on ? (sort!.direction === 'asc' ? 'ascending' : 'descending') : 'none');
+      th.dataset.direction = on ? sort!.direction : '';
+    }
+  };
+
+  // ── The rows ─────────────────────────────────────────────────────────────
+  const rowOf = (id: RowId) => [...body.rows].find((tr) => tr.dataset.id === String(id)) ?? null;
+  const fillCell = (cell: HTMLTableCellElement, row: T, column: DataColumn<T>) => {
+    cell.replaceChildren();
+    if (column.render) column.render(valueOf(row, column), row, cell);
+    else if (column.type === 'boolean') {
+      const pill = el('span', 'data-mk-dt-bool', textOf(row, column));
+      pill.dataset.value = String(Boolean(valueOf(row, column)));
+      cell.append(pill);
+    } else cell.append(markText(textOf(row, column), column.searchable === false ? '' : query));
+  };
+  const rowElement = (row: T, index: number) => {
+    const id = idOf(row);
+    const tr = el('tr');
+    tr.dataset.id = String(id);
+    tr.dataset.flipId = String(id);
+    const chosen = selection.has(id);
+    tr.toggleAttribute('data-selected', chosen);
+    const first = visibleColumns()[0];
+    const name = first ? textOf(row, first) : `fila ${index + 1}`;
+    if (options.selectable) {
+      const td = el('td', 'data-mk-dt-select');
+      const { box } = checkbox(`Seleccionar ${name}`);
+      paintCheck(box, chosen ? 'true' : 'false', false);
+      td.append(box);
+      tr.append(td);
+    }
+    for (const column of visibleColumns()) {
+      const td = el('td');
+      td.dataset.key = column.key;
+      td.dataset.align = column.align ?? (column.type === 'number' ? 'end' : 'start');
+      fillCell(td, row, column);
+      tr.append(td);
+    }
+    if (options.actions?.length) {
+      const td = el('td', 'data-mk-dt-actions');
+      const button = el('button', 'data-mk-dt-row-menu');
+      button.type = 'button';
+      button.innerHTML = ICONS.more;
+      button.setAttribute('aria-label', `Acciones de ${name}`);
+      button.setAttribute('aria-haspopup', 'menu');
+      td.append(button);
+      tr.append(td);
+    }
+    return tr;
+  };
+  const bones = () => {
+    const count = pageSize || 6;
+    const width = visibleColumns().length + (options.selectable ? 1 : 0) + (options.actions?.length ? 1 : 0);
+    return Array.from({ length: Math.min(count, 12) }, (_, r) => {
+      const tr = el('tr', 'data-mk-dt-loading');
+      for (let c = 0; c < width; c++) {
+        const td = el('td');
+        const bone = el('span', 'data-mk-dt-bone');
+        bone.style.width = `${45 + ((r * 7 + c * 13) % 45)}%`;
+        td.append(bone);
+        tr.append(td);
+      }
+      return tr;
+    });
+  };
+
+  let empty: ReturnType<typeof createEmptyState> | null = null;
+  const paintEmpty = (count: number) => {
+    const none = !loading && !count;
+    emptyHost.hidden = !none;
+    table.toggleAttribute('data-mk-dt-empty-table', none);
+    if (!none) return;
+    const searching = rows.length > 0;
+    const next = {
+      illustration: searching ? ('search' as const) : ('inbox' as const),
+      title: searching ? 'Sin resultados' : (options.emptyTitle ?? 'Sin datos todavía'),
+      description: searching ? 'Prueba con otra búsqueda o quita los filtros.' : (options.emptyDescription ?? 'Cuando haya filas, aparecerán aquí.'),
+      actions: searching ? [{ id: 'clear', label: 'Limpiar búsqueda y filtros' }] : [],
+    };
+    if (empty) empty.update(next);
+    else empty = createEmptyState(emptyHost, { ...next, onAction: (id) => id === 'clear' && clearAll() });
+  };
+  scope.add(() => empty?.destroy());
+  scope.on(emptyHost, 'mk:action', (event) => event.stopPropagation());
+
+  const paintFoot = (count: number) => {
+    const pages = pageCount(count);
+    page = Math.min(page, pages - 1);
+    const from = count ? page * (pageSize || count) + 1 : 0;
+    const to = pageSize ? Math.min(count, (page + 1) * pageSize) : count;
+    const text = count ? `${number.format(from)}–${number.format(to)} de ${number.format(count)}` : '0 resultados';
+    if (range.textContent !== text) range.textContent = text;
+    pageLabel.textContent = `${number.format(page + 1)} / ${number.format(pages)}`;
+    previous.disabled = page === 0;
+    next.disabled = page >= pages - 1;
+    pager.hidden = !pageSize || pages <= 1;
+    sizeField.hidden = !pageSize;
+  };
+
+  const paintSelection = (animate: boolean) => {
+    for (const tr of body.rows) {
+      const id = tr.dataset.id;
+      if (id === undefined || tr.hasAttribute('data-mk-dt-loading')) continue;
+      const row = shown.find((each) => String(idOf(each)) === id);
+      const chosen = row ? selection.has(idOf(row)) : false;
+      tr.toggleAttribute('data-selected', chosen);
+      const box = tr.querySelector<HTMLElement>('[data-mk-dt-check]');
+      if (box) paintCheck(box, chosen ? 'true' : 'false', animate);
+    }
+    if (headCheck) {
+      const onPage = shown.map(idOf);
+      const count = onPage.filter((id) => selection.has(id)).length;
+      paintCheck(headCheck, count && count === onPage.length ? 'true' : count ? 'mixed' : 'false', animate);
+    }
+    paintBulk(animate);
+  };
+
+  let bulkShown = false;
+  const paintBulk = (animate: boolean) => {
+    const count = selection.size;
+    const show = count > 0;
+    const text = String(count);
+    if (show) {
+      const same = bulkCount.textContent === text;
+      if (!same && bulkShown && animate && !reduced()) keep(rollDigits(bulkCount, text, Number(text) > Number(bulkCount.textContent || 0) ? 1 : -1, 0.3));
+      else bulkCount.textContent = text;
+      bulkText.textContent = count === 1 ? ' seleccionada' : ' seleccionadas';
+      // The whole page chosen and more beyond it: offer them all.
+      const total = results().length;
+      const pageIds = shown.map(idOf);
+      const pageFull = pageIds.length > 0 && pageIds.every((id) => selection.has(id));
+      bulkAll.hidden = !(pageFull && total > count);
+      bulkAll.textContent = `Seleccionar las ${number.format(total)}`;
+    }
+    if (show === bulkShown) return;
+    bulkShown = show;
+    gsap.killTweensOf(bulk);
+    if (show) {
+      bulk.hidden = false;
+      if (animate && !reduced()) keep(gsap.fromTo(bulk, { opacity: 0, y: 16, filter: 'blur(8px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.35, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+    } else if (animate && !reduced()) {
+      keep(gsap.to(bulk, { opacity: 0, y: 16, filter: 'blur(6px)', duration: 0.22, ease: 'power2.in', onComplete: () => {
+        bulk.hidden = true;
+        gsap.set(bulk, { clearProps: 'opacity,transform,filter' });
+      } }));
+    } else bulk.hidden = true;
+  };
+
+  /** Draw the page; `motion`: how the rows change (glide, slide from a side, or nothing). */
+  const render = (motion: 'reflow' | 'forward' | 'back' | 'none' = 'none') => {
+    const all = loading ? [] : results();
+    const pages = pageCount(all.length);
+    page = Math.max(0, Math.min(page, pages - 1));
+    shown = loading ? [] : pageSize ? all.slice(page * pageSize, (page + 1) * pageSize) : all;
+    const before = motion === 'reflow' && !reduced() ? [...body.rows].filter((tr) => !tr.hasAttribute('data-mk-dt-loading')) : [];
+    const state = before.length && before.length <= 80 ? Flip.getState(before) : null;
+    const wasLoading = body.querySelector('[data-mk-dt-loading]') !== null;
+    body.replaceChildren(...(loading ? bones() : shown.map(rowElement)));
+    table.setAttribute('aria-busy', String(loading));
+    paintEmpty(all.length);
+    paintFoot(all.length);
+    paintSelection(false);
+    const fresh = [...body.rows];
+    if (!reduced() && !loading && fresh.length) {
+      if (state) {
+        keep(
+          Flip.from(state, {
+            targets: fresh,
+            duration: TIMING.layoutTravel,
+            ease: EASE.layoutReflow,
+            onEnter: (entering) => gsap.fromTo(entering, { opacity: 0 }, { opacity: 1, duration: 0.3, delay: 0.1, ease: 'power1.out', clearProps: 'opacity' }),
+          }),
+        );
+      } else if (motion === 'forward' || motion === 'back') {
+        keep(gsap.fromTo(fresh, { opacity: 0, x: motion === 'forward' ? 24 : -24 }, { opacity: 1, x: 0, duration: 0.32, stagger: 0.015, ease: 'power2.out', clearProps: 'opacity,transform' }));
+      } else if (wasLoading) keep(gsap.fromTo(fresh, { opacity: 0, y: 6 }, { opacity: 1, y: 0, duration: 0.35, stagger: 0.025, ease: 'power2.out', clearProps: 'opacity,transform' }));
+    }
+    options.onRender?.(body);
+  };
+
+  // ── Changes ──────────────────────────────────────────────────────────────
+  const notifySelection = () => {
+    const ids = [...selection];
+    const chosen = rows.filter((row) => selection.has(idOf(row)));
+    options.onSelectionChange?.(ids, chosen);
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { ids, rows: chosen } }));
+  };
+  const setSelection = (ids: Iterable<RowId>, notify = true) => {
+    const next = new Set(ids);
+    const same = next.size === selection.size && [...next].every((id) => selection.has(id));
+    selection = next;
+    paintSelection(true);
+    if (!same) {
+      status.textContent = selection.size ? plural(selection.size, 'fila seleccionada', 'filas seleccionadas') : 'Sin selección';
+      if (notify) notifySelection();
+    }
+  };
+  const announceResults = () => {
+    const count = results().length;
+    status.textContent = plural(count, 'resultado', 'resultados');
+  };
+  const filtersChanged = (notify = true) => {
+    page = 0;
+    const known = fields();
+    const conditions = hasConditions(filter, known);
+    const sentence = conditions ? describeFilter(filter, known) : '';
+    const wasHidden = active.hidden;
+    active.hidden = !conditions;
+    activeText.textContent = sentence;
+    if (conditions && wasHidden && !reduced()) keep(gsap.fromTo(active, { opacity: 0, y: -6, filter: 'blur(6px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.3, ease: 'power2.out', clearProps: 'opacity,transform,filter' }));
+    const ruleCount = countRules(filter, known);
+    filterCount.hidden = !ruleCount;
+    if (ruleCount && filterCount.textContent !== String(ruleCount) && !reduced()) keep(gsap.fromTo(filterCount, { scale: 0.5 }, { scale: 1, duration: 0.35, ease: EASE.pop, clearProps: 'transform' }));
+    filterCount.textContent = String(ruleCount);
+    render('reflow');
+    if (!notify) return;
+    announceResults();
+    options.onFilterChange?.(cloneFilter(filter), query);
+    root.dispatchEvent(new CustomEvent('mk:filter', { bubbles: true, detail: { filter: cloneFilter(filter), query } }));
+  };
+  const countRules = (group: FilterGroup, known: FilterField[]): number =>
+    group.rules.reduce((sum, node) => sum + ('rules' in node ? countRules(node as FilterGroup, known) : hasConditions({ id: 'x', combinator: 'and', rules: [node] }, known) ? 1 : 0), 0);
+  const clearAll = () => {
+    query = '';
+    if (searchInput) searchInput.value = '';
+    filter = emptyFilter();
+    builder?.setValue(filter);
+    filtersChanged();
+  };
+
+  const sortBy = (key: string | null, direction?: SortDirection) => {
+    const column = key ? columns.find((each) => each.key === key) : undefined;
+    sort = column ? { key: column.key, direction: direction ?? 'asc' } : null;
+    paintHead();
+    render('reflow');
+    status.textContent = sort ? `Ordenado por ${column!.label}, ${sort.direction === 'asc' ? 'ascendente' : 'descendente'}` : 'Sin orden';
+    options.onSortChange?.(sort ? { ...sort } : null);
+    root.dispatchEvent(new CustomEvent('mk:sort', { bubbles: true, detail: { sort: sort ? { ...sort } : null } }));
+  };
+  const setPage = (next: number) => {
+    const pages = pageCount(results().length);
+    const target = Math.max(0, Math.min(pages - 1, next));
+    if (target === page) return;
+    const forward = target > page;
+    page = target;
+    render(forward ? 'forward' : 'back');
+    status.textContent = `Página ${page + 1} de ${pages}`;
+    options.onPageChange?.(page);
+    root.dispatchEvent(new CustomEvent('mk:page', { bubbles: true, detail: { page } }));
+  };
+
+  // ── Pointer and keyboard ─────────────────────────────────────────────────
+  scope.on(head, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-dt-sort]');
+    if (!button) return;
+    const key = button.closest<HTMLElement>('th')!.dataset.key!;
+    // Ascending, descending, then no order.
+    if (sort?.key !== key) sortBy(key, 'asc');
+    else if (sort.direction === 'asc') sortBy(key, 'desc');
+    else sortBy(null);
+  });
+  scope.on(head, 'change', (event) => {
+    if (!(event.target as Element).closest('[data-mk-dt-check]')) return;
+    const ids = shown.map(idOf);
+    const all = ids.every((id) => selection.has(id));
+    setSelection(all ? [...selection].filter((id) => !ids.includes(id)) : [...selection, ...ids]);
+  });
+  scope.on(body, 'click', (event) => {
+    const target = event.target as Element | null;
+    const input = target?.closest('[data-mk-dt-check] input');
+    if (input) {
+      const tr = input.closest<HTMLElement>('tr')!;
+      const row = shown.find((each) => String(idOf(each)) === tr.dataset.id);
+      if (!row) return;
+      const id = idOf(row);
+      const mouse = event as MouseEvent;
+      if (mouse.shiftKey && anchor !== null) {
+        const order = shown.map(idOf);
+        const a = order.indexOf(anchor);
+        const b = order.indexOf(id);
+        if (a >= 0 && b >= 0) {
+          const span = order.slice(Math.min(a, b), Math.max(a, b) + 1);
+          const on = !selection.has(id);
+          const next = new Set(selection);
+          for (const each of span) {
+            if (on) next.add(each);
+            else next.delete(each);
+          }
+          anchor = id;
+          return setSelection(next);
+        }
+      }
+      anchor = id;
+      const next = new Set(selection);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      setSelection(next);
+      return;
+    }
+    const menuButton = target?.closest<HTMLElement>('[data-mk-dt-row-menu]');
+    if (menuButton) openRowMenu(menuButton);
+  });
+  // Changes of the boxes are handled on click (it knows about Shift); keep the box in step.
+  scope.on(body, 'change', (event) => {
+    const box = (event.target as Element).closest<HTMLElement>('[data-mk-dt-check]');
+    if (box) paintSelection(false);
+  });
+  if (searchInput) {
+    const input = searchInput;
+    scope.on(input, 'input', () => {
+      query = input.value;
+      filtersChanged();
+    });
+  }
+  scope.on(previous, 'click', () => {
+    keep(press(previous));
+    setPage(page - 1);
+  });
+  scope.on(next, 'click', () => {
+    keep(press(next));
+    setPage(page + 1);
+  });
+  scope.on(sizeSelect, 'change', () => {
+    pageSize = Number(sizeSelect.value) || 0;
+    page = 0;
+    render('reflow');
+  });
+  scope.on(clearButton, 'click', clearAll);
+  scope.on(bulkClose, 'click', () => setSelection([]));
+  scope.on(bulkAll, 'click', () => setSelection(results().map(idOf)));
+  scope.on(bulkActions, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLElement>('[data-action]');
+    if (!button) return;
+    keep(press(button));
+    const chosen = rows.filter((row) => selection.has(idOf(row)));
+    options.onBulkAction?.(button.dataset.action!, chosen);
+    root.dispatchEvent(new CustomEvent('mk:bulk-action', { bubbles: true, detail: { action: button.dataset.action, rows: chosen } }));
+  });
+
+  // ── Panels: row menu, columns, filters ───────────────────────────────────
+  const panelDialog = (name: string, label: string) => {
+    const dialog = el('dialog');
+    dialog.className = 'mk-dialog mk-dt-panel';
+    dialog.dataset.mkDtPanel = name;
+    dialog.setAttribute('aria-label', label);
+    root.append(dialog);
+    scope.add(() => dialog.remove());
+    return dialog;
+  };
+
+  let rowMenu: ReturnType<typeof createMenu> | null = null;
+  let menuRow: T | null = null;
+  if (options.actions?.length) {
+    const dialog = panelDialog('menu', 'Acciones de la fila');
+    dialog.className = 'mk-dialog mk-menu mk-dt-menu';
+    for (const action of options.actions) {
+      const item = el('button', 'data-mk-item', action.label);
+      item.type = 'button';
+      item.dataset.mkValue = action.id;
+      if (action.danger) item.dataset.danger = '';
+      dialog.append(item);
+    }
+    rowMenu = createMenu(dialog, {
+      triggers: false,
+      onClose: () => {
+        for (const button of body.querySelectorAll('[data-mk-dt-row-menu][aria-expanded="true"]')) button.setAttribute('aria-expanded', 'false');
+      },
+      onSelect: (value) => {
+        const row = menuRow;
+        if (!row) return;
+        options.onAction?.(value, row);
+        root.dispatchEvent(new CustomEvent('mk:action', { bubbles: true, detail: { action: value, row } }));
+      },
+    });
+    // The menu's own events stay inside: listeners on the table hear the table's.
+    scope.on(dialog, 'mk:select', (event) => event.stopPropagation());
+    scope.add(() => rowMenu?.destroy());
+  }
+  const openRowMenu = (button: HTMLElement) => {
+    const tr = button.closest<HTMLElement>('tr');
+    menuRow = shown.find((each) => String(idOf(each)) === tr?.dataset.id) ?? null;
+    if (!menuRow || !rowMenu) return;
+    button.setAttribute('aria-expanded', 'true');
+    rowMenu.open(button);
+  };
+
+  let columnsPanel: ReturnType<typeof createDialog> | null = null;
+  if (columnsButton) {
+    const dialog = panelDialog('columns', 'Columnas');
+    const title = el('p', 'data-mk-dt-panel-title', 'Columnas visibles');
+    const list = el('div', 'data-mk-dt-column-list');
+    dialog.append(title, list);
+    const fill = () => {
+      list.replaceChildren(
+        ...columns
+          .filter((column) => column.hideable !== false)
+          .map((column) => {
+            const label = el('label', 'data-mk-dt-column');
+            const { box, input } = checkbox(column.label);
+            paintCheck(box, hidden.has(column.key) ? 'false' : 'true', false);
+            input.dataset.key = column.key;
+            label.append(box, el('span', undefined, column.label));
+            return label;
+          }),
+      );
+    };
+    columnsPanel = createDialog(dialog, {
+      placement: 'anchor',
+      backdrop: false,
+      drag: false,
+      autoResize: false,
+      triggers: false,
+      animateContent: false,
+      onOpen: () => {
+        fill();
+        keep(flowInMenu([title, ...list.children]));
+        list.querySelector<HTMLInputElement>('input')?.focus({ preventScroll: true });
+      },
+    });
+    scope.add(() => columnsPanel?.destroy());
+    scope.on(list, 'change', (event) => {
+      const input = event.target as HTMLInputElement;
+      const key = input.dataset.key;
+      if (!key) return;
+      // At least one column stays.
+      if (!input.checked && visibleColumns().length <= 1) {
+        input.checked = true;
+        return;
+      }
+      paintCheck(input.closest<HTMLElement>('[data-mk-dt-check]')!, input.checked ? 'true' : 'false', true);
+      setColumnVisible(key, input.checked);
+    });
+    scope.on(columnsButton, 'click', () => {
+      keep(press(columnsButton));
+      columnsPanel?.open(columnsButton);
+    });
+  }
+
+  let filtersPanel: ReturnType<typeof createDialog> | null = null;
+  let builder: ReturnType<typeof createFilterBuilder> | null = null;
+  if (filtersButton) {
+    const dialog = panelDialog('filters', 'Filtros');
+    dialog.classList.add('mk-dt-filters');
+    const holder = el('div', 'data-mk-dt-builder');
+    holder.className = 'mk-filter-builder';
+    dialog.append(holder);
+    builder = createFilterBuilder(holder, {
+      fields: fields(),
+      value: filter,
+      onChange: (next) => {
+        filter = next;
+        filtersChanged();
+      },
+    });
+    // The builder's own events stay inside the panel.
+    scope.on(dialog, 'mk:change', (event) => event.stopPropagation());
+    filtersPanel = createDialog(dialog, {
+      placement: 'anchor',
+      backdrop: false,
+      drag: false,
+      autoResize: false,
+      triggers: false,
+      animateContent: false,
+      onOpen: () => keep(flowInMenu([...holder.children])),
+    });
+    scope.add(() => {
+      builder?.destroy();
+      filtersPanel?.destroy();
+    });
+    scope.on(filtersButton, 'click', () => {
+      keep(press(filtersButton));
+      filtersPanel?.open(filtersButton);
+    });
+  }
+
+  const setColumnVisible = (key: string, visible: boolean) => {
+    if (!columns.some((column) => column.key === key) || hidden.has(key) === !visible) return;
+    if (visible) hidden.delete(key);
+    else hidden.add(key);
+    buildHead();
+    render();
+    // The column that comes in fades in; the table settles out of a light blur.
+    if (!reduced()) {
+      const cells = [...table.querySelectorAll<HTMLElement>('[data-key]')].filter((cell) => cell.dataset.key === key);
+      if (visible && cells.length) keep(gsap.fromTo(cells, { opacity: 0, y: -4 }, { opacity: 1, y: 0, duration: 0.3, stagger: 0.01, ease: 'power2.out', clearProps: 'opacity,transform' }));
+      else keep(gsap.fromTo(table, { opacity: 0.6, filter: 'blur(2px)' }, { opacity: 1, filter: 'blur(0px)', duration: 0.3, ease: 'power1.out', clearProps: 'opacity,filter' }));
+    }
+    const column = columns.find((each) => each.key === key)!;
+    status.textContent = `Columna ${column.label} ${visible ? 'visible' : 'oculta'}`;
+  };
+
+  buildHead();
+  filtersChanged(false);
+
+  return {
+    setRows(next) {
+      if (scope.disposed) return;
+      rows = [...next];
+      const ids = new Set(rows.map(idOf));
+      const kept = [...selection].filter((id) => ids.has(id));
+      const lost = kept.length !== selection.size;
+      selection = new Set(kept);
+      loading = false;
+      render('reflow');
+      if (lost) notifySelection();
+    },
+    updateRow(id, patch) {
+      const index = rows.findIndex((row) => idOf(row) === id);
+      if (index < 0) return;
+      rows[index] = { ...rows[index]!, ...patch };
+      render();
+    },
+    removeRows(ids) {
+      const gone = new Set(ids);
+      const leaving = [...body.rows].filter((tr) => [...gone].some((id) => String(id) === tr.dataset.id));
+      const apply = () => {
+        rows = rows.filter((row) => !gone.has(idOf(row)));
+        const had = selection.size;
+        selection = new Set([...selection].filter((id) => !gone.has(id)));
+        render('reflow');
+        if (had !== selection.size) notifySelection();
+        status.textContent = plural(ids.length, 'fila eliminada', 'filas eliminadas');
+      };
+      if (!leaving.length || reduced()) return apply();
+      keep(gsap.to(leaving, { opacity: 0, x: -24, duration: 0.22, ease: 'power2.in', onComplete: apply }));
+    },
+    setLoading(next) {
+      if (loading === next) return;
+      loading = next;
+      render();
+    },
+    sortBy,
+    setPage,
+    setPageSize(size) {
+      pageSize = Math.max(0, Math.floor(size));
+      sizeSelect.value = String(pageSize);
+      page = 0;
+      render('reflow');
+    },
+    setQuery(next) {
+      query = next;
+      if (searchInput) searchInput.value = next;
+      filtersChanged();
+    },
+    setFilter(next) {
+      filter = cloneFilter(next);
+      builder?.setValue(filter);
+      filtersChanged();
+    },
+    setColumnVisible,
+    select: (ids) => setSelection(ids, false),
+    rowOf: (id) => rowOf(id) as HTMLTableRowElement | null,
+    cellOf: (id, key) => [...(rowOf(id)?.cells ?? [])].find((cell) => cell.dataset.key === key) ?? null,
+    refresh: () => render(),
+    idOf,
+    get rows() {
+      return [...rows];
+    },
+    get results() {
+      return results();
+    },
+    get page() {
+      return page;
+    },
+    get pageCount() {
+      return pageCount(results().length);
+    },
+    get selection() {
+      return [...selection];
+    },
+    get sort() {
+      return sort ? { ...sort } : null;
+    },
+    get query() {
+      return query;
+    },
+    get filter() {
+      return cloneFilter(filter);
+    },
+    get columns() {
+      return columns.map((column) => ({ ...column, hidden: hidden.has(column.key) }));
+    },
+    body,
+    destroy: () => scope.dispose(),
+  };
+}