@json-to-office/jto-ops 4.2.0 → 4.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FontRuntimeOpts, ServicesConfig, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, ResolvedFont } from '@json-to-office/shared';
+import { FontRuntimeOpts, ServicesConfig, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, JsonBlockDefinition, BlockSlot, ResolvedFont } from '@json-to-office/shared';
 import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis, QualityRulePack, QualityDiagnostic, QualityAnalyzeOptions } from '@json-to-office/quality';
 
 type FormatName = 'docx' | 'pptx';
@@ -470,6 +470,22 @@ interface TextOccurrence {
     endPageIndex: number;
     parts: OccurrencePart[];
 }
+/**
+ * Word indices in the order a reader takes them, decided from geometry
+ * rather than from the order poppler emitted them: poppler 24 lists a table
+ * row line by line across every cell, poppler 26 lists it cell by cell, and
+ * an authored string in a wrapped cell only survives the second.
+ *
+ * Rows are grouped by vertical overlap and split into fragments at gaps
+ * wider than half the line is tall. A row of two or more fragments opens a
+ * column block; the rows under it belong to the block while each of their
+ * fragments sits inside one column (a right-aligned cell's second line
+ * starts further right; a wrapped label's later lines are the only
+ * fragment of their row) and the rows stay a line apart. A block reads
+ * column by column, so a cell's lines come out together; a row of one
+ * fragment outside any block — prose — reads as it lies.
+ */
+declare function readingOrder(words: readonly PdfTextWord[]): number[];
 /** What an inventory entry needs to be matched: its text, in reading order. */
 interface InventoryEntry {
     path: string;
@@ -617,6 +633,128 @@ declare const VISIBLE_SPILL_PT = 2;
  */
 declare function analyzeRenderedDocument(input: RenderedAnalysisInput, options?: QualityAnalyzeOptions): RenderedAnalysis;
 
+/**
+ * The block boundary matrix (#343, report portion): every JSON block
+ * definition a playground template embeds, invoked at the edges of its own
+ * slot schema — minimum and maximum cardinality, every string at its word
+ * budget, every figure at its widest — on each bundled theme, with the
+ * design fonts and with the fallback faces LibreOffice substitutes when a
+ * host lacks them, on A4 and on Letter.
+ *
+ * The generator is pure and reads nothing but the template it is handed:
+ * a definition gains coverage by being embedded, never by being listed here.
+ * What the suites do with a case — the static rules under the archetype's
+ * profile, the rendered pass over the LibreOffice PDF — is theirs; this
+ * module only says what a boundary document is.
+ *
+ * Two shapes come out. A *block case* is a small report — cover, running
+ * head, section opener — with one block at an edge in the body, so a
+ * finding names the block that caused it. A *report case* is the template's
+ * own document with every invocation at that edge, so the blocks meet each
+ * other the way they do in a real report. Both carry their definitions and
+ * dependencies inline, so nothing is resolved at render time.
+ */
+
+type Rec = Record<string, unknown>;
+type MatrixEdge = 'min' | 'max';
+type MatrixFont = 'design' | 'fallback';
+type MatrixCanvas = 'A4' | 'LETTER';
+interface BlockMatrixDefinition {
+    name: string;
+    /** The template the definition is embedded in, as the catalog names it. */
+    template: string;
+    /** Where inside that template: `/props/blocks/<name>`. */
+    pointer: string;
+    definition: JsonBlockDefinition;
+    /** The template's own first invocation, when it has one: the nominal fill. */
+    example?: Rec;
+}
+interface BlockMatrixCase {
+    id: string;
+    /** The block at its edge, or `report` for the whole template at that edge. */
+    block: string;
+    edge: MatrixEdge;
+    theme: string;
+    font: MatrixFont;
+    canvas: MatrixCanvas;
+    document: Rec;
+}
+interface BlockMatrixOptions {
+    themes: readonly string[];
+    fonts?: readonly MatrixFont[];
+    edges?: readonly MatrixEdge[];
+    canvases?: readonly MatrixCanvas[];
+    /** Whether the whole-template report cases are generated. Default true. */
+    report?: boolean;
+    /** Whether the per-block cases are generated. Default true. */
+    blocks?: boolean;
+    /**
+     * Slot roles the profile under test requires present, so `min` keeps them:
+     * the client-report profile's `takeaway` and `source`.
+     */
+    requiredRoles?: readonly string[];
+}
+interface CaseConditions {
+    font?: MatrixFont;
+    canvas?: MatrixCanvas;
+    requiredRoles?: readonly string[];
+}
+/**
+ * The face every LibreOffice ships with, bundled inside the application on
+ * each platform: what a design font degrades to when the host lacks it, and
+ * wider than Arial or Calibri, so a fit at these metrics is a fit anywhere.
+ * Only the roles a report paints are overridden: a family declared for a
+ * role nothing uses is never embedded, and the rendered pass would report
+ * it as substituted.
+ */
+declare const FALLBACK_FONTS: {
+    readonly heading: {
+        readonly family: "DejaVu Sans";
+    };
+    readonly body: {
+        readonly family: "DejaVu Sans";
+    };
+};
+/** A 4x2 PNG: an image with an aspect ratio, and no bytes outside the process. */
+declare const MATRIX_IMAGE = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAYAAABytg0kAAAAFElEQVR42mNk+M9QzwAFjDAGACPuA/8fMSCgAAAAAElFTkSuQmCC";
+/**
+ * The widest number of a given length: a true minus, thousands separators
+ * and one decimal, every glyph at tabular width. `−1,234,567.0` for 12.
+ */
+declare function widestNumber(length: number, seed?: number): string;
+/** A slot's value at an edge; `undefined` means "leave it out". */
+declare function boundarySlotValue(slot: BlockSlot, name: string, edge: MatrixEdge, seed?: number): unknown;
+/**
+ * One invocation of a definition with every slot at the edge: optional slots
+ * left out at `min` (so defaults are what renders), every slot at `max`.
+ * A slot whose role the profile requires — a source under every figure —
+ * is never optional to that profile, so `requiredRoles` keeps it at `min`.
+ * Columns whose cells must count the rows do; nothing else knows a block.
+ */
+declare function boundaryInvocation(name: string, definition: JsonBlockDefinition, edge: MatrixEdge, seed?: number, requiredRoles?: readonly string[]): Rec;
+/**
+ * The same invocation one past the edge: the first budgeted string a word
+ * over, or the first bounded array an item over. What a slot violation
+ * looks like, so a suite can prove it is reported at the authored pointer.
+ */
+declare function overBudgetInvocation(name: string, definition: JsonBlockDefinition, seed?: number): {
+    invocation: Rec;
+    slot: string;
+    kind: 'words' | 'items';
+} | undefined;
+/** Every definition a template embeds, with the template's own example of it. */
+declare function enumerateBlockDefinitions(template: unknown, templateName: string): BlockMatrixDefinition[];
+/**
+ * A small report with one block at its edge: the chrome at the template's
+ * nominal values (or at the edge, when the chrome block is the one under
+ * test), the block in the first body section, body copy after it.
+ */
+declare function blockCaseDocument(entries: readonly BlockMatrixDefinition[], name: string, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles }?: CaseConditions): Rec;
+/** The whole template with every invocation at the edge. */
+declare function reportCaseDocument(template: unknown, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles }?: CaseConditions): Rec;
+/** Every case the options span, in a stable order. */
+declare function generateBlockMatrix(template: unknown, templateName: string, options: BlockMatrixOptions): BlockMatrixCase[];
+
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
  * duration of one PDF conversion, then clean up.
@@ -808,4 +946,4 @@ declare function emitDiagnostic(text: string, tone?: DiagnosticTone): void;
  */
 declare const stderrDiagnosticSink: DiagnosticSink;
 
-export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, type InventoryEntry, type InventoryMatch, MacOSCoreTextStager, type MappingStatus, NoopFontStager, type PdfFontInfo, type PdfTextLine, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, RENDERED_QUALITY_RULES, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, type RenderedRuleId, type RenderedTextEntry, type RequestedFont, type TextOccurrence, VISIBLE_SPILL_PT, WindowsFontStager, analyzeRenderedDocument, assignInventory, authoredTextForMatch, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, extractPdfFonts, extractPdfTextGeometry, familyRendered, getFontStager, getRasterizerCacheStats, normalizeForMatch, parsePdfFonts, parsePdfTextBbox, pdffontsAvailable, pdftotextAvailable, runWithDiagnosticSink, stderrDiagnosticSink };
+export { type BlockMatrixCase, type BlockMatrixDefinition, type BlockMatrixOptions, type CaseConditions, type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, FALLBACK_FONTS, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, type InventoryEntry, type InventoryMatch, MATRIX_IMAGE, MacOSCoreTextStager, type MappingStatus, type MatrixCanvas, type MatrixEdge, type MatrixFont, NoopFontStager, type PdfFontInfo, type PdfTextLine, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, RENDERED_QUALITY_RULES, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, type RenderedRuleId, type RenderedTextEntry, type RequestedFont, type TextOccurrence, VISIBLE_SPILL_PT, WindowsFontStager, analyzeRenderedDocument, assignInventory, authoredTextForMatch, blockCaseDocument, boundaryInvocation, boundarySlotValue, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, enumerateBlockDefinitions, extractPdfFonts, extractPdfTextGeometry, familyRendered, generateBlockMatrix, getFontStager, getRasterizerCacheStats, normalizeForMatch, overBudgetInvocation, parsePdfFonts, parsePdfTextBbox, pdffontsAvailable, pdftotextAvailable, readingOrder, reportCaseDocument, runWithDiagnosticSink, stderrDiagnosticSink, widestNumber };