reamkit 1.30.0 → 1.32.0

package/dist/esm/pdf-reader/layout.d.ts

@@ -1,6 +1,14 @@
+import { PageNumbering } from './page-numbers.js';
 import { PdfVector } from './vector.js';
+import { BodyElement, SectionProperties } from '../core/document-model/index.js';
+import { TextRun } from './content.js';
 import { PdfFile } from './document.js';
 import { Reconstruction } from './flow-build.js';
+/** The relationships the reconstruction files its running head and foot under. */
+export declare const FOOTER_PART = "pdf-running-foot";
+/** The part the running foot of a book's even pages is written to (see `sidesOf`). */
+export declare const EVEN_FOOTER_PART = "pdf-running-foot-even";
+export declare const HEADER_PART = "pdf-running-head";
 /** §9.10.2 — a glyph the face maps to no character (see `./font`). */
 export declare const UNMAPPED = "\uFFFD";
 /**
@@ -19,6 +27,20 @@ export declare const UNMAPPED = "\uFFFD";
  * @returns The reconstructed {@link FlowDoc} plus any read-time losses.
  */
 export declare function reconstructByLayout(file: PdfFile, mode?: 'flow' | 'positional'): Reconstruction;
+/** Where the page's text starts and ends, ignoring what is only a space. */
+export declare function pageTextEdges(runs: ReadonlyArray<TextRun>): {
+    left: number;
+    right: number;
+} | undefined;
+/**
+ * Whether this page STEPS between its words rather than writing spaces.
+ *
+ * Counted rather than guessed: bigboundingbox.pdf writes a space in one run in
+ * a hundred, TAMReview.pdf in a third of them, and no page does a little of
+ * both. A page with almost no text says nothing either way and keeps the
+ * cautious reading.
+ */
+export declare function stepsBetweenWords(runs: ReadonlyArray<TextRun>): boolean;
 /**
  * Whether a line ENDED a paragraph, rather than wrapping into the next.
  *
@@ -57,6 +79,77 @@ export declare function endedParagraph(prev: {
     left: number;
     right: number;
 } | undefined): boolean;
+/**
+ * §17.6.13 — the running foot a document repeats at the bottom of its pages.
+ *
+ * A page number, a title, a URL: it stands below the text block, in the margin,
+ * and it is not part of what the page SAYS. Read as body it goes wherever the
+ * reflow puts it — bug1997343.pdf's "1" came out on a sheet of its own between
+ * the two the paper has, and TAMReview.pdf's "Sprouts — http://…" landed in the
+ * middle of the abstract.
+ *
+ * What makes it a running foot is that it RUNS: the same place, page after
+ * page, cut off from the text above it by more than a line of white. One page
+ * proves nothing, so two are asked for.
+ *
+ * @param pageRuns Each page's runs, placed.
+ * @param shown    Each page's shown geometry.
+ * @returns The runs to lift off each page and the band to put them in, or
+ *          `undefined` where the document repeats nothing.
+ */
+export declare function runningFoot(pageRuns: ReadonlyArray<ReadonlyArray<TextRun>>, shown: ReadonlyArray<{
+    height: number;
+}>, where: 'head' | 'foot'): {
+    lift: ReadonlyArray<ReadonlySet<TextRun>>;
+    band: ReadonlyArray<TextRun>;
+    /** Whether a number in it is the PAGE's number rather than part of the text. */
+    numbered: boolean;
+} | undefined;
+/** How many of a document's pages must carry the foot before it is running. */
+/**
+ * §17.6.12 — how a document's pages are numbered, read off the band that
+ * prints their numbers (see ./page-numbers).
+ *
+ * @param band The running head or foot whose numbers change from page to page.
+ * @returns The numbering, or undefined where no band numbers the pages.
+ */
+export declare function numberingOf(band: {
+    readonly lift: ReadonlyArray<ReadonlySet<TextRun>>;
+} | undefined): PageNumbering | undefined;
+/**
+ * The numbering a section opening at `page` states: the numerals of the
+ * sequence the page is counted in, and the number the sequence starts at where
+ * it starts there.
+ *
+ * @param numbering The document's numbering.
+ * @param page      The section's first page.
+ * @returns The section's `pageNumberFormat` and `pageNumberStart`, as needed.
+ */
+export declare function numberedFrom(numbering: PageNumbering | undefined, page: number): Pick<SectionProperties, 'pageNumberFormat' | 'pageNumberStart'>;
+/**
+ * The band itself: the foot's own line, with the number in it made a field.
+ *
+ * §17.16.5.35 — a page number is not the text "1"; it is the number of the page
+ * it is drawn on, which is why the same band serves every page.
+ *
+ * A foot is written in REGIONS, the way a spreadsheet's is: something at the
+ * left of the sheet, something at the middle, something against the far edge.
+ * ZapfDingbats.pdf signs each page "© RenderX 2000" at the left and "XSL
+ * Formatting Objects Test Suite" at the right, and the two hundred points
+ * between them came back as one word space, the two texts crowding each other
+ * at the left. They stand on TAB STOPS instead (§17.3.1.38), which is what the
+ * two hundred points are.
+ *
+ * @param runs     The foot's runs.
+ * @param stepped  Whether the page steps between its words.
+ * @param measure  The measure it was set across, for its alignment.
+ * @param numbered Whether a number in it is the page's own.
+ * @param numeral  That number as this band prints it, where it is known.
+ */
+export declare function footerBand(runs: ReadonlyArray<TextRun>, stepped: boolean, measure: {
+    left: number;
+    right: number;
+} | undefined, numbered: boolean, numeral?: string): Array<BodyElement>;
 /**
  * §9.6.6 — the glyphs a page draws for want of characters, gathered into the
  * WORDS they stand in: a traced glyph that stands against the one before it,