@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/client/versions/preview-decoration.ts

@@ -0,0 +1,54 @@
+/**
+ * Turning a diff into a canvas overlay (docs/issue/0022 P5).
+ *
+ * The *order* of a diff is not the same as its direction, and which tones may be
+ * painted depends on which side of the comparison the canvas is showing: a
+ * removed cell does not exist in the snapshot that is on screen, so painting it
+ * would tint an empty cell. That rule is the whole reason this is a module.
+ */
+import { versionChangeDirection } from '#contracts'
+import type { WorkbookChange } from '../../types.ts'
+import type { WorkbookDecoration } from '../univer/loader.ts'
+
+/**
+ * Turn a change list into the canvas overlay (PRD v3.3 §7.2): every changed
+ * cell, toned by direction, plus the first changed cell as the focus so
+ * switching what is inspected moves the viewport onto what actually changed.
+ *
+ * A removed cell exists only in the baseline, so it cannot be tinted in this
+ * snapshot; it is counted in the bar instead of being painted nowhere.
+ */
+export function toDecoration(changes: WorkbookChange[], side: 'before' | 'after'): WorkbookDecoration | undefined {
+  const cells: WorkbookDecoration['cells'] = []
+  let focus: WorkbookDecoration['focus']
+  for (const change of changes) {
+    if (change.kind !== 'cell' || change.row === undefined || change.column === undefined) continue
+    const sheetRef = change.sheetId ?? change.sheetName
+    const direction = versionChangeDirection({
+      kind: 'cell',
+      target: '',
+      description: '',
+      row: change.row,
+      column: change.column,
+      ...(change.before === undefined ? {} : { before: change.before }),
+      ...(change.after === undefined ? {} : { after: change.after }),
+    })
+    // A diff is directional, and the canvas shows exactly one of its two sides:
+    //  - showing the newer side, an addition/replacement is paint-able (green /
+    //    amber) and a deletion has no cell here at all;
+    //  - showing the older side — the default when previewing an old Version
+    //    against the current content — it is the other way round, and the cell
+    //    that no longer exists is the red one.
+    // Painting the wrong side's cells would tint empty cells and claim a change
+    // the reader cannot see.
+    const tone = direction === 'add' ? 'add' as const : direction === 'remove' ? 'remove' as const : 'modify' as const
+    const paintable = side === 'after' ? tone !== 'remove' : tone !== 'add'
+    if (!paintable) continue
+    cells.push({ ...(sheetRef === undefined ? {} : { sheetRef }), row: change.row, column: change.column, tone })
+    if (focus === undefined) {
+      focus = { ...(sheetRef === undefined ? {} : { sheetRef }), row: change.row, column: change.column }
+    }
+  }
+  if (cells.length === 0 && focus === undefined) return undefined
+  return { cells, ...(focus === undefined ? {} : { focus }) }
+}

package/src/client/versions/records.ts

