@casualoffice/sheets 0.9.0

package/package.json

@@ -0,0 +1,293 @@
+{
+  "name": "@casualoffice/sheets",
+  "version": "0.9.0",
+  "description": "Casual Sheets SDK — signing pipeline, iframe postMessage protocol, and CasualSheets React wrapper around Univer.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CasualOffice/sheets.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/CasualOffice/sheets/tree/main/packages/sdk",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./signing": {
+      "types": "./dist/signing.d.ts",
+      "import": "./dist/signing.js",
+      "require": "./dist/signing.cjs"
+    },
+    "./embed": {
+      "types": "./dist/embed.d.ts",
+      "import": "./dist/embed.js",
+      "require": "./dist/embed.cjs"
+    },
+    "./sheets": {
+      "types": "./dist/sheets.d.ts",
+      "import": "./dist/sheets.js",
+      "require": "./dist/sheets.cjs"
+    },
+    "./styles": {
+      "import": "./dist/styles.js",
+      "require": "./dist/styles.cjs"
+    },
+    "./xlsx": {
+      "types": "./dist/xlsx.d.ts",
+      "import": "./dist/xlsx.js",
+      "require": "./dist/xlsx.cjs"
+    },
+    "./univer": {
+      "types": "./dist/univer.d.ts",
+      "import": "./dist/univer.js",
+      "require": "./dist/univer.cjs"
+    },
+    "./embed-runtime": {
+      "import": "./dist/embed/embed-runtime.js"
+    },
+    "./embed/embed.html": "./dist/embed/embed.html"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@univerjs/core": "^0.25.0",
+    "@univerjs/design": "^0.25.0",
+    "@univerjs/docs": "^0.25.0",
+    "@univerjs/docs-ui": "^0.25.0",
+    "@univerjs/drawing": "^0.25.0",
+    "@univerjs/drawing-ui": "^0.25.0",
+    "@univerjs/engine-formula": "^0.25.0",
+    "@univerjs/engine-render": "^0.25.0",
+    "@univerjs/find-replace": "^0.25.0",
+    "@univerjs/sheets": "^0.25.0",
+    "@univerjs/sheets-conditional-formatting": "^0.25.0",
+    "@univerjs/sheets-conditional-formatting-ui": "^0.25.0",
+    "@univerjs/sheets-data-validation": "^0.25.0",
+    "@univerjs/sheets-data-validation-ui": "^0.25.0",
+    "@univerjs/sheets-drawing": "^0.25.0",
+    "@univerjs/sheets-drawing-ui": "^0.25.0",
+    "@univerjs/sheets-filter": "^0.25.0",
+    "@univerjs/sheets-filter-ui": "^0.25.0",
+    "@univerjs/sheets-find-replace": "^0.25.0",
+    "@univerjs/sheets-formula": "^0.25.0",
+    "@univerjs/sheets-formula-ui": "^0.25.0",
+    "@univerjs/sheets-hyper-link": "^0.25.0",
+    "@univerjs/sheets-hyper-link-ui": "^0.25.0",
+    "@univerjs/sheets-note": "^0.25.0",
+    "@univerjs/sheets-note-ui": "^0.25.0",
+    "@univerjs/sheets-numfmt": "^0.25.0",
+    "@univerjs/sheets-numfmt-ui": "^0.25.0",
+    "@univerjs/sheets-sort": "^0.25.0",
+    "@univerjs/sheets-sort-ui": "^0.25.0",
+    "@univerjs/sheets-table": "^0.25.0",
+    "@univerjs/sheets-table-ui": "^0.25.0",
+    "@univerjs/sheets-thread-comment": "^0.25.0",
+    "@univerjs/sheets-thread-comment-ui": "^0.25.0",
+    "@univerjs/sheets-ui": "^0.25.0",
+    "@univerjs/themes": "^0.25.0",
+    "@univerjs/thread-comment": "^0.25.0",
+    "@univerjs/thread-comment-ui": "^0.25.0",
+    "@univerjs/ui": "^0.25.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@univerjs/core": {
+      "optional": true
+    },
+    "@univerjs/design": {
+      "optional": true
+    },
+    "@univerjs/docs": {
+      "optional": true
+    },
+    "@univerjs/docs-ui": {
+      "optional": true
+    },
+    "@univerjs/drawing": {
+      "optional": true
+    },
+    "@univerjs/drawing-ui": {
+      "optional": true
+    },
+    "@univerjs/engine-formula": {
+      "optional": true
+    },
+    "@univerjs/engine-render": {
+      "optional": true
+    },
+    "@univerjs/find-replace": {
+      "optional": true
+    },
+    "@univerjs/sheets": {
+      "optional": true
+    },
+    "@univerjs/sheets-conditional-formatting": {
+      "optional": true
+    },
+    "@univerjs/sheets-conditional-formatting-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-data-validation": {
+      "optional": true
+    },
+    "@univerjs/sheets-data-validation-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-drawing": {
+      "optional": true
+    },
+    "@univerjs/sheets-drawing-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-filter": {
+      "optional": true
+    },
+    "@univerjs/sheets-filter-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-find-replace": {
+      "optional": true
+    },
+    "@univerjs/sheets-formula": {
+      "optional": true
+    },
+    "@univerjs/sheets-formula-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-hyper-link": {
+      "optional": true
+    },
+    "@univerjs/sheets-hyper-link-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-note": {
+      "optional": true
+    },
+    "@univerjs/sheets-note-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-numfmt": {
+      "optional": true
+    },
+    "@univerjs/sheets-numfmt-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-sort": {
+      "optional": true
+    },
+    "@univerjs/sheets-sort-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-table": {
+      "optional": true
+    },
+    "@univerjs/sheets-table-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-thread-comment": {
+      "optional": true
+    },
+    "@univerjs/sheets-thread-comment-ui": {
+      "optional": true
+    },
+    "@univerjs/sheets-ui": {
+      "optional": true
+    },
+    "@univerjs/themes": {
+      "optional": true
+    },
+    "@univerjs/thread-comment": {
+      "optional": true
+    },
+    "@univerjs/thread-comment-ui": {
+      "optional": true
+    },
+    "@univerjs/ui": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@univerjs/core": "0.25.0",
+    "@univerjs/design": "0.25.0",
+    "@univerjs/docs": "0.25.0",
+    "@univerjs/docs-ui": "0.25.0",
+    "@univerjs/drawing": "0.25.0",
+    "@univerjs/drawing-ui": "0.25.0",
+    "@univerjs/engine-formula": "0.25.0",
+    "@univerjs/engine-render": "0.25.0",
+    "@univerjs/find-replace": "0.25.0",
+    "@univerjs/sheets": "0.25.0",
+    "@univerjs/sheets-conditional-formatting": "0.25.0",
+    "@univerjs/sheets-conditional-formatting-ui": "0.25.0",
+    "@univerjs/sheets-data-validation": "0.25.0",
+    "@univerjs/sheets-data-validation-ui": "0.25.0",
+    "@univerjs/sheets-drawing": "0.25.0",
+    "@univerjs/sheets-drawing-ui": "0.25.0",
+    "@univerjs/sheets-filter": "0.25.0",
+    "@univerjs/sheets-filter-ui": "0.25.0",
+    "@univerjs/sheets-find-replace": "0.25.0",
+    "@univerjs/sheets-formula": "0.25.0",
+    "@univerjs/sheets-formula-ui": "0.25.0",
+    "@univerjs/sheets-hyper-link": "0.25.0",
+    "@univerjs/sheets-hyper-link-ui": "0.25.0",
+    "@univerjs/sheets-note": "0.25.0",
+    "@univerjs/sheets-note-ui": "0.25.0",
+    "@univerjs/sheets-numfmt": "0.25.0",
+    "@univerjs/sheets-numfmt-ui": "0.25.0",
+    "@univerjs/sheets-sort": "0.25.0",
+    "@univerjs/sheets-sort-ui": "0.25.0",
+    "@univerjs/sheets-table": "0.25.0",
+    "@univerjs/sheets-table-ui": "0.25.0",
+    "@univerjs/sheets-thread-comment": "0.25.0",
+    "@univerjs/sheets-thread-comment-ui": "0.25.0",
+    "@univerjs/sheets-ui": "0.25.0",
+    "@univerjs/themes": "0.25.0",
+    "@univerjs/thread-comment": "0.25.0",
+    "@univerjs/thread-comment-ui": "0.25.0",
+    "@univerjs/ui": "0.25.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sheets",
+    "spreadsheet",
+    "signing",
+    "iframe",
+    "postmessage",
+    "univer",
+    "casual-sheets"
+  ],
+  "dependencies": {
+    "exceljs": "4.4.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx 'src/**/*.unit.test.ts'"
+  }
+}

