Merge pull request #3487 from superdoc-dev/caio-pizzol/SD-typecheck-coverage-drain-3

test(typecheck): drain 18 UI/state obligations from public-method coverage (SD-673)

Author: caio-pizzol

tests/consumer-typecheck/public-method-coverage-debt-snapshot.json

@@ -7,41 +7,23 @@
     "canPerformPermission:returns",
     "closeSurface:parameters",
     "closeSurface:returns",
-    "destroy:returns",
-    "element:returns",
     "export:parameters",
     "export:returns",
     "exportEditorsToDOCX:parameters",
     "exportEditorsToDOCX:returns",
-    "focus:returns",
     "getPresentationEditorForDocument:parameters",
     "getPresentationEditorForDocument:returns",
     "lockSuperdoc:parameters",
     "lockSuperdoc:returns",
     "openSurface:parameters",
     "openSurface:returns",
     "removeCommentsList:returns",
-    "requiredNumberOfEditors:returns",
     "save:returns",
     "scrollToComment:parameters",
     "scrollToComment:returns",
-    "setDisableContextMenu:parameters",
-    "setDisableContextMenu:returns",
-    "setHighContrastMode:parameters",
-    "setHighContrastMode:returns",
     "setLocked:parameters",
     "setLocked:returns",
-    "setShowBookmarks:parameters",
-    "setShowBookmarks:returns",
-    "setShowFormattingMarks:parameters",
-    "setShowFormattingMarks:returns",
-    "setTrackedChangesPreferences:parameters",
-    "setTrackedChangesPreferences:returns",
-    "setZoom:parameters",
-    "setZoom:returns",
     "state:returns",
-    "toggleFormattingMarks:returns",
-    "toggleRuler:returns",
     "upgradeToCollaboration:parameters",
     "upgradeToCollaboration:returns"
   ]

tests/consumer-typecheck/src/ui-state-control-apis.ts

@@ -0,0 +1,161 @@
+/**
+ * Consumer typecheck: UI and state-control public APIs on `SuperDoc`.
+ *
+ * Drains the low-risk UI/state batch from the public-method coverage
+ * gate. Each method's parameter or return shape is asserted against
+ * the emitted `.d.ts` with strict identity equality, so a future
+ * migration that narrows or widens any of these contracts will fail
+ * CI on the obligation diff rather than slipping silently into a
+ * release.
+ *
+ * Methods covered here, with returns verified against the emitted
+ * `.d.ts` and not inferred from intent:
+ *
+ *   - `setZoom(percent)` → `void`
+ *   - `setHighContrastMode(isHighContrast)` → `void`
+ *   - `setShowBookmarks(show?)` → `void`
+ *   - `setShowFormattingMarks(show?)` → `void`
+ *   - `setDisableContextMenu(disabled?)` → `void`
+ *   - `setTrackedChangesPreferences(preferences?)` → `void`
+ *   - `toggleFormattingMarks()` → `void`
+ *   - `toggleRuler()` → `void`
+ *   - `focus()` → `void`
+ *   - `destroy()` → `void`
+ *   - `element` (getter) → `Element | null`
+ *   - `requiredNumberOfEditors` (getter) → `number`
+ *
+ * Drained obligations (18): 6 method pairs (parameters + returns)
+ * for the setters, plus 4 zero-param method returns and 2 getter
+ * returns.
+ *
+ * Not covered here:
+ *
+ *   - The `state` getter returns `{ documents: RuntimeDocument[]; users: User[] }`.
+ *     RuntimeDocument is an internal-only type (declared in
+ *     core/types/index.ts with an "Internal use only; not part of any
+ *     public typedef" header) and is not re-exported through the
+ *     public facade. Asserting the indexed return type against a
+ *     consumer-importable shape would require either widening the
+ *     source return to use the public Document (lossy for internal
+ *     callers) or promoting RuntimeDocument to a public supported-root
+ *     type (out of scope here). The corresponding obligation is left
+ *     on the debt snapshot until that surface decision is made.
+ */
+import type { SuperDoc } from 'superdoc';
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type AssertEqual<A, B> = Equal<A, B> extends true ? true : never;
+
+declare const sd: SuperDoc;
+
+// ─── setZoom ────────────────────────────────────────────────────────
+// Updates the active zoom in the Pinia store; the Vue layer's
+// activeZoom watcher propagates to each PresentationEditor.
+// Early-returns on non-positive / non-finite input.
+const _setZoomParamsOk: AssertEqual<Parameters<SuperDoc['setZoom']>, [percent: number]> = true;
+const _setZoomReturnOk: AssertEqual<ReturnType<SuperDoc['setZoom']>, void> = true;
+sd.setZoom(150);
+
+// ─── setHighContrastMode ────────────────────────────────────────────
+// Forwards to `activeEditor.setHighContrastMode` and writes to the
+// highContrastModeStore. No-op until the active editor exists.
+const _setHighContrastParamsOk: AssertEqual<
+  Parameters<SuperDoc['setHighContrastMode']>,
+  [isHighContrast: boolean]
+> = true;
+const _setHighContrastReturnOk: AssertEqual<ReturnType<SuperDoc['setHighContrastMode']>, void> = true;
+sd.setHighContrastMode(true);
+
+// ─── setShowBookmarks ───────────────────────────────────────────────
+// Writes `layoutEngineOptions.showBookmarks` and forwards to each
+// PresentationEditor. Parameter has a `= true` default in source, so
+// the emitted signature is `(show?: boolean)`.
+const _setShowBookmarksParamsOk: AssertEqual<Parameters<SuperDoc['setShowBookmarks']>, [show?: boolean]> = true;
+const _setShowBookmarksReturnOk: AssertEqual<ReturnType<SuperDoc['setShowBookmarks']>, void> = true;
+sd.setShowBookmarks(true);
+sd.setShowBookmarks();
+
+// ─── setShowFormattingMarks ─────────────────────────────────────────
+// Same shape as setShowBookmarks. Writes the layout option, forwards
+// to PresentationEditor, and emits `formatting-marks-change`.
+const _setShowFormattingMarksParamsOk: AssertEqual<
+  Parameters<SuperDoc['setShowFormattingMarks']>,
+  [show?: boolean]
+> = true;
+const _setShowFormattingMarksReturnOk: AssertEqual<ReturnType<SuperDoc['setShowFormattingMarks']>, void> = true;
+sd.setShowFormattingMarks(true);
+
+// ─── setDisableContextMenu ──────────────────────────────────────────
+// Writes `config.disableContextMenu` and forwards to each
+// PresentationEditor / Editor. Same `(disabled?: boolean)` default
+// shape as the other toggles.
+const _setDisableContextMenuParamsOk: AssertEqual<
+  Parameters<SuperDoc['setDisableContextMenu']>,
+  [disabled?: boolean]
+> = true;
+const _setDisableContextMenuReturnOk: AssertEqual<ReturnType<SuperDoc['setDisableContextMenu']>, void> = true;
+sd.setDisableContextMenu(true);
+
+// ─── setTrackedChangesPreferences ───────────────────────────────────
+// Accepts an inline literal of mode + enabled. The source param is
+// optional; an empty object normalizes to `undefined`. Mode is the
+// closed union `'review' | 'original' | 'final' | 'off'`.
+const _setTrackedChangesParamsOk: AssertEqual<
+  Parameters<SuperDoc['setTrackedChangesPreferences']>,
+  [preferences?: { mode?: 'review' | 'original' | 'final' | 'off'; enabled?: boolean }]
+> = true;
+const _setTrackedChangesReturnOk: AssertEqual<ReturnType<SuperDoc['setTrackedChangesPreferences']>, void> = true;
+sd.setTrackedChangesPreferences({ mode: 'review', enabled: true });
+
+// ─── toggleFormattingMarks ──────────────────────────────────────────
+// Reads current `layoutEngineOptions.showFormattingMarks` and flips
+// via `setShowFormattingMarks`. Zero-arg.
+const _toggleFormattingMarksReturnOk: AssertEqual<ReturnType<SuperDoc['toggleFormattingMarks']>, void> = true;
+
+// ─── toggleRuler ────────────────────────────────────────────────────
+// Flips `config.rulers` and writes through to each RuntimeDocument's
+// `rulers` mirror in the Pinia store. Throws (via `#requireSuperdocStore`)
+// when called pre-ready.
+const _toggleRulerReturnOk: AssertEqual<ReturnType<SuperDoc['toggleRuler']>, void> = true;
+
+// ─── focus ──────────────────────────────────────────────────────────
+// Focuses `activeEditor` if present; otherwise walks the document
+// list and focuses the first editor found.
+const _focusReturnOk: AssertEqual<ReturnType<SuperDoc['focus']>, void> = true;
+
+// ─── destroy ────────────────────────────────────────────────────────
+// Tears down surfaces, toolbar, Vue app, collaboration, and the
+// internal mount wrapper. Idempotent: marks `#destroyed` early so
+// in-flight init bails out.
+const _destroyReturnOk: AssertEqual<ReturnType<SuperDoc['destroy']>, void> = true;
+
+// ─── element (getter) ───────────────────────────────────────────────
+// Resolves `config.selector` to a DOM element. String selectors go
+// through `document.querySelector` (`Element | null`); element
+// references are returned as-is. Emitted return is `Element | null`.
+const _elementOk: AssertEqual<SuperDoc['element'], Element | null> = true;
+
+// ─── requiredNumberOfEditors (getter) ───────────────────────────────
+// Count of DOCX documents in the Pinia store. Throws pre-ready.
+const _requiredNumberOfEditorsOk: AssertEqual<SuperDoc['requiredNumberOfEditors'], number> = true;
+
+void [
+  _setZoomParamsOk,
+  _setZoomReturnOk,
+  _setHighContrastParamsOk,
+  _setHighContrastReturnOk,
+  _setShowBookmarksParamsOk,
+  _setShowBookmarksReturnOk,
+  _setShowFormattingMarksParamsOk,
+  _setShowFormattingMarksReturnOk,
+  _setDisableContextMenuParamsOk,
+  _setDisableContextMenuReturnOk,
+  _setTrackedChangesParamsOk,
+  _setTrackedChangesReturnOk,
+  _toggleFormattingMarksReturnOk,
+  _toggleRulerReturnOk,
+  _focusReturnOk,
+  _destroyReturnOk,
+  _elementOk,
+  _requiredNumberOfEditorsOk,
+];