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

package/src/client/surface-context.ts

@@ -0,0 +1,123 @@
+import type { SurfaceSelection } from '@tita-agent/dsh-surface-bridge'
+
+export const DATA_SHEET_SURFACE_ID = 'data-sheet'
+
+export interface DataSheetFocusTarget {
+  readonly workbookId: string
+  readonly sheetId: string
+  readonly startRow: number
+  readonly startColumn: number
+  readonly endRow: number
+  readonly endColumn: number
+}
+
+export interface DataSheetRangeContext extends Omit<DataSheetFocusTarget, 'workbookId'> {
+  readonly sheetName: string
+  readonly values: readonly (readonly unknown[])[]
+}
+
+export interface DataSheetSelectionContext {
+  readonly workbookId: string
+  readonly workbookName: string
+  readonly revision: number
+  readonly documentRevision: number
+  readonly ranges: readonly DataSheetRangeContext[]
+}
+
+/** Keep source-specific focus data opaque to the bridge, but stable in transcript metadata. */
+export function dataSheetFocusId(target: DataSheetFocusTarget): string {
+  return JSON.stringify(target)
+}
+
+/** Decode a focus id emitted by this source. */
+export function dataSheetFocusTargetOf(value: string): DataSheetFocusTarget | undefined {
+  try {
+    const target = JSON.parse(value) as Partial<DataSheetFocusTarget>
+    if (typeof target.workbookId !== 'string' || typeof target.sheetId !== 'string') return undefined
+    for (const key of ['startRow', 'startColumn', 'endRow', 'endColumn'] as const) {
+      if (!Number.isSafeInteger(target[key]) || target[key]! < 0) return undefined
+    }
+    return target as DataSheetFocusTarget
+  } catch {
+    return undefined
+  }
+}
+
+function columnName(index: number): string {
+  let value = index + 1
+  let name = ''
+  while (value > 0) {
+    const remainder = (value - 1) % 26
+    name = String.fromCharCode(65 + remainder) + name
+    value = Math.floor((value - 1) / 26)
+  }
+  return name
+}
+
+function cellAddress(row: number, column: number): string {
+  return `${columnName(column)}${row + 1}`
+}
+
+function rangeAddress(range: DataSheetRangeContext): string {
+  const start = cellAddress(range.startRow, range.startColumn)
+  const end = cellAddress(range.endRow, range.endColumn)
+  return `${range.sheetName}!${start === end ? start : `${start}:${end}`}`
+}
+
+function cellText(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  try { return JSON.stringify(value) ?? '' } catch { return String(value) }
+}
+
+function previewText(values: readonly (readonly unknown[])[]): string | undefined {
+  if (values.length === 0) return undefined
+  const rendered = values.map(row => row.map(cellText).join('\t')).join('\n').slice(0, 2_000)
+  return rendered.length === 0 ? undefined : rendered
+}
+
+/** Project the active Univer ranges into the bridge's shared context vocabulary. */
+export function projectDataSheetSelection(input: DataSheetSelectionContext): SurfaceSelection | null {
+  const ranges = input.ranges.filter(range => range.startRow <= range.endRow && range.startColumn <= range.endColumn)
+  if (ranges.length === 0) return null
+  const count = ranges.reduce((total, range) => total
+    + (range.endRow - range.startRow + 1) * (range.endColumn - range.startColumn + 1), 0)
+  const items = ranges.slice(0, 40).map(range => {
+    const address = rangeAddress(range)
+    return {
+      id: dataSheetFocusId({ workbookId: input.workbookId, ...range }),
+      type: 'range',
+      label: address,
+      ...(previewText(range.values) === undefined ? {} : { text: previewText(range.values) }),
+      attributes: {
+        workbookId: input.workbookId,
+        sheetId: range.sheetId,
+        sheetName: range.sheetName,
+        address,
+        startRow: range.startRow,
+        startColumn: range.startColumn,
+        endRow: range.endRow,
+        endColumn: range.endColumn,
+      },
+    }
+  })
+  const labels = ranges.map(rangeAddress)
+  const summary = ranges.length === 1
+    ? `已选中 ${labels[0]}，共 ${count} 个单元格`
+    : `已选中 ${ranges.length} 个区域，共 ${count} 个单元格`
+  const note = `工作簿 ID：${input.workbookId}；选区：${labels.join('、')}。条目文本最多预览每个区域前 10 行 × 20 列；完整数据用 workbook_read(workbookId="${input.workbookId}", target={kind:"range", sheetId, range}) 读取。写入前先读取最新 revision，再用 workbook_edit。`
+  return {
+    source: DATA_SHEET_SURFACE_ID,
+    revision: input.revision,
+    count,
+    countLabel: `${count} 个单元格`,
+    title: 'Table',
+    summary,
+    items,
+    ...(ranges.length > items.length ? { truncated: true } : {}),
+    resource: { name: input.workbookId, display: input.workbookName, version: input.documentRevision },
+    notes: [note],
+    capabilities: [`使用 workbook_read / workbook_edit 操作工作簿 ${input.workbookId}；写入时传该 id 和最新 revision。`],
+  }
+}