package/src/embed/EmbedHostTransport.ts

@@ -0,0 +1,226 @@
+/**
+ * EmbedHostTransport — the parent side of the embed iframe bridge for
+ * the sheet SDK. Mirror of @casualoffice/docs's host transport.
+ *
+ * Wire shape: `docs/SDK_SIGNING_EMBED.md` (cross-link in the doc repo at
+ * `docs/internal/13-iframe-protocol.md`) + `16-sdk-iframe-architecture.md`.
+ *
+ * Lifetime: constructed once when the wrapper mounts the iframe.
+ * `destroy()` removes the event listener; safe to call multiple times.
+ */
+
+import {
+  isCasualEnvelope,
+  type CasualApp,
+  type CasualEnvelope,
+  type CasualErrorData,
+  type CommandSetReadOnlyData,
+  type CommandSetThemeData,
+  type CommandSetLocaleData,
+  type CommandSetViewModeData,
+  type CommandExecuteData,
+  type SelectionFormatStateData,
+  type EditorHelloData,
+  type HostHelloData,
+  type LoadRequestData,
+  type LoadResponseData,
+  type SaveRequestData,
+  type SaveResponseData,
+  type SelectionChangedData,
+  type SignatureCancelData,
+  type SignatureCompleteData,
+  type SignatureFieldSignedData,
+  type SignatureRequestData,
+  type TelemetryEventData,
+} from './protocol';
+
+export interface EmbedHostTransportOptions {
+  app: CasualApp;
+  /** The iframe's `contentWindow`. */
+  iframeWindow: Window;
+  /** Origin allowed to send + receive messages. Same-origin internal
+   *  embed is `window.location.origin`. */
+  embedOrigin: string;
+  /** Optional injection — tests pass a stub. */
+  hostWindow?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}
+
+export interface EmbedHostHandlers {
+  onEditorReady?: (data: EditorHelloData) => void;
+  /** Editor requests bytes for `docId`. */
+  onLoadRequest?: (data: LoadRequestData) => Promise<LoadResponseData> | LoadResponseData;
+  /** Editor requests a save. */
+  onSaveRequest?: (data: SaveRequestData) => Promise<SaveResponseData> | SaveResponseData;
+  onSelectionChanged?: (data: SelectionChangedData) => void;
+  onSelectionFormatState?: (data: SelectionFormatStateData) => void;
+  onTelemetry?: (data: TelemetryEventData) => void;
+  onSignatureFieldSigned?: (data: SignatureFieldSignedData) => void;
+  onSignatureComplete?: (data: SignatureCompleteData) => void;
+  onSignatureCancel?: (data: SignatureCancelData) => void;
+  onError?: (data: CasualErrorData) => void;
+}
+
+type IframePostMessage = (msg: unknown, targetOrigin: string, transfer?: Transferable[]) => void;
+
+export class EmbedHostTransport {
+  private readonly opts: EmbedHostTransportOptions;
+  private handlers: EmbedHostHandlers = {};
+  private readonly boundOnMessage: (ev: MessageEvent) => void;
+  private destroyed = false;
+
+  constructor(opts: EmbedHostTransportOptions) {
+    this.opts = opts;
+    this.boundOnMessage = this.onMessage.bind(this);
+    const target = opts.hostWindow ?? window;
+    target.addEventListener('message', this.boundOnMessage);
+  }
+
+  on(handlers: EmbedHostHandlers): void {
+    this.handlers = { ...this.handlers, ...handlers };
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    const target = this.opts.hostWindow ?? window;
+    target.removeEventListener('message', this.boundOnMessage);
+  }
+
+  sendHostHello(data: HostHelloData): void {
+    this.post('casual.hello', data);
+  }
+
+  sendSetViewMode(data: CommandSetViewModeData): void {
+    this.post('casual.command.set.viewmode', data);
+  }
+
+  sendSetReadOnly(data: CommandSetReadOnlyData): void {
+    this.post('casual.command.set.readonly', data);
+  }
+
+  sendSetTheme(data: CommandSetThemeData): void {
+    this.post('casual.command.set.theme', data);
+  }
+
+  sendSetLocale(data: CommandSetLocaleData): void {
+    this.post('casual.command.set.locale', data);
+  }
+
+  sendCommandSave(): void {
+    this.post('casual.command.save', null);
+  }
+
+  sendCommandFocus(): void {
+    this.post('casual.command.focus', null);
+  }
+
+  /** Host → Editor: run a formatting / navigation command (bold,
+   *  italic, undo, …) against the active selection. v0.6+. */
+  sendCommandExecute(data: CommandExecuteData): void {
+    this.post('casual.command.execute', data);
+  }
+
+  sendSignatureRequest(id: string, data: SignatureRequestData): void {
+    this.post('casual.signature.request', data, id);
+  }
+
+  sendSignatureCancel(data: SignatureCancelData): void {
+    this.post('casual.signature.cancel', data);
+  }
+
+  private onMessage(ev: MessageEvent): void {
+    if (this.destroyed) return;
+    if (ev.origin !== this.opts.embedOrigin) return;
+    if (ev.source !== this.opts.iframeWindow) return;
+    if (!isCasualEnvelope(ev.data)) return;
+    if (ev.data.app !== this.opts.app) return;
+
+    void this.dispatch(ev.data);
+  }
+
+  private async dispatch(env: CasualEnvelope): Promise<void> {
+    switch (env.type) {
+      case 'casual.ready':
+        this.handlers.onEditorReady?.(env.data as EditorHelloData);
+        return;
+      case 'casual.load.request': {
+        if (!this.handlers.onLoadRequest) return;
+        const id = env.id ?? '';
+        try {
+          const resp = await this.handlers.onLoadRequest(env.data as LoadRequestData);
+          const transfer: Transferable[] = resp.ok ? [resp.bytes] : [];
+          this.post('casual.load.response', resp, id, transfer);
+        } catch (err) {
+          this.post(
+            'casual.load.response',
+            {
+              ok: false as const,
+              code: 'host_error',
+              message: err instanceof Error ? err.message : String(err),
+            },
+            id,
+          );
+        }
+        return;
+      }
+      case 'casual.save.request': {
+        if (!this.handlers.onSaveRequest) return;
+        const id = env.id ?? '';
+        try {
+          const resp = await this.handlers.onSaveRequest(env.data as SaveRequestData);
+          this.post('casual.save.response', resp, id);
+        } catch (err) {
+          this.post(
+            'casual.save.response',
+            {
+              ok: false as const,
+              code: 'host_error',
+              message: err instanceof Error ? err.message : String(err),
+            },
+            id,
+          );
+        }
+        return;
+      }
+      case 'casual.selection.changed':
+        this.handlers.onSelectionChanged?.(env.data as SelectionChangedData);
+        return;
+      case 'casual.selection.format-state':
+        this.handlers.onSelectionFormatState?.(env.data as SelectionFormatStateData);
+        return;
+      case 'casual.telemetry.event':
+        this.handlers.onTelemetry?.(env.data as TelemetryEventData);
+        return;
+      case 'casual.signature.field.signed':
+        this.handlers.onSignatureFieldSigned?.(env.data as SignatureFieldSignedData);
+        return;
+      case 'casual.signature.complete':
+        this.handlers.onSignatureComplete?.(env.data as SignatureCompleteData);
+        return;
+      case 'casual.signature.cancel':
+        this.handlers.onSignatureCancel?.(env.data as SignatureCancelData);
+        return;
+      case 'casual.signature.request.ack':
+        return;
+      case 'casual.error':
+        this.handlers.onError?.(env.data as CasualErrorData);
+        return;
+      default:
+        return;
+    }
+  }
+
+  private post(type: string, data: unknown, id?: string, transfer?: Transferable[]): void {
+    const env: CasualEnvelope = {
+      type,
+      app: this.opts.app,
+      v: 1,
+      data,
+      ...(id ? { id } : {}),
+    };
+    const send = this.opts.iframeWindow.postMessage.bind(
+      this.opts.iframeWindow,
+    ) as IframePostMessage;
+    send(env, this.opts.embedOrigin, transfer);
+  }
+}