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

package/lib/types/client/workspace-host.js

@@ -0,0 +1,124 @@
+/**
+ * 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;
+/** 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 = {
+    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); },
+};
+let environment = domEnvironment;
+let container = null;
+let parkingLot = null;
+let releaseTimer = null;
+let unmount = null;
+/** Replace the DOM environment (tests only). Resets any resident workspace. */
+export function setWorkspaceHostEnvironment(next) {
+    environment = next;
+    releaseTimer = null;
+    unmount = null;
+    container = null;
+    parkingLot = null;
+}
+/** The resident container, or null when nothing is resident. */
+export function workspaceHostElement() {
+    return container;
+}
+/** Whether the resident workspace is currently parked off-screen. */
+export function isWorkspaceHostParked() {
+    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, mount) {
+    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() {
+    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() {
+    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() {
+    if (releaseTimer === null)
+        return;
+    environment.cancel(releaseTimer);
+    releaseTimer = null;
+}
+function parking() {
+    if (parkingLot === null || parkingLot.parentElement === null) {
+        parkingLot = environment.createParkingLot();
+        environment.body().append(parkingLot);
+    }
+    return parkingLot;
+}

package/lib/types/collaboration-hub.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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;
+export declare const MAX_LISTENERS_PER_WORKBOOK = 64;
+export interface WorkbookPresenceEvent {
+    workbookId: string;
+    presence: WorkbookPresence;
+}
+type WorkbookPresenceListener = (event: WorkbookPresenceEvent) => void;
+/** Presence is intentionally capped separately from durable operation streams. */
+export declare const MAX_PRESENCE_LISTENERS_PER_WORKBOOK = 128;
+/** Subscribe to committed operations for one workbook. */
+export declare function subscribeWorkbookCollaboration(workbookId: string, listener: WorkbookCollaborationListener): () => void;
+/** Fan out a committed operation to currently connected workbook sessions. */
+export declare function publishWorkbookCollaboration(operation: WorkbookOperation): void;
+/** Subscribe to ephemeral selection/editing state for one workbook. */
+export declare function subscribeWorkbookPresence(workbookId: string, listener: WorkbookPresenceListener): () => void;
+/** Fan out ephemeral presence without touching WorkbookManager or revision. */
+export declare function publishWorkbookPresence(presence: WorkbookPresence): void;
+export {};

package/lib/types/collaboration-hub.js

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+const listeners = new Map();
+export const MAX_LISTENERS_PER_WORKBOOK = 64;
+const presenceListeners = new Map();
+/** 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, listener) {
+    const current = listeners.get(workbookId) ?? new Set();
+    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) {
+    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, listener) {
+    const current = presenceListeners.get(workbookId) ?? new Set();
+    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) {
+    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/lib/types/contract/ids.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function normalizeWorkbookId(id: string): string;
+/** Normalize an isolated worktree id to a safe file-name segment. */
+export declare function normalizeWorktreeId(id: string): string;
+/** Mint a fresh worktree id, for the callers that do not name one. */
+export declare function newWorktreeId(): string;
+/**
+ * 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 declare function nextContinuationVersionId(workbookId: string, previousVersionId: string): string;

package/lib/types/contract/ids.js

@@ -0,0 +1,46 @@
+/**
+ * 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.js";
+/**
+ * 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) {
+    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) {
+    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() {
+    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, previousVersionId) {
+    return `user-version:${workbookId}:continuation:${previousVersionId.slice(-24)}:${randomUUID().slice(0, 8)}`;
+}

package/lib/types/contract/mutations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The snapshot mutator: one DSH operation in, the rewritten snapshot out
+ * (docs/issue/0022 P0/P1).
+ *
+ * Pure and Univer-free — it is the model's own answer to "what does this
+ * operation mean", and `store/read.ts` replays operations through it when a
+ * workbook's snapshot is older than its revision. It lives in `contract/`
+ * rather than in `store/` precisely because it is not about the disk: moving
+ * the read path into the store without it would have made `store/` import
+ * *up* into `workbook-manager`, which the architecture guard forbids.
+ */
+import { type WorkbookOperation, type WorkbookOperationPayload, type WorkbookOperationType, type WorkbookRange } from '../types.ts';
+import { type WorkbookSnapshot } from './snapshots.ts';
+/** Apply one DSH operation to a Univer-compatible snapshot. */
+export declare function applyWorkbookOperation(snapshot: unknown, operation: WorkbookOperation): unknown;
+/** Read a rectangular range as a compact 2D value matrix. */
+export declare function validateSnapshotBounds(value: unknown): void;
+/**
+ * Mirrored by the browser projection's `applyAppendRows`, which runs the same
+ * check against live Univer state. The hint names `headerRowIndex` because that
+ * is what unblocks a report sheet whose real header is not row 0.
+ */
+export declare function formatCells(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined, style: WorkbookOperationPayload['style']): void;
+/** Resolve data-dependent children before an operation is persisted/replayed. */
+export declare function resolveOperationPayload(snapshot: unknown, type: WorkbookOperationType, payload: WorkbookOperationPayload): WorkbookOperationPayload;