package/src/client/surface-control.ts

@@ -0,0 +1,13 @@
+/** One live workbook view can honour focus requests from the shared bridge chip. */
+let focusHandler: ((itemId: string) => void) | undefined
+
+export function registerDataSheetFocusHandler(handler: (itemId: string) => void): () => void {
+  focusHandler = handler
+  return () => {
+    if (focusHandler === handler) focusHandler = undefined
+  }
+}
+
+export function focusDataSheetItem(itemId: string): void {
+  focusHandler?.(itemId)
+}

package/src/client/transport/workbookApi.ts

@@ -0,0 +1,355 @@
+import type {
+  WorkbookLocalChange,
+  WorkbookOperation,
+  WorkbookSummary,
+  WorkbookWorktree,
+  WorkbookWorktreeSummary,
+  WorkbookChange,
+  WorkbookPresencePayload,
+  WorkbookHistoryVersion,
+} from '../../types.ts'
+
+export class HttpStatusError extends Error {
+  constructor(readonly status: number, message: string, readonly code?: string, readonly details?: unknown) {
+    super(message)
+    this.name = 'HttpStatusError'
+  }
+}
+
+export class RevisionConflictError extends HttpStatusError {
+  constructor(message = 'workbook revision conflict', details?: unknown) {
+    super(409, message, 'REVISION_CONFLICT', details)
+    this.name = 'RevisionConflictError'
+  }
+}
+
+const SESSION_STORAGE_KEY = 'data-sheet.session-id'
+let cachedSessionId: string | null = null
+
+/**
+ * The DSH Session whose project this page reads and writes.
+ *
+ * Set once when the panel mounts (the sidebar hands its Session id to the body)
+ * or, for the standalone page, read from its URL. Every workbook path is
+ * resolved by the Host inside that Session's project —
+ * `<project>/storages/data-table` — so a request that names the wrong Session
+ * reads and writes another project's workbooks. A request that names **no**
+ * Session keeps the pre-project per-user store instead, which is right for a
+ * script and wrong for a page: the panel always sets this.
+ */
+let dshSessionId: string | null = null
+
+/** Tell the transport which DSH Session this page belongs to. */
+export function setDshSessionId(id: string | undefined): void {
+  dshSessionId = id === undefined || id.length === 0 ? null : id
+}
+
+/** The Session this page is bound to, when it is bound to one. */
+export function currentDshSessionId(): string | null {
+  return dshSessionId
+}
+
+/** Route browser requests through the official Electron Connection carrier. */
+export function dataSheetClientPath(path: string): string {
+  const transport = (globalThis as { __DSH_TRANSPORT__?: { ownsHost?: boolean } }).__DSH_TRANSPORT__
+  return transport?.ownsHost === true
+    ? `/api/data-sheet?path=${encodeURIComponent(path)}`
+    : path
+}
+
+/** Stable per-tab scope used by worktree APIs and Host audit logs. */
+export function dataSheetSessionId(): string {
+  if (cachedSessionId !== null) return cachedSessionId
+  try {
+    const existing = window.sessionStorage.getItem(SESSION_STORAGE_KEY)
+    if (existing !== null && existing.trim().length > 0) {
+      cachedSessionId = existing
+      return existing
+    }
+    const generated = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : `${Date.now()}-${Math.random().toString(36).slice(2)}`
+    window.sessionStorage.setItem(SESSION_STORAGE_KEY, generated)
+    cachedSessionId = generated
+    return generated
+  } catch {
+    cachedSessionId = `ephemeral-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    return cachedSessionId
+  }
+}
+
+/**
+ * The live collaboration stream for one workbook.
+ *
+ * `EventSource` cannot set the `x-dsh-session` header every other call carries,
+ * so the Session — which decides *which project's* workbook this is — travels as
+ * a query parameter it can carry. The `session` parameter is a different thing:
+ * this browser tab's own id, used for presence and worktrees.
+ *
+ * @param workbookId - Workbook to watch.
+ * @param after - Revision to resume from.
+ * @returns a same-origin path, ready for `dataSheetClientPath`.
+ */
+export function collaborationStreamPath(workbookId: string, after: number): string {
+  const project = currentDshSessionId()
+  const scope = project === null ? '' : `&sessionId=${encodeURIComponent(project)}`
+  return `/data-sheet/workbook/${encodeURIComponent(workbookId)}/collaboration?after=${after}`
+    + `&session=${encodeURIComponent(dataSheetSessionId())}${scope}`
+}
+
+/**
+ * The standalone page for one workbook.
+ *
+ * A new tab has no sidebar to hand it a Session id, so the project travels in
+ * the URL: without it the page resolves against the sandbox policy root and
+ * could open another project's workbook.
+ *
+ * @param workbookId - Workbook to open in a plain browser document.
+ * @returns a same-origin path.
+ */
+export function standaloneWorkbookPath(workbookId: string): string {
+  const project = currentDshSessionId()
+  return `/data-sheet/workbook/${encodeURIComponent(workbookId)}/view`
+    + (project === null ? '' : `?sessionId=${encodeURIComponent(project)}`)
+}
+
+async function requestJson<T>(path: string, init: RequestInit = {}): Promise<T> {
+  const headers = new Headers(init.headers)
+  headers.set('accept', 'application/json')
+  headers.set('x-data-sheet-session', dataSheetSessionId())
+  // Which *project* the Host should resolve the path inside. Distinct from the
+  // header above, which is this browser tab's own id for worktrees and presence.
+  if (dshSessionId !== null) headers.set('x-dsh-session', dshSessionId)
+  if (init.body !== undefined && !headers.has('content-type')) headers.set('content-type', 'application/json')
+  let response: Response | null = null
+  let networkError: unknown = null
+  // GETs and writes carrying an opId are safe to retry: the Host's idempotency
+  // check makes a lost response indistinguishable from a successful retry.
+  const retryable = init.method === undefined || init.method === 'GET' || init.method === 'HEAD'
+    || typeof init.body === 'string' && init.body.includes('"opId"')
+  for (let attempt = 0; attempt < (retryable ? 3 : 1); attempt += 1) {
+    try {
+      response = await fetch(dataSheetClientPath(path), { ...init, headers })
+      networkError = null
+      break
+    } catch (error) {
+      networkError = error
+      if (attempt + 1 < (retryable ? 3 : 1)) await new Promise(resolve => window.setTimeout(resolve, 150 * (attempt + 1)))
+    }
+  }
+  if (response === null) {
+    const detail = networkError instanceof Error ? networkError.message : ''
+    throw new HttpStatusError(0, detail === 'Failed to fetch' ? '网络请求失败，请确认 DSH 服务仍在运行后重试' : (detail || '网络请求失败'), 'NETWORK_ERROR', { detail })
+  }
+  let body: unknown = null
+  try { body = await response.json() } catch { /* non-json host/proxy failure */ }
+  if (!response.ok) {
+    const record = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {}
+    const message = typeof record.error === 'string' ? record.error
+      : typeof record.message === 'string' ? record.message
+        : `${response.status} ${response.statusText || '请求失败'}`
+    const code = typeof record.code === 'string' ? record.code : undefined
+    if (response.status === 409 || code === 'REVISION_CONFLICT') throw new RevisionConflictError(message, body)
+    throw new HttpStatusError(response.status, message, code, body)
+  }
+  return body as T
+}
+
+export interface WorkbookEnvelope {
+  ok?: boolean
+  workbookId?: string
+  revision?: number
+  updatedAt?: string
+  snapshot?: object
+}
+
+export interface ChangesEnvelope {
+  revision?: number
+  operations?: WorkbookOperation[]
+  requiresSnapshot?: boolean
+  snapshot?: object
+}
+
+export interface HistoryEntry {
+  opId: string
+  revision: number
+  parentRevision?: number
+  actor: 'agent' | 'user'
+  type: string
+  timestamp: string
+  summary: string
+  canPreview?: boolean
+}
+
+export interface HistoryEnvelope {
+  entries?: HistoryEntry[]
+  versions?: WorkbookHistoryVersion[]
+  checkpoints?: number[]
+  revision?: number
+}
+
+export interface HistoryDiffEnvelope {
+  workbookId?: string
+  from?: number
+  to?: number
+  changes?: WorkbookChange[]
+  /** True when the server stopped at its diff limit, so the counts are a floor. */
+  truncated?: boolean
+}
+
+export interface WorkbookMutationEnvelope {
+  workbook?: {
+    id: string
+    name: string
+    sheets?: WorkbookSummary['sheets']
+    updatedAt?: string
+  }
+}
+
+export async function fetchWorkbook(id: string): Promise<WorkbookEnvelope> {
+  const value = await requestJson<WorkbookEnvelope | object>(`/data-sheet/workbook/${encodeURIComponent(id)}.json`)
+  if (typeof value === 'object' && value !== null && 'snapshot' in value) return value as WorkbookEnvelope
+  return { ok: true, workbookId: id, revision: 0, snapshot: value as object }
+}
+
+/** One entry of the project file chooser's listing; mirrors the Host's shape. */
+export interface ProjectFileEntry {
+  name: string
+  path: string
+  type: 'file' | 'directory'
+  size: number
+  createdAt: string
+  modifiedAt: string
+}
+
+/** One directory of `<project>/storages`, with sizes and dates. */
+export async function fetchProjectFiles(directory: string): Promise<{ directory: string; entries: ProjectFileEntry[]; truncated?: number }> {
+  return requestJson(`/data-sheet/project-files.json?dir=${encodeURIComponent(directory)}`)
+}
+
+/**
+ * Read one file the chooser listed.
+ *
+ * The browser cannot open a path, so the Host reads it and the bytes arrive here
+ * as a buffer, ready for the import pipeline that already existed.
+ */
+export async function readProjectFile(path: string): Promise<{ name: string; data: ArrayBuffer }> {
+  const headers = new Headers({ accept: 'application/octet-stream' })
+  if (dshSessionId !== null) headers.set('x-dsh-session', dshSessionId)
+  const response = await fetch(dataSheetClientPath(`/data-sheet/project-file.json?path=${encodeURIComponent(path)}`), { headers })
+  if (!response.ok) {
+    const body = await response.json().catch(() => null) as { error?: unknown } | null
+    throw new HttpStatusError(response.status, typeof body?.error === 'string' ? body.error : `读取文件失败：${response.status}`)
+  }
+  const encoded = response.headers.get('x-file-name')
+  const name = encoded === null ? (path.split('/').pop() ?? path) : decodeURIComponent(encoded)
+  return { name, data: await response.arrayBuffer() }
+}
+
+export async function fetchWorkbooks(): Promise<{ workbooks?: WorkbookSummary[] }> {
+  return requestJson('/data-sheet/workbooks.json')
+}
+
+export async function createWorkbook(name: string): Promise<WorkbookMutationEnvelope> {
+  return requestJson('/data-sheet/workbooks.json', {
+    method: 'POST',
+    body: JSON.stringify({ action: 'create', name }),
+  })
+}
+
+export async function renameWorkbook(id: string, name: string): Promise<WorkbookMutationEnvelope> {
+  return requestJson('/data-sheet/workbooks.json', {
+    method: 'POST',
+    body: JSON.stringify({ action: 'rename', workbookId: id, name }),
+  })
+}
+
+export async function fetchChanges(id: string, after: number): Promise<ChangesEnvelope> {
+  return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/changes?after=${after}`)
+}
+
+export async function fetchHistory(id: string): Promise<HistoryEnvelope> {
+  return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history`)
+}
+
+export interface HistorySnapshotEnvelope {
+  revision?: number
+  snapshot?: object
+  step?: number
+  stepCount?: number
+  /** True when the Step's change list stopped at the server's limit. */
+  truncated?: boolean
+  /**
+   * What the requested Step changed. Present for Step previews, so the canvas
+   * can locate and tint the cells instead of leaving the reader to find them
+   * (PRD v3.3 §7.2).
+   */
+  changes?: WorkbookChange[]
+}
+
+export async function fetchHistorySnapshot(id: string, revision: number, step?: number): Promise<HistorySnapshotEnvelope> {
+  const query = step === undefined ? `revision=${revision}` : `revision=${revision}&step=${step}`
+  return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history?${query}`)
+}
+
+export async function fetchHistoryDiff(id: string, from: number, to: number): Promise<HistoryDiffEnvelope> {
+  return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history/diff?from=${from}&to=${to}`)
+}
+
+export async function rollbackWorkbook(id: string, targetRevision: number, baseRevision: number, summary?: string): Promise<{ revision?: number }> {
+  return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/rollback`, {
+    method: 'POST',
+    body: JSON.stringify({ targetRevision, baseRevision, ...(summary === undefined ? {} : { summary }) }),
+  })
+}
+
+export async function deleteWorkbook(id: string): Promise<void> {
+  await requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}.json?action=delete`, { method: 'POST', body: JSON.stringify({ confirm: true }) })
+}
+
+export interface SaveResult {
+  revision: number
+  operation?: WorkbookOperation
+  rebasedOperations?: WorkbookOperation[]
+}
+
+export async function saveOperationChanges(id: string, changes: WorkbookLocalChange[], baseRevision: number, opId: string, version?: { id: string; status: 'open' | 'final' }): Promise<SaveResult | null> {
+  const operation = changes.length === 1 ? changes[0] : { type: 'batch' as const, payload: { operations: changes } }
+  const body = JSON.stringify({ type: operation.type, payload: operation.payload, actor: 'user', baseRevision, opId, ...(version === undefined ? {} : { versionId: version.id, versionStatus: version.status }) })
+  return requestJson<SaveResult | null>(`/data-sheet/workbook/${encodeURIComponent(id)}/operations`, {
+    method: 'POST',
+    ...(body.length <= 60 * 1024 ? { keepalive: true } : {}),
+    body,
+  })
+}
+
+export interface SnapshotSaveOptions {
+  /** Named save: the Version gets this summary and closes the session. */
+  summary?: string
+  /** Session Step: joins the open user Version (PRD v3.1 §4). */
+  versionId?: string
+  versionStatus?: 'open' | 'final'
+  versionKind?: 'named' | 'auto'
+}
+
+export async function saveSnapshot(id: string, snapshotData: unknown, baseRevision: number, opId: string, options: SnapshotSaveOptions = {}): Promise<SaveResult | null> {
+  return requestJson<SaveResult | null>(`/data-sheet/workbook/${encodeURIComponent(id)}.json`, {
+    method: 'POST',
+    body: JSON.stringify({
+      snapshot: snapshotData,
+      baseRevision,
+      opId,
+      ...(options.summary === undefined ? {} : { versionSummary: options.summary }),
+      ...(options.versionId === undefined ? {} : { versionId: options.versionId }),
+      ...(options.versionStatus === undefined ? {} : { versionStatus: options.versionStatus }),
+      ...(options.versionKind === undefined ? {} : { versionKind: options.versionKind }),
+    }),
+  })
+}
+
+export async function publishPresence(workbookId: string, presence: WorkbookPresencePayload): Promise<void> {
+  await requestJson(`/data-sheet/workbook/${encodeURIComponent(workbookId)}/presence`, {
+    method: 'POST',
+    body: JSON.stringify(presence),
+  })
+}

package/src/client/univer/SheetView.module.css

@@ -0,0 +1,110 @@
+.toolRow {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  width: 100%;
+}
+
+.toolLine {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  font-size: 12px;
+  opacity: 0.8;
+}
+
+.toolName {
+  font-weight: 600;
+}
+
+.toolState {
+  opacity: 0.7;
+}
+
+.view {
+  display: flex;
+  flex-direction: column;
+  /* The inline tool row has an auto-height parent, where `height: 100%`
+     resolves to auto and would collapse the flex body to 0; floor the
+     sheet height so the embedded table always has room. The rail panel
+     (definite-height parent) still fills via `height: 100%`. */
+  height: 100%;
+  min-height: 320px;
+  border: 1px solid var(--tita-line);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--tita-surface);
+}
+
+.bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--tita-line);
+  font-size: 12px;
+  flex-shrink: 0;
+}
+
+.title {
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dimensions {
+  opacity: 0.65;
+  margin-right: auto;
+}
+
+.button {
+  padding: 2px 10px;
+  border: 1px solid var(--tita-line-strong);
+  border-radius: 6px;
+  background: transparent;
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.button:hover {
+  background: var(--tita-surface-muted);
+}
+
+.body {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+}
+
+.hint {
+  padding: 14px;
+  font-size: 12px;
+  color: var(--tita-ink-muted);
+  text-align: center;
+}
+
+.hintSub {
+  margin-top: 4px;
+  opacity: 0.7;
+}
+
+.univer {
+  position: absolute;
+  inset: 0;
+  height: 100%;
+  width: 100%;
+}
+
+.toggle {
+  padding: 3px 10px;
+  border: 1px solid var(--tita-line-strong);
+  border-radius: 6px;
+  background: transparent;
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.toggle:hover {
+  background: var(--tita-surface-muted);
+}

package/src/client/univer/StandaloneWorkbookPage.module.css

@@ -0,0 +1,8 @@
+.root {
+  width: 100vw;
+  height: 100vh;
+  min-width: 760px;
+  min-height: 520px;
+  overflow: hidden;
+  background: var(--tita-canvas);
+}

package/src/client/univer/StandaloneWorkbookPage.tsx

@@ -0,0 +1,15 @@
+import { WorkbookWorkspace } from '../SheetPanel.tsx'
+import styles from './StandaloneWorkbookPage.module.css'
+
+export interface StandaloneWorkbookPageProps {
+  workbookId: string
+}
+
+/** Full-browser workbook workspace. It deliberately reuses the embedded controller. */
+export function StandaloneWorkbookPage({ workbookId }: StandaloneWorkbookPageProps) {
+  return (
+    <main className={styles.root}>
+      <WorkbookWorkspace open standalone initialWorkbookId={workbookId} />
+    </main>
+  )
+}