@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/api/scope-metadata-resolver-types.ts

@@ -0,0 +1,88 @@
+/**
+ * Metadata persistence mode — overlay-level default.
+ *
+ * - `"internal"`: every entry / field is inlined in the bw:workflowPayload
+ *   XML body. Self-contained docx; no host callback required.
+ * - `"external"`: entries / fields are stored by reference via a host-owned
+ *   ScopeMetadataResolver; the docx carries only a `storageRef` string.
+ *
+ * Unknown values → preserve-only (spec §8.2). Readers must never silently
+ * coerce to a known value.
+ */
+export type MetadataPersistenceMode = "internal" | "external";
+
+/**
+ * Per-scope / per-entry / per-field override. `"inherit"` defers to the
+ * parent (entry inherits scope; scope inherits overlay; overlay inherits
+ * the default `"internal"`).
+ */
+export type ScopeMetadataPersistence = "internal" | "external" | "inherit";
+
+/**
+ * Opaque host-owned reference for externally-stored metadata values. The
+ * editor never parses this string — it is passed verbatim to the
+ * resolver. Host examples:
+ *
+ *   "clm-workblock-row:wb-123:row-42:v-3"
+ *   "https://rowstore.internal/metadata/abc"
+ *   "s3://bucket/tenant-1/scope-metadata/e91a.json"
+ */
+export type ScopeMetadataStorageRef = string;
+
+/**
+ * Host-supplied resolver. The editor calls `resolve` whenever it needs
+ * the actual value of an external entry / field; it calls `publish` when
+ * toggling a scope / entry from `"internal"` to `"external"` and needs
+ * to hand the current inline value off to the host's store.
+ *
+ * All methods are async so the host can make network calls. An
+ * `undefined` return from `resolve` signals a missing or revoked ref;
+ * the editor surfaces this as a non-fatal warning and renders the entry
+ * as detached in the scope card. `undefined` (rather than `null`)
+ * matches the shipped `ExternalCustodyResolver.restore` convention (P7).
+ *
+ * `delete` is optional — hosts that don't need cleanup on toggle may
+ * omit it. The editor only calls it when transitioning a scope from
+ * `"external"` back to `"internal"` (hand the value back inline, then
+ * release the ref).
+ */
+export interface ScopeMetadataResolver {
+  /**
+   * Fetch the value for an opaque storageRef.  Returns `undefined`
+   * when the ref is unknown or revoked — the editor surfaces this as
+   * a non-fatal warning and renders the entry as detached in the
+   * scope card.  `version` (when present) is the rowstore's current
+   * version; the editor compares it against the docx's embedded
+   * `metadataVersion` hint and emits `metadata_conflict_detected` on
+   * mismatch.  Matches the `ExternalCustodyResolver.restore`
+   * convention (P7) — prefer `undefined` over `null` for consistency.
+   */
+  resolve(ref: ScopeMetadataStorageRef): Promise<
+    | { value: Record<string, unknown>; version?: number }
+    | undefined
+  >;
+
+  /**
+   * Publish an inline value to the host store.  `expectedVersion`
+   * (when set) enables optimistic concurrency: the host rejects the
+   * write if the stored row has advanced past the expected version,
+   * throwing a host-defined error that the editor surfaces via
+   * `metadata_conflict_detected`.
+   *
+   * Returns the opaque ref plus the version the store recorded for
+   * this write.  The editor embeds this version on the XML element.
+   */
+  publish(input: {
+    scopeId: string;
+    metadataId: string;
+    entryId?: string;
+    fieldKey?: string;
+    value: Record<string, unknown>;
+    expectedVersion?: number;
+  }): Promise<{
+    ref: ScopeMetadataStorageRef;
+    version: number;
+  }>;
+
+  delete?(ref: ScopeMetadataStorageRef): Promise<void>;
+}

package/src/core/commands/formatting-commands.ts

@@ -188,7 +188,7 @@ type ToggleFormattingMark =
   | "strikethrough"
   | "superscript"
   | "subscript";
-type FormattingOperation =
+export type FormattingOperation =
   | { type: "toggle"; mark: ToggleFormattingMark }
   | { type: "set-font-family"; fontFamily: string | null }
   | { type: "set-font-size"; size: number | null }