@casualoffice/sheets 0.9.0

package/src/embed/protocol.ts

@@ -0,0 +1,258 @@
+/**
+ * Iframe protocol — wire envelopes that match
+ * `docs/internal/13-iframe-protocol.md`.
+ *
+ * Mirror updates to the doc whenever a new envelope shape lands.
+ * The discriminator on `type` (always starts with `casual.`) and
+ * the per-envelope `data` shape are the contract.
+ */
+
+import type {
+  CancelReason,
+  SignatureCompletePayload,
+  SignatureField,
+  SignatureMode,
+  SignedFieldPayload,
+} from '../signing/types';
+
+export type CasualApp = 'docs' | 'sheet';
+
+/** Common envelope shape — every postMessage on the wire matches this. */
+export interface CasualEnvelope<T = unknown> {
+  type: string;
+  app: CasualApp;
+  /** Per-request id for request/response correlation. Empty for fire-and-forget. */
+  id?: string;
+  /** Protocol version. Bumped only on breaking changes. */
+  v: 1;
+  data: T;
+}
+
+// ---------------------------------------------------------------
+// Handshake
+// ---------------------------------------------------------------
+
+export interface EditorHelloData {
+  capabilities: string[];
+  version: string;
+  commit: string;
+}
+
+export interface HostHelloData {
+  capabilities: string[];
+  authToken?: string;
+}
+
+// ---------------------------------------------------------------
+// Load + save (editor → host requests; host → editor responses)
+// ---------------------------------------------------------------
+
+export interface LoadRequestData {
+  docId: string;
+}
+
+export interface LoadResponseDataOk {
+  ok: true;
+  bytes: ArrayBuffer;
+  etag?: string;
+  fileName: string;
+  readOnly?: boolean;
+}
+
+export interface LoadResponseDataErr {
+  ok: false;
+  code: string;
+  message?: string;
+}
+
+export type LoadResponseData = LoadResponseDataOk | LoadResponseDataErr;
+
+export interface SaveRequestData {
+  docId: string;
+  bytes: ArrayBuffer;
+  baseEtag?: string;
+}
+
+export interface SaveResponseDataOk {
+  ok: true;
+  etag: string;
+}
+
+export interface SaveResponseDataErr {
+  ok: false;
+  code: string;
+  etag?: string;
+  message?: string;
+}
+
+export type SaveResponseData = SaveResponseDataOk | SaveResponseDataErr;
+
+// ---------------------------------------------------------------
+// Selection + telemetry + lock (editor → host notifications)
+// ---------------------------------------------------------------
+
+export interface SelectionChangedData {
+  docs?: { paraId: string; from: number; to: number; selectedText: string };
+  sheet?: { sheet: string; from: string; to: string };
+}
+
+export interface TelemetryEventData {
+  kind: string;
+  /** Arbitrary metric fields. */
+  [k: string]: unknown;
+}
+
+export interface LockLostData {
+  reason: 'taken_by_other' | 'expired' | 'host_revoked';
+}
+
+// ---------------------------------------------------------------
+// Commands (host → editor)
+// ---------------------------------------------------------------
+
+export interface CommandSetReadOnlyData {
+  readOnly: boolean;
+}
+
+export interface CommandSetThemeData {
+  theme: 'light' | 'dark' | 'system';
+}
+
+export interface CommandSetLocaleData {
+  locale: string;
+}
+
+/** Host → editor: switch chrome density between the two consumer-facing
+ *  modes without re-mounting. `preview` hides toolbar / formula bar /
+ *  side panel / status bar / sheet tabs and runs read-only; `editor`
+ *  shows the full UI. Mirrors the `viewMode` prop on `<CasualSheetsIframe>`. */
+export interface CommandSetViewModeData {
+  viewMode: 'preview' | 'editor';
+}
+
+/** Host → editor: execute a formatting / navigation command against
+ *  the active selection in the embedded workbook. Hosts (like Casual
+ *  Drive) build their own toolbar above the iframe and dispatch these
+ *  commands instead of Univer's built-in ribbon, which the SDK can't
+ *  ship because the ribbon resolves IRPCChannelService at construction
+ *  and that service needs a worker the SDK doesn't bundle.
+ *
+ *  v0.6 covered the toggle set; v0.7 adds the rich-format set (font,
+ *  size, colour, fill) + merge / unmerge. Arg-carrying commands read
+ *  the relevant field off `args` — every other command ignores it. */
+export interface CommandExecuteData {
+  command: // v0.6 — toggle / nav (no args)
+    | 'undo'
+    | 'redo'
+    | 'bold'
+    | 'italic'
+    | 'underline'
+    | 'strikethrough'
+    | 'align-left'
+    | 'align-center'
+    | 'align-right'
+    // v0.7 — rich format (args carry the value)
+    | 'set-font-family'
+    | 'set-font-size'
+    | 'set-text-color'
+    | 'reset-text-color'
+    | 'set-bg-color'
+    | 'reset-bg-color'
+    | 'merge'
+    | 'unmerge'
+    // v0.8 — number formats + freeze + wrap
+    | 'numfmt-currency'
+    | 'numfmt-percent'
+    | 'numfmt-add-decimal'
+    | 'numfmt-subtract-decimal'
+    | 'numfmt-custom'
+    | 'wrap-toggle'
+    | 'freeze-first-row'
+    | 'freeze-first-column'
+    | 'freeze-none';
+  args?: {
+    /** Used by `set-font-family`. */
+    family?: string;
+    /** Used by `set-font-size`. Integer point size. */
+    size?: number;
+    /** Used by `set-text-color` and `set-bg-color`. Hex like `#1a73e8`. */
+    color?: string;
+    /** Used by `numfmt-custom`. The Excel-style format string, e.g.
+     *  `"#,##0.00"`, `"$#,##0"`, `"0.00%"`, `"d-mmm-yy"`. v0.8+. */
+    pattern?: string;
+  };
+}
+
+/** Editor → host: emitted whenever the selection's active cell's
+ *  format flags change. Drive's toolbar mirrors this state in the
+ *  button "pressed" / value indicators so the surface always reflects
+ *  what the user would see in the cell. v0.7 widens the payload with
+ *  the rich-format read-back (fontFamily, fontSize, textColor, bgColor)
+ *  so the toolbar's font picker / size stepper / colour swatches stay
+ *  in sync without the host having to poll. */
+export interface SelectionFormatStateData {
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  align: 'left' | 'center' | 'right' | null;
+  /** Defined font family on the active cell, or null when the cell
+   *  inherits the workbook default. v0.7+. */
+  fontFamily: string | null;
+  /** Defined font size on the active cell, or null when the cell
+   *  inherits the workbook default. v0.7+. */
+  fontSize: number | null;
+  /** Hex text colour like `#1a73e8`, or null when default. v0.7+. */
+  textColor: string | null;
+  /** Hex background colour, or null when no fill is set. v0.7+. */
+  bgColor: string | null;
+}
+
+// ---------------------------------------------------------------
+// Errors (editor → host fatal signals)
+// ---------------------------------------------------------------
+
+/** Editor → host: a fatal error during boot / load. Hosts surface this
+ *  via the wrapper's `onError` callback. */
+export interface CasualErrorData {
+  code: 'embed_not_served' | 'load_failed' | 'parse_failed' | 'boot_failed' | 'internal';
+  message: string;
+}
+
+// ---------------------------------------------------------------
+// Signing (uniform with the SDK `signing` prop)
+// ---------------------------------------------------------------
+
+export interface SignatureRequestData {
+  fields: SignatureField[];
+  mode: SignatureMode;
+  banner?: string;
+}
+
+export interface SignatureRequestAckData {
+  ok: boolean;
+  code?: string;
+}
+
+export type SignatureFieldSignedData = SignedFieldPayload;
+export type SignatureCompleteData = SignatureCompletePayload;
+
+export interface SignatureCancelData {
+  reason: CancelReason;
+}
+
+// ---------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------
+
+export function isCasualEnvelope(value: unknown): value is CasualEnvelope {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.type === 'string' &&
+    v.type.startsWith('casual.') &&
+    (v.app === 'docs' || v.app === 'sheet') &&
+    v.v === 1 &&
+    'data' in v
+  );
+}

package/src/embed-runtime/embed.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Casual Sheets (embed)</title>
+    <style>
+      html, body { margin: 0; padding: 0; height: 100%; background: #fff; overflow: hidden; }
+      #casual-embed-root { width: 100%; height: 100%; }
+      /* Preview-mode chrome hiding — v0.5.x ties these to component
+         props; v0.5.0 lands the wire end-to-end and uses CSS gates. */
+      [data-view-mode="preview"] [data-toolbar],
+      [data-view-mode="preview"] [data-formula-bar],
+      [data-view-mode="preview"] [data-status-bar],
+      [data-view-mode="preview"] [data-sheet-tabs] { display: none !important; }
+    </style>
+    <link rel="stylesheet" href="./embed-runtime.css" />
+  </head>
+  <body>
+    <div id="casual-embed-root"></div>
+    <script type="module">
+      import { mountEmbedded } from './embed-runtime.js';
+      const root = document.getElementById('casual-embed-root');
+      if (root) {
+        mountEmbedded({ root });
+      }
+    </script>
+  </body>
+</html>