@@ -0,0 +1,78 @@
+/**
+ * A stored Version as the panel renders it (docs/issue/0022 P5).
+ *
+ * The history payload and the shared `VersionManager` speak different shapes:
+ * the payload is what the store knows (revisions, steps, lineage), and the row
+ * model is what a person sees. This is that translation, and nothing else — it
+ * is the module PRD 0002 keeps touching, so it is a module rather than twelve
+ * helpers at the bottom of the panel.
+ */
+import { formatVersionTime, type VersionManagerEntry } from '@tita-agent/ui/versions'
+import type { WorkbookHistoryVersion } from '../../types.ts'
+import type { HistoryEntry } from '../transport/workbookApi.ts'
+
+/** The history payload's Version, under the name the panel's rows use. */
+export type HistoryVersion = WorkbookHistoryVersion
+
+/** The shared component formats Version times; re-exported so callers did not have to move. */
+export const formatHistoryTime = formatVersionTime
+
+export function historyVersionsFromEntries(entries: HistoryEntry[]): HistoryVersion[] {
+  return entries.map((entry, index) => ({
+    versionId: `revision:${entry.revision}`,
+    number: index + 1,
+    startRevision: entry.revision,
+    revision: entry.revision,
+    parentRevision: entry.parentRevision ?? Math.max(0, entry.revision - 1),
+    actor: entry.actor,
+    timestamp: entry.timestamp,
+    summary: entry.summary,
+    stepCount: 1,
+    steps: [{ index: 0, opId: entry.opId, type: entry.type as HistoryVersion['steps'][number]['type'], summary: entry.summary }],
+    canPreview: entry.canPreview === true,
+    status: 'final',
+    // A legacy operation-log row is a deliberate step, not session churn.
+    kind: 'named',
+    branch: 'main',
+  }))
+}
+
+/** Shared drawer entry shape (docs/issue/0002 Phase 3 / PRD v3 §7). */
+export function toVersionManagerEntry(version: HistoryVersion, index: number, all: HistoryVersion[]): VersionManagerEntry {
+  const status: VersionManagerEntry['status'] = version.branch === 'superseded'
+    ? 'superseded'
+    : version.status === 'final'
+      ? 'committed'
+      : 'open'
+  const restoredFromNumber = version.restoredFromNumber
+    ?? (version.restoredFromRevision === undefined
+      ? undefined
+      : all.find(candidate => candidate.revision === version.restoredFromRevision)?.number)
+  const restoredFrom = restoredFromNumber === undefined
+    ? undefined
+    : all.find(candidate => candidate.number === restoredFromNumber)
+  return {
+    id: version.versionId,
+    number: version.number ?? all.length - index,
+    revision: version.revision,
+    summary: version.summary,
+    actor: version.actor === 'agent' ? 'agent' : 'user',
+    time: formatHistoryTime(version.timestamp),
+    timestamp: version.timestamp,
+    status,
+    kind: version.kind,
+    ...(restoredFrom === undefined
+      ? (restoredFromNumber === undefined ? {} : { restoredFromNumber })
+      : { restoredFromTime: formatHistoryTime(restoredFrom.timestamp) }),
+    stepCount: version.stepCount,
+    replayable: version.canPreview,
+    steps: version.steps.map(step => ({
+      id: step.opId,
+      index: step.index,
+      label: `Step ${step.index + 1}`,
+      summary: step.summary,
+      ...(step.revision === undefined ? {} : { revision: step.revision }),
+    })),
+    ...(version.intent === undefined ? {} : { intent: version.intent }),
+  }
+}

package/src/client/workspace-host.ts

