@shbernal/ts-pptx 3.2.0 → 3.4.0

package/dist/measure.d.ts

@@ -1,5 +1,5 @@
-import { bn as TextPropsOptions, i as ObjectOptions, sn as MeasureTextOptions, un as OverflowBoxOptions, vn as TextMeasurement, yn as TextProps } from "./slide-BTfn1Pyp.js";
-import { a as TsPptxError, d as InvalidOptionErrorCode, f as MediaErrorCode, h as UnsupportedFeatureErrorCode, i as PackageReadError, l as ErrorCode, m as TsPptxCode, n as InvalidOptionError, o as TsPptxErrorOptions, p as PackageReadErrorCode, r as MediaError, s as UnsupportedFeatureError, t as InternalError, u as InternalErrorCode } from "./errors-BVLCFr-t.js";
+import { dn as TextMeasurement, en as MeasureTextOptions, fn as TextProps, i as ObjectOptions, pn as TextPropsOptions, rn as OverflowBoxOptions } from "./slide-B_aInw3N.js";
+import { a as TsPptxError, d as InvalidOptionErrorCode, f as MediaErrorCode, h as UnsupportedFeatureErrorCode, i as PackageReadError, l as ErrorCode, m as TsPptxCode, n as InvalidOptionError, o as TsPptxErrorOptions, p as PackageReadErrorCode, r as MediaError, s as UnsupportedFeatureError, t as InternalError, u as InternalErrorCode } from "./errors-fB1KDJKQ.js";
 //#region src/measure/font-metrics.d.ts
 /** Per-(face,bold,italic) advance-width source backed by a parsed font file. */
 interface FontMetrics {
@@ -26,8 +26,34 @@ interface FontMetrics {
  * registered metrics at all does not engage measured fit, so this never fires there.
  */
 declare function getHeuristicFontMetrics(): FontMetrics;
-/** Parse a font file (TTF/OTF) into a `FontMetrics`. Lazily imports opentype.js. */
-declare function parseFontMetrics(data: Uint8Array): Promise<FontMetrics>;
+/** Options for {@link parseFontMetrics}. */
+interface ParseFontMetricsOptions {
+  /**
+   * Which font to read out of a file that holds several: a 0-based index, or a name
+   * matched case-insensitively against the family, full, and PostScript names
+   * (`listFontFaces` lists them). Omitted selects the first.
+   *
+   * Collections (`.ttc`/`.otc`) are why this exists: `msgothic.ttc` is three fonts and
+   * `cambria.ttc` is two. The selector means the same thing for a plain TTF/OTF, which
+   * is a one-entry list, so a wrong index or an unmatched name is an error there rather
+   * than being ignored.
+   */
+  readonly font?: number | string;
+}
+/**
+ * Parse a font file into a `FontMetrics`. Lazily imports opentype.js.
+ *
+ * Reads plain TTF/OTF and **font collections** (`.ttc`/`.otc`); for a collection, pass
+ * `font` to say which member, since a collection has no single answer. The underlying
+ * parser does not read the `ttcf` wrapper, so the selected member is unwrapped into a
+ * standalone sfnt first (see `measure/font-collection.ts`).
+ * @param {Uint8Array} data - the font file's bytes
+ * @param {ParseFontMetricsOptions} [opts] - which font, for a file holding several
+ * @returns {Promise<FontMetrics>} advance widths and cmap coverage for that font
+ * @example await parseFontMetrics(bytes) // a plain .ttf
+ * @example await parseFontMetrics(ttcBytes, { font: 'MS PGothic' })
+ */
+declare function parseFontMetrics(data: Uint8Array, opts?: ParseFontMetricsOptions): Promise<FontMetrics>;
 /**
  * Registry of `FontMetrics` keyed by `(face, bold, italic)`. Variant advances
  * differ, so bold/italic are stored separately; lookup falls back to the regular
@@ -188,6 +214,68 @@ type ResizeOutcome = {
 declare function solveResize(paragraphs: FitParagraph[], box: FitBox, resolve: MetricsResolver): ResizeOutcome;
 declare function solveShrink(paragraphs: FitParagraph[], box: FitBox, resolve: MetricsResolver): ShrinkOutcome;
 //#endregion
+//#region src/measure/font-collection.d.ts
+/**
+ * Font **collection** (`.ttc` / `.otc`) support for the write-side metrics.
+ *
+ * A collection is a single file holding several fonts that share their heavy tables.
+ * `msgothic.ttc` is three fonts (MS Gothic, MS UI Gothic, MS PGothic) over one 5.5 MB
+ * `glyf`; `cambria.ttc` is Cambria plus Cambria Math over one outline set. On Windows
+ * that is how most of the East Asian faces ship, and Cambria too, so a measurement API
+ * that only reads a bare sfnt cannot measure them at all.
+ *
+ * `opentype.js` does not read the `ttcf` wrapper (it throws `Unsupported OpenType
+ * signature ttcf` from `parseBuffer`, still true in 2.0.0), so this module unwraps one
+ * member into a standalone sfnt before handing the bytes over. It parses only the two
+ * structures that requires: the table directories and the `name` table.
+ *
+ * Upstream tracks the gap as opentypejs/opentype.js#379, open since 2019, with #866 an
+ * unmerged PR implementing it; check both before rewriting any of this.
+ *
+ * ## Layout
+ *
+ * ```text
+ * 0    'ttcf'  uint16 major, uint16 minor, uint32 numFonts, uint32 dirOffset[numFonts]
+ * ...  per member: uint32 sfntVersion, uint16 numTables, uint16 searchRange,
+ *      uint16 entrySelector, uint16 rangeShift, then numTables x 16-byte records
+ *      { char tag[4], uint32 checksum, uint32 offset, uint32 length }
+ * ```
+ *
+ * The record `offset` is **absolute from the start of the file**, which is the whole
+ * trick: two members name the same `glyf` bytes by pointing at them. So a member does
+ * not have to be *copied out* to be read on its own; it is enough to give the reader a
+ * buffer whose first bytes are that member's directory, leaving every table where it
+ * already sits. See {@link extractFontFace}.
+ */
+/** Identity of one font inside a font file, as read from its `name` table. */
+interface FontFaceInfo {
+  /** Position in the file: `0` for a plain TTF/OTF, `0..n-1` inside a collection. */
+  readonly index: number;
+  /** `name` ID 1, e.g. `'MS PGothic'`. Absent when the table has no readable record. */
+  readonly family?: string;
+  /** `name` ID 2, e.g. `'Regular'`. */
+  readonly subfamily?: string;
+  /** `name` ID 4, e.g. `'MS PGothic'`. */
+  readonly fullName?: string;
+  /** `name` ID 6, e.g. `'MS-PGothic'`. */
+  readonly postScriptName?: string;
+}
+/** True when `data` starts with the `ttcf` tag, i.e. holds more than one font. */
+declare function isFontCollection(data: Uint8Array): boolean;
+/**
+ * The fonts inside `data`, in file order. A plain TTF/OTF yields exactly one entry, so a
+ * caller never has to branch on the container format.
+ *
+ * Identity comes from each member's own `name` table, which is one of the tables a
+ * collection does *not* share. A field is absent when the table carries no readable
+ * record for it; a font whose `name` table is missing or malformed still yields an entry
+ * (with only `index`), because the metrics do not depend on it.
+ * @param {Uint8Array} data - the font file's bytes
+ * @returns {FontFaceInfo[]} one entry per font, index-ordered
+ * @example listFontFaces(readFileSync('C:/Windows/Fonts/msgothic.ttc')).map((f) => f.family)
+ */
+declare function listFontFaces(data: Uint8Array): FontFaceInfo[];
+//#endregion
 //#region src/measure/fit.d.ts
 /**
  * Layout-time text measurement against registered metrics — the public engine
@@ -205,7 +293,9 @@ declare function solveShrink(paragraphs: FitParagraph[], box: FitBox, resolve: M
  * Synchronous: assumes metrics are pre-registered (lookup is sync). A named face
  * with no exact metrics silently uses the conservative heuristic (same as export)
  * and is reported in `approximatedFaces`; an unnamed theme-default face returns
- * `measurable: false`.
+ * `measurable: false`. Code points a *registered* face has no glyph for are reported
+ * in `uncoveredCodepoints`, and are the one case where the height may come back short
+ * rather than tall — there is no font fallback here, only the font's `.notdef` advance.
  */
 declare function measureText(registry: FontMetricsRegistry, text: string | TextProps[], opts: MeasureTextOptions): TextMeasurement;
 //#endregion
@@ -219,5 +309,5 @@ type RunOpts = TextPropsOptions & ObjectOptions;
  */
 declare function buildFitParagraphs(runs: TextProps[], opts: RunOpts): FitParagraph[] | null;
 //#endregion
-export { type ErrorCode, FONT_SCALE_STEP_PCT, type FitBox, type FitParagraph, type FitRun, type FontMetrics, FontMetricsRegistry, HEIGHT_SAFETY_FACTOR, InternalError, type InternalErrorCode, InvalidOptionError, type InvalidOptionErrorCode, type LayoutResult, MIN_FONT_SCALE_PCT, type MeasureTextOptions, MediaError, type MediaErrorCode, type MetricsResolver, type OverflowBoxOptions, PackageReadError, type PackageReadErrorCode, type ResizeOutcome, SINGLE_LINE_PITCH, type ShrinkOutcome, type ShrinkResult, type TextMeasurement, type TsPptxCode, TsPptxError, type TsPptxErrorOptions, UnsupportedFeatureError, type UnsupportedFeatureErrorCode, WIDTH_SAFETY_FACTOR, buildFitParagraphs, getHeuristicFontMetrics, makeRegistryResolver, measureHeightPt, measureLayout, measureText, parseFontMetrics, solveResize, solveShrink };
+export { type ErrorCode, FONT_SCALE_STEP_PCT, type FitBox, type FitParagraph, type FitRun, type FontFaceInfo, type FontMetrics, FontMetricsRegistry, HEIGHT_SAFETY_FACTOR, InternalError, type InternalErrorCode, InvalidOptionError, type InvalidOptionErrorCode, type LayoutResult, MIN_FONT_SCALE_PCT, type MeasureTextOptions, MediaError, type MediaErrorCode, type MetricsResolver, type OverflowBoxOptions, PackageReadError, type PackageReadErrorCode, type ParseFontMetricsOptions, type ResizeOutcome, SINGLE_LINE_PITCH, type ShrinkOutcome, type ShrinkResult, type TextMeasurement, type TsPptxCode, TsPptxError, type TsPptxErrorOptions, UnsupportedFeatureError, type UnsupportedFeatureErrorCode, WIDTH_SAFETY_FACTOR, buildFitParagraphs, getHeuristicFontMetrics, isFontCollection, listFontFaces, makeRegistryResolver, measureHeightPt, measureLayout, measureText, parseFontMetrics, solveResize, solveShrink };
 //# sourceMappingURL=measure.d.ts.map

package/dist/measure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"measure.d.ts","names":[],"sources":["../src/measure/font-metrics.ts","../src/measure/text-fit.ts","../src/measure/fit.ts","../src/measure/paragraphs.ts"],"mappings":";;;;UAkBiB;;WAEP;;;;;;EAMT,iBAAiB,cAAc,gBAAgB;;;;;;;EAO/C,eAAe;;;;;;;;iBAgGA,2BAA2B;;iBAMrB,iBAAiB,MAAM,aAAa,QAAQ;;;;;;;cAqBrD;mBACK;UAET;EAIR,IAAI,cAAc,SAAS,aAAa;IAAS;IAAgB;;;EAKjE,QAAQ;;;;;;;;;;;;EAiBR,aACC,iCACA,YACA;IAAS;IAAgB;;;EAM1B,IAAI,iCAAiC,gBAAc,mBAAiB;MAahE;;;;;;;iBAUW,qBACf,UAAU,qBACV,eAAe,wBACb;;;;;;;;;;;cCpMU;;cAGA;;cAGA;;;;;;;;;;;cAYA;cACA;;UAGI;EAChB;EACA;EACA;EACA;EACA;;EAEA;;;UAIgB;EAChB,MAAM;;EAEN;;EAEA;EACA;EACA;;;UAIgB;EAChB;EACA;;;;;;;;;;EAUA;;;KAIW,mBAAmB,KAAK,WAAW;UAE9B;EAChB;EACA;;KAGW;EACP;;EACA;;EACA;EAAgB,QAAQ;;;UAmIZ;EAChB;EACA;;;;;;;EAOA;;;;;;;;;iBAUe,cACf,YAAY,gBACZ,sBACA,SAAS,iBACT,sBACA,2BACA,uBACE;;;;;iBA0Ba,gBACf,YAAY,gBACZ,sBACA,SAAS,iBACT,sBACA,2BACA;;;;;;;;;;;KAgBW;EACP;;EACA;EAAgB;;iBAoBL,YAAY,YAAY,gBAAgB,KAAK,QAAQ,SAAS,kBAAkB;iBAMhF,YAAY,YAAY,gBAAgB,KAAK,QAAQ,SAAS,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBC/OhF,YACf,UAAU,qBACV,eAAe,aACf,MAAM,qBACJ;;;KCrES,UAAU,mBAAmB;;;;;;;iBA8BzB,mBAAmB,MAAM,aAAa,MAAM,UAAU"}
+{"version":3,"file":"measure.d.ts","names":[],"sources":["../src/measure/font-metrics.ts","../src/measure/text-fit.ts","../src/measure/font-collection.ts","../src/measure/fit.ts","../src/measure/paragraphs.ts"],"mappings":";;;;UAmBiB;;WAEP;;;;;;EAMT,iBAAiB,cAAc,gBAAgB;;;;;;;EAO/C,eAAe;;;;;;;;iBAgGA,2BAA2B;;UAM1B;;;;;;;;;;;WAWP;;;;;;;;;;;;;;;iBAgBY,iBAAiB,MAAM,YAAY,OAAO,0BAA0B,QAAQ;;;;;;;cA4BrF;mBACK;UAET;EAIR,IAAI,cAAc,SAAS,aAAa;IAAS;IAAgB;;;EAKjE,QAAQ;;;;;;;;;;;;EAiBR,aACC,iCACA,YACA;IAAS;IAAgB;;;EAM1B,IAAI,iCAAiC,gBAAc,mBAAiB;MAahE;;;;;;;iBAUW,qBACf,UAAU,qBACV,eAAe,wBACb;;;;;;;;;;;cCvOU;;cAGA;;cAGA;;;;;;;;;;;cAYA;cACA;;UAGI;EAChB;EACA;EACA;EACA;EACA;;EAEA;;;UAIgB;EAChB,MAAM;;EAEN;;EAEA;EACA;EACA;;;UAIgB;EAChB;EACA;;;;;;;;;;EAUA;;;KAIW,mBAAmB,KAAK,WAAW;UAE9B;EAChB;EACA;;KAGW;EACP;;EACA;;EACA;EAAgB,QAAQ;;;UAiMZ;EAChB;EACA;;;;;;;EAOA;;;;;;;;;iBAUe,cACf,YAAY,gBACZ,sBACA,SAAS,iBACT,sBACA,2BACA,uBACE;;;;;iBA0Ba,gBACf,YAAY,gBACZ,sBACA,SAAS,iBACT,sBACA,2BACA;;;;;;;;;;;KAgBW;EACP;;EACA;EAAgB;;iBAoBL,YAAY,YAAY,gBAAgB,KAAK,QAAQ,SAAS,kBAAkB;iBAMhF,YAAY,YAAY,gBAAgB,KAAK,QAAQ,SAAS,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UClV/E;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;;iBA+BM,iBAAiB,MAAM;;;;;;;;;;;;;iBA0HvB,cAAc,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;iBC1GjC,YACf,UAAU,qBACV,eAAe,aACf,MAAM,qBACJ;;;KCzFS,UAAU,mBAAmB;;;;;;;iBA8BzB,mBAAmB,MAAM,aAAa,MAAM,UAAU"}

package/dist/measure.js

@@ -1,3 +1,3 @@
 import { a as TsPptxError, i as PackageReadError, n as InvalidOptionError, o as UnsupportedFeatureError, r as MediaError, t as InternalError } from "./errors-Bvln0H-7.js";
-import { _ as parseFontMetrics, a as FONT_SCALE_STEP_PCT, c as SINGLE_LINE_PITCH, d as measureLayout, f as solveResize, g as makeRegistryResolver, h as getHeuristicFontMetrics, i as buildFitParagraphs, l as WIDTH_SAFETY_FACTOR, m as FontMetricsRegistry, n as measureText, o as HEIGHT_SAFETY_FACTOR, p as solveShrink, s as MIN_FONT_SCALE_PCT, u as measureHeightPt } from "./fit-DhMbQG5O.js";
-export { FONT_SCALE_STEP_PCT, FontMetricsRegistry, HEIGHT_SAFETY_FACTOR, InternalError, InvalidOptionError, MIN_FONT_SCALE_PCT, MediaError, PackageReadError, SINGLE_LINE_PITCH, TsPptxError, UnsupportedFeatureError, WIDTH_SAFETY_FACTOR, buildFitParagraphs, getHeuristicFontMetrics, makeRegistryResolver, measureHeightPt, measureLayout, measureText, parseFontMetrics, solveResize, solveShrink };
+import { _ as parseFontMetrics, a as FONT_SCALE_STEP_PCT, c as SINGLE_LINE_PITCH, d as measureLayout, f as solveResize, g as makeRegistryResolver, h as getHeuristicFontMetrics, i as buildFitParagraphs, l as WIDTH_SAFETY_FACTOR, m as FontMetricsRegistry, n as measureText, o as HEIGHT_SAFETY_FACTOR, p as solveShrink, s as MIN_FONT_SCALE_PCT, u as measureHeightPt, v as isFontCollection, y as listFontFaces } from "./fit-TjpNbMru.js";
+export { FONT_SCALE_STEP_PCT, FontMetricsRegistry, HEIGHT_SAFETY_FACTOR, InternalError, InvalidOptionError, MIN_FONT_SCALE_PCT, MediaError, PackageReadError, SINGLE_LINE_PITCH, TsPptxError, UnsupportedFeatureError, WIDTH_SAFETY_FACTOR, buildFitParagraphs, getHeuristicFontMetrics, isFontCollection, listFontFaces, makeRegistryResolver, measureHeightPt, measureLayout, measureText, parseFontMetrics, solveResize, solveShrink };