@lnsy/data-table 0.1.0

package/src/table-component.js

@@ -0,0 +1,1031 @@
+/**
+ * <data-table> — a dependency-free tabular data component.
+ *
+ * This is not just a spreadsheet: one component, three presentation modes,
+ * all backed by the same engine.
+ *
+ *   mode="spreadsheet"  Full grid. Formulas (=SUM(A1:A5)), endpoint calls
+ *                       (=HTTP(…), =ENDPOINT(…)), wikilinks, copy/paste.
+ *   mode="table"        Searchable, sortable table. First row is the header.
+ *   mode="list"         Searchable single-column list with wikilink support.
+ *
+ * Attributes:
+ *   mode                spreadsheet | table | list   (default: spreadsheet)
+ *   read-only           disable editing
+ *   rows / cols         initial grid size (spreadsheet mode)
+ *   wikilink-base-url   prefix for [[wikilink]] hrefs; without it, clicks
+ *                       dispatch a bubbling `wikilink-navigate` event.
+ *
+ * Events:
+ *   change              any cell edited  { detail: { row, col, value } }
+ *   selection-change    active cell moved { detail: { row, col } }
+ *   wikilink-navigate   a [[link]] was clicked { detail: { target } }
+ */
+
+import { FormulaEngine, indexToCol, displayValue } from './formula.js';
+import { renderCellValue } from './wikilinks.js';
+
+class DataTable extends HTMLElement {
+  static get observedAttributes() {
+    return ['mode', 'read-only', 'rows', 'cols', 'wikilink-base-url'];
+  }
+
+  connectedCallback() {
+    if (!this._initialized) {
+      this._initialized = true;
+      this._data = this._data || [];
+      this._engine = new FormulaEngine(() => this._data);
+      // Bind global-ish listeners exactly once; _build() may run many times.
+      this._bindClipboard();
+      this._bindResizeHandles();
+      this._build();
+    }
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (!this._initialized) return;
+    if (['mode', 'read-only'].includes(name)) {
+      this._build();
+    } else if (name === 'wikilink-base-url') {
+      this._applyWikilinkBase();
+    }
+  }
+
+  // ── Configuration ────────────────────────────────────────────
+
+  get mode() {
+    return this.getAttribute('mode') || 'spreadsheet';
+  }
+
+  get readOnly() {
+    return this.hasAttribute('read-only');
+  }
+
+  /** Register named endpoints usable via =ENDPOINT("name"). */
+  setEndpoints(endpoints) {
+    this._engine.setEndpoints(endpoints);
+    this.recalculate();
+  }
+
+  setData(data) {
+    const norm = (v) => (v === null || v === undefined ? '' : String(v));
+    this._data = Array.isArray(data)
+      ? data.map((row) => (Array.isArray(row) ? row.map(norm) : [norm(row)]))
+      : [];
+    this._build();
+  }
+
+  getData() {
+    return this._data.map((row) => [...row]);
+  }
+
+  /** Computed (formula-evaluated) value of a cell, formatted for display. */
+  getComputedValue(row, col) {
+    const key = `${row}:${col}`;
+    if (this._engine.values.has(key)) {
+      return displayValue(this._engine.values.get(key));
+    }
+    const raw = this._engine.getRaw(row, col);
+    return raw === '' ? '' : String(raw);
+  }
+
+  setCellValue(row, col, value) {
+    this._ensureSize(row + 1, col + 1);
+    this._data[row][col] = value;
+    this.recalculate();
+    this._updateCellDisplay(row, col);
+    this.emitChange(row, col, value);
+  }
+
+  async recalculate() {
+    await this._engine.recalcAll();
+    if (this.mode === 'spreadsheet') {
+      this._refreshAllCells();
+    } else if (this.mode === 'table') {
+      this._renderTableView();
+    } else if (this.mode === 'list') {
+      this._renderListView();
+    }
+  }
+
+  emitChange(row, col, value) {
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { row, col, value },
+    }));
+  }
+
+  // ── DOM construction ─────────────────────────────────────────
+
+  _build() {
+    this.innerHTML = '';
+    this.classList.toggle('read-only', this.readOnly);
+    this.setAttribute('tabindex', '0');
+
+    this._applyWikilinkBase();
+    this._selection = null;       // { anchor:{r,c}, focus:{r,c} }
+    this._editing = null;
+    this._sortColumn = null;
+    this._sortDirection = 'asc';
+
+    switch (this.mode) {
+      case 'table': this._buildTableMode(); break;
+      case 'list': this._buildListMode(); break;
+      default: this._buildSpreadsheetMode();
+    }
+
+    this.recalculate();
+  }
+
+  _applyWikilinkBase() {
+    const base = this.getAttribute('wikilink-base-url') || '';
+    if (base) {
+      this.dataset.wikilinkBase = base;
+    } else {
+      delete this.dataset.wikilinkBase;
+    }
+  }
+
+  _ensureSize(rows, cols) {
+    while (this._data.length < rows) {
+      this._data.push([]);
+    }
+    for (const row of this._data) {
+      while (row.length < cols) row.push('');
+    }
+  }
+
+  // ── Spreadsheet mode ─────────────────────────────────────────
+
+  _buildSpreadsheetMode() {
+    const rows = Math.max(parseInt(this.getAttribute('rows'), 10) || 50, 1);
+    const cols = Math.max(parseInt(this.getAttribute('cols'), 10) || 12, 1);
+    this._ensureSize(rows, cols);
+
+    const root = document.createElement('div');
+    root.className = 'dt-root dt-spreadsheet';
+
+    // Formula bar
+    const bar = document.createElement('div');
+    bar.className = 'dt-formula-bar';
+    const refLabel = document.createElement('span');
+    refLabel.className = 'dt-cell-ref';
+    const formulaInput = document.createElement('input');
+    formulaInput.className = 'dt-formula-input';
+    formulaInput.type = 'text';
+    formulaInput.spellcheck = false;
+    formulaInput.placeholder = 'Enter a value or =FORMULA()';
+    bar.append(refLabel, formulaInput);
+    this._refLabel = refLabel;
+    this._formulaInput = formulaInput;
+
+    formulaInput.addEventListener('keydown', (e) => {
+      // Keep formula-bar keystrokes out of the grid's keyboard handlers.
+      e.stopPropagation();
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        this._commitFormulaBar();
+        this._grid.focus({ preventScroll: true });
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        // Restore the bar from the cell regardless of focus, so the blur
+        // handler cannot commit the reverted text.
+        const { r, c } = this._selection.anchor;
+        this._formulaInput.value = String(this._engine.getRaw(r, c) ?? '');
+        this._grid.focus({ preventScroll: true });
+      }
+    });
+    formulaInput.addEventListener('blur', () => this._commitFormulaBar());
+
+    // Grid
+    this._grid = document.createElement('div');
+    this._grid.className = 'dt-grid-scroll';
+    this._grid.tabIndex = -1; // focusable so keyboard nav works after click
+    const table = this._renderGridTable();
+    this._grid.appendChild(table);
+
+    // Footer controls
+    const footer = document.createElement('div');
+    footer.className = 'dt-footer';
+    const addRowBtn = document.createElement('button');
+    addRowBtn.type = 'button';
+    addRowBtn.textContent = '+ Row';
+    addRowBtn.addEventListener('click', () => this.insertRow());
+    const status = document.createElement('span');
+    status.className = 'dt-status';
+    this._statusEl = status;
+    footer.append(addRowBtn, status);
+
+    root.append(bar, this._grid, footer);
+    this.appendChild(root);
+    this._applyGridMetrics();
+
+    this._selectCell(0, 0);
+  }
+
+  _renderGridTable() {
+    const table = document.createElement('table');
+    table.className = 'dt-grid';
+
+    const colgroup = document.createElement('colgroup');
+    colgroup.className = 'dt-cols';
+    colgroup.appendChild(document.createElement('col'));
+    for (let c = 0; c < this._colCount(); c++) {
+      colgroup.appendChild(document.createElement('col'));
+    }
+    table.appendChild(colgroup);
+
+    const thead = document.createElement('thead');
+    const headRow = document.createElement('tr');
+    const corner = document.createElement('th');
+    corner.className = 'dt-corner';
+    headRow.appendChild(corner);
+    for (let c = 0; c < this._colCount(); c++) {
+      const th = document.createElement('th');
+      th.className = 'dt-col-header';
+      th.textContent = indexToCol(c);
+      headRow.appendChild(th);
+    }
+    thead.appendChild(headRow);
+
+    const tbody = document.createElement('tbody');
+    for (let r = 0; r < this._rowCount(); r++) {
+      tbody.appendChild(this._renderGridRow(r));
+    }
+
+    table.append(thead, tbody);
+    return table;
+  }
+
+  _colCount() {
+    return Math.max(...this._data.map((r) => r.length), 1);
+  }
+
+  _renderGridRow(r) {
+    const tr = document.createElement('tr');
+    const rowHeader = document.createElement('th');
+    rowHeader.className = 'dt-row-header';
+    rowHeader.textContent = r + 1;
+    tr.appendChild(rowHeader);
+    for (let c = 0; c < this._colCount(); c++) {
+      tr.appendChild(this._renderCell(r, c));
+    }
+    return tr;
+  }
+
+  _renderCell(r, c) {
+    const td = document.createElement('td');
+    td.className = 'dt-cell';
+    td.dataset.row = r;
+    td.dataset.col = c;
+    td.tabIndex = -1;
+
+    const computed = this.getComputedValue(r, c);
+    if (computed !== '') {
+      td.appendChild(renderCellValue(computed));
+    }
+    if (this._engine.formulas.has(`${r}:${c}`)) {
+      td.classList.add('dt-has-formula');
+    }
+
+    if (!this.readOnly) {
+      td.addEventListener('mousedown', (e) => this._onCellMouseDown(e, r, c));
+      td.addEventListener('mouseenter', () => this._onCellMouseEnter(r, c));
+      td.addEventListener('dblclick', () => this._startEdit(r, c));
+    } else {
+      td.addEventListener('mousedown', (e) => {
+        this._selectCell(r, c, e.shiftKey);
+      });
+    }
+
+    return td;
+  }
+
+
+
+  _rowCount() {
+    return this._data.length;
+  }
+
+  // ── Column & row resizing (spreadsheet mode) ─────────────────
+
+  static RESIZE_EDGE_PX = 6;
+  static MIN_COL_WIDTH = 40;
+  static MIN_ROW_HEIGHT = 20;
+  static DEFAULT_COL_WIDTH = 100;
+
+  _colWidth(c) {
+    this._colWidths = this._colWidths || {};
+    return this._colWidths[c] ?? DataTable.DEFAULT_COL_WIDTH;
+  }
+
+  _rowHeight(r) {
+    this._rowHeights = this._rowHeights || {};
+    return this._rowHeights[r] ?? this._defaultRowHeight();
+  }
+
+  _defaultRowHeight() {
+    if (this.__defaultRowH == null) {
+      const td = this.querySelector('.dt-grid td.dt-cell');
+      this.__defaultRowH = td ? td.offsetHeight : 30;
+    }
+    return this.__defaultRowH;
+  }
+
+  /** Wire hover cursor + drag-to-resize on header edges. Bound once. */
+  _bindResizeHandles() {
+    this.addEventListener('mousemove', (e) => {
+      if (this._resizing) return;
+      const hit = this._resizeTargetAt(e);
+      const el = hit ? hit.el : null;
+      if (el !== this._resizeHoverEl) {
+        this._resizeHoverEl?.classList.remove('dt-col-resize', 'dt-row-resize');
+        this._resizeHoverEl = el;
+        if (hit) {
+          hit.el.classList.add(hit.type === 'col' ? 'dt-col-resize' : 'dt-row-resize');
+        }
+      }
+    });
+
+    this.addEventListener('mouseleave', () => {
+      this._resizeHoverEl?.classList.remove('dt-col-resize', 'dt-row-resize');
+      this._resizeHoverEl = null;
+    });
+
+    this.addEventListener('mousedown', (e) => this._onResizeMouseDown(e));
+    this.addEventListener('dblclick', (e) => this._onResizeDblClick(e));
+  }
+
+  /** Header element under the pointer's resize edge, if any. */
+  _resizeTargetAt(e) {
+    if (this.mode !== 'spreadsheet') return null;
+    const th = e.target instanceof Element ? e.target.closest('th') : null;
+    if (!th) return null;
+    const rect = th.getBoundingClientRect();
+    const edge = DataTable.RESIZE_EDGE_PX;
+
+    if (th.classList.contains('dt-col-header') && rect.right - e.clientX <= edge) {
+      const index = Array.prototype.indexOf.call(th.parentElement.children, th) - 1;
+      return { el: th, type: 'col', index };
+    }
+    if (th.classList.contains('dt-row-header') && rect.bottom - e.clientY <= edge) {
+      const index = Array.prototype.indexOf.call(th.closest('tbody').children, th.parentElement);
+      return { el: th, type: 'row', index };
+    }
+    return null;
+  }
+
+  _onResizeMouseDown(e) {
+    const hit = this._resizeTargetAt(e);
+    if (!hit || hit.index < 0) return;
+    e.preventDefault();
+    e.stopPropagation();
+
+    const { type, index } = hit;
+    const startPos = type === 'col' ? e.clientX : e.clientY;
+    const startSize = type === 'col' ? this._colWidth(index) : this._rowHeight(index);
+
+    const onMove = (ev) => {
+      const delta = (type === 'col' ? ev.clientX : ev.clientY) - startPos;
+      if (type === 'col') {
+        this._colWidths[index] = Math.max(DataTable.MIN_COL_WIDTH, startSize + delta);
+      } else {
+        this._rowHeights[index] = Math.max(DataTable.MIN_ROW_HEIGHT, startSize + delta);
+      }
+      this._applyGridMetrics();
+    };
+    const onUp = () => {
+      document.removeEventListener('mousemove', onMove);
+      document.removeEventListener('mouseup', onUp);
+      document.body.classList.remove('dt-resizing', 'dt-col-resizing', 'dt-row-resizing');
+      this._resizing = false;
+    };
+
+    this._resizing = true;
+    document.body.classList.add(
+      'dt-resizing',
+      type === 'col' ? 'dt-col-resizing' : 'dt-row-resizing'
+    );
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup', onUp);
+  }
+
+  /** Double-click an edge to reset that column/row to its default size. */
+  _onResizeDblClick(e) {
+    const hit = this._resizeTargetAt(e);
+    if (!hit || hit.index < 0) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (hit.type === 'col') delete this._colWidths[hit.index];
+    else delete this._rowHeights[hit.index];
+    this._applyGridMetrics();
+  }
+
+  /** Push stored column widths / row heights into the DOM. */
+  _applyGridMetrics() {
+    if (this.mode !== 'spreadsheet') return;
+    const table = this.querySelector('.dt-grid');
+    if (!table) return;
+
+    let bodyTotal = 0;
+    const cols = table.querySelectorAll('colgroup.dt-cols col');
+    cols.forEach((col, i) => {
+      if (i === 0) {
+        col.style.width = '3rem'; // row-header gutter
+      } else {
+        const w = Math.round(this._colWidth(i - 1));
+        col.style.width = w + 'px';
+        bodyTotal += w;
+      }
+    });
+    table.style.width = `calc(3rem + ${bodyTotal}px)`;
+
+    const rows = table.tBodies[0]?.children ?? [];
+    for (let r = 0; r < rows.length; r++) {
+      rows[r].style.height = this._rowHeight(r) + 'px';
+    }
+  }
+
+  // ── Selection & keyboard (spreadsheet mode) ──────────────────
+
+  _onCellMouseDown(event, r, c) {
+    if (this._editing && (this._editing.r !== r || this._editing.c !== c)) {
+      this._commitEdit();
+    }
+    this._dragging = true;
+    this._selectCell(r, c, event.shiftKey);
+    event.preventDefault();
+    this._grid.focus({ preventScroll: true });
+  }
+
+  _onCellMouseEnter(r, c) {
+    if (this._dragging && this._selection) {
+      this._selection.focus = { r, c };
+      this._paintSelection();
+    }
+  }
+
+  _selectCell(r, c, extend = false) {
+    const maxR = this._rowCount() - 1;
+    const maxC = this._colCount() - 1;
+    r = Math.min(Math.max(r, 0), maxR);
+    c = Math.min(Math.max(c, 0), maxC);
+
+    if (extend && this._selection) {
+      this._selection.focus = { r, c };
+    } else {
+      this._selection = { anchor: { r, c }, focus: { r, c } };
+    }
+    this._paintSelection();
+    this._syncFormulaBar();
+
+    this.dispatchEvent(new CustomEvent('selection-change', {
+      bubbles: true,
+      detail: { row: this._selection.focus.r, col: this._selection.focus.c },
+    }));
+  }
+
+  _paintSelection() {
+    const grid = this.querySelector('.dt-grid');
+    if (!grid || !this._selection) return;
+    grid.querySelectorAll('.dt-active').forEach((el) => el.classList.remove('dt-active'));
+    grid.querySelectorAll('.dt-in-range').forEach((el) => el.classList.remove('dt-in-range'));
+
+    const { anchor, focus } = this._normalizedSelection();
+    const activeTd = this._cellElement(focus.r, focus.c);
+    if (activeTd) activeTd.classList.add('dt-active');
+
+    for (let r = anchor.r; r <= focus.r; r++) {
+      for (let c = anchor.c; c <= focus.c; c++) {
+        const td = this._cellElement(r, c);
+        if (td && !(r === focus.r && c === focus.c)) {
+          td.classList.add('dt-in-range');
+        }
+      }
+    }
+  }
+
+  _normalizedSelection() {
+    const { anchor, focus } = this._selection;
+    return {
+      anchor: {
+        r: Math.min(anchor.r, focus.r),
+        c: Math.min(anchor.c, focus.c),
+      },
+      focus: {
+        r: Math.max(anchor.r, focus.r),
+        c: Math.max(anchor.c, focus.c),
+      },
+    };
+  }
+
+  _cellElement(r, c) {
+    return this.querySelector(`td[data-row="${r}"][data-col="${c}"]`);
+  }
+
+  _handleKeydown(event) {
+    if (this.mode !== 'spreadsheet' || !this._selection) return;
+    if (this._editing) return; // the editor input handles its own keys
+    if (event.ctrlKey || event.metaKey) return; // clipboard shortcuts pass through
+
+    const { anchor, focus } = this._selection;
+    const moveKeys = {
+      ArrowUp: [-1, 0], ArrowDown: [1, 0],
+      ArrowLeft: [0, -1], ArrowRight: [0, 1],
+      Tab: [0, event.shiftKey ? -1 : 1],
+    };
+
+    if (moveKeys[event.key]) {
+      event.preventDefault();
+      const [dr, dc] = moveKeys[event.key];
+      if (event.shiftKey && event.key.startsWith('Arrow')) {
+        this._selection.focus = {
+          r: focus.r + dr, c: focus.c + dc,
+        };
+        this._paintSelection();
+      } else {
+        const target = event.key === 'Tab' ? focus : anchor;
+        this._selectCell(target.r + dr, target.c + dc);
+      }
+      return;
+    }
+
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      if (!this.readOnly) this._startEdit(focus.r, focus.c);
+      return;
+    }
+
+    if (event.key === 'Delete' || event.key === 'Backspace') {
+      event.preventDefault();
+      if (!this.readOnly) this.clearSelection();
+      return;
+    }
+
+    if (event.key.length === 1 && !event.altKey) {
+      if (!this.readOnly) {
+        event.preventDefault();
+        this._startEdit(focus.r, focus.c, event.key);
+      }
+    }
+  }
+
+  // ── Editing ──────────────────────────────────────────────────
+
+  _startEdit(r, c, initialText = null) {
+    if (this.readOnly || this._editing) return;
+    const td = this._cellElement(r, c);
+    if (!td) return;
+
+    const raw = this._engine.getRaw(r, c);
+    const input = document.createElement('input');
+    input.className = 'dt-editor';
+    input.type = 'text';
+    input.value = initialText !== null ? initialText : String(raw ?? '');
+    td.textContent = '';
+    td.appendChild(input);
+    input.focus({ preventScroll: true });
+    if (initialText === null) input.select();
+
+    this._editing = { r, c, input };
+
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        this._commitEdit();
+        this._selectCell(r + 1, c);
+        this._grid?.focus({ preventScroll: true });
+      } else if (e.key === 'Tab') {
+        e.preventDefault();
+        this._commitEdit();
+        this._selectCell(r, c + (e.shiftKey ? -1 : 1));
+        this._grid?.focus({ preventScroll: true });
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        this._cancelEdit();
+        this._grid?.focus({ preventScroll: true });
+      }
+      e.stopPropagation();
+    });
+
+    input.addEventListener('blur', () => {
+      if (this._editing && this._editing.input === input) {
+        this._commitEdit();
+      }
+    });
+  }
+
+  _commitEdit() {
+    if (!this._editing) return;
+    const { r, c, input } = this._editing;
+    const value = input.value;
+    this._editing = null;
+    this.setCellValue(r, c, value);
+  }
+
+  _cancelEdit() {
+    if (!this._editing) return;
+    const { r, c } = this._editing;
+    this._editing = null;
+    this._updateCellDisplay(r, c);
+  }
+
+  _commitFormulaBar() {
+    if (!this._formulaInput || !this._selection || this.readOnly) return;
+    const { r, c } = this._selection.anchor;
+    const value = this._formulaInput.value;
+    if (value !== String(this._engine.getRaw(r, c))) {
+      this.setCellValue(r, c, value);
+    }
+  }
+
+  _syncFormulaBar() {
+    if (!this._formulaInput || !this._selection) return;
+    const { r, c } = this._selection.anchor;
+    if (document.activeElement === this._formulaInput) return;
+    this._refLabel.textContent = `${indexToCol(c)}${r + 1}`;
+    this._formulaInput.value = String(this._engine.getRaw(r, c) ?? '');
+  }
+
+  _updateCellDisplay(r, c) {
+    const td = this._cellElement(r, c);
+    if (!td) return;
+    td.classList.toggle(
+      'dt-has-formula',
+      this._engine.formulas.has(`${r}:${c}`)
+    );
+    const computed = this.getComputedValue(r, c);
+    td.textContent = '';
+    if (computed !== '') {
+      td.appendChild(renderCellValue(computed));
+    }
+    this._syncFormulaBar();
+  }
+
+  _refreshAllCells() {
+    if (this.mode !== 'spreadsheet') return;
+    for (let r = 0; r < this._rowCount(); r++) {
+      for (let c = 0; c < this._colCount(); c++) {
+        this._updateCellDisplay(r, c);
+      }
+    }
+    this._paintSelection();
+  }
+
+  // ── Structural edits ─────────────────────────────────────────
+
+  insertRow(count = 1) {
+    const totalCols = this._colCount();
+    for (let i = 0; i < count; i++) {
+      this._data.push(Array(totalCols).fill(''));
+    }
+    this._syncGridDimensions();
+    this.recalculate();
+  }
+
+  insertColumn() {
+    this._ensureSize(this._rowCount(), this._colCount() + 1);
+    const headRow = this.querySelector('.dt-grid thead tr');
+    if (!headRow) return;
+    const c = this._colCount() - 1;
+    const th = document.createElement('th');
+    th.className = 'dt-col-header';
+    th.textContent = indexToCol(c);
+    headRow.appendChild(th);
+    for (let r = 0; r < this._rowCount(); r++) {
+      const row = this.querySelector(`.dt-grid tbody tr:nth-child(${r + 1})`);
+      if (row) row.appendChild(this._renderCell(r, c));
+    }
+    const colgroup = this.querySelector('.dt-grid colgroup.dt-cols');
+    if (colgroup) colgroup.appendChild(document.createElement('col'));
+    this._applyGridMetrics();
+  }
+
+  /**
+   * Grow the rendered grid (spreadsheet mode) so every row/column present in
+   * the data model has a DOM element.
+   */
+  _syncGridDimensions() {
+    const table = this.querySelector('.dt-grid');
+    if (!table) return;
+
+    // Columns
+    const headRow = table.querySelector('thead tr');
+    while (headRow && headRow.children.length - 1 < this._colCount()) {
+      const c = headRow.children.length - 1;
+      const th = document.createElement('th');
+      th.className = 'dt-col-header';
+      th.textContent = indexToCol(c);
+      headRow.appendChild(th);
+    }
+
+    // Rows
+    const tbody = table.querySelector('tbody');
+    while (tbody && tbody.children.length < this._rowCount()) {
+      const r = tbody.children.length;
+      tbody.appendChild(this._renderGridRow(r));
+    }
+
+    // Keep the colgroup in step with new columns.
+    const colgroup = table.querySelector('colgroup.dt-cols');
+    while (colgroup && colgroup.children.length < this._colCount() + 1) {
+      colgroup.appendChild(document.createElement('col'));
+    }
+    this._applyGridMetrics();
+  }
+
+  clearSelection() {
+    if (!this._selection) return;
+    const { anchor, focus } = this._normalizedSelection();
+    for (let r = anchor.r; r <= focus.r; r++) {
+      for (let c = anchor.c; c <= focus.c; c++) {
+        if (this._data[r]) this._data[r][c] = '';
+      }
+    }
+    this.recalculate().then(() => this.emitChange(anchor.r, anchor.c, ''));
+  }
+
+  // ── Copy / Cut / Paste & keyboard bindings ─────────────────
+
+  _bindClipboard() {
+    this.addEventListener('keydown', (e) => this._handleKeydown(e));
+
+    document.addEventListener('mouseup', () => { this._dragging = false; });
+
+    // When the event originates from a text field (cell editor or the formula
+    // bar), let the browser handle copy/cut/paste natively instead of
+    // hijacking it for grid operations.
+    const targetsTextField = (e) =>
+      e.composedPath().some(
+        (el) => el instanceof HTMLElement && el.matches('input, textarea')
+      );
+
+    this.addEventListener('copy', (e) => {
+      if (targetsTextField(e)) return;
+      if (this.mode !== 'spreadsheet' || this._editing || !this._selection) return;
+      e.preventDefault();
+      const tsv = this.selectionToTSV();
+      e.clipboardData.setData('text/plain', tsv);
+      this._setStatus(`Copied ${this._selectionSize()} cells`);
+    });
+
+    this.addEventListener('cut', (e) => {
+      if (targetsTextField(e)) return;
+      if (this.mode !== 'spreadsheet' || this.readOnly || this._editing || !this._selection) return;
+      e.preventDefault();
+      const tsv = this.selectionToTSV();
+      e.clipboardData.setData('text/plain', tsv);
+      this.clearSelection();
+      this._setStatus(`Cut ${this._selectionSize()} cells`);
+    });
+
+    this.addEventListener('paste', (e) => {
+      if (targetsTextField(e)) return;
+      if (this.mode !== 'spreadsheet' || this.readOnly || this._editing) return;
+      e.preventDefault();
+      const text = e.clipboardData.getData('text/plain');
+      if (text) this.pasteText(text);
+    });
+  }
+
+  selectionToTSV() {
+    if (!this._selection) return '';
+    const { anchor, focus } = this._normalizedSelection();
+    const lines = [];
+    for (let r = anchor.r; r <= focus.r; r++) {
+      const row = [];
+      for (let c = anchor.c; c <= focus.c; c++) {
+        row.push(String(this._engine.getRaw(r, c) ?? '').replace(/\t|\n/g, ' '));
+      }
+      lines.push(row.join('\t'));
+    }
+    return lines.join('\n');
+  }
+
+  /** Parse TSV text and write it starting at the active cell. */
+  pasteText(text) {
+    if (!this._selection) return;
+    const startRow = this._selection.anchor.r;
+    const startCol = this._selection.anchor.c;
+    const rows = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+      .split('\n')
+      .filter((line, i, arr) => line !== '' || i < arr.length - 1)
+      .map((line) => line.split('\t'));
+
+    const neededRows = startRow + rows.length;
+    const neededCols = startCol + Math.max(...rows.map((r) => r.length));
+    this._ensureSize(neededRows, neededCols);
+    this._syncGridDimensions();
+
+    for (let i = 0; i < rows.length; i++) {
+      for (let j = 0; j < rows[i].length; j++) {
+        this._data[startRow + i][startCol + j] = rows[i][j];
+      }
+    }
+
+    // Extend selection over pasted region.
+    this._selection = {
+      anchor: { r: startRow, c: startCol },
+      focus: { r: neededRows - 1, c: neededCols - 1 },
+    };
+
+    this.recalculate().then(() => {
+      this._refreshAllCells();
+      this._paintSelection();
+      this.emitChange(startRow, startCol, '');
+    });
+    this._setStatus(`Pasted ${rows.length}×${rows[0].length} block`);
+  }
+
+  copySelection() {
+    const tsv = this.selectionToTSV();
+    navigator.clipboard.writeText(tsv).then(() => {
+      this._setStatus(`Copied ${this._selectionSize()} cells`);
+    }).catch((err) => {
+      console.warn('Clipboard write failed:', err);
+      this._setStatus('Copy failed — clipboard access blocked');
+    });
+    return tsv;
+  }
+
+  _selectionSize() {
+    if (!this._selection) return 0;
+    const { anchor, focus } = this._normalizedSelection();
+    return (focus.r - anchor.r + 1) * (focus.c - anchor.c + 1);
+  }
+
+  _setStatus(text) {
+    if (this._statusEl) {
+      this._statusEl.textContent = text;
+      clearTimeout(this._statusTimer);
+      this._statusTimer = setTimeout(() => {
+        this._statusEl.textContent = '';
+      }, 2500);
+    }
+  }
+
+  // ── Table mode ───────────────────────────────────────────────
+
+  _buildTableMode() {
+    const root = document.createElement('div');
+    root.className = 'dt-root dt-table-mode';
+
+    const toolbar = document.createElement('div');
+    toolbar.className = 'dt-toolbar';
+    const label = document.createElement('label');
+    label.textContent = 'Search';
+    label.htmlFor = 'dt-search-' + Date.now();
+    const search = document.createElement('input');
+    search.type = 'search';
+    search.id = label.htmlFor;
+    search.placeholder = 'Filter records…';
+    search.autocomplete = 'off';
+    search.addEventListener('input', () => {
+      this._searchTerm = search.value.trim().toLowerCase();
+      this._renderTableView();
+    });
+    const count = document.createElement('span');
+    count.className = 'dt-count';
+    this._countEl = count;
+    toolbar.append(label, search, count);
+    this._searchTerm = '';
+
+    this._grid = document.createElement('div');
+    this._grid.className = 'dt-grid-scroll';
+    root.append(toolbar, this._grid);
+    this.appendChild(root);
+
+    this._renderTableView();
+  }
+
+  /** Rows visible after filtering/sorting → original data indexes. */
+  _tableViewIndexes() {
+    const indexes = [];
+    for (let r = 1; r < this._rowCount(); r++) {
+      indexes.push(r);
+    }
+    let view = indexes;
+    if (this._searchTerm) {
+      view = view.filter((r) =>
+        (this._data[r] || []).some((cell) =>
+          String(cell ?? '').toLowerCase().includes(this._searchTerm))
+      );
+    }
+    if (this._sortColumn !== null) {
+      const col = this._sortColumn;
+      const dir = this._sortDirection === 'asc' ? 1 : -1;
+      view = [...view].sort((a, b) =>
+        dir * String(this._data[a]?.[col] ?? '').localeCompare(
+          String(this._data[b]?.[col] ?? ''), undefined, { numeric: true }
+        ));
+    }
+    return view;
+  }
+
+  _renderTableView() {
+    const headers = (this._data[0] || []).map((h) => String(h ?? ''));
+    const view = this._tableViewIndexes();
+
+    const table = document.createElement('table');
+    table.className = 'dt-grid dt-data-table';
+
+    const thead = document.createElement('thead');
+    const headRow = document.createElement('tr');
+    headers.forEach((header, c) => {
+      const th = document.createElement('th');
+      th.className = 'dt-col-header dt-sortable';
+      th.textContent = header;
+      if (this._sortColumn === c) {
+        th.classList.add('dt-sorted');
+        th.textContent += this._sortDirection === 'asc' ? ' ↑' : ' ↓';
+      }
+      th.addEventListener('click', () => {
+        if (this._sortColumn === c) {
+          this._sortDirection = this._sortDirection === 'asc' ? 'desc' : 'asc';
+        } else {
+          this._sortColumn = c;
+          this._sortDirection = 'asc';
+        }
+        this._renderTableView();
+      });
+      headRow.appendChild(th);
+    });
+    thead.appendChild(headRow);
+
+    const tbody = document.createElement('tbody');
+    for (const dataIndex of view) {
+      const tr = document.createElement('tr');
+      headers.forEach((_, c) => {
+        const td = document.createElement('td');
+        td.className = 'dt-cell';
+        const computed = this.getComputedValue(dataIndex, c);
+        if (computed !== '') td.appendChild(renderCellValue(computed));
+        tr.appendChild(td);
+      });
+      tbody.appendChild(tr);
+    }
+
+    table.append(thead, tbody);
+    this._grid.textContent = '';
+    this._grid.appendChild(table);
+
+    if (this._countEl) {
+      this._countEl.textContent =
+        `${view.length} of ${Math.max(this._rowCount() - 1, 0)} records`;
+    }
+  }
+
+  // ── List mode ────────────────────────────────────────────────
+
+  _buildListMode() {
+    const root = document.createElement('div');
+    root.className = 'dt-root dt-list-mode';
+
+    const toolbar = document.createElement('div');
+    toolbar.className = 'dt-toolbar';
+    const label = document.createElement('label');
+    label.textContent = 'Search';
+    label.htmlFor = 'dt-list-search-' + Date.now();
+    const search = document.createElement('input');
+    search.type = 'search';
+    search.id = label.htmlFor;
+    search.placeholder = 'Filter items…';
+    search.autocomplete = 'off';
+    search.addEventListener('input', () => {
+      this._searchTerm = search.value.trim().toLowerCase();
+      this._renderListView();
+    });
+    toolbar.append(label, search);
+
+    this._listEl = document.createElement('ul');
+    this._listEl.className = 'dt-list';
+    root.append(toolbar, this._listEl);
+    this.appendChild(root);
+
+    this._searchTerm = '';
+    this._renderListView();
+  }
+
+  _renderListView() {
+    const ul = this._listEl;
+    ul.textContent = '';
+
+    let shown = 0;
+    for (let r = 0; r < this._rowCount(); r++) {
+      const raw = String(this.getComputedValue(r, 0) ?? '');
+      if (raw === '') continue;
+      if (this._searchTerm && !raw.toLowerCase().includes(this._searchTerm)) continue;
+      shown++;
+      const li = document.createElement('li');
+      li.appendChild(renderCellValue(raw));
+      ul.appendChild(li);
+    }
+  }
+}
+
+if (!customElements.get('data-table')) {
+  customElements.define('data-table', DataTable);
+}
+
+export default DataTable;