@yewdiel21/motion-kit 0.10.0 → 0.14.0

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

@@ -0,0 +1,775 @@
+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 { fromJson } from '../../core/dates';
+import { toTime } from '../../core/relative-time';
+import { press, rollDigits, shake } from '../../motion/micro';
+import { createDataTable, type DataColumn, type DataRow, type DataTableInstance, type DataTableOptions, type RowId } from '../data-table/engine';
+
+/*
+ * Editable table: data-table with cells that edit in place. A ring glides from
+ * cell to cell with the arrows (.22 s, swing); Enter, F2 or simply typing
+ * opens the cell's editor (text, number, date, a choice or a check) with a
+ * small pop; Enter keeps it and goes down, Tab goes to the side, Escape lets
+ * it be. A value that does not pass shakes and says why. Changed cells keep a
+ * dot that pops in and a soft tint; a bar with the count (rolling) folds open
+ * above the table with Descartar and Guardar (Ctrl/⌘+S). Saving waits on
+ * onSave(): the button spins, then the saved cells flash and their marks fade,
+ * or the bar shakes and the changes stay. New rows come in at the top with
+ * their first cell open.
+ */
+
+export type EditorKind = 'text' | 'number' | 'date' | 'select' | 'checkbox';
+
+export interface EditableColumn<T extends DataRow = DataRow> extends DataColumn<T> {
+  /** Can be edited (default true). */
+  editable?: boolean;
+  /** The editor (default: from the column's type). */
+  editor?: EditorKind;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  /** An error message, or nothing when the value is fine. */
+  validate?: (value: unknown, row: T) => string | null | undefined | void;
+}
+
+export interface RowChange<T extends DataRow = DataRow> {
+  id: RowId;
+  /** The row as it is now (as it was, for a removed one). */
+  row: T;
+  /** The values that changed (all of them for a new row). */
+  changes: Partial<T>;
+  isNew?: boolean;
+  removed?: boolean;
+}
+
+export interface EditableTableOptions<T extends DataRow = DataRow> extends Omit<DataTableOptions<T>, 'columns'> {
+  columns?: EditableColumn<T>[];
+  /** Keep the changes: resolve when they are saved; reject (or throw) to keep them pending. */
+  onSave?: (changes: RowChange<T>[], rows: T[]) => Promise<void> | void;
+  /** After every edit. */
+  onChange?: (changes: RowChange<T>[]) => void;
+  /** A new row's values: shows "Agregar fila". */
+  newRow?: () => Partial<T>;
+}
+
+export interface EditableTableInstance<T extends DataRow = DataRow> extends Instance {
+  /** Open a cell's editor. */
+  edit(id: RowId, key: string): void;
+  setValue(id: RowId, key: string, value: unknown): boolean;
+  addRow(values?: Partial<T>): RowId;
+  removeRows(ids: RowId[]): void;
+  save(): Promise<boolean>;
+  discard(): void;
+  setRows(rows: T[]): void;
+  readonly changes: RowChange<T>[];
+  readonly dirty: boolean;
+  readonly rows: T[];
+  readonly table: DataTableInstance<T>;
+}
+
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+let sequence = 0;
+
+const sameValue = (a: unknown, b: unknown) => (a === b || ((a === null || a === undefined || a === '') && (b === null || b === undefined || b === '')));
+
+export function createEditableTable<T extends DataRow = DataRow>(root: HTMLElement | null, options: EditableTableOptions<T> = {}): EditableTableInstance<T> {
+  if (!root) {
+    return inert({
+      edit() {}, setValue: () => false, addRow: () => '', removeRows() {}, save: () => Promise.resolve(false), discard() {}, setRows() {},
+      changes: [], dirty: false, rows: [], table: null as unknown as DataTableInstance<T>,
+    });
+  }
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-et-${++sequence}`;
+  const columns: EditableColumn<T>[] = (fromJson(options.columns) ?? []).map((column) => ({ ...column }));
+  const rowKey = options.rowKey ?? 'id';
+  const idOf = (row: T): RowId => (typeof rowKey === 'function' ? rowKey(row) : (row[rowKey] as RowId));
+  /** The rows as last saved. */
+  let base: T[] = [...(fromJson(options.rows) ?? [])];
+  const edits = new Map<RowId, Partial<T>>();
+  let added: T[] = [];
+  const removed = new Map<RowId, T>();
+  const errors = new Map<string, string>();
+  let made = 0;
+  let active: { id: RowId; key: string } | null = null;
+  let editing: { id: RowId; key: string; editor: HTMLElement; cell: HTMLTableCellElement; done: (save: boolean, move?: 'down' | 'right' | 'left' | null) => boolean } | null = null;
+  let saving = false;
+  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);
+  };
+
+  const isEditable = (column: EditableColumn<T> | undefined) => Boolean(column && column.editable !== false && !column.render);
+  const columnOf = (key: string) => columns.find((column) => column.key === key);
+  const kindOf = (column: EditableColumn<T>): EditorKind =>
+    column.editor ?? (column.type === 'number' ? 'number' : column.type === 'date' ? 'date' : column.type === 'select' ? 'select' : column.type === 'boolean' ? 'checkbox' : 'text');
+  const cellKey = (id: RowId, key: string) => `${id}\u0000${key}`;
+  const merged = (row: T): T => {
+    const patch = edits.get(idOf(row));
+    return patch ? { ...row, ...patch } : row;
+  };
+  const display = () => [...added.map(merged), ...base.filter((row) => !removed.has(idOf(row))).map(merged)];
+  const originalOf = (id: RowId) => base.find((row) => idOf(row) === id) ?? null;
+  const isNew = (id: RowId) => added.some((row) => idOf(row) === id);
+
+  const changes = (): RowChange<T>[] => {
+    const list: RowChange<T>[] = [];
+    for (const row of added) list.push({ id: idOf(row), row: merged(row), changes: { ...merged(row) }, isNew: true });
+    for (const row of base) {
+      const id = idOf(row);
+      if (removed.has(id)) {
+        list.push({ id, row, changes: {}, removed: true });
+        continue;
+      }
+      const patch = edits.get(id);
+      if (patch && Object.keys(patch).length) list.push({ id, row: merged(row), changes: { ...patch } });
+    }
+    return list;
+  };
+  const dirtyCount = () => changes().reduce((sum, change) => sum + (change.isNew || change.removed ? 1 : Object.keys(change.changes).length), 0);
+
+  // ── The table underneath ─────────────────────────────────────────────────
+  const userRender = options.onRender;
+  // The table draws once while it is made, before the cells can be decorated: that first time is done below.
+  let ready = false;
+  const table = createDataTable<T>(root, {
+    ...options,
+    columns,
+    rows: display(),
+    rowKey,
+    onRender: (body) => {
+      if (ready) decorate(body);
+      userRender?.(body);
+    },
+  });
+  scope.add(() => table.destroy());
+  const tableElement = table.body.closest('table')!;
+  const scroll = root.querySelector<HTMLElement>('[data-mk-dt-scroll]')!;
+  scope.attr(tableElement, 'role', 'grid');
+  scope.attr(root, 'data-mk-editable', '');
+
+  // The ring that glides between cells.
+  const ring = document.createElement('span');
+  ring.dataset.mkEtRing = '';
+  ring.setAttribute('aria-hidden', 'true');
+  scroll.append(ring);
+
+  // The bar of pending changes, folded until there are some.
+  const bar = document.createElement('div');
+  bar.dataset.mkEtSave = '';
+  bar.hidden = true;
+  const barText = document.createElement('span');
+  barText.dataset.mkEtSaveText = '';
+  const barCount = document.createElement('span');
+  barCount.dataset.mkEtSaveCount = '';
+  const barLabel = document.createElement('span');
+  barText.append(barCount, barLabel);
+  const barError = document.createElement('span');
+  barError.dataset.mkEtError = '';
+  barError.setAttribute('role', 'alert');
+  const discardButton = document.createElement('button');
+  discardButton.type = 'button';
+  discardButton.dataset.mkEtDiscard = '';
+  discardButton.textContent = 'Descartar';
+  const saveButton = document.createElement('button');
+  saveButton.type = 'button';
+  saveButton.dataset.mkEtSaveButton = '';
+  saveButton.textContent = 'Guardar';
+  bar.append(barText, barError, discardButton, saveButton);
+  scroll.before(bar);
+  let addButton: HTMLButtonElement | null = null;
+  if (options.newRow) {
+    addButton = document.createElement('button');
+    addButton.type = 'button';
+    addButton.dataset.mkDtTool = '';
+    addButton.dataset.mkEtAdd = '';
+    addButton.innerHTML = '<svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>';
+    addButton.append(Object.assign(document.createElement('span'), { textContent: 'Agregar fila' }));
+    root.querySelector('[data-mk-dt-tools]')?.prepend(addButton);
+  }
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(status);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    ring.remove();
+    bar.remove();
+    addButton?.remove();
+    status.remove();
+  });
+
+  // ── Cells ────────────────────────────────────────────────────────────────
+  const dataCells = (body: HTMLTableSectionElement = table.body) => [...body.querySelectorAll<HTMLTableCellElement>('td[data-key]')];
+  const cellOf = (id: RowId, key: string) => table.cellOf(id, key);
+  const positionOf = (cell: HTMLTableCellElement) => {
+    const tr = cell.parentElement as HTMLTableRowElement;
+    const rows = [...table.body.rows].filter((row) => row.dataset.id !== undefined);
+    const cells = [...tr.cells].filter((each) => each.dataset.key !== undefined);
+    return { row: rows.indexOf(tr), column: cells.indexOf(cell), rows, cells };
+  };
+  const idFromCell = (cell: HTMLTableCellElement): RowId | null => {
+    const raw = (cell.parentElement as HTMLElement).dataset.id;
+    if (raw === undefined) return null;
+    const row = table.rows.find((each) => String(idOf(each)) === raw);
+    return row ? idOf(row) : null;
+  };
+
+  let restoreFocus = false;
+  /** Every time the rows are drawn: roles, the roving cell, marks of changes and errors. */
+  const decorate = (body: HTMLTableSectionElement) => {
+    for (const tr of body.rows) if (tr.dataset.id !== undefined) tr.setAttribute('aria-rowindex', String(tr.sectionRowIndex + 2));
+    const cells = dataCells(body);
+    for (const cell of cells) {
+      const column = columnOf(cell.dataset.key!);
+      const id = idFromCell(cell);
+      cell.tabIndex = -1;
+      cell.toggleAttribute('data-mk-et-editable', isEditable(column));
+      if (isEditable(column)) cell.setAttribute('aria-readonly', 'false');
+      else cell.setAttribute('aria-readonly', 'true');
+      if (id === null || !column) continue;
+      const original = originalOf(id);
+      const current = table.rows.find((row) => idOf(row) === id);
+      const dirty = isNew(id) || Boolean(original && current && !sameValue(original[column.key], current[column.key]));
+      cell.toggleAttribute('data-mk-et-dirty', dirty);
+      const error = errors.get(cellKey(id, column.key));
+      cell.toggleAttribute('data-mk-et-invalid', Boolean(error));
+      if (error) cell.title = error;
+      else cell.removeAttribute('title');
+    }
+    for (const tr of body.rows) tr.toggleAttribute('data-mk-et-new', tr.dataset.id !== undefined && added.some((row) => String(idOf(row)) === tr.dataset.id));
+    // The roving cell: the active one if it is on this page, else the first.
+    let target = active ? (cellOf(active.id, active.key) ?? null) : null;
+    if (!target) {
+      target = cells[0] ?? null;
+      if (target) {
+        const id = idFromCell(target);
+        active = id === null ? null : { id, key: target.dataset.key! };
+      }
+    }
+    if (target) target.tabIndex = 0;
+    if (restoreFocus && target) {
+      restoreFocus = false;
+      target.focus({ preventScroll: true });
+    }
+    placeRing(false);
+  };
+
+  const placeRing = (animate: boolean) => {
+    const cell = active ? cellOf(active.id, active.key) : null;
+    const focused = cell && (document.activeElement === cell || cell.contains(document.activeElement));
+    if (!cell || !focused) {
+      ring.style.opacity = '0';
+      return;
+    }
+    // While rows glide (a transform on the row), the row becomes the cell's offset parent: measure through it.
+    const row = cell.parentElement as HTMLElement;
+    const inRow = cell.offsetParent === row;
+    const target = {
+      x: (inRow ? row.offsetLeft : 0) + cell.offsetLeft + tableElement.offsetLeft,
+      y: (inRow ? row.offsetTop : 0) + cell.offsetTop + tableElement.offsetTop,
+      width: cell.offsetWidth,
+      height: cell.offsetHeight,
+    };
+    const shown = ring.style.opacity === '1';
+    ring.style.opacity = '1';
+    if (!animate || !shown || reduced()) {
+      gsap.killTweensOf(ring);
+      gsap.set(ring, target);
+      return;
+    }
+    keep(gsap.to(ring, { ...target, duration: 0.22, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+
+  const focusCell = (cell: HTMLTableCellElement | null | undefined, animate = true) => {
+    if (!cell) return;
+    const id = idFromCell(cell);
+    if (id === null) return;
+    for (const each of dataCells()) each.tabIndex = each === cell ? 0 : -1;
+    active = { id, key: cell.dataset.key! };
+    cell.focus({ preventScroll: true });
+    cell.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    placeRing(animate);
+  };
+
+  // ── Values ───────────────────────────────────────────────────────────────
+  const parse = (column: EditableColumn<T>, raw: unknown): unknown => {
+    const kind = kindOf(column);
+    if (kind === 'checkbox') return Boolean(raw);
+    if (typeof raw !== 'string') return raw;
+    const text = raw.trim();
+    if (kind === 'number') {
+      if (!text) return null;
+      // "1250,5" and "1,250.50" both mean what they say.
+      const normal = text.includes(',') && !text.includes('.') ? text.replace(',', '.') : text.replace(/,/g, '');
+      const value = Number(normal);
+      return Number.isFinite(value) ? value : NaN;
+    }
+    return text;
+  };
+  const problemWith = (column: EditableColumn<T>, value: unknown, row: T): string | null => {
+    const empty = value === null || value === undefined || value === '';
+    if (column.required && empty) return `${column.label}: escribe un valor`;
+    if (kindOf(column) === 'number' && typeof value === 'number' && Number.isNaN(value)) return `${column.label}: escribe un número`;
+    if (typeof value === 'number' && column.min !== undefined && value < column.min) return `${column.label}: el mínimo es ${column.min}`;
+    if (typeof value === 'number' && column.max !== undefined && value > column.max) return `${column.label}: el máximo es ${column.max}`;
+    if (kindOf(column) === 'date' && !empty && !toTime(value as string)) return `${column.label}: la fecha no es válida`;
+    const custom = column.validate?.(value, row);
+    return custom ? String(custom) : null;
+  };
+
+  const report = () => {
+    const list = changes();
+    options.onChange?.(list);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { changes: list } }));
+  };
+
+  /** A cell's new value comes in out of a light blur (no movement: it is a table cell). */
+  const fadeCell = (cell: HTMLElement) => keep(gsap.fromTo(cell, { opacity: 0.4, filter: 'blur(4px)' }, { opacity: 1, filter: 'blur(0px)', duration: 0.3, ease: 'power1.out', clearProps: 'opacity,filter' }));
+  /** Why a value cannot go in a cell (null when it can). */
+  const check = (id: RowId, key: string, raw: unknown): string | null => {
+    const column = columnOf(key);
+    const current = table.rows.find((row) => idOf(row) === id);
+    if (!column || !current) return 'Esa celda no existe';
+    const value = parse(column, raw);
+    return problemWith(column, value, { ...current, [key]: value } as T);
+  };
+  /** Put a value in a cell; false (and a reason) when it does not pass. */
+  const setValue = (id: RowId, key: string, raw: unknown, animate = true): boolean => {
+    const column = columnOf(key);
+    const current = table.rows.find((row) => idOf(row) === id);
+    if (!column || !current) return false;
+    const value = parse(column, raw);
+    const problem = problemWith(column, value, { ...current, [key]: value } as T);
+    if (problem) {
+      errors.set(cellKey(id, key), problem);
+      barError.textContent = problem;
+      paintBar(animate);
+      return false;
+    }
+    errors.delete(cellKey(id, key));
+    barError.textContent = [...errors.values()][0] ?? '';
+    const original = originalOf(id);
+    const patch = { ...(edits.get(id) ?? {}) } as Partial<T>;
+    if (original && sameValue(original[key], value)) delete patch[key as keyof T];
+    else (patch as Record<string, unknown>)[key] = value;
+    if (Object.keys(patch).length) edits.set(id, patch);
+    else edits.delete(id);
+    const wasDirty = cellOf(id, key)?.hasAttribute('data-mk-et-dirty') ?? false;
+    // Redrawn rows are new elements: the focus comes back to the active cell.
+    const focused = document.activeElement;
+    restoreFocus = Boolean(focused && table.body.contains(focused));
+    table.setRows(display());
+    const cell = cellOf(id, key);
+    if (cell && animate && !reduced()) {
+      fadeCell(cell);
+      if (!wasDirty && cell.hasAttribute('data-mk-et-dirty')) cell.setAttribute('data-mk-et-pop', '');
+    }
+    paintBar(animate);
+    report();
+    return true;
+  };
+
+  // ── Editing ──────────────────────────────────────────────────────────────
+  const startEdit = (cell: HTMLTableCellElement, typed?: string) => {
+    if (saving) return;
+    const column = columnOf(cell.dataset.key!);
+    const id = idFromCell(cell);
+    if (!isEditable(column) || id === null) {
+      if (column && !isEditable(column)) keep(shake(cell, 3));
+      return;
+    }
+    finishEdit(true);
+    const row = table.rows.find((each) => idOf(each) === id)!;
+    const value = row[column!.key];
+    const kind = kindOf(column!);
+    // A check flips at once: no editor.
+    if (kind === 'checkbox') {
+      setValue(id, column!.key, !value);
+      return;
+    }
+    let editor: HTMLInputElement | HTMLSelectElement;
+    if (kind === 'select') {
+      const select = document.createElement('select');
+      for (const option of column!.options ?? []) {
+        const element = document.createElement('option');
+        element.value = option.value;
+        element.textContent = option.label;
+        select.append(element);
+      }
+      select.value = String(value ?? '');
+      editor = select;
+    } else {
+      const input = document.createElement('input');
+      input.type = kind === 'number' ? 'text' : kind === 'date' ? 'date' : 'text';
+      if (kind === 'number') input.inputMode = 'decimal';
+      const date = kind === 'date' ? toTime(value as string) : null;
+      input.value = typed ?? (date ? `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}` : value === null || value === undefined ? '' : String(value));
+      editor = input;
+    }
+    editor.dataset.mkEtEditor = '';
+    editor.setAttribute('aria-label', `${column!.label}, editar`);
+    const previous = [...cell.childNodes];
+    cell.replaceChildren(editor);
+    cell.setAttribute('data-mk-et-editing', '');
+    editor.focus();
+    if (editor instanceof HTMLInputElement && editor.type === 'text') {
+      if (typed === undefined) editor.select();
+      else editor.setSelectionRange(editor.value.length, editor.value.length);
+    }
+    if (!reduced()) keep(gsap.fromTo(editor, { scale: 0.96, opacity: 0.4 }, { scale: 1, opacity: 1, duration: 0.25, ease: EASE.pop, clearProps: 'transform,opacity' }));
+    const done = (save: boolean, move: 'down' | 'right' | 'left' | null = null) => {
+      if (!editing || editing.editor !== editor) return true;
+      if (save) {
+        const problem = check(id, column!.key, editor.value);
+        if (problem) {
+          errors.set(cellKey(id, column!.key), problem);
+          barError.textContent = problem;
+          paintBar(true);
+          editor.setAttribute('aria-invalid', 'true');
+          keep(shake(editor));
+          status.textContent = problem;
+          return false;
+        }
+      }
+      // Done before the table redraws (the editor goes with the old cell).
+      editing = null;
+      if (save) setValue(id, column!.key, editor.value);
+      else {
+        cell.replaceChildren(...previous);
+        cell.removeAttribute('data-mk-et-editing');
+        errors.delete(cellKey(id, column!.key));
+        barError.textContent = [...errors.values()][0] ?? '';
+        paintBar(true);
+      }
+      // After a save the table drew the row again: find the cell anew, then move.
+      restoreFocus = false;
+      const fresh = cellOf(id, column!.key);
+      if (fresh) focusCell(fresh, false);
+      if (move) moveFrom(fresh ?? cell, move);
+      return true;
+    };
+    editing = { id, key: column!.key, editor, cell, done };
+    editor.addEventListener('keydown', (event) => {
+      const key = event as KeyboardEvent;
+      key.stopPropagation();
+      if (key.key === 'Enter') {
+        key.preventDefault();
+        done(true, 'down');
+      } else if (key.key === 'Escape') {
+        key.preventDefault();
+        done(false);
+      } else if (key.key === 'Tab') {
+        key.preventDefault();
+        done(true, key.shiftKey ? 'left' : 'right');
+      }
+    });
+    editor.addEventListener('input', () => editor.removeAttribute('aria-invalid'));
+    // Leaving the editor keeps a good value and drops a wrong one.
+    editor.addEventListener('blur', () => {
+      if (!done(true)) done(false);
+    });
+  };
+  const finishEdit = (save: boolean) => editing?.done(save);
+
+  const moveFrom = (cell: HTMLTableCellElement, move: 'down' | 'right' | 'left' | 'up') => {
+    const { row, column, rows, cells } = positionOf(cell);
+    if (move === 'right' || move === 'left') {
+      const step = move === 'right' ? 1 : -1;
+      const next = cells[column + step];
+      if (next) return focusCell(next);
+      // Past the end of a row: the next row's first cell (or the previous row's last).
+      const otherRow = rows[row + step];
+      const otherCells = otherRow ? [...otherRow.cells].filter((each) => each.dataset.key !== undefined) : [];
+      return focusCell(move === 'right' ? otherCells[0] : otherCells[otherCells.length - 1]);
+    }
+    const otherRow = rows[row + (move === 'down' ? 1 : -1)];
+    if (otherRow) focusCell([...otherRow.cells].filter((each) => each.dataset.key !== undefined)[column]);
+  };
+
+  // ── The bar ──────────────────────────────────────────────────────────────
+  let barShown = false;
+  const paintBar = (animate: boolean) => {
+    const count = dirtyCount();
+    const show = count > 0 || errors.size > 0;
+    const text = String(count);
+    if (barCount.textContent !== text) {
+      if (barShown && animate && !reduced() && barCount.textContent) keep(rollDigits(barCount, text, count > Number(barCount.textContent) ? 1 : -1, 0.3));
+      else barCount.textContent = text;
+    }
+    barLabel.textContent = count === 1 ? ' cambio sin guardar' : ' cambios sin guardar';
+    saveButton.disabled = errors.size > 0 || !count || saving;
+    discardButton.disabled = saving;
+    barError.hidden = !barError.textContent;
+    if (show === barShown) return;
+    barShown = show;
+    gsap.killTweensOf(bar);
+    if (show) {
+      bar.hidden = false;
+      if (animate && !reduced()) keep(gsap.fromTo(bar, { height: 0, opacity: 0, filter: 'blur(6px)', overflow: 'hidden' }, { height: 'auto', opacity: 1, filter: 'blur(0px)', duration: 0.3, ease: EASE.signature, clearProps: 'height,opacity,filter,overflow' }));
+    } else if (animate && !reduced()) {
+      keep(gsap.to(bar, { height: 0, opacity: 0, overflow: 'hidden', duration: 0.24, ease: 'power2.in', onComplete: () => {
+        bar.hidden = true;
+        gsap.set(bar, { clearProps: 'height,opacity,overflow' });
+      } }));
+    } else bar.hidden = true;
+  };
+
+  const save = async (): Promise<boolean> => {
+    finishEdit(true);
+    if (saving || errors.size || !dirtyCount()) return false;
+    saving = true;
+    const list = changes();
+    const rows = display();
+    saveButton.setAttribute('aria-busy', 'true');
+    saveButton.textContent = 'Guardando…';
+    paintBar(true);
+    keep(press(saveButton));
+    try {
+      await options.onSave?.(list, rows);
+    } catch {
+      if (scope.disposed) return false;
+      saving = false;
+      saveButton.removeAttribute('aria-busy');
+      saveButton.textContent = 'Guardar';
+      barError.textContent = 'No se pudo guardar: los cambios siguen aquí';
+      paintBar(true);
+      keep(shake(bar));
+      status.textContent = barError.textContent;
+      return false;
+    }
+    if (scope.disposed) return true;
+    // What was saved is the new starting point.
+    const flashed = dataCells().filter((cell) => cell.hasAttribute('data-mk-et-dirty'));
+    base = rows.map((row) => ({ ...row }));
+    added = [];
+    edits.clear();
+    removed.clear();
+    saving = false;
+    saveButton.removeAttribute('aria-busy');
+    saveButton.textContent = 'Guardar';
+    barError.textContent = '';
+    status.textContent = plural(list.length, 'fila guardada', 'filas guardadas');
+    const ids = flashed.map((cell) => `${(cell.parentElement as HTMLElement).dataset.id}\u0000${cell.dataset.key}`);
+    table.setRows(display());
+    if (!reduced()) {
+      for (const cell of dataCells()) {
+        if (ids.includes(`${(cell.parentElement as HTMLElement).dataset.id}\u0000${cell.dataset.key}`)) cell.setAttribute('data-mk-et-saved', '');
+      }
+      scope.timeout(() => dataCells().forEach((cell) => cell.removeAttribute('data-mk-et-saved')), 1400);
+    }
+    paintBar(true);
+    report();
+    root.dispatchEvent(new CustomEvent('mk:save', { bubbles: true, detail: { changes: list } }));
+    return true;
+  };
+
+  const discard = () => {
+    finishEdit(false);
+    if (!dirtyCount() && !errors.size) return;
+    const touched = dataCells().filter((cell) => cell.hasAttribute('data-mk-et-dirty')).map((cell) => `${(cell.parentElement as HTMLElement).dataset.id}\u0000${cell.dataset.key}`);
+    edits.clear();
+    added = [];
+    removed.clear();
+    errors.clear();
+    barError.textContent = '';
+    table.setRows(display());
+    if (!reduced()) for (const cell of dataCells()) if (touched.includes(`${(cell.parentElement as HTMLElement).dataset.id}\u0000${cell.dataset.key}`)) fadeCell(cell);
+    status.textContent = 'Cambios descartados';
+    paintBar(true);
+    report();
+  };
+
+  const addRow = (values?: Partial<T>): RowId => {
+    finishEdit(true);
+    const fresh = { ...(options.newRow?.() ?? {}), ...(values ?? {}) } as T;
+    const key = typeof rowKey === 'string' ? rowKey : 'id';
+    let id = idOf(fresh);
+    if (id === undefined || id === null || id === '') {
+      id = `${uid}-new-${++made}`;
+      (fresh as Record<string, unknown>)[key] = id;
+    }
+    added = [fresh, ...added];
+    table.sortBy(null);
+    table.setQuery('');
+    table.setPage(0);
+    table.setRows(display());
+    const tr = table.rowOf(id);
+    if (tr && !reduced()) keep(gsap.fromTo(tr, { opacity: 0, y: -12 }, { opacity: 1, y: 0, duration: 0.35, ease: 'power2.out', clearProps: 'opacity,transform' }));
+    paintBar(true);
+    report();
+    status.textContent = 'Fila nueva';
+    const first = columns.find(isEditable);
+    const cell = first ? cellOf(id, first.key) : null;
+    if (cell) {
+      focusCell(cell, false);
+      startEdit(cell);
+    }
+    return id;
+  };
+
+  // ── Pointer and keyboard ─────────────────────────────────────────────────
+  scope.on(table.body, 'click', (event) => {
+    const cell = (event.target as Element | null)?.closest<HTMLTableCellElement>('td[data-key]');
+    if (!cell || cell.hasAttribute('data-mk-et-editing')) return;
+    focusCell(cell);
+  });
+  scope.on(table.body, 'dblclick', (event) => {
+    const cell = (event.target as Element | null)?.closest<HTMLTableCellElement>('td[data-key]');
+    if (cell && !cell.hasAttribute('data-mk-et-editing')) startEdit(cell);
+  });
+  scope.on(table.body, 'focusin', (event) => {
+    const cell = (event.target as Element | null)?.closest<HTMLTableCellElement>('td[data-key]');
+    if (!cell) return;
+    const id = idFromCell(cell);
+    if (id !== null) active = { id, key: cell.dataset.key! };
+    placeRing(true);
+  });
+  scope.on(table.body, 'focusout', () => {
+    scope.timeout(() => {
+      if (!table.body.contains(document.activeElement)) ring.style.opacity = '0';
+    }, 0);
+  });
+  scope.on(table.body, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const cell = (key.target as Element | null)?.closest<HTMLTableCellElement>('td[data-key]');
+    if (!cell || cell !== key.target) return;
+    const command = key.ctrlKey || key.metaKey;
+    const { rows, cells } = positionOf(cell);
+    switch (key.key) {
+      case 'ArrowRight':
+        key.preventDefault();
+        return focusCell(cells[cells.indexOf(cell) + 1]);
+      case 'ArrowLeft':
+        key.preventDefault();
+        return focusCell(cells[cells.indexOf(cell) - 1]);
+      case 'ArrowDown':
+        key.preventDefault();
+        return moveFrom(cell, 'down');
+      case 'ArrowUp':
+        key.preventDefault();
+        return moveFrom(cell, 'up');
+      case 'Home': {
+        key.preventDefault();
+        const row = command ? rows[0] : (cell.parentElement as HTMLTableRowElement);
+        return focusCell(row ? [...row.cells].find((each) => each.dataset.key !== undefined) : undefined);
+      }
+      case 'End': {
+        key.preventDefault();
+        const row = command ? rows[rows.length - 1] : (cell.parentElement as HTMLTableRowElement);
+        const all = row ? [...row.cells].filter((each) => each.dataset.key !== undefined) : [];
+        return focusCell(all[all.length - 1]);
+      }
+      case 'Enter':
+      case 'F2':
+        key.preventDefault();
+        return startEdit(cell);
+      case 'Delete':
+      case 'Backspace': {
+        key.preventDefault();
+        const column = columnOf(cell.dataset.key!);
+        const id = idFromCell(cell);
+        if (id === null || !isEditable(column)) return;
+        if (kindOf(column!) === 'checkbox') return;
+        if (!setValue(id, column!.key, '')) {
+          keep(shake(cell, 3));
+          status.textContent = barError.textContent ?? '';
+        }
+        return;
+      }
+      case ' ': {
+        const column = columnOf(cell.dataset.key!);
+        if (column && kindOf(column) === 'checkbox') {
+          key.preventDefault();
+          startEdit(cell);
+        }
+        return;
+      }
+    }
+    // Typing starts the editor with what was typed.
+    if (!command && !key.altKey && key.key.length === 1) {
+      const column = columnOf(cell.dataset.key!);
+      if (column && isEditable(column) && ['text', 'number'].includes(kindOf(column))) {
+        key.preventDefault();
+        startEdit(cell, key.key);
+      }
+    }
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    if ((key.ctrlKey || key.metaKey) && key.key.toLowerCase() === 's') {
+      key.preventDefault();
+      void save();
+    }
+  });
+  scope.on(saveButton, 'click', () => void save());
+  scope.on(discardButton, 'click', discard);
+  if (addButton) {
+    const button = addButton;
+    scope.on(button, 'click', () => {
+      keep(press(button));
+      addRow();
+    });
+  }
+
+  ready = true;
+  decorate(table.body);
+
+  return {
+    edit(id, key) {
+      const cell = cellOf(id, key);
+      if (!cell) return;
+      focusCell(cell, false);
+      startEdit(cell);
+    },
+    setValue: (id, key, value) => setValue(id, key, value),
+    addRow,
+    removeRows(ids) {
+      finishEdit(false);
+      for (const id of ids) {
+        if (isNew(id)) added = added.filter((row) => idOf(row) !== id);
+        else {
+          const row = originalOf(id);
+          if (row) removed.set(id, row);
+        }
+        edits.delete(id);
+        for (const key of [...errors.keys()]) if (key.startsWith(`${id}\u0000`)) errors.delete(key);
+      }
+      table.removeRows(ids);
+      paintBar(true);
+      report();
+    },
+    save,
+    discard,
+    setRows(rows) {
+      if (scope.disposed) return;
+      finishEdit(false);
+      base = [...rows];
+      edits.clear();
+      added = [];
+      removed.clear();
+      errors.clear();
+      barError.textContent = '';
+      table.setRows(display());
+      paintBar(false);
+    },
+    get changes() {
+      return changes();
+    },
+    get dirty() {
+      return dirtyCount() > 0;
+    },
+    get rows() {
+      return display();
+    },
+    table,
+    destroy: () => scope.dispose(),
+  };
+}