@file-viewer/docx 0.3.27 → 0.3.28

package/README.md

@@ -38,6 +38,7 @@ const options = {
   updatePageReferences: false,
   hideWebHiddenContent: false,
   externalLinkPolicy: "allow",
+  externalResourcePolicy: "block",
   progress: ev => console.log(ev.phase, ev.current, ev.total, ev.message)
 };
 
@@ -59,6 +60,80 @@ await renderAsync(fileOrArrayBuffer, container, null, {
 });
 ```
 
+Under a CSP with `require-trusted-types-for 'script'`, create the Worker at the
+application boundary and pass it through `workerFactory`:
+
+```ts
+const workerPolicy = trustedTypes.createPolicy("app-docx-worker", {
+  createScriptURL(value) {
+    const url = new URL(value, location.href);
+    if (url.origin !== location.origin)
+      throw new TypeError("DOCX Worker must be same-origin");
+    return url.href;
+  }
+});
+
+await renderAsync(fileOrArrayBuffer, container, null, {
+  useWorker: true,
+  workerFactory: () => new Worker(
+    workerPolicy.createScriptURL("/assets/docx-preview.worker.js")
+  )
+});
+```
+
+Copy `dist/docx-preview.worker.js` to that same-origin application asset path as
+part of your build or deployment.
+
+Allow the application-owned Worker policy and the renderer's three narrow HTML
+policies in the `trusted-types` CSP directive:
+
+```text
+trusted-types app-docx-worker file-viewer-docx-xml-parser file-viewer-docx-altchunk-parser file-viewer-docx-altchunk-srcdoc;
+require-trusted-types-for 'script';
+```
+
+The renderer policies brand only the exact value being sent to an inert XML/HTML
+parser or the sanitized altChunk `srcdoc`; no default policy is installed.
+
+### Read-only review preview
+
+Tracked changes remain disabled by default. Pass `reviewMode` to keep Word revision
+markup in the DOM, show comments by default, and enable the four read-only views:
+
+```ts
+import {
+  collectDocxReviewChanges,
+  renderAsync,
+  setDocxReviewMode
+} from "@file-viewer/docx";
+
+const document = await renderAsync(file, container, null, {
+  reviewMode: "all" // "final" | "original" | "simple" | "all"
+});
+
+const changes = collectDocxReviewChanges(document);
+setDocxReviewMode(container, "original"); // no reparse required
+```
+
+`renderChanges: true` is retained as a compatibility alias for `reviewMode: "all"`.
+Set `renderComments: false` explicitly when tracked changes are required without
+the comments surface.
+
+The mode values follow Word's **Display for Review** semantics: `simple` keeps
+the current text with compact change indicators, `all` exposes every supported
+revision and comment anchor, `final` is the current document with markup hidden,
+and `original` restores the pre-revision text with markup hidden. A host that
+wants Word-style margin balloons can use `collectDocxReviewChanges()` together
+with the stable `data-docx-change-*` anchors; the renderer does not force that
+optional review UI on normal document previews.
+
+`collectDocxReviewChanges()` returns logical Word review items rather than raw
+OOXML wrappers. Adjacent/nested revision fragments from the same paragraph,
+author, and edit session are coalesced; `ids` lists every source revision id.
+The `presentation` field is `inline` for insert/move-to items and `balloon` for
+delete/move-from/format/comment items. Formatting items include structured
+`formatChanges` and a semantic description such as `无下划线`.
+
 ## API
 
 ```ts
@@ -139,6 +214,7 @@ collectLayoutSnapshot(
   renderEndnotes: true,
   renderComments: false,
   renderAltChunks: true,
+  reviewMode: undefined, // opt-in: "final" | "original" | "simple" | "all"
   renderChanges: false,
   experimental: false,
   trimXmlDeclaration: true,
@@ -176,7 +252,18 @@ For Word-authored documents, keep `ignoreLastRenderedPageBreak: false`. Those ma
 
 `w:webHidden` is not hidden by default in this renderer because it only applies to Word's Web Layout view. In Print Layout, Word still displays the TOC tab before the page number and the cached `PAGEREF` result even when those runs are marked `w:webHidden`. Set `hideWebHiddenContent: true` only for an explicit Web Layout style preview.
 
-External hyperlinks remain active by default. Set `externalLinkPolicy: "block"` to omit their `href` while preserving their text and target metadata. Document-internal bookmark links remain active in either mode.
+External hyperlinks remain active by default, but only HTTP(S), `mailto:`, `tel:`
+and safe relative targets receive an `href`. Script-capable, local-file, blob,
+protocol-relative and unknown schemes are rejected in every mode. Set
+`externalLinkPolicy: "block"` to omit safe external `href` values while preserving
+their text and sanitized target metadata. Document-internal bookmark links remain
+active in either mode.
+
+External image relationships are blocked by default. Set `externalResourcePolicy: "allow"` only when the document is trusted to load HTTP(S) image resources. Package-embedded images and local `data:image/...` or `blob:` image URLs remain available without enabling network access; unknown and script-capable protocols are rejected in either mode.
+
+`renderAltChunks` remains compatible with existing integrations. Embedded HTML is
+parsed inertly and stripped of scripts, active elements, event handlers, CSS and
+URL-bearing attributes before it reaches a maximally restricted sandboxed iframe.
 
 Set `darkMode: true` to reproduce Word Online's "Switch Modes" dark appearance. Every color the renderer emits — text, backgrounds/highlights, borders, underlines, theme colors and DrawingML/VML shape fills and strokes — is converted with the same lightness-inversion algorithm Microsoft uses for this exact purpose (see `roosterjs`'s `getDarkColor`): the color is converted to CIE Lab, only the lightness (`L`) channel is inverted around a fixed base value (the `L` of `#333333`), and hue/chroma (`a`/`b`) are left untouched. That guarantees every color stays legible on a dark page — pure black becomes pure white, pure white becomes `#333333`, and an arbitrary color such as `rgb(99, 36, 35)` keeps its reddish hue while becoming light enough to read — without the hue-flipping side effects of a naive per-channel RGB invert. The toggle is purely a rendering-time CSS transform — it does not change the parsed document model — and every transformed color is wrapped in a CSS variable so that `@media print` can restore the exact original light-mode value; print output always renders with Word's normal light appearance regardless of `darkMode`.
 

package/dist/docx-preview.d.ts

@@ -3,6 +3,7 @@ export interface Options {
     hideWrapperOnPrint: boolean;
     ignoreWidth: boolean;
     ignoreHeight: boolean;
+    fixedPageHeight: boolean;
     ignoreFonts: boolean;
     breakPages: boolean;
     strictWordCompatibility: boolean;
@@ -11,16 +12,19 @@ export interface Options {
     awaitLayout: boolean;
     useWorker: boolean;
     workerUrl?: string;
+    workerFactory?: () => Worker;
     workerJsZipUrl?: string;
     workerFallback: boolean;
     workerTimeout: number;
     renderPageBatchSize: number;
     renderYieldEveryMs: number;
     progress?: (event: DocxProgressEvent) => void;
+    licenseToken?: unknown;
     preserveComplexFieldResults: boolean;
     updatePageReferences: boolean;
     hideWebHiddenContent: boolean;
     externalLinkPolicy: "allow" | "block";
+    externalResourcePolicy: "allow" | "block";
     darkMode: boolean;
     debug: boolean;
     experimental: boolean;
@@ -33,10 +37,20 @@ export interface Options {
     ignoreLastRenderedPageBreak: boolean;
     useBase64URL: boolean;
     renderChanges: boolean;
+    reviewMode?: ReviewMode;
     renderComments: boolean;
     renderAltChunks: boolean;
     h: (elem: any) => Node;
 }
+export type ReviewMode = "final" | "original" | "simple" | "all";
+export type ReviewChangeKind = "insert" | "delete" | "move-from" | "move-to" | "format";
+export interface ReviewChange {
+    id?: string;
+    kind: ReviewChangeKind;
+    author?: string;
+    date?: string;
+    text: string;
+}
 export interface DocxProgressEvent {
     phase: "worker" | "parse" | "render" | "layout" | "done" | string;
     current?: number;
@@ -76,3 +90,5 @@ export declare function parseAsyncInWorker(data: Blob | any, userOptions?: Parti
 export declare function awaitRenderedLayout(container: HTMLElement, userOptions?: Partial<Options>): Promise<LayoutSnapshot>;
 export declare function collectLayoutSnapshot(container: HTMLElement, userOptions?: Partial<Options>): LayoutSnapshot;
 export declare function yieldToBrowser(): Promise<void>;
+export declare function collectDocxReviewChanges(documentOrRoot: any): ReviewChange[];
+export declare function setDocxReviewMode(container: HTMLElement, mode: ReviewMode): boolean;