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

package/lib/types/client/SheetToggle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Session-header toggle for dsh-data-table: the top-right entry
+ * button flipping the right sheet column (AppFrame `details`).
+ * @module dsh-data-table/client/SheetToggle
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+type ToggleProps = PropsRuntime<'conversation.session.header.utilities'> & {
+    /** Bound toggle action (registration inject). */
+    toggleSheet: () => void;
+    /** Reopens the layout column after a session switch when the feature was open. */
+    ensureSheetOpen: () => void;
+};
+/**
+ * Header utility button: opens/closes the sheet column (top-right corner).
+ * @param props - standard session header utility share.
+ */
+export declare function SheetToggle({ toggleSheet, ensureSheetOpen }: ToggleProps): import("react").JSX.Element;
+export {};

package/lib/types/client/SheetToggle.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Session-header toggle for dsh-data-table: the top-right entry
+ * button flipping the right sheet column (AppFrame `details`).
+ * @module dsh-data-table/client/SheetToggle
+ */
+import { useEffect } from 'react';
+import { useSheetOpen } from "./store.js";
+import styles from './SheetToggle.module.css';
+/** Small spreadsheet glyph: a header row plus a quiet 2×3 cell grid. */
+function SheetIcon() {
+    return (_jsxs("svg", { width: "14", height: "14", viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", focusable: "false", children: [_jsx("rect", { x: "1.75", y: "2.25", width: "12.5", height: "11.5", rx: "2", stroke: "currentColor", strokeWidth: "1.25" }), _jsx("path", { d: "M2.25 5.75H13.75", stroke: "currentColor", strokeWidth: "1.25" }), _jsx("path", { d: "M5.75 5.75V13.25M10.25 5.75V13.25", stroke: "currentColor", strokeWidth: "1.1" }), _jsx("path", { d: "M3.5 3.65H12", stroke: "currentColor", strokeWidth: "1.1", strokeLinecap: "round", opacity: "0.55" })] }));
+}
+/**
+ * Header utility button: opens/closes the sheet column (top-right corner).
+ * @param props - standard session header utility share.
+ */
+export function SheetToggle({ toggleSheet, ensureSheetOpen }) {
+    const open = useSheetOpen();
+    const label = open ? '关闭 Table' : '打开 Table';
+    useEffect(() => {
+        if (open)
+            ensureSheetOpen();
+    }, [open, ensureSheetOpen]);
+    return (_jsxs("button", { type: "button", className: styles.toggle, "data-open": open, "aria-label": label, "aria-pressed": open, title: label, onClick: toggleSheet, children: [_jsx("span", { className: styles.icon, "aria-hidden": "true", children: _jsx(SheetIcon, {}) }), _jsx("span", { className: styles.label, children: open ? '关闭' : 'Table' })] }));
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser half of dsh-data-table.
+ *
+ * The workbook is a first-class extension of DSH's official right Sidebar:
+ * the tab type is registered in `sidebarRightTabs`, while the body is mounted
+ * through the keyed `sidebar.right.pane.tab` seat. Keeping those two steps
+ * separate means the plugin never reaches into the Sidebar's layout store and
+ * can be published to the upstream datastudio/dsh extension surface.
+ * @module dsh-data-table/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Required services for the official two-stage Sidebar extension path. */
+export declare const inject: readonly ["slots", "sidebarRightTabs", "sidebarRight", "surfaceBridge"];
+/** Register the type and its keyed body; both registrations are disposable. */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/index.js

@@ -0,0 +1,110 @@
+/**
+ * Browser half of dsh-data-table.
+ *
+ * The workbook is a first-class extension of DSH's official right Sidebar:
+ * the tab type is registered in `sidebarRightTabs`, while the body is mounted
+ * through the keyed `sidebar.right.pane.tab` seat. Keeping those two steps
+ * separate means the plugin never reaches into the Sidebar's layout store and
+ * can be published to the upstream datastudio/dsh extension surface.
+ * @module dsh-data-table/client
+ */
+import { startSurfaceOperationLoop } from '@tita-agent/dsh-surface-bridge/client/loop';
+import { Table2 } from '@tita-agent/ui/icons';
+import { createElement, useEffect, useLayoutEffect, useRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { WorkbookWorkspace } from "./SheetPanel.js";
+import { setSheetVisible, useSheetVisible } from "./store.js";
+import { adoptWorkspaceHost, parkWorkspaceHost } from "./workspace-host.js";
+import { setDshSessionId } from "./transport/workbookApi.js";
+import { DATA_SHEET_SURFACE_ID } from "./surface-context.js";
+import { focusDataSheetItem } from "./surface-control.js";
+import styles from './SheetPanel.module.css';
+/** This package's identity in the official right-Sidebar registry. */
+const DATA_SHEET_ID = 'dsh-data-table';
+const DATA_SHEET_KIND = 'data-sheet';
+/** Stage one: describe the page type and its entry in the official guide. */
+function dataSheetDefinition() {
+    return {
+        id: DATA_SHEET_ID,
+        kind: DATA_SHEET_KIND,
+        priority: 'extension',
+        title: () => 'Table',
+        guide: [{ id: `${DATA_SHEET_ID}-guide`, order: 45, title: () => 'Table', icon: Table2 }],
+    };
+}
+/**
+ * The resident workspace: one React tree for the whole page life.
+ *
+ * `open` is true because the workspace stays live while parked off-screen;
+ * `visible` carries the pane's real visibility to the few behaviours that must
+ * be tied to it (the window-level save shortcut).
+ */
+function ResidentWorkspace({ bridge }) {
+    const visible = useSheetVisible();
+    return createElement(WorkbookWorkspace, { open: true, visible, bridge });
+}
+/**
+ * Create the workspace root; called once per workspace lifetime.
+ * @returns the disposer that releases the React tree again.
+ */
+function mountResidentWorkspace(container, bridge) {
+    const root = createRoot(container);
+    root.render(createElement(ResidentWorkspace, { bridge }));
+    return () => { root.unmount(); };
+}
+/**
+ * Stage two: render the workbook for the active right-Sidebar tab.
+ *
+ * The pane body is only a frame: the dock unmounts it whenever another tab
+ * becomes active, so the workspace itself is adopted from a resident container
+ * instead of being rendered here. That is what stops a tab switch from
+ * disposing the Univer engine and reloading the workbook.
+ */
+function DataSheetTab({ sessionId, useTabInfo, bridge }) {
+    const { tab } = useTabInfo();
+    const frameRef = useRef(null);
+    // Bind the transport to this Session's project for as long as the tab exists:
+    // every workbook read and write resolves to `<project>/storages/data-table`.
+    useEffect(() => {
+        setDshSessionId(sessionId);
+        return () => { setDshSessionId(undefined); };
+    }, [sessionId]);
+    // Layout effect: its cleanup runs while the pane DOM is still connected, so
+    // the workspace can be moved out before the browser reports a 0x0 resize.
+    useLayoutEffect(() => {
+        const frame = frameRef.current;
+        if (frame === null)
+            return;
+        adoptWorkspaceHost(frame, container => mountResidentWorkspace(container, bridge));
+        return () => { parkWorkspaceHost(); };
+    }, [bridge]);
+    useEffect(() => {
+        setSheetVisible(tab.visible);
+        bridge.setVisible(DATA_SHEET_SURFACE_ID, tab.visible);
+        if (!tab.visible)
+            return;
+        const stop = startSurfaceOperationLoop(sessionId, DATA_SHEET_SURFACE_ID, bridge);
+        return () => {
+            stop();
+            bridge.setVisible(DATA_SHEET_SURFACE_ID, false);
+            setSheetVisible(false);
+        };
+    }, [bridge, sessionId, tab.visible]);
+    return createElement('div', { ref: frameRef, className: styles.sidebarTab, 'data-data-table-frame': '' });
+}
+/** Required services for the official two-stage Sidebar extension path. */
+export const inject = ['slots', 'sidebarRightTabs', 'sidebarRight', 'surfaceBridge'];
+/** Register the type and its keyed body; both registrations are disposable. */
+export function apply(ctx) {
+    const bridge = ctx.surfaceBridge;
+    ctx.effect(() => ctx.sidebarRightTabs.register(dataSheetDefinition()), 'data-sheet: right Sidebar type');
+    ctx.effect(() => bridge.registerContext({
+        id: DATA_SHEET_SURFACE_ID,
+        label: 'Table',
+        icon: Table2,
+        order: 20,
+        reveal: () => { ctx.sidebarRight.openTab(DATA_SHEET_KIND); },
+        focusItem: focusDataSheetItem,
+    }), 'data-sheet: composer context source');
+    ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({ name: 'sidebar.right.pane.tab', key: DATA_SHEET_ID, inject: () => ({ bridge }) }, DataSheetTab)), 'data-sheet: right Sidebar body');
+}

package/lib/types/client/persistence/changes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deciding what may be applied from elsewhere (docs/issue/0022 P5).
+ *
+ * A remote operation arriving while the user has unsaved local edits is the one
+ * genuinely concurrent case in this plugin: either the operation touches
+ * different cells and can be applied on top, or it overlaps and the pane has to
+ * fall back to a snapshot reload. These are the predicates that decide.
+ */
+import type { WorkbookLocalChange, WorkbookOperation } from '../../types.ts';
+/** Return cell coordinates for the subset that can be safely rebased live. */
+export declare function operationCellKeys(operation: WorkbookOperation, target?: Set<string>): Set<string> | null;
+export declare function canApplyRemoteWhileEditing(operation: WorkbookOperation, snapshotFallback: boolean): boolean;
+export declare function coalesceLocalChanges(changes: WorkbookLocalChange[]): WorkbookLocalChange[];
+/** Keep the Univer snapshot name aligned with the Datasheet workbook name. */
+export declare function withWorkbookName(snapshot: object, name: string): object;

package/lib/types/client/persistence/changes.js

@@ -0,0 +1,51 @@
+/** Return cell coordinates for the subset that can be safely rebased live. */
+export function operationCellKeys(operation, target = new Set()) {
+    if (operation.type === 'update_cells') {
+        const sheetId = operation.payload.sheetId ?? operation.payload.sheetName;
+        if (sheetId === undefined || operation.payload.cells === undefined || operation.payload.cells.length === 0)
+            return null;
+        for (const cell of operation.payload.cells)
+            target.add(`${sheetId}:${cell.row}:${cell.column}`);
+        return target;
+    }
+    if (operation.type === 'batch') {
+        const children = operation.payload.operations ?? [];
+        if (children.length === 0)
+            return null;
+        for (const child of children) {
+            const childKeys = operationCellKeys({ ...operation, type: child.type, payload: child.payload }, target);
+            if (childKeys === null)
+                return null;
+        }
+        return target;
+    }
+    return null;
+}
+export function canApplyRemoteWhileEditing(operation, snapshotFallback) {
+    // The Host already serializes cell operations and applies the later
+    // revision to the latest snapshot. Keep all cell-only operations visible in
+    // the canvas; the pending local changes are replayed immediately after the
+    // remote projection and are then submitted as the later revision — which is
+    // why this needs no view of them. It used to take them and `void` them.
+    if (snapshotFallback)
+        return false;
+    return operationCellKeys(operation) !== null;
+}
+export function coalesceLocalChanges(changes) {
+    const sheets = new Map();
+    for (const change of changes) {
+        const cells = sheets.get(change.payload.sheetId) ?? new Map();
+        for (const cell of change.payload.cells)
+            cells.set(`${cell.row}:${cell.column}`, cell);
+        sheets.set(change.payload.sheetId, cells);
+    }
+    return [...sheets.entries()].map(([sheetId, cells]) => ({
+        type: 'update_cells',
+        payload: { sheetId, cells: [...cells.values()] },
+    }));
+}
+/** Keep the Univer snapshot name aligned with the Datasheet workbook name. */
+export function withWorkbookName(snapshot, name) {
+    const root = snapshot;
+    return { ...root, name: name.trim() || root.name || 'workbook' };
+}

package/lib/types/client/persistence/ids.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ids the browser mints for its own writes (docs/issue/0022 P5).
+ *
+ * An opId makes a retried save idempotent and a versionId keeps one editing
+ * session together across requests; both are the client's to name because the
+ * Host cannot tell a retry from a new edit.
+ */
+export declare function nextUserOpId(workbookId: string): string;
+export declare function nextUserVersionId(workbookId: string): string;
+export interface OwnOpLog {
+    /** Mint the op id for a write this browser is about to make, and remember it. */
+    next: (workbookId: string) => string;
+    /**
+     * Claim an op id that came back. True when this browser minted it — i.e. the
+     * operation is this client's own write being echoed, not a peer's edit.
+     */
+    take: (opId: string) => boolean;
+}
+/**
+ * The op ids this browser has sent and not yet seen come back (GUI feedback
+ * 2026-09-20).
+ *
+ * The collaboration stream echoes a write to **every** client on the workbook,
+ * the one that made it included, and the echo can arrive before the POST's own
+ * response — the Host publishes as soon as it has written. Without this log the
+ * Table panel read its own `snapshot_replace` as a foreign one and answered it
+ * the only way that operation can be answered, by re-downloading the snapshot
+ * and remounting the canvas: 「保存版本」 flashed the grid on every save, even
+ * though the canvas was already showing exactly the revision just stored.
+ *
+ * Bounded, because a save whose answer never comes back — a dropped connection —
+ * must not grow this for the life of the page.
+ */
+export declare function createOwnOpLog(limit?: number): OwnOpLog;

package/lib/types/client/persistence/ids.js

@@ -0,0 +1,48 @@
+/**
+ * Ids the browser mints for its own writes (docs/issue/0022 P5).
+ *
+ * An opId makes a retried save idempotent and a versionId keeps one editing
+ * session together across requests; both are the client's to name because the
+ * Host cannot tell a retry from a new edit.
+ */
+export function nextUserOpId(workbookId) {
+    const suffix = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function' ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return `user:${workbookId}:${suffix}`;
+}
+export function nextUserVersionId(workbookId) {
+    const suffix = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function' ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return `user-version:${workbookId}:${suffix}`;
+}
+/** How many unclaimed op ids one page remembers before the oldest is dropped. */
+const OWN_OP_LIMIT = 64;
+/**
+ * The op ids this browser has sent and not yet seen come back (GUI feedback
+ * 2026-09-20).
+ *
+ * The collaboration stream echoes a write to **every** client on the workbook,
+ * the one that made it included, and the echo can arrive before the POST's own
+ * response — the Host publishes as soon as it has written. Without this log the
+ * Table panel read its own `snapshot_replace` as a foreign one and answered it
+ * the only way that operation can be answered, by re-downloading the snapshot
+ * and remounting the canvas: 「保存版本」 flashed the grid on every save, even
+ * though the canvas was already showing exactly the revision just stored.
+ *
+ * Bounded, because a save whose answer never comes back — a dropped connection —
+ * must not grow this for the life of the page.
+ */
+export function createOwnOpLog(limit = OWN_OP_LIMIT) {
+    const ids = new Set();
+    return {
+        next: (workbookId) => {
+            const opId = nextUserOpId(workbookId);
+            ids.add(opId);
+            if (ids.size > limit) {
+                const oldest = ids.values().next().value;
+                if (oldest !== undefined)
+                    ids.delete(oldest);
+            }
+            return opId;
+        },
+        take: (opId) => ids.delete(opId),
+    };
+}

package/lib/types/client/persistence/merge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Three-way merge for Univer workbook snapshots.
+ *
+ * The browser keeps the last server snapshot as the base. When a user save
+ * races an Agent/user write, this module compares base/local/remote at cell
+ * granularity, adopts one-sided changes automatically, and keeps local values
+ * for true conflicts while adding a visible conflict style.
+ */
+import type { WorkbookLocalChange, WorkbookOperation } from '../../types.ts';
+export interface MergeConflict {
+    kind: 'cell' | 'structure' | 'sheet';
+    sheetId?: string;
+    sheetName?: string;
+    row?: number;
+    column?: number;
+    address?: string;
+    baseValue?: unknown;
+    localValue?: unknown;
+    remoteValue?: unknown;
+    description: string;
+}
+export interface WorkbookMergeResult {
+    snapshot: object;
+    conflicts: MergeConflict[];
+    autoMergedCells: number;
+    conflictStyleMap: Record<string, string | null>;
+}
+/** Merge local and remote snapshots against the last common base snapshot. */
+export declare function mergeWorkbookSnapshots(baseSnapshot: object, localSnapshot: object, remoteSnapshot: object): WorkbookMergeResult;
+/** Remove temporary conflict styles before a merged snapshot is persisted. */
+export declare function stripConflictMarkers(snapshot: object, conflictStyleMap: Record<string, string | null>): object;
+/** Apply ordinary cell edits to the merge base without cloning the workbook. */
+export declare function applyIncrementalChangesToSnapshot(snapshot: object, changes: WorkbookLocalChange[]): void;
+/** Patch a merge base from a replayable operation log; false means fallback. */
+export declare function applyIncrementalOperationsToSnapshot(snapshot: object, operations: WorkbookOperation[]): boolean;