postext-pdf 1.14.1 → 1.15.0

package/dist/pdf-backend/shapedText.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Text shaped with HarfBuzz, painted through glyph ids (issue #380).
+ *
+ * pdf-lib's own text path asks fontkit for the glyphs (`encodeText`). For
+ * a run HarfBuzz shapes (`complexShaping.ts`) the glyphs are registered
+ * with the font's subset here instead, as the vertical twins register
+ * theirs (`verticalFonts.ts`): the subset keeps every glyph a run shows and
+ * its `W` width, and the hex codes are the subset's ids (or the face's own,
+ * for a font embedded whole).
+ *
+ * Positions: a run is one `TJ` per stretch of glyphs at one height. Its
+ * numbers move the pen to each glyph's origin (`pen + xOffset`) and, after
+ * the last, to where HarfBuzz's advances end, so a run is exactly as wide
+ * as the layout measured it. A mark HarfBuzz raises or lowers (`yOffset`:
+ * a fatha on a shadda, a kasra under a dotted letter) is shown with the
+ * text rise (`Ts`) set to it, which moves no pen. Glyphs are shown left to
+ * right, a right-to-left run in visual order, as every right-to-left PDF
+ * shows them: readers put the line back in logical order from their
+ * positions.
+ *
+ * Reading the text back (`/ToUnicode`): clusters are graphemes, a letter
+ * with its marks. Each glyph newly added to the font is given the
+ * characters of its cluster it stands for ({@link clusterCodePoints}), and
+ * the font's map is written from them. That map is global to the font, so
+ * a glyph keeps the characters it was first given: a mirrored bracket
+ * shares its glyph with the other bracket, a contextual form can stand for
+ * other text elsewhere. A cluster whose glyphs do not read back as its own
+ * characters, a vocalised letter (readers set a raised or lowered mark on
+ * a line of its own, or after the next letter) and a cluster holding
+ * kashidas justification inserted are shown under an `/ActualText` span
+ * with the cluster's text as written, in logical order (PDF 1.7 §14.9.4).
+ * pdf.js 5 ignores the span and reads the glyphs; Poppler reads it, but
+ * turns a span of several characters around in a right-to-left line.
+ */
+import { type Color, type PDFFont } from 'pdf-lib';
+import { type PageCtx, type TextOutline, type TextShow } from './primitives';
+/** How {@link drawShapedTextPx} sets a text. */
+export interface ShapedTextOptions {
+    /** The text is one bidi run in this direction (a VDT segment flagged
+     *  `rtl`, or one without it on a line that carries directions). Absent:
+     *  the text is cut into runs first, by the engine's UAX #9
+     *  (`resolveParagraph`, `lineRuns`). */
+    direction?: 'ltr' | 'rtl';
+    /** With no {@link direction}: the paragraph direction the runs are
+     *  ordered in; by default the text's first strong letter's. */
+    base?: 'ltr' | 'rtl';
+    /** BCP 47 language of the text, for the font's `locl` forms. */
+    language?: string;
+    /** What copying and text extraction read for the glyphs: by default
+     *  each glyph's characters, with the clusters that cannot be read so (see
+     *  the module comment) under spans of their own; the whole text under one
+     *  span when given (the line's repeated hyphen left out); null for no
+     *  span at all. */
+    actualText?: string | null;
+    /** Leave tatweels (U+0640) out of the text read: justification inserted
+     *  them. `true`: every one; a number: that many, the ones kashida
+     *  justification inserted into a word (`VDTLineSegment.kashida`), so a
+     *  tatweel the author typed stays in the text read. */
+    hideTatweel?: boolean | number;
+    outline?: TextOutline;
+}
+/**
+ * Paint `text` shaped by HarfBuzz from `xPx` on the baseline, in one text
+ * object: each bidi run in its direction, the runs left to right, each run
+ * cut by the file of the face that has its characters. Character spacing
+ * is turned off for a text with joining letters, whose joins it would
+ * break. On a mirrored page the text object is turned back about the box
+ * HarfBuzz's own advances give the text (`pushTextObject`'s `advancePx`),
+ * so it lands exactly where it was measured. Returns false, painting
+ * nothing, when HarfBuzz is not loaded: the caller paints the text the
+ * fontkit way.
+ */
+export declare function drawShapedTextPx(ctx: PageCtx, text: string, xPx: number, baselinePx: number, font: PDFFont, sizePx: number, color: Color, options?: ShapedTextOptions): boolean;
+/**
+ * Text of an SVG drawing (`svgVector.ts`) shaped by HarfBuzz: the show
+ * operators of one text object in `font`'s face at `size` (the drawing's
+ * units), and its advance in those units. No `/ActualText` spans: the
+ * drawing is a figure, read through its alternate text. Null when
+ * HarfBuzz is not loaded.
+ */
+export declare function shapedSvgText(font: PDFFont, text: string, size: number, base?: 'ltr' | 'rtl'): {
+    shows: TextShow[];
+    advance: number;
+} | null;
+/** A styled run of a word painted by {@link drawStyledWordPx}: `[start,
+ *  end)` in the word's text, and the face and colour it is set in. */
+export interface StyledWordPart {
+    start: number;
+    end: number;
+    font: PDFFont;
+    color: Color;
+}
+/**
+ * Paint a word set in several styles (`VDTLineSegment.runs`, `كتا**ب**`)
+ * as one shaped run, so its letters keep the forms they take in the whole
+ * word, each glyph in the style of the run its character belongs to.
+ *
+ * The word is shaped once in its own face (`font`, the style it was
+ * measured in): that shaping gives every glyph's place and the word's
+ * width. Walking its glyphs left to right, each stretch of glyphs of one
+ * run is shown in that run's colour:
+ * - in the same face, the stretch's own glyphs, where they are;
+ * - in another face (a bold letter in a regular word), the word is shaped
+ *   whole in that face too, so the letters at the cut take the joining
+ *   forms of the whole word, and the glyphs of the stretch's characters are
+ *   shown over the box the stretch has in the word's own shaping,
+ *   horizontally scaled (`Tz`) to its width: the joins at both ends meet
+ *   their neighbours, and the word keeps the width it was measured with.
+ *   A stretch of vowel signs alone (no advance) keeps the word's face and
+ *   takes only the colour, since a mark's place depends on its letter's
+ *   glyph.
+ * A vowel sign in a run of its own (a red fatha) is a glyph of its own,
+ * so it is coloured apart from its letter. All the stretches are one text
+ * object, glyphs left to right (each stretch placed with `Td`), so the
+ * word reads back as one, as an unstyled word does.
+ *
+ * Returns false, painting nothing, when HarfBuzz is not loaded or a face
+ * sets the word from several files: the caller then paints the word in
+ * one style.
+ */
+export declare function drawStyledWordPx(ctx: PageCtx, text: string, xPx: number, baselinePx: number, font: PDFFont, sizePx: number, color: Color, parts: readonly StyledWordPart[], options?: Pick<ShapedTextOptions, 'direction' | 'language' | 'hideTatweel' | 'actualText'>): boolean;
+//# sourceMappingURL=shapedText.d.ts.map

package/dist/pdf-backend/shapedText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapedText.d.ts","sourceRoot":"","sources":["../../src/pdf-backend/shapedText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAA+J,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAKhN,OAAO,EAAoE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAoa/I,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC;;;4CAGwC;IACxC,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC1B;mEAC+D;IAC/D,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;uBAImB;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;2DAGuD;IACvD,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAwGD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAgBT;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG5I;AAED;sEACsE;AACtE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;CACd;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,CAAM,GAC7F,OAAO,CAyET"}