@openpresentation/opf 0.9.0 → 0.10.1

package/dist/composition.d.ts

@@ -41,6 +41,20 @@ declare function tableGrid(value: unknown, path?: string): TableGrid;
 /** Row boundaries that preserve every vertical merge, used by pagination. */
 declare function tableRowBoundaries(value: unknown): number[];
 
+declare function colorContrast(foreground: string, background: string): number | undefined;
+/** Keep an inherited text color at >=4.5:1; otherwise select black or white.
+ * Callers must preserve explicit text-color overrides before using this fallback.
+ * An unresolved/translucent fill preserves the preferred color, without a contrast claim.
+ */
+declare function textColorForFill(fill: string, preferred: string): string;
+/** Keep an inherited chart mark at >=3:1 against its opaque panel. Otherwise
+ * mix toward black or white in bounded 1/255 steps, choosing the first passing
+ * step (higher contrast breaks a tie). This retains a recognizable palette;
+ * it does not establish distinction between adjacent series or colorblind safety.
+ * Explicit mark overrides belong to the caller; unresolved alpha is preserved.
+ */
+declare function chartColorForFill(fill: string, preferred: string): string;
+
 /** Portable layout geometry. No fonts, DOM, renderer, or network dependencies. */
 interface Composition {
     mode?: "auto" | "grid" | "row" | "column";
@@ -59,15 +73,22 @@ interface LayoutBox {
     height: number;
 }
 interface LayoutDiagnostic {
-    code: "text-overflow" | "small-cell";
+    code: "text-overflow" | "small-cell" | "unresolved-content";
     path: string;
     message: string;
 }
+/** Physical legacy-family selection supplied by a font provider, independently of its numeric weight. */
+interface FontFaceSelection {
+    family: string;
+    bold: boolean;
+    italic: boolean;
+}
 interface TextStyle {
     fontFamily: string;
     fontWeight: number;
     italic?: boolean;
     path?: string;
+    fontFace?: FontFaceSelection;
 }
 interface FontFamilies {
     heading: string;
@@ -78,16 +99,48 @@ declare function resolveFontFamilies(input: unknown): FontFamilies;
 interface TextMeasurement {
     measure: (text: string, fontSize: number, style: TextStyle) => number;
     resolveStyle?: (style: TextStyle) => TextStyle;
+    /** Shaped vector ink relative to the left baseline origin (positive y down).
+     * Null means no outline. These are not hinted/antialiased raster bounds. */
+    outlineBounds?: (text: string, fontSize: number, style: TextStyle) => LayoutBox | null;
 }
 type MeasureTextWidth = (text: string, fontSize: number) => number;
 declare function resolveTextStyle(style: TextStyle, measurement?: TextMeasurement): TextStyle;
 declare function textWidthMeasurer(style: TextStyle, measurement?: TextMeasurement): MeasureTextWidth;
+/** Validate an optional host outline measurement without inventing raster coverage. */
+declare function measureTextOutline(text: string, fontSize: number, style: TextStyle, measurement?: TextMeasurement): LayoutBox | null | undefined;
+interface TextLineInk {
+    width: number;
+    y: number;
+    baseline: number;
+    height: number;
+    outline: LayoutBox | null;
+}
+interface TextPlacementLine {
+    x: number;
+    y: number;
+    baseline: number;
+    height: number;
+    width: number;
+    outline: LayoutBox | null;
+}
+interface TextPlacement {
+    alignment: 'left' | 'center' | 'right';
+    /** Reference-pixel clearance around vector outlines; not a universal raster guarantee. */
+    rasterPadding: number;
+    lines: TextPlacementLine[];
+    height: number;
+    overflow: boolean;
+}
 interface TextFit {
     lines: string[];
     fontSize: number;
     lineHeight: number;
     overflow: boolean;
+    placement?: TextPlacement;
 }
+/** Place complete measured lines, preserving alignment where it leaves room for ink.
+ * Move following baselines together when outlines need more vertical separation. */
+declare function placeTextLines(lines: readonly TextLineInk[], box: LayoutBox, alignment?: TextPlacement['alignment'], rasterPadding?: number): TextPlacement;
 interface ComposedItem {
     path: string;
     field: string;
@@ -95,12 +148,18 @@ interface ComposedItem {
     value: unknown;
     payload: Record<string, unknown>;
     box: LayoutBox;
+    /** Optional visible card allocation; box and all accepted internals occupy its padded interior. */
+    frameBox?: LayoutBox;
     text?: TextFit | RichTextFit | ListFit | CodeTextFit;
     textStyle?: TextStyle;
     /** Complete accepted quote internals; consumers must reuse these fits and styles. */
     quoteLayout?: QuoteLayout;
     /** Complete accepted code internals, including source lines and literal tab positions. */
     codeLayout?: CodeLayout;
+    /** Complete shared metric geometry, including its unit, label and metadata. */
+    metricLayout?: MetricLayout;
+    /** Complete timeline fields, markers and connector accepted by composition. */
+    timelineLayout?: TimelineLayout;
     /** Effective container settings, including inherited readability constraints. */
     composition: Composition;
 }
@@ -125,7 +184,7 @@ interface ComposedFlow {
     itemCount: number;
     slotCount: number;
 }
-/** Additive penalties in grid-score-v3; lower is preferred. These are not quality percentages. */
+/** Additive penalties in grid-score-v9; lower is preferred. These are not quality percentages. */
 interface CompositionPenalties {
     cellProportions: number;
     fontReduction: number;
@@ -149,9 +208,13 @@ interface CompositionDecision {
     candidates: CompositionCandidate[];
 }
 interface CompositionExplanation {
-    algorithm: 'grid-score-v3';
+    algorithm: 'grid-score-v9';
     /** Provided widths do not establish shaping, glyph coverage or native fidelity. */
     textMeasurement: 'estimated' | 'provided';
+    /** Optional vector coverage for headings and scalar/rich text, not every payload. */
+    textOutlines: 'provided' | 'unavailable';
+    /** Effective body-text reference pixels; furniture reports its own placement padding. Not a universal raster tolerance. */
+    textRasterPadding: number;
     decisions: CompositionDecision[];
     /** Payloads whose complete internal fit is not covered by this scoring model. */
     unmeasuredPayloads: string[];
@@ -165,10 +228,29 @@ interface SlideComposition {
     flows: ComposedFlow[];
     diagnostics: LayoutDiagnostic[];
     composition: Composition;
+    /** Repeated furniture is measured separately from body pagination leaves. */
+    furniture?: FurnitureLayout;
     explanation?: CompositionExplanation;
 }
 interface ComposeSlideOptions {
+    /** Context for inherited furniture and generated organization names. */
+    presentation?: {
+        design?: {
+            header?: unknown;
+            footer?: unknown;
+        };
+        organization?: unknown;
+    };
+    /** One-based displayed number; source paths still use slideIndex. */
+    slideNumber?: number;
     fonts?: Partial<FontFamilies>;
+    /** Host-resolved alignment for shared content; slide design can override it. */
+    contentAlignment?: 'left' | 'center' | 'right';
+    titleAlignment?: 'left' | 'center' | 'right';
+    /** Unscaled reference pixels around provided vector outlines; defaults to 1 for body text and 2 for furniture. Explicit values apply to both. */
+    textRasterPadding?: number;
+    /** Host-resolved body cards. A slide's explicit design.contentBox overrides this value. */
+    contentBox?: boolean;
     textMeasurement?: TextMeasurement;
     width?: number;
     height?: number;
@@ -183,10 +265,50 @@ declare class OPFCompositionError extends Error {
     readonly explanation?: CompositionExplanation;
     constructor(diagnostics: LayoutDiagnostic[], explanation?: CompositionExplanation);
 }
+interface FurniturePartBase {
+    kind: 'header' | 'footer';
+    zone: 'left' | 'center' | 'right';
+    field: 'text' | 'image' | 'organization' | 'section' | 'slideNumber' | 'date';
+    /** Literal field or controlling flag, with the actual inherited/local path. */
+    path: string;
+    /** String/asset source, when different from a generated field's flag. */
+    sourcePath?: string;
+    generated: boolean;
+    box: LayoutBox;
+    alignment: 'left' | 'center' | 'right';
+}
+interface FurnitureTextPart extends FurniturePartBase {
+    type: 'text';
+    text: string;
+    style: TextStyle;
+    requestedFontSize: number;
+    minFontSize: number;
+    fit: SourceTextFit;
+}
+interface FurnitureImagePart extends FurniturePartBase {
+    type: 'image';
+    image: unknown;
+}
+type FurniturePart = FurnitureTextPart | FurnitureImagePart;
+interface FurnitureLayout {
+    algorithm: 'furniture-flow-v2';
+    /** Includes explicitly empty definitions, which override inherited furniture. */
+    configured: boolean;
+    textMeasurement: 'estimated' | 'provided';
+    textOutlines: 'provided' | 'unavailable';
+    parts: FurniturePart[];
+    /** Outer occupied edges; composeSlide adds its normal content gap. */
+    headerBottom: number;
+    footerTop: number;
+    diagnostics: LayoutDiagnostic[];
+    overflow: boolean;
+}
+/** Resolve and measure repeated fields without mutating metadata or consulting a clock. */
+declare function layoutFurniture(input: unknown, options?: ComposeSlideOptions): FurnitureLayout;
 /** 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;
+declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth): SourceTextFit;
 interface QuoteContent {
     text: string;
     attribution?: string;
@@ -240,12 +362,132 @@ interface QuoteLayoutOptions {
  * 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 MetricContent {
+    value: string | number;
+    label?: string;
+    description?: string;
+    unit?: string;
+    delta?: string | number;
+    trend?: 'up' | 'down' | 'flat';
+}
+/** Ranges address String(sourceValue), not the numeric token spelling in serialized JSON. */
+interface MetricTextSource {
+    path: string;
+    value: string | number;
+    start: number;
+    end: number;
+}
+interface MetricTextPart {
+    role: keyof MetricContent;
+    path: string;
+    text: string;
+    sources: MetricTextSource[];
+    /** Empty optional fields retain their source mapping but occupy no visible space. */
+    visible: boolean;
+    /** Accepted absolute origin/baseline for each fit.sourceLines entry, including blank lines. */
+    linePositions: {
+        x: number;
+        baseline: number;
+    }[];
+    box: LayoutBox;
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    /** Source-preserving line/segment representation shared with code, with proportional fonts. */
+    fit?: CodeTextFit;
+}
+interface MetricLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    parts: MetricTextPart['role'][];
+}
+interface MetricLayout {
+    algorithm: 'metric-flow-v1';
+    alignment: 'left' | 'center' | 'right';
+    textMeasurement: 'estimated' | 'provided';
+    arrangement: 'inline-unit' | 'stacked';
+    /** At most 48 arrangements; value fitting is bounded by 77 reference-size trials per arrangement. */
+    attempts: number;
+    parts: MetricTextPart[];
+    diagnostics: MetricLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface MetricLayoutOptions extends QuoteLayoutOptions {
+    align?: 'left' | 'center' | 'right';
+    /** Unscaled clearance around available vector outlines; defaults to one reference pixel. */
+    textRasterPadding?: number;
+}
+/**
+ * Measure every metric field before accepting geometry. Short single-line values and units can
+ * share a baseline; longer values or units stack. No locale formatting, trend icons or rewritten
+ * source text are invented. Consumers must reuse these accepted parts and source ranges.
+ */
+declare function layoutMetric(value: string | number | MetricContent, box: LayoutBox, options?: MetricLayoutOptions): MetricLayout;
+interface TimelineEvent {
+    when?: string;
+    what: string;
+    description?: string;
+}
+interface TimelineContent {
+    name?: string;
+    description?: string;
+    events: TimelineEvent[];
+}
+interface TimelineTextPart {
+    role: 'name' | 'description' | 'when' | 'what' | 'event-description';
+    eventIndex?: number;
+    path: string;
+    text: string;
+    sources: {
+        path: string;
+        start: number;
+        end: number;
+    }[];
+    box: LayoutBox;
+    alignment: 'left' | 'center';
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    fit?: SourceTextFit;
+}
+interface TimelineLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'text-fit' | 'part-outside-cell' | 'event-space';
+}
+interface TimelineLayout {
+    algorithm: 'timeline-flow-v1';
+    arrangement: 'alternating' | 'vertical';
+    attempts: number;
+    textMeasurement: 'provided' | 'estimated';
+    textOutlines: 'provided' | 'unavailable';
+    parts: TimelineTextPart[];
+    markers: {
+        path: string;
+        eventIndex: number;
+        x: number;
+        y: number;
+        radius: number;
+    }[];
+    connector: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    diagnostics: TimelineLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface TimelineLayoutOptions extends QuoteLayoutOptions {
+    textRasterPadding?: number;
+}
+/** Preserve event order and field boundaries while trying at most 50 readable arrangements. */
+declare function layoutTimeline(value: readonly TimelineEvent[] | TimelineContent, box: LayoutBox, options?: TimelineLayoutOptions): TimelineLayout;
 interface CodeContent {
     source: string;
     language?: string;
     filename?: string;
 }
-interface CodeLineSegment {
+interface TextLineSegment {
     kind: 'text' | 'tab';
     start: number;
     end: number;
@@ -254,21 +496,26 @@ interface CodeLineSegment {
     width: number;
 }
 /** Exact half-open UTF-16 offsets into the part text, including consumed hard line breaks. */
-interface CodeLineSource {
+interface TextLineSource {
     start: number;
     end: number;
     nextStart: number;
     boundary: 'soft' | 'hard' | 'end';
     width: number;
     /** Explicit tab placement is required in SVG; CSS tab-size alone does not implement it. */
-    segments: CodeLineSegment[];
+    segments: TextLineSegment[];
 }
-interface CodeTextFit extends TextFit {
-    sourceLines: CodeLineSource[];
+interface SourceTextFit extends TextFit {
+    sourceLines: TextLineSource[];
     /** Tabs advance to the next multiple of four measured spaces from each displayed line's origin. */
     tabSize: 4;
     tabWidth: number;
 }
+/** Compatibility names for the shared source-preserving line contract. */
+type CodeLineSegment = TextLineSegment;
+type CodeLineSource = TextLineSource;
+interface CodeTextFit extends SourceTextFit {
+}
 interface CodeTextPart {
     role: 'filename' | 'language' | 'body';
     path: string;
@@ -426,4 +673,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { type CodeContent, type CodeLayout, type CodeLayoutDiagnostic, type CodeLayoutOptions, type CodeLineSegment, type CodeLineSource, type CodeTextFit, type CodeTextPart, 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, layoutCode, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };
+export { type CodeContent, type CodeLayout, type CodeLayoutDiagnostic, type CodeLayoutOptions, type CodeLineSegment, type CodeLineSource, type CodeTextFit, type CodeTextPart, type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionCandidate, type CompositionDecision, type CompositionExplanation, type CompositionPenalties, type CompositionTrack, type FontFaceSelection, type FontFamilies, type FurnitureImagePart, type FurnitureLayout, type FurniturePart, type FurniturePartBase, type FurnitureTextPart, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, type MetricContent, type MetricLayout, type MetricLayoutDiagnostic, type MetricLayoutOptions, type MetricTextPart, type MetricTextSource, 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 SourceTextFit, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextLineInk, type TextLineSegment, type TextLineSource, type TextMeasurement, type TextPlacement, type TextPlacementLine, type TextStyle, type TimelineContent, type TimelineEvent, type TimelineLayout, type TimelineLayoutDiagnostic, type TimelineLayoutOptions, type TimelineTextPart, chartColorForFill, colorContrast, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutFurniture, layoutMetric, layoutQuote, layoutTable, layoutTimeline, measureText, measureTextOutline, placeTextLines, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textColorForFill, textWidthMeasurer, wrapText };

package/dist/composition.js

@@ -1 +1 @@
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-JA5W5TVA.js';
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, chartColorForFill, colorContrast, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutFurniture, layoutMetric, layoutQuote, layoutTable, layoutTimeline, measureText, measureTextOutline, placeTextLines, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textColorForFill, textWidthMeasurer, wrapText } from './chunk-PQJRDNA6.js';