@@ -0,0 +1,147 @@
+/**
+ * Resident host for the embedded Table workspace.
+ *
+ * The dock renders only the active tab's body (`DockSurface` → `renderTab`), so
+ * switching DSH tabs — or switching conversation sessions — unmounts the pane's
+ * React tree. When the workspace lived in that tree, every re-entry disposed the
+ * Univer engine, re-fetched the whole snapshot and rebuilt the sheet, which is
+ * exactly the "reloads on every visit" the panel used to show.
+ *
+ * The workspace therefore lives in one long-lived container that is created
+ * once and merely *moves* between the pane and an off-screen parking lot. Re-
+ * entering the tab re-parents the existing DOM and React tree, so the editor,
+ * its scroll position, its unsaved drafts and its collaboration stream all
+ * survive. A long stay in the parking lot releases it again, so the engine is
+ * not held for the life of the page either.
+ *
+ * The DOM access and the timer are injected so the adoption/parking bookkeeping
+ * can be tested without a browser (this repository has no DOM test
+ * environment).
+ *
+ * @module dsh-data-table/client/workspace-host
+ */
+
+/** How long a parked workspace is kept warm before it is released. */
+export const PARKED_RELEASE_MS = 10 * 60 * 1000
+
+/** Minimal DOM surface this module needs; injectable for tests. */
+export interface WorkspaceHostEnvironment {
+  /** Create the element that owns the workspace. */
+  createContainer(): HTMLElement
+  /** Create the off-screen element a parked workspace is moved into. */
+  createParkingLot(): HTMLElement
+  /** The document body the parking lot is attached to. */
+  body(): HTMLElement
+  /** Schedule the idle release (injectable so tests stay deterministic). */
+  schedule(callback: () => void, delayMs: number): unknown
+  /** Cancel a scheduled idle release. */
+  cancel(handle: unknown): void
+}
+
+/** Off-screen geometry: keeps the engine's measured size while it is not shown. */
+const PARKED_STYLE = 'position:fixed;left:-20000px;top:0;overflow:hidden;pointer-events:none;contain:strict;'
+const ADOPTED_STYLE = 'width:100%;height:100%;min-width:0;min-height:0;display:flex;flex-direction:column;'
+
+const domEnvironment: WorkspaceHostEnvironment = {
+  createContainer: () => {
+    const element = document.createElement('div')
+    element.setAttribute('data-data-table-workspace', '')
+    return element
+  },
+  createParkingLot: () => {
+    const element = document.createElement('div')
+    element.setAttribute('data-data-table-parked', '')
+    element.style.cssText = `${PARKED_STYLE}width:0;height:0;`
+    return element
+  },
+  body: () => document.body,
+  schedule: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  cancel: handle => { globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>) },
+}
+
+let environment: WorkspaceHostEnvironment = domEnvironment
+let container: HTMLElement | null = null
+let parkingLot: HTMLElement | null = null
+let releaseTimer: unknown = null
+let unmount: (() => void) | null = null
+
+/** Replace the DOM environment (tests only). Resets any resident workspace. */
+export function setWorkspaceHostEnvironment(next: WorkspaceHostEnvironment): void {
+  environment = next
+  releaseTimer = null
+  unmount = null
+  container = null
+  parkingLot = null
+}
+
+/** The resident container, or null when nothing is resident. */
+export function workspaceHostElement(): HTMLElement | null {
+  return container
+}
+
+/** Whether the resident workspace is currently parked off-screen. */
+export function isWorkspaceHostParked(): boolean {
+  return container !== null && container.parentElement === parking()
+}
+
+/**
+ * Put the resident workspace inside `target`, creating it on first use.
+ * @param target - the pane element that should display the workspace.
+ * @param mount - called once per workspace lifetime; may return a disposer.
+ * @returns the resident container.
+ */
+export function adoptWorkspaceHost(target: HTMLElement, mount: (container: HTMLElement) => void | (() => void)): HTMLElement {
+  if (container === null) {
+    container = environment.createContainer()
+    unmount = mount(container) ?? null
+  }
+  cancelRelease()
+  if (container.parentElement === target) return container
+  container.style.cssText = ADOPTED_STYLE
+  target.append(container)
+  return container
+}
+
+/**
+ * Move the resident workspace off-screen without destroying it.
+ *
+ * Its measured size is kept so the engine sees no resize while parked; that is
+ * what makes re-adoption invisible instead of a relayout. The workspace is
+ * released after {@link PARKED_RELEASE_MS} so a tab the user has moved on from
+ * does not pin a whole engine for the life of the page.
+ */
+export function parkWorkspaceHost(): void {
+  if (container === null || container.parentElement === null) return
+  const rect = container.getBoundingClientRect()
+  container.style.cssText = `${PARKED_STYLE}width:${Math.max(Math.round(rect.width), 320)}px;height:${Math.max(Math.round(rect.height), 240)}px;`
+  parking().append(container)
+  cancelRelease()
+  releaseTimer = environment.schedule(() => { releaseTimer = null; disposeWorkspaceHost() }, PARKED_RELEASE_MS)
+}
+
+/** Release the resident workspace, unmounting its React tree. Safe when empty. */
+export function disposeWorkspaceHost(): void {
+  cancelRelease()
+  const dispose = unmount
+  unmount = null
+  container?.remove()
+  parkingLot?.remove()
+  container = null
+  parkingLot = null
+  // Unmount last: the disposer tears down effects that may still touch the DOM.
+  dispose?.()
+}
+
+function cancelRelease(): void {
+  if (releaseTimer === null) return
+  environment.cancel(releaseTimer)
+  releaseTimer = null
+}
+
+function parking(): HTMLElement {
+  if (parkingLot === null || parkingLot.parentElement === null) {
+    parkingLot = environment.createParkingLot()
+    environment.body().append(parkingLot)
+  }
+  return parkingLot
+}

package/src/collaboration-hub.ts

@@ -0,0 +1,83 @@
+/**
+ * In-process collaboration transport for Datasheet.
+ *
+ * This is deliberately small and dependency-free.  It provides the same
+ * server-to-client fan-out seam that a WebSocket/Univer collaboration server
+ * would provide, while keeping the DSH plugin self-contained.  Durable state
+ * still lives in WorkbookManager; the hub is only a live notification layer.
+ */
+
+import type { WorkbookOperation, WorkbookPresence } from './types.ts'
+
+export interface WorkbookCollaborationEvent {
+  workbookId: string
+  operation: WorkbookOperation
+}
+
+type WorkbookCollaborationListener = (event: WorkbookCollaborationEvent) => void
+
+const listeners = new Map<string, Set<WorkbookCollaborationListener>>()
+export const MAX_LISTENERS_PER_WORKBOOK = 64
+
+export interface WorkbookPresenceEvent {
+  workbookId: string
+  presence: WorkbookPresence
+}
+
+type WorkbookPresenceListener = (event: WorkbookPresenceEvent) => void
+
+const presenceListeners = new Map<string, Set<WorkbookPresenceListener>>()
+/** Presence is intentionally capped separately from durable operation streams. */
+export const MAX_PRESENCE_LISTENERS_PER_WORKBOOK = 128
+
+/** Subscribe to committed operations for one workbook. */
+export function subscribeWorkbookCollaboration(workbookId: string, listener: WorkbookCollaborationListener): () => void {
+  const current = listeners.get(workbookId) ?? new Set<WorkbookCollaborationListener>()
+  if (current.size >= MAX_LISTENERS_PER_WORKBOOK) {
+    throw new Error(`工作簿协同连接数已达上限（最多 ${MAX_LISTENERS_PER_WORKBOOK} 个）`)
+  }
+  current.add(listener)
+  listeners.set(workbookId, current)
+  return () => {
+    current.delete(listener)
+    if (current.size === 0 && listeners.get(workbookId) === current) listeners.delete(workbookId)
+  }
+}
+
+/** Fan out a committed operation to currently connected workbook sessions. */
+export function publishWorkbookCollaboration(operation: WorkbookOperation): void {
+  const current = listeners.get(operation.workbookId)
+  if (current === undefined) return
+  const event = { workbookId: operation.workbookId, operation }
+  for (const listener of [...current]) {
+    try {
+      listener(event)
+    } catch {
+      // A disconnected response must not affect persistence or other clients.
+    }
+  }
+}
+
+/** Subscribe to ephemeral selection/editing state for one workbook. */
+export function subscribeWorkbookPresence(workbookId: string, listener: WorkbookPresenceListener): () => void {
+  const current = presenceListeners.get(workbookId) ?? new Set<WorkbookPresenceListener>()
+  if (current.size >= MAX_PRESENCE_LISTENERS_PER_WORKBOOK) {
+    throw new Error(`工作簿 presence 连接数已达上限（最多 ${MAX_PRESENCE_LISTENERS_PER_WORKBOOK} 个）`)
+  }
+  current.add(listener)
+  presenceListeners.set(workbookId, current)
+  return () => {
+    current.delete(listener)
+    if (current.size === 0 && presenceListeners.get(workbookId) === current) presenceListeners.delete(workbookId)
+  }
+}
+
+/** Fan out ephemeral presence without touching WorkbookManager or revision. */
+export function publishWorkbookPresence(presence: WorkbookPresence): void {
+  const current = presenceListeners.get(presence.workbookId)
+  if (current === undefined) return
+  const event = { workbookId: presence.workbookId, presence }
+  for (const listener of [...current]) {
+    try { listener(event) } catch { /* disconnected clients are harmless */ }
+  }
+}

package/src/contract/ids.ts

@@ -0,0 +1,50 @@
+/**
+ * Identifier vocabulary of the workbook repository (docs/issue/0022 P0).
+ *
+ * Pure string work plus one id mint: it knows nothing about the disk, about
+ * Univer, or about Versions as a concept. It is the node half's vocabulary —
+ * the browser addresses ids as opaque strings and never mints a workbook,
+ * worktree or Version id — but nothing here reads or writes anything, so the
+ * split is about who *creates* ids, not about what they are.
+ */
+import { randomUUID } from 'node:crypto'
+import { storageSegment } from '#contracts'
+import { DEFAULT_WORKBOOK } from '../types.ts'
+
+/**
+ * Normalize a workbook id to a safe file name segment.
+ *
+ * The character set is the shared one (`storageSegment`), so a name that survives
+ * in one plugin survives in the next: it keeps 汉字 — the id *is* the file name,
+ * and a newly created workbook is named `yyyymmdd-中文名` (see `storageNameOf` in
+ * `tools/workbook-catalog.ts`) — while spaces, punctuation and path separators
+ * become `-`.
+ *
+ * Deliberately no date prefix and no truncation here: this runs on every lookup,
+ * including ids minted by earlier versions, and "normalizing" an existing id is
+ * renaming someone's file.
+ */
+export function normalizeWorkbookId(id: string): string {
+  const safe = storageSegment(id)
+  return safe.length === 0 ? DEFAULT_WORKBOOK : safe
+}
+
+/** Normalize an isolated worktree id to a safe file-name segment. */
+export function normalizeWorktreeId(id: string): string {
+  const safe = storageSegment(id)
+  return safe.length === 0 ? newWorktreeId() : safe
+}
+
+/** Mint a fresh worktree id, for the callers that do not name one. */
+export function newWorktreeId(): string {
+  return `wt-${randomUUID().slice(0, 8)}`
+}
+
+/**
+ * Id of the Version that continues `previousVersionId`. A continuation keeps
+ * the `user-version:` prefix the store groups by, so it is a Version like any
+ * other rather than a second kind of thing.
+ */
+export function nextContinuationVersionId(workbookId: string, previousVersionId: string): string {
+  return `user-version:${workbookId}:continuation:${previousVersionId.slice(-24)}:${randomUUID().slice(0, 8)}`
+}