@json-to-office/core-docx 1.4.0 → 1.5.0

package/dist/quality/facts.d.ts

@@ -0,0 +1,82 @@
+import type { PreparedDocument, QualityFact } from '@json-to-office/quality';
+import type { FontRuntimeOpts, GenerationWarning } from '@json-to-office/shared';
+import type { ReportComponentDefinition } from '../types';
+import type { ThemeConfig } from '../styles';
+import { type GenerationThemeContext } from '../core/generationContext';
+import { type ResolvedDocumentTree } from '../core/structure';
+export interface DocxTableWidthFact extends QualityFact {
+    kind: 'docx/table-width';
+    totalWidthTwips: number;
+    availableWidthTwips: number;
+    hasExplicitWidth: boolean;
+    allColumnsExplicit: boolean;
+    pointSum: number;
+    percentSum: number;
+    /**
+     * Authored explicit widths by column index (points as numbers, `"NN%"`
+     * strings kept verbatim) — what a fix has to rescale. Columns without an
+     * explicit width are absent.
+     */
+    explicitWidths: ReadonlyArray<{
+        index: number;
+        width: number | string;
+    }>;
+}
+export interface DocxHeadingFact extends QualityFact {
+    kind: 'docx/heading';
+    level: number;
+    previousLevel?: number;
+}
+/**
+ * A paragraph pinned into a floating frame — the one place in DOCX where the
+ * author, not the layout engine, decides how much room the text gets. Flowed
+ * body copy repaginates; a frame keeps its declared box and lets the text spill
+ * or break inside it.
+ */
+export interface DocxFrameTextFact extends QualityFact {
+    kind: 'docx/frame-text';
+    text: string;
+    fontSizePt: number;
+    /** Height of one line, including the resolved line-spacing rule. */
+    lineHeightPt: number;
+    /** Signed tracking in points: negative when the run is condensed. */
+    characterSpacingPt: number;
+    frameWidthTwips: number;
+    frameHeightTwips?: number;
+    /** Frame top, when pinned with an absolute vertical offset. */
+    offsetYTwips?: number;
+    /** The paper edge — the last twip anything can render on. */
+    pageBottomTwips: number;
+    /** The longest whitespace-delimited token — the one with nowhere to wrap. */
+    longestWord: string;
+}
+/**
+ * A `<text>` element inside an inline SVG, with the canvas it has to sit in.
+ * SVG has no overflow rule to fall back on: a baseline past the viewBox is
+ * simply not painted, and the words leave the document's text layer with it.
+ */
+export interface DocxSvgTextFact extends QualityFact {
+    kind: 'docx/svg-text';
+    content: string;
+    /** Baseline position and nominal size, in viewBox units. */
+    baselineY: number;
+    fontSizeUnits: number;
+    viewBoxMinY: number;
+    viewBoxHeight: number;
+}
+export type DocxQualityFact = DocxTableWidthFact | DocxHeadingFact | DocxFrameTextFact | DocxSvgTextFact;
+export interface DocxQualityModel {
+    authored: ReportComponentDefinition;
+    context: GenerationThemeContext;
+    document: ResolvedDocumentTree;
+    themeName: string;
+}
+export interface PrepareDocxQualityOptions {
+    customThemes?: Record<string, ThemeConfig>;
+    fonts?: FontRuntimeOpts;
+    warnings?: GenerationWarning[];
+    context?: GenerationThemeContext;
+    renderer?: string;
+}
+export declare function prepareDocxQualityDocument(document: ReportComponentDefinition, options?: PrepareDocxQualityOptions): PreparedDocument<DocxQualityModel, DocxQualityFact>;
+//# sourceMappingURL=facts.d.ts.map

package/dist/quality/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/quality/facts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,WAAW,EACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAuB,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,IAAI,EAAE,kBAAkB,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,eAAe,GACf,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,yBAAyB,CAAC;IACpC,OAAO,EAAE,sBAAsB,CAAC;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAkPD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,yBAAyB,EACnC,OAAO,GAAE,yBAA8B,GACtC,gBAAgB,CAAC,gBAAgB,EAAE,eAAe,CAAC,CA+ErD"}

package/dist/quality/preflight.d.ts

@@ -0,0 +1,15 @@
+/** DOCX quality analysis over renderer-aligned prepared facts. */
+import { type PreparedDocument, type QualityAnalysis, type QualityPolicy, type QualityProfile } from '@json-to-office/quality';
+import type { ThemeConfig } from '../styles';
+import type { DocxQualityFact, DocxQualityModel } from './facts';
+export interface DocxQualityOptions {
+    customThemes?: Record<string, ThemeConfig>;
+}
+export interface DocxQualityAnalysisOptions extends DocxQualityOptions {
+    renderer?: string;
+    profile?: QualityProfile;
+    policy?: QualityPolicy;
+    prepared?: PreparedDocument<DocxQualityModel, DocxQualityFact>;
+}
+export declare function analyzeDocxQuality(doc: unknown, options?: DocxQualityAnalysisOptions): QualityAnalysis;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/quality/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/quality/preflight.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EAEpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAUjE,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,gBAAgB,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;CAChE;AAiBD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,0BAA+B,GACvC,eAAe,CA2CjB"}

package/dist/quality/rules.d.ts

@@ -0,0 +1,38 @@
+import { QualityEngine, type QualityProfile, type QualityRule, type QualityRulePack } from '@json-to-office/quality';
+import type { DocxQualityFact, DocxQualityModel } from './facts';
+export declare const docxTableWidthRule: QualityRule<DocxQualityModel, DocxQualityFact>;
+export declare const docxHeadingHierarchyRule: QualityRule<DocxQualityModel, DocxQualityFact>;
+export declare const docxTextFitRule: QualityRule<DocxQualityModel, DocxQualityFact>;
+export declare const docxSvgTextBoundsRule: QualityRule<DocxQualityModel, DocxQualityFact>;
+export declare const DOCX_QUALITY_RULES: QualityRulePack<DocxQualityModel, DocxQualityFact>;
+export declare const DOCX_QUALITY_PROFILES: {
+    readonly 'executive-report': {
+        readonly id: "executive-report";
+        readonly formats: readonly ["docx"];
+        readonly description: "Short decision document with strict outline continuity.";
+        readonly rules: {
+            readonly 'docx/heading-hierarchy': {
+                readonly severity: "warning";
+            };
+        };
+    };
+    readonly 'technical-report': {
+        readonly id: "technical-report";
+        readonly formats: readonly ["docx"];
+        readonly description: "Portable professional report defaults.";
+    };
+    readonly 'legal-appendix': {
+        readonly id: "legal-appendix";
+        readonly formats: readonly ["docx"];
+        readonly description: "Dense appendix: preserve integrity without editorial taste.";
+    };
+};
+export declare const DOCX_DEFAULT_QUALITY_PROFILE: QualityProfile;
+/**
+ * Callers name a shipped profile by id — `{ id: 'executive-report', formats: ['docx'] }`.
+ * Without this lookup that request reaches the engine carrying nothing but its id,
+ * so the analysis runs on defaults while stamping the requested profileId.
+ */
+export declare function resolveDocxQualityProfile(requested: QualityProfile | undefined): QualityProfile | undefined;
+export declare const docxQualityEngine: QualityEngine<DocxQualityModel, DocxQualityFact>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/quality/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/quality/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAGV,eAAe,EACf,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAejB,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAC1C,gBAAgB,EAChB,eAAe,CA6DhB,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAChD,gBAAgB,EAChB,eAAe,CAuChB,CAAC;AAsBF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,gBAAgB,EAAE,eAAe,CAwF1E,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAC7C,gBAAgB,EAChB,eAAe,CAqChB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAAe,CAC9C,gBAAgB,EAChB,eAAe,CAShB,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;CAmBiB,CAAC;AAEpD,eAAO,MAAM,4BAA4B,EAAE,cACA,CAAC;AAK5C;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,cAAc,GAAG,SAAS,GACpC,cAAc,GAAG,SAAS,CAK5B;AAED,eAAO,MAAM,iBAAiB,kDAA8C,CAAC"}

package/dist/quality/text-metrics.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A width model for authored runs, used only to answer "does this text fit".
+ *
+ * A single characters-per-point factor cannot do this job. Measured against the
+ * shipped display headings (`pdftotext -bbox`), the implied factor ran 0.435
+ * for mixed-case words and 0.694 for all-caps — a 39% spread that no single
+ * constant survives, because caps and lowercase are simply different widths.
+ *
+ * These are the standard Helvetica advance widths in 1/1000 em. The grotesque
+ * sans faces the stock templates use (DM Sans, Inter, Geist, Archivo) track
+ * them closely enough that summing real characters lands within about 8% of the
+ * rendered width, and it under-estimates more often than it over-estimates —
+ * the safe direction for a rule that only speaks up on overflow.
+ *
+ * Validated against rendered geometry at authoring time:
+ *
+ *   "Vision,"      80pt  model 179.2pt  actual 182.7pt  −1.9%
+ *   "Financial"    80pt  model 241.8pt  actual 246.8pt  −2.0%
+ *   "Global"      107pt  model 251.6pt  actual 264.4pt  −4.8%
+ *   "Performance"  80pt  model 362.2pt  actual 383.0pt  −5.4%
+ *   "OUR"          76pt  model 168.9pt  actual 158.2pt  +6.8%
+ */
+/**
+ * Width of `text` in points at `fontSizePt`, with `trackingPt` of signed
+ * letter-spacing applied per character (negative when the run is condensed).
+ */
+export declare function estimateTextWidthPt(text: string, fontSizePt: number, trackingPt?: number): number;
+/**
+ * Lines `text` needs when wrapped at `widthPt`, breaking on spaces. A word
+ * wider than the line gets its own line here; the renderer would break it
+ * mid-word, which `docx/text-fit` reports separately.
+ */
+export declare function estimateWrappedLines(text: string, widthPt: number, fontSizePt: number, trackingPt?: number): number;
+//# sourceMappingURL=text-metrics.d.ts.map

package/dist/quality/text-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-metrics.d.ts","sourceRoot":"","sources":["../../src/quality/text-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAgFH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,SAAI,GACb,MAAM,CAOR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,SAAI,GACb,MAAM,CAuBR"}