reamkit 1.29.0 → 1.31.0

package/dist/esm/pdf-reader/flow-build.d.ts

@@ -1,7 +1,8 @@
-import { BodyElement, ParagraphProperties, Section, SectionProperties, TextOutline } from '../core/document-model/index.js';
-import { FlowDoc } from '../core/ir/flow.js';
+import { BodyElement, Ligatures, ParagraphProperties, Section, SectionProperties, ShapeBlock, TextOutline } from '../core/document-model/index.js';
+import { FaceFamily, FaceOutlines, FlowDoc } from '../core/ir/flow.js';
 import { FontRegistry } from '../core/font/index.js';
-import { Loss, ResourceStore } from '../core/ir/index.js';
+import { Loss, Pt, ResourceStore } from '../core/ir/index.js';
+import { Display } from './display.js';
 import { PdfImage } from './images.js';
 import { PdfPage } from './document.js';
 import { PdfVector } from './vector.js';
@@ -36,6 +37,28 @@ export interface PageFrame {
  */
 export declare function paragraphBlock(text: string, outlineLevel?: number): BodyElement;
 /** One piece of reconstructed text, carrying any hyperlink (E-PDF EP8). */
+/**
+ * The space set between a span and what follows it, in the span's own size and
+ * face: a word space is as wide as the type it stands in.
+ *
+ * Written bare, the space took the document's default size, whatever the words
+ * around it were set at: issue10665_reduced.pdf sets "78" and "110" twenty
+ * points apart in 60-point type, and the eleven-point space between them closed
+ * them up to "78110"; in 7-point footnotes the same space is half as wide
+ * again as the page's, and pushes their lines over.
+ *
+ * A space between two words one text markup marks is marked with them: the
+ * band a highlighter lays runs across the gap. comments.pdf highlights two
+ * lines on its sixth page, and with its spaces left bare the band came back
+ * broken at every word.
+ *
+ * @param before The span the space follows, where there is one.
+ * @param after  What follows the space, where anything does.
+ * @returns The space.
+ */
+export declare function spaceAfter(before: TextSpan | undefined, after?: {
+    readonly markup?: TextMarkup;
+}): TextSpan;
 export interface TextSpan {
     readonly text: string;
     readonly href?: string;
@@ -59,6 +82,12 @@ export interface TextSpan {
     readonly script?: 'superscript' | 'subscript';
     /** §12.5.6.10 — a text-markup annotation marks these words. */
     readonly markup?: TextMarkup;
+    /**
+     * §17.3.2.43 — the share of their own width the characters are set at: a
+     * word space the page set narrower than the face's own (see `fittedSpace` in
+     * ./layout).
+     */
+    readonly widthScale?: number;
 }
 /**
  * Build a paragraph {@link BodyElement} from positioned {@link TextSpan}s,
@@ -66,7 +95,21 @@ export interface TextSpan {
  * survives as its own run) and squashing whitespace. With no hrefs this
  * collapses to a single run — the same shape {@link paragraphBlock} produces.
  */
-export declare function paragraphFromRuns(spans: ReadonlyArray<TextSpan>, outlineLevel?: number, placement?: Pick<ParagraphProperties, 'alignment' | 'spacingBefore' | 'indentLeft' | 'indentFirstLine' | 'tabs'>): BodyElement;
+export declare function paragraphFromRuns(spans: ReadonlyArray<TextSpan>, outlineLevel?: number, placement?: Pick<ParagraphProperties, 'alignment' | 'spacingBefore' | 'spacingLine' | 'spacingLineRule' | 'indentLeft' | 'indentRight' | 'indentFirstLine' | 'tabs'>): BodyElement;
+/**
+ * The height of a line that carries nothing to read: one twip, the least
+ * §17.3.1.33 can state. Zero is not a height a writer states at all — it is
+ * read as "no line spacing given", and the reader's single spacing comes back.
+ */
+export declare const CARRIER_LINE_PT: Pt;
+/**
+ * §17.3.1.33 — the paragraph a floating mark is anchored in, which takes no
+ * room: the mark stands where the page drew it and the line carrying it is on
+ * no page. Left at a reader's single spacing, every rule and fill an invoice
+ * draws was a blank line in the flow, and the text under it moved down a line
+ * for each.
+ */
+export declare const FLOAT_CARRIER: ParagraphProperties;
 /**
  * Store a {@link PdfImage}'s bytes (content-addressed dedup) and build the image
  * {@link BodyElement} that references them, sized in points from the placement
@@ -97,6 +140,53 @@ export declare function positionedText(spans: ReadonlyArray<TextSpan>, box: {
     width: number;
     height: number;
 }, frame: PageFrame, zOrder: number, rotation60k?: number): BodyElement;
+/**
+ * One part of a figure (see `./figures`): the shape it is drawn as, and where
+ * its box stands on the page — its left edge and its top, y-up.
+ */
+export interface FigureMember {
+    readonly shape: ShapeBlock;
+    readonly left: number;
+    readonly top: number;
+}
+/** A path of a figure, drawn where the page drew it. */
+export declare function vectorMember(v: PdfVector): FigureMember;
+/**
+ * A picture of a figure: a box filled with it (§20.1.8.14), which is what a
+ * `pic:pic` inside a group is — the shadows comments.pdf lays under each of
+ * its boxes.
+ */
+export declare function imageMember(image: PdfImage, resources: ResourceStore): FigureMember;
+/**
+ * A label of a figure: a line of its words, in a box as wide as they are.
+ * The box never wraps — set in a face a little wider than the page's, one
+ * word would break in two.
+ */
+export declare function labelMember(spans: ReadonlyArray<TextSpan>, box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rotation60k?: number): FigureMember;
+/** The box a figure's parts stand in, on the page (y-up). */
+export declare function membersBox(members: ReadonlyArray<FigureMember>): {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * §20.5.2.17 — a figure as the one drawing it is: a group holding its paths,
+ * its pictures and its labels at their places in it, set in a paragraph of
+ * its own. An inline drawing takes the room it is tall (a line holding
+ * nothing but a picture is the picture's height in Word), so the text after
+ * it follows it, and the figure goes with its paragraph wherever the text
+ * puts that.
+ *
+ * @param members    Its parts, in the order they are painted.
+ * @param properties The paragraph it stands in.
+ */
+export declare function figureBlock(members: ReadonlyArray<FigureMember>, properties: ParagraphProperties): BodyElement;
 /** Collapse losses sharing a `detail` message (the same colour space dropped on many pages). */
 export declare function dedupeLosses(losses: ReadonlyArray<Loss>): Array<Loss>;
 /**
@@ -122,7 +212,106 @@ export declare function shapeBlock(v: PdfVector, frame?: PageFrame, zOrder?: num
  * this single geometry — a known approximation, still far better than a fixed
  * `A4`. Returns `undefined` when there is no usable first-page box.
  */
-export declare function sectionFromPdfPages(pages: ReadonlyArray<PdfPage>): SectionProperties | undefined;
+export declare function sectionFromPdfPages(pages: ReadonlyArray<PdfPage>, display?: Display): SectionProperties | undefined;
+/**
+ * §17.6.20 — a section read in a page's text frame (see `textFrameOf`), set
+ * back on the sheet the page is shown on, its lines running down it (`tbRl`).
+ *
+ * The frame is the sheet turned back a quarter, so its measurements carry
+ * over edge for edge: the frame's left margin is where each line starts, the
+ * sheet's top one; its top margin is where the first line stands, the
+ * sheet's right one.
+ *
+ * @param section The section as the frame measured it.
+ * @param display The geometry its pages were read in.
+ * @returns The section on the sheet, or the section unchanged for a page read
+ *          on its sheet.
+ */
+export declare function sectionOnSheet(section: SectionProperties | undefined, display: Display | undefined): SectionProperties | undefined;
+/**
+ * A mark anchored to a page read in its text frame, set on the SHEET the page
+ * is shown on: where the page drew it, turned with the page.
+ *
+ * Word lays a `tbRl` section's text down the sheet but stands a drawing
+ * anchored to the page at its offsets on the sheet, upright (§17.6.20) — so a
+ * picture the frame placed is carried onto the sheet, and turned a quarter
+ * clockwise as the words around it are.
+ *
+ * @param el         A body element, anchored or not.
+ * @param sheetWidth The sheet's width, which is the frame's height.
+ * @returns The element, anchored on the sheet.
+ */
+export declare function floatOntoSheet(el: BodyElement, sheetWidth: number): BodyElement;
+/** How many lines a sheet must hold before where they end says where its measure does. */
+export declare const MEASURE_LINES = 3;
+/**
+ * How far in, as a share of the sheet, a right margin the lines do not show
+ * may come: what a sheet of a line or two is re-set across is at least the
+ * rest of it.
+ */
+export declare const GUESSED_MARGIN: number;
+/**
+ * §17.3.1.33 — where the baseline of an EXACT line stands in its box, from the
+ * top. LibreOffice puts it at four fifths of the height; Word at the height
+ * less the face's descent, which for the faces documents use is within a tenth
+ * of a line of the same place.
+ */
+export declare const BASELINE_AT = 0.8;
+/** A line's box where no pitch was measured: the ordinary single spacing, in ems. */
+export declare const NATURAL_LINE_EM = 1.2;
+/**
+ * How far above its baseline the first line's BOX reaches, as a fraction of the
+ * size — which is what the top margin has to leave room for. The lines are set
+ * in exact boxes (see `groupIntoParagraphs`), so this is where the box's top
+ * stands, not where a face's ascender happens to.
+ */
+export declare const ASCENDER: number;
+/**
+ * The size a document's text is set in: the middle of every size its runs
+ * carry.
+ *
+ * @param pageRuns Each page's runs.
+ * @returns The size, in points; 0 where no run states one.
+ */
+export declare function textSizeOf(pageRuns: ReadonlyArray<ReadonlyArray<TextRun>>): number;
+/**
+ * Whether a run is set too small to be read, beside the text of its document —
+ * a mark the producer leaves on the sheet, not a line of the page.
+ *
+ * TCPDF signs the last page of everything it makes "Powered by TCPDF
+ * (www.tcpdf.org)" in type one point high, three points from the corner of the
+ * paper. Taken for text it was the leftmost and the lowest thing on the page:
+ * the margins came in at the edge of the sheet and every line of basicapi.pdf
+ * and alphatrans.pdf was set against it.
+ *
+ * @param run      The run.
+ * @param textSize The size the document's text is set in (see {@link textSizeOf}).
+ * @returns `true` where the run is a mark rather than text.
+ */
+export declare function tooSmallToRead(run: TextRun, textSize: number): boolean;
+/**
+ * The margins the SOURCE used, measured off where its words actually sit.
+ *
+ * A PDF states none — text is placed anywhere on the MediaBox — so the reader
+ * used to leave them at zero rather than invent an inch. But the words
+ * themselves say where the margin was: the leftmost glyph on the page is the
+ * left margin, and reflowing inside it keeps the measure the author set instead
+ * of running the text from edge to edge.
+ *
+ * Measured on the MEDIAN page rather than the extreme one, so a single full-
+ * bleed rule or a page number in the corner does not collapse the margin for
+ * the whole document, and clamped so a strange page cannot leave no text area
+ * at all.
+ *
+ * @param section  The section the page box gave, or `undefined`.
+ * @param shown    Each page as it is shown, for its own width and height.
+ * @param pageRuns Each page's runs, already placed on the shown page.
+ * @param pageMarks Each page's pictures, which the measure has to hold.
+ * @param foot     The running foot lifted off the pages, as the first page
+ *                 showed it — the band the text block stands above.
+ * @returns The section with measured margins, or `section` when nothing is
+ *          measurable.
+ */
 export declare function withMeasuredMargins(section: SectionProperties | undefined, shown: ReadonlyArray<{
     width: number;
     height: number;
@@ -131,7 +320,35 @@ export declare function withMeasuredMargins(section: SectionProperties | undefin
     y: number;
     widthPt: number;
     heightPt: number;
-}>>): SectionProperties | undefined;
+}>>, foot?: ReadonlyArray<TextRun>): SectionProperties | undefined;
+/** What a face's runs ask of a word processor to be set as the page set them. */
+export interface Typesetting {
+    /** §17.3.2.19 — kerned from this size up. */
+    readonly kerningMinPt?: Pt;
+    /** [MS-DOCX] `w14:ligatures` — set with these ligatures. */
+    readonly ligatures?: Ligatures;
+}
+/**
+ * The runs set in a face the page KERNED or LIGATED, marked so (see
+ * `pageSpacing`, `FaceOutlines.ligatures`): a word processor kerns nothing a
+ * run does not ask it to, and set unkerned, a line kerned on the page runs
+ * longer than it did there; a ligature the embedded face carries is formed
+ * where the run asks for its face's ligatures.
+ *
+ * @param blocks   The blocks to mark, tables and text boxes within them too.
+ * @param typeset  Run font name → what its runs ask for.
+ * @returns The blocks, their runs in those faces asking for it.
+ */
+export declare function typesetRuns(blocks: ReadonlyArray<BodyElement>, typeset: ReadonlyMap<string, Typesetting>): Array<BodyElement>;
+/**
+ * What each face's runs ask for: kerning where the page kerned the face, and
+ * its standard ligatures where the page drew one of them (the ligatures the
+ * face's embedded font then forms are exactly the ones the page drew).
+ *
+ * @param kerned       The run font names of the faces the page kerned.
+ * @param faceOutlines Run font name → the face's outlines, ligatures among them.
+ */
+export declare function typesetting(kerned: ReadonlySet<string>, faceOutlines: ReadonlyMap<string, FaceOutlines> | undefined): Map<string, Typesetting>;
 /**
  * Assemble the final {@link FlowDoc} for a reconstruction: the body elements
  * with their styles resolved against the empty style sheet, the lifted-image
@@ -139,4 +356,4 @@ export declare function withMeasuredMargins(section: SectionProperties | undefin
  * both reconstruction paths (the tagged fast-path EP3 and the heuristic layout
  * path EP4).
  */
-export declare function buildFlowDoc(body: ReadonlyArray<BodyElement>, resources?: ResourceStore, section?: SectionProperties, embeddedFonts?: ReadonlyMap<string, FontRegistry>, sections?: ReadonlyArray<Section>, headersFooters?: ReadonlyMap<string, ReadonlyArray<BodyElement>>): FlowDoc;
+export declare function buildFlowDoc(body: ReadonlyArray<BodyElement>, resources?: ResourceStore, section?: SectionProperties, embeddedFonts?: ReadonlyMap<string, FontRegistry>, sections?: ReadonlyArray<Section>, headersFooters?: ReadonlyMap<string, ReadonlyArray<BodyElement>>, faceFamilies?: ReadonlyMap<string, FaceFamily>, faceOutlines?: ReadonlyMap<string, FaceOutlines>, kerned?: ReadonlySet<string>): FlowDoc;