mrmd-editor 0.7.1 → 0.8.0

package/src/tables/README.md

@@ -0,0 +1,97 @@
+# mrmd-editor/src/tables
+
+Internal linked-table UI/editor adapter subsystem.
+
+This folder is where MRMD-specific editor integration lives.
+It should depend on pure table packages, but the pure packages must not depend back on this folder.
+
+## Ownership
+
+- linked-table block detection inside editor documents
+- small/document view widget
+- active-inline interactions
+- full grid workspace shell
+- editor commands for linked tables
+- browser-side table job client
+
+## Planned tree
+
+```text
+mrmd-editor/src/tables/
+  index.js
+  facets.js
+  commands/
+    insert-linked-table.js
+    open-table-workspace.js
+    open-table-source.js
+    refresh-linked-table.js
+  parsing/
+    linked-table-blocks.js
+    anchors.js
+  state/
+    linked-table-state.js
+    table-workspace-state.js
+  decorations/
+    linked-table-decorations.js
+  widgets/
+    linked-table-widget.js
+    linked-table-chrome.js
+    linked-table-status.js
+  workspace/
+    controller.js
+    layout.js
+    result-grid.js
+    source-grid.js
+    panels/
+      join-panel.js
+      bind-rows-panel.js
+      bind-cols-panel.js
+      formula-panel.js
+      document-view-panel.js
+      source-info-panel.js
+  jobs/
+    client.js
+    status.js
+  styles.js
+```
+
+## Current phase
+
+The first editor-side shell is now wired through the first real sort/import/source/workspace paths for:
+- linked-table block detection from markdown/spec headers
+- small embedded linked-table widget rendering
+- linked badge/chrome row
+- header-sort event dispatch
+- explicit `Open grid` / `Open source` / `Reveal source` / `Open markdown` / `Refresh` action dispatch
+- browser-side `tableJobs` client + wait/status helpers
+- Yjs block-anchor creation for linked-table jobs
+- controller wiring from header-sort widget actions to real `tableJobs` requests
+- host-backed linked-table import insertion helpers in the editor layer
+- first studio/status-bar UI command path for linked-table import
+- block-local markdown-source reveal with a visible `Return to linked view` path
+- first widget job-status badge updates for linked tables
+- basic source-mtime stale detection for visible linked tables
+- first real `Open grid` workspace panel hook (implemented in the Electron app for now)
+- no reveal-on-click for linked tables in the markdown block-decoration path
+
+## First slice here
+
+Phase 1 editor work should only prove:
+- linked-table block detection
+- small embedded widget rendering
+- linked badge/chrome row
+- header-sort action
+- `Open grid` shell
+- no reveal-on-click for linked tables
+
+Known gaps after the first manual app test:
+- latency is visible because the first materialization path is still simple and mostly unoptimized
+- widget chrome status is still only a first-pass badge layer, not the full stale/progress/error design yet
+- the new workspace is still an MVP inspection shell, not yet the full editing/data-workbench experience
+
+## Non-goals for the first slice
+
+- full grid editing richness
+- source editor tabs
+- join/bind UI end to end
+- raw-source editing UI

package/src/tables/commands/insert-linked-table.js

@@ -0,0 +1,122 @@
+/**
+ * Linked-table import/insert helpers.
+ */
+
+function getHostApi(hostApi) {
+  if (hostApi) return hostApi;
+  if (typeof window !== 'undefined') return window.electronAPI || null;
+  return null;
+}
+
+function ensureTrailingNewlinePair(text, side) {
+  const value = String(text || '');
+  if (!value) return '';
+
+  if (side === 'before') {
+    if (value.endsWith('\n\n')) return '';
+    if (value.endsWith('\n')) return '\n';
+    return '\n\n';
+  }
+
+  if (value.startsWith('\n\n')) return '';
+  if (value.startsWith('\n')) return '\n';
+  return '\n\n';
+}
+
+export function canImportLinkedTableFromHost(hostApi) {
+  const host = getHostApi(hostApi);
+  return typeof host?.table?.importDelimited === 'function';
+}
+
+export function normalizeLinkedTableBlockInsertion(docText, from, to, blockMarkdown) {
+  const fullText = String(docText || '');
+  const safeFrom = Math.max(0, Math.min(fullText.length, Number.isInteger(from) ? from : 0));
+  const safeTo = Math.max(safeFrom, Math.min(fullText.length, Number.isInteger(to) ? to : safeFrom));
+  const before = fullText.slice(0, safeFrom);
+  const after = fullText.slice(safeTo);
+  const block = String(blockMarkdown || '').trim();
+
+  if (!block) {
+    return {
+      from: safeFrom,
+      to: safeTo,
+      insert: '',
+      selectionAnchor: safeFrom,
+    };
+  }
+
+  const prefix = before.length > 0 ? ensureTrailingNewlinePair(before, 'before') : '';
+  const suffix = after.length > 0 ? ensureTrailingNewlinePair(after, 'after') : '';
+  const insert = `${prefix}${block}${suffix}`;
+
+  return {
+    from: safeFrom,
+    to: safeTo,
+    insert,
+    selectionAnchor: safeFrom + insert.length,
+  };
+}
+
+export function insertLinkedTableBlock(editor, blockMarkdown, options = {}) {
+  const view = editor?.view || options.view;
+  if (!view?.state || typeof view.dispatch !== 'function') {
+    throw new Error('insertLinkedTableBlock requires an editor/view with dispatch support');
+  }
+
+  const selection = options.selection || view.state.selection?.main || { from: 0, to: 0 };
+  const docText = view.state.doc?.toString?.() || '';
+  const normalized = normalizeLinkedTableBlockInsertion(docText, selection.from, selection.to, blockMarkdown);
+
+  view.dispatch({
+    changes: {
+      from: normalized.from,
+      to: normalized.to,
+      insert: normalized.insert,
+    },
+    selection: {
+      anchor: normalized.selectionAnchor,
+    },
+    scrollIntoView: true,
+  });
+
+  return normalized;
+}
+
+export async function importLinkedTableFromHost(editor, options = {}) {
+  const host = getHostApi(options.hostApi);
+  if (!canImportLinkedTableFromHost(host)) {
+    throw new Error('Linked-table import requires an Electron host exposing `electronAPI.table.importDelimited()`');
+  }
+
+  const projectRoot = options.projectRoot || editor?.getLinkedTableHostContext?.()?.projectRoot || null;
+  const documentPath = options.documentPath || editor?.getLinkedTableHostContext?.()?.documentPath || null;
+  const sourceFilePath = options.sourceFilePath;
+
+  if (!projectRoot) throw new Error('Linked-table import requires a project root');
+  if (!documentPath) throw new Error('Linked-table import requires a document path');
+  if (!sourceFilePath) throw new Error('Linked-table import requires a source file path');
+
+  const result = await host.table.importDelimited({
+    projectRoot,
+    documentPath,
+    sourceFilePath,
+    tableId: options.tableId,
+    label: options.label,
+    cacheFormat: options.cacheFormat,
+    maxRows: options.maxRows,
+    overflow: options.overflow,
+  });
+
+  insertLinkedTableBlock(editor, result.blockMarkdown, {
+    selection: options.selection,
+  });
+
+  return result;
+}
+
+export default {
+  canImportLinkedTableFromHost,
+  normalizeLinkedTableBlockInsertion,
+  insertLinkedTableBlock,
+  importLinkedTableFromHost,
+};

package/src/tables/commands/open-table-workspace.js

@@ -0,0 +1,43 @@
+/**
+ * Linked-table workspace command/event helpers.
+ */
+
+export const LINKED_TABLE_EVENT = 'mrmd-linked-table-action';
+
+/**
+ * Dispatch a linked-table UI action from the editor surface.
+ * Host/app code can listen on `view.dom` or `window`.
+ *
+ * @param {import('@codemirror/view').EditorView} view
+ * @param {Object} detail
+ * @returns {boolean}
+ */
+export function dispatchLinkedTableAction(view, detail) {
+  if (!view?.dom) return false;
+  const event = new CustomEvent(LINKED_TABLE_EVENT, {
+    bubbles: true,
+    detail,
+  });
+  view.dom.dispatchEvent(event);
+  return true;
+}
+
+/**
+ * Convenience helper for opening the full linked-table workspace.
+ *
+ * @param {import('@codemirror/view').EditorView} view
+ * @param {Object} detail
+ * @returns {boolean}
+ */
+export function openLinkedTableWorkspace(view, detail) {
+  return dispatchLinkedTableAction(view, {
+    action: 'open-grid',
+    ...detail,
+  });
+}
+
+export default {
+  LINKED_TABLE_EVENT,
+  dispatchLinkedTableAction,
+  openLinkedTableWorkspace,
+};

package/src/tables/index.js

@@ -0,0 +1,24 @@
+/**
+ * Linked-table editor integration exports.
+ */
+
+export { findLinkedTableBlocksInState, getLinkedTableBlockRange, isRangeInsideLinkedTable } from './parsing/linked-table-blocks.js';
+export { createLinkedTableBlockAnchor, resolveLinkedTableBlockAnchor } from './parsing/anchors.js';
+export {
+  linkedTableMarkdownState,
+  revealLinkedTableMarkdownEffect,
+  hideLinkedTableMarkdownEffect,
+  clearLinkedTableMarkdownEffect,
+  isLinkedTableMarkdownOpen,
+} from './state/linked-table-state.js';
+export { LINKED_TABLE_EVENT, dispatchLinkedTableAction, openLinkedTableWorkspace } from './commands/open-table-workspace.js';
+export {
+  canImportLinkedTableFromHost,
+  normalizeLinkedTableBlockInsertion,
+  insertLinkedTableBlock,
+  importLinkedTableFromHost,
+} from './commands/insert-linked-table.js';
+export { TableJobsClient, TABLE_JOB_STATUS, createTableJobsClient } from './jobs/client.js';
+export { LinkedTableController, createLinkedTableController } from './workspace/controller.js';
+export { LinkedTableWidget } from './widgets/linked-table-widget.js';
+export { LinkedTableSourceBannerWidget } from './widgets/linked-table-source-banner.js';

package/src/tables/jobs/client.js

@@ -0,0 +1,158 @@
+/**
+ * Browser-side linked-table job coordination.
+ *
+ * Mirrors the monitor execution coordination pattern but for `tableJobs`.
+ */
+
+import * as Y from 'yjs';
+
+export const TABLE_JOB_STATUS = {
+  REQUESTED: 'requested',
+  CLAIMED: 'claimed',
+  RUNNING: 'running',
+  WRITING: 'writing',
+  COMPLETED: 'completed',
+  ERROR: 'error',
+  CANCELLED: 'cancelled',
+};
+
+export class TableJobsClient {
+  constructor(ydoc, clientId = ydoc?.clientID) {
+    this.ydoc = ydoc;
+    this.clientId = clientId;
+    this.jobs = ydoc.getMap('tableJobs');
+    this._statusCallbacks = new Map();
+    this._observers = new Set();
+    this._setupObserver();
+  }
+
+  static generateJobId() {
+    return `tablejob-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  _setupObserver() {
+    const observer = (event) => {
+      event.changes.keys.forEach((change, jobId) => {
+        const job = this.jobs.get(jobId);
+        const callback = this._statusCallbacks.get(jobId);
+        if (callback && job) {
+          callback(job.status, job);
+        }
+      });
+    };
+
+    this.jobs.observe(observer);
+    this._observers.add(observer);
+  }
+
+  requestJob({ tableId, blockAnchor = null, spec = null, jobType = 'applyOps', opList = [], metadata = {} }) {
+    const jobId = TableJobsClient.generateJobId();
+    this.jobs.set(jobId, {
+      id: jobId,
+      tableId,
+      jobType,
+      status: TABLE_JOB_STATUS.REQUESTED,
+      requestedBy: this.clientId,
+      requestedAt: Date.now(),
+      claimedBy: null,
+      claimedAt: null,
+      completedAt: null,
+      blockAnchor,
+      spec,
+      opList,
+      metadata,
+      result: null,
+      error: null,
+    });
+    return jobId;
+  }
+
+  requestSort({ tableId, blockAnchor = null, spec = null, column, direction = 'asc', metadata = {} }) {
+    return this.requestJob({
+      tableId,
+      blockAnchor,
+      spec,
+      jobType: 'applyOps',
+      opList: [{ type: 'sort', column, direction }],
+      metadata,
+    });
+  }
+
+  requestRefresh({ tableId, blockAnchor = null, spec = null, metadata = {} }) {
+    return this.requestJob({
+      tableId,
+      blockAnchor,
+      spec,
+      jobType: 'refresh',
+      opList: [],
+      metadata,
+    });
+  }
+
+  getJob(jobId) {
+    return this.jobs.get(jobId);
+  }
+
+  cancelJob(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job) return;
+    if ([TABLE_JOB_STATUS.COMPLETED, TABLE_JOB_STATUS.ERROR, TABLE_JOB_STATUS.CANCELLED].includes(job.status)) {
+      return;
+    }
+    this.jobs.set(jobId, {
+      ...job,
+      status: TABLE_JOB_STATUS.CANCELLED,
+      completedAt: Date.now(),
+    });
+  }
+
+  onStatusChange(jobId, callback) {
+    this._statusCallbacks.set(jobId, callback);
+    return () => {
+      this._statusCallbacks.delete(jobId);
+    };
+  }
+
+  waitForStatus(jobId, targetStatus, timeout = 30000) {
+    const statuses = Array.isArray(targetStatus) ? targetStatus : [targetStatus];
+
+    return new Promise((resolve, reject) => {
+      const current = this.getJob(jobId);
+      if (current && statuses.includes(current.status)) {
+        resolve(current);
+        return;
+      }
+
+      let timeoutId = null;
+      const unsubscribe = this.onStatusChange(jobId, (status, job) => {
+        if (!statuses.includes(status)) return;
+        if (timeoutId) clearTimeout(timeoutId);
+        unsubscribe();
+        resolve(job);
+      });
+
+      timeoutId = setTimeout(() => {
+        unsubscribe();
+        reject(new Error(`Timeout waiting for table job status ${statuses.join('/')} on ${jobId}`));
+      }, timeout);
+    });
+  }
+
+  destroy() {
+    for (const observer of this._observers) {
+      this.jobs.unobserve(observer);
+    }
+    this._observers.clear();
+    this._statusCallbacks.clear();
+  }
+}
+
+export function createTableJobsClient(ydoc) {
+  return new TableJobsClient(ydoc, ydoc.clientID);
+}
+
+export default {
+  TABLE_JOB_STATUS,
+  TableJobsClient,
+  createTableJobsClient,
+};

package/src/tables/parsing/anchors.js

@@ -0,0 +1,82 @@
+/**
+ * Linked-table Yjs anchor helpers.
+ *
+ * These anchors let table jobs survive surrounding document edits.
+ */
+
+import * as Y from 'yjs';
+
+function assertRange(range) {
+  const from = range?.headerFrom ?? range?.from;
+  const to = range?.snapshotTo ?? range?.to;
+
+  if (!Number.isInteger(from) || from < 0) {
+    throw new TypeError('Linked-table anchor range must include a non-negative `from`/`headerFrom`');
+  }
+  if (!Number.isInteger(to) || to < from) {
+    throw new TypeError('Linked-table anchor range must include a `to`/`snapshotTo` >= `from`');
+  }
+
+  return { from, to };
+}
+
+function toRelativePositionJson(yText, index, assoc) {
+  const relPos = Y.createRelativePositionFromTypeIndex(yText, index, assoc);
+  return Y.relativePositionToJSON(relPos);
+}
+
+function toAbsoluteIndex(ydoc, relPosJson) {
+  if (!relPosJson) return null;
+
+  try {
+    const relPos = Y.createRelativePositionFromJSON(relPosJson);
+    const absPos = Y.createAbsolutePositionFromRelativePosition(relPos, ydoc);
+    return absPos?.index ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a Yjs-stable anchor for one linked-table block.
+ *
+ * Start uses right association so inserts at the exact start stay outside the block.
+ * End uses left association so inserts at the exact end stay outside the block.
+ */
+export function createLinkedTableBlockAnchor(yText, range, options = {}) {
+  if (!yText?.doc) {
+    throw new TypeError('createLinkedTableBlockAnchor requires a Y.Text attached to a Y.Doc');
+  }
+
+  const resolved = assertRange(range);
+
+  return {
+    type: 'linked-table-block-anchor-v1',
+    tableId: options.tableId || range?.tableId || range?.spec?.id || null,
+    from: toRelativePositionJson(yText, resolved.from, 1),
+    to: toRelativePositionJson(yText, resolved.to, -1),
+    createdAt: Date.now(),
+  };
+}
+
+/**
+ * Resolve a linked-table anchor back to absolute document offsets.
+ */
+export function resolveLinkedTableBlockAnchor(ydoc, anchor) {
+  if (!ydoc || !anchor) return null;
+
+  const from = toAbsoluteIndex(ydoc, anchor.from);
+  const to = toAbsoluteIndex(ydoc, anchor.to);
+  if (!Number.isInteger(from) || !Number.isInteger(to) || to < from) return null;
+
+  return {
+    from,
+    to,
+    tableId: anchor.tableId || null,
+  };
+}
+
+export default {
+  createLinkedTableBlockAnchor,
+  resolveLinkedTableBlockAnchor,
+};

package/src/tables/parsing/linked-table-blocks.js

@@ -0,0 +1,61 @@
+/**
+ * Linked-table block parsing helpers for the editor.
+ *
+ * Bridges CodeMirror editor state/doc text to the pure `mrmd-table-spec`
+ * block-discovery layer.
+ */
+
+import { findLinkedTableBlocks } from '../../../../mrmd-table-spec/src/index.js';
+
+function splitLines(text) {
+  return String(text || '').split(/\r?\n/);
+}
+
+/**
+ * Find linked-table blocks in the current editor state.
+ * Enriches pure spec blocks with table text/lines for widget rendering.
+ *
+ * @param {import('@codemirror/state').EditorState} state
+ * @returns {Array<Object>}
+ */
+export function findLinkedTableBlocksInState(state) {
+  const text = state.doc.toString();
+  return findLinkedTableBlocks(text).map((block) => ({
+    ...block,
+    headerText: text.slice(block.headerFrom, block.headerTo),
+    tableText: text.slice(block.tableFrom, block.tableTo),
+    tableLines: splitLines(text.slice(block.tableFrom, block.tableTo)),
+  }));
+}
+
+/**
+ * Get the full replacement range for a linked table block.
+ * Includes hidden metadata header + visible snapshot region.
+ *
+ * @param {Object} block
+ * @returns {{from:number,to:number}}
+ */
+export function getLinkedTableBlockRange(block) {
+  return {
+    from: block.headerFrom,
+    to: block.snapshotTo,
+  };
+}
+
+/**
+ * Whether a normal markdown table range is covered by a linked-table block.
+ * Used to suppress the legacy plain-table renderer for linked snapshots.
+ *
+ * @param {{from:number,to:number}} range
+ * @param {Array<Object>} linkedBlocks
+ * @returns {boolean}
+ */
+export function isRangeInsideLinkedTable(range, linkedBlocks) {
+  return linkedBlocks.some((block) => range.from >= block.tableFrom && range.to <= block.tableTo);
+}
+
+export default {
+  findLinkedTableBlocksInState,
+  getLinkedTableBlockRange,
+  isRangeInsideLinkedTable,
+};

package/src/tables/state/linked-table-state.js

@@ -0,0 +1,68 @@
+/**
+ * Linked-table local editor state.
+ *
+ * Phase 1 uses this to reveal one linked table's raw markdown without forcing
+ * the whole editor into global source mode.
+ */
+
+import { StateEffect, StateField } from '@codemirror/state';
+
+export const revealLinkedTableMarkdownEffect = StateEffect.define();
+export const hideLinkedTableMarkdownEffect = StateEffect.define();
+export const clearLinkedTableMarkdownEffect = StateEffect.define();
+
+function normalizeTableId(value) {
+  const tableId = String(value || '').trim();
+  return tableId || null;
+}
+
+export const linkedTableMarkdownState = StateField.define({
+  create() {
+    return new Set();
+  },
+
+  update(value, tr) {
+    let next = value;
+
+    for (const effect of tr.effects) {
+      if (effect.is(clearLinkedTableMarkdownEffect)) {
+        if (next.size > 0) next = new Set();
+        continue;
+      }
+
+      if (effect.is(revealLinkedTableMarkdownEffect)) {
+        const tableId = normalizeTableId(effect.value?.tableId ?? effect.value);
+        if (tableId && !next.has(tableId)) {
+          next = new Set(next);
+          next.add(tableId);
+        }
+        continue;
+      }
+
+      if (effect.is(hideLinkedTableMarkdownEffect)) {
+        const tableId = normalizeTableId(effect.value?.tableId ?? effect.value);
+        if (tableId && next.has(tableId)) {
+          next = new Set(next);
+          next.delete(tableId);
+        }
+      }
+    }
+
+    return next;
+  },
+});
+
+export function isLinkedTableMarkdownOpen(state, tableId) {
+  const normalized = normalizeTableId(tableId);
+  if (!normalized) return false;
+  const revealed = state.field(linkedTableMarkdownState, false);
+  return !!(revealed && revealed.has(normalized));
+}
+
+export default {
+  linkedTableMarkdownState,
+  revealLinkedTableMarkdownEffect,
+  hideLinkedTableMarkdownEffect,
+  clearLinkedTableMarkdownEffect,
+  isLinkedTableMarkdownOpen,
+};