@openpresentation/opf 0.6.0 → 0.8.0

package/dist/composition.d.ts

@@ -1,3 +1,46 @@
+/** Canonical table grid. No renderer, fonts, DOM or network dependencies. */
+interface TableBorder {
+    color: string;
+    width: number;
+    dash?: 'solid' | 'dash' | 'dot';
+}
+interface TableCellStyle {
+    fill?: string;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    padding?: Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
+    borders?: Partial<Record<'top' | 'right' | 'bottom' | 'left', TableBorder>>;
+}
+interface TableGridCell {
+    input: unknown;
+    value: unknown;
+    style: TableCellStyle;
+    row: number;
+    column: number;
+    rowSpan: number;
+    colSpan: number;
+    header: boolean;
+    path: string;
+    valuePath: string;
+}
+interface TableGridIssue {
+    path: string;
+    message: string;
+}
+interface TableGrid {
+    rows: TableGridCell[][];
+    columnCount: number;
+    rowCount: number;
+    hasHeaders: boolean;
+    /** Anchor at each covered position; covered positions are not additional cells. */
+    owners: (TableGridCell | undefined)[][];
+    issues: TableGridIssue[];
+}
+declare function tableGrid(value: unknown, path?: string): TableGrid;
+/** Row boundaries that preserve every vertical merge, used by pagination. */
+declare function tableRowBoundaries(value: unknown): number[];
+
 /** Portable layout geometry. No fonts, DOM, renderer, or network dependencies. */
 interface Composition {
     mode?: "auto" | "grid" | "row" | "column";
@@ -54,6 +97,8 @@ interface ComposedItem {
     box: LayoutBox;
     text?: TextFit | RichTextFit | ListFit;
     textStyle?: TextStyle;
+    /** Complete accepted quote internals; consumers must reuse these fits and styles. */
+    quoteLayout?: QuoteLayout;
     /** Effective container settings, including inherited readability constraints. */
     composition: Composition;
 }
@@ -78,6 +123,37 @@ interface ComposedFlow {
     itemCount: number;
     slotCount: number;
 }
+/** Additive penalties in grid-score-v2; lower is preferred. These are not quality percentages. */
+interface CompositionPenalties {
+    cellProportions: number;
+    fontReduction: number;
+    textOverflow: number;
+    tableOverflow: number;
+    smallCells: number;
+    emptySlots: number;
+}
+interface CompositionCandidate {
+    columns: number;
+    rows: number;
+    score: number;
+    penalties: CompositionPenalties;
+}
+interface CompositionDecision {
+    path: string;
+    mode: NonNullable<Composition['mode']> | 'regions';
+    reason: 'lowest-score' | 'configured-mode' | 'promoted-regions';
+    selectedColumns?: number;
+    /** Only candidates actually evaluated by automatic selection, in tie-break order. */
+    candidates: CompositionCandidate[];
+}
+interface CompositionExplanation {
+    algorithm: 'grid-score-v2';
+    /** Provided widths do not establish shaping, glyph coverage or native fidelity. */
+    textMeasurement: 'estimated' | 'provided';
+    decisions: CompositionDecision[];
+    /** Payloads whose complete internal fit is not covered by this scoring model. */
+    unmeasuredPayloads: string[];
+}
 interface SlideComposition {
     width: number;
     height: number;
@@ -87,6 +163,7 @@ interface SlideComposition {
     flows: ComposedFlow[];
     diagnostics: LayoutDiagnostic[];
     composition: Composition;
+    explanation?: CompositionExplanation;
 }
 interface ComposeSlideOptions {
     fonts?: Partial<FontFamilies>;
@@ -95,16 +172,72 @@ interface ComposeSlideOptions {
     height?: number;
     slideIndex?: number;
     layout?: Record<string, unknown>;
+    /** Return candidate scores and coverage without changing the selected geometry. */
+    explain?: boolean;
 }
 declare class OPFCompositionError extends Error {
     readonly diagnostics: LayoutDiagnostic[];
     readonly code = "layout-overflow";
-    constructor(diagnostics: LayoutDiagnostic[]);
+    readonly explanation?: CompositionExplanation;
+    constructor(diagnostics: LayoutDiagnostic[], explanation?: CompositionExplanation);
 }
 /** Deterministic estimate, not a font shaping engine. Preserves explicit line breaks. */
 declare function measureText(text: string, fontSize: number): number;
 declare function wrapText(text: string, width: number, fontSize: number, measure?: MeasureTextWidth): string[];
 declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth): TextFit;
+interface QuoteContent {
+    text: string;
+    attribution?: string;
+    source?: string;
+}
+/** Source and displayed-text ranges are half-open UTF-16 offsets. Added punctuation has no source range. */
+interface QuoteTextSource {
+    path: string;
+    start: number;
+    end: number;
+    outputStart: number;
+    outputEnd: number;
+}
+interface QuoteTextPart {
+    role: 'body' | 'footer';
+    path: string;
+    text: string;
+    sources: QuoteTextSource[];
+    /** Available space, before fitting. Invalid dimensions remain visible in failed results. */
+    box: LayoutBox;
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    /** Absent when the available box is invalid; never fit against an invented one-pixel box. */
+    fit?: TextFit;
+}
+interface QuoteLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    parts: QuoteTextPart['role'][];
+}
+interface QuoteLayout {
+    algorithm: 'quote-flow-v1';
+    textMeasurement: 'estimated' | 'provided';
+    parts: QuoteTextPart[];
+    diagnostics: QuoteLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface QuoteLayoutOptions {
+    /** Canvas short edge divided by 720. Insets retain the current 18 reference-pixel contract. */
+    scale?: number;
+    fonts?: Partial<FontFamilies>;
+    /** Readability floor in reference pixels, before canvas scaling. */
+    minFontSize?: number;
+    overflow?: Composition['overflow'];
+    path?: string;
+    textMeasurement?: TextMeasurement;
+}
+/**
+ * Allocate and measure quote body/footer space for composition, rendering and export. Callers must
+ * check overflow before accepting the parts. Line boxes are not shaped glyph or native raster bounds.
+ */
+declare function layoutQuote(value: string | QuoteContent, box: LayoutBox, options?: QuoteLayoutOptions): QuoteLayout;
 interface RichTextRun {
     text: string;
     bold?: boolean;
@@ -190,6 +323,13 @@ interface TableLayoutOptions {
 }
 interface TableCellLayout {
     value: unknown;
+    input: unknown;
+    sourcePath: string;
+    style: TableCellStyle;
+    row: number;
+    column: number;
+    rowSpan: number;
+    colSpan: number;
     path: string;
     header: boolean;
     rich: boolean;
@@ -222,4 +362,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableCellLayout, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textWidthMeasurer, wrapText };
+export { type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionCandidate, type CompositionDecision, type CompositionExplanation, type CompositionPenalties, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type QuoteContent, type QuoteLayout, type QuoteLayoutDiagnostic, type QuoteLayoutOptions, type QuoteTextPart, type QuoteTextSource, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

package/dist/composition.js

@@ -1 +1 @@
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textWidthMeasurer, wrapText } from './chunk-C7GKRLI6.js';
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-NEQAPMS2.js';