@office-kit/pptx-preview 0.15.0 → 0.17.0

package/README.md

@@ -42,6 +42,28 @@ const svg = renderSlideToSvg(pres, getSlides(pres)[0]);
 // → '<svg …>…</svg>'  (text laid out via <foreignObject> — the browser wraps it)
 ```
 
+Pass `{ textLayout: 'svg', measureText }` to lay text out as pure SVG
+`<text>` instead of `<foreignObject>` (for example when the SVG is shown as an
+`<img>` or sanitized). In that mode each run's font is replaced with one of the
+bundled metric-compatible substitutes (`substituteFamily`: Carlito, Caladea,
+Liberation Sans / Serif / Mono). To keep a family the viewer can load — say
+through `@font-face` rules you embed in the SVG — pass `resolveFamily`, and a
+`measureText` that knows that font's metrics so line breaks match its glyphs
+(in a browser, for example, one that wraps `CanvasRenderingContext2D.measureText`
+once the font has loaded). Return a single family name; the renderer quotes it
+in the SVG when CSS requires that:
+
+```ts
+import { renderSlideToSvg, substituteFamily } from '@office-kit/pptx-preview';
+
+const svg = renderSlideToSvg(pres, slide, {
+  textLayout: 'svg',
+  measureText,
+  resolveFamily: (family) =>
+    family === 'Lora' || family === 'Inter' ? family : substituteFamily(family),
+});
+```
+
 `renderSlideLayoutToSvg(pres, layout, { master })` draws what a slide master
 editor shows behind the placeholders: the layout's background and decorative
 shapes over its master's (the master's are left out when the layout hides
@@ -95,7 +117,7 @@ const measureText = buildFontkitMeasurer({
 });
 
 const issues = auditTextLayout(pres, { measureText, reportSoftWraps: true });
-// → [{ kind: 'overflow-y', slideIndex: 2, shapeName: 'Title 1', overflowPx: 14.3, approximate: false }, …]
+// → [{ kind: 'overflow-y', slideIndex: 2, shapeName: 'Title 1', overflowPx: 14.3, shapeOverflowPx: 9.5, lineHeightPx: 52.8, approximate: false }, …]
 ```
 
 `auditTextLayout` measures every shape's text body — placeholders, text boxes,
@@ -103,11 +125,20 @@ autoshapes, shapes inside groups — with the same engine the preview renders
 with, honouring the effective bodyPr cascade (insets, wrap, anchor, vertical
 text, columns) and `normAutofit` shrinking. It returns one issue per finding:
 
-| `kind`       | Meaning                                                                       | Extra fields                   |
-| ------------ | ----------------------------------------------------------------------------- | ------------------------------ |
-| `overflow-x` | Text ink escapes the box horizontally (typically `wrap="none"`)               | `overflowPx`                   |
-| `overflow-y` | Wrapped text is taller than the box (or escapes the top when bottom-anchored) | `overflowPx`                   |
-| `soft-wrap`  | A paragraph wrapped onto more lines than its authored `<a:br>` count (段落ち) | `paragraphIndex`, `extraLines` |
+| `kind`            | Meaning                                                                             | Extra fields                   |
+| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
+| `overflow-x`      | Text ink escapes the box horizontally (typically `wrap="none"`)                     | `overflowPx` and the two below |
+| `overflow-y`      | Wrapped text is taller than the box (or escapes the top when bottom-anchored)       | `overflowPx` and the two below |
+| `soft-wrap`       | A paragraph wrapped onto more lines than its authored `<a:br>` count (段落ち)       | `paragraphIndex`, `extraLines` |
+| `word-break`      | A wrap split a word (Latin / Greek / Cyrillic letters or digits, or a katakana run) | `paragraphIndex`, `text`       |
+| `short-last-line` | A wrapped paragraph ends on a line of one or two characters (泣き別れ)              | `paragraphIndex`, `text`       |
+| `small-font`      | The shape draws text below `minFontSizePt`, after autofit shrinking                 | `sizePt`                       |
+
+`overflowPx` is measured against the text area (the box minus its insets);
+`shapeOverflowPx` is how much ink lies outside the shape itself, both sides
+added (a centre-anchored body spills above and below; 0 while the spill stays
+inside the insets, where nobody sees it); `lineHeightPx` is the
+tallest line's height, about how far one misjudged wrap moves the text.
 
 Every issue also carries `slideIndex`, `shapeName`, and `approximate` —
 `true` when a width had to be estimated (the heuristic measurer, or glyphs the
@@ -124,6 +155,13 @@ Options:
 - `reportSoftWraps` — opt into `soft-wrap` issues. Off by default because
   wrapping is normal for body text; turn it on when auditing titles or labels
   meant to stay on one line.
+- `reportBadWraps` — opt into `word-break` and `short-last-line` issues
+  (horizontal text only). A word inside a kanji compound cannot be told apart
+  from its neighbours, so only the scripts listed above are checked.
+  A `word-break` issue is reported once per word; its `text` is the word with
+  `|` at each line break. `short-last-line` counts characters, not words, so a
+  Latin last line of `to` is reported and one of `the` is not.
+- `minFontSizePt` — report `small-font` for shapes with text below this size.
 
 Accuracy: the bundled fonts are metric-compatible with the common default fonts, so
 verdicts for Calibri / Cambria / Arial / Times / Courier decks match real glyph

package/dist/{index-74n14k3Y.d.ts → index-C8dvep3H.d.ts}

@@ -2,8 +2,10 @@ import { BulletStyle, PresentationData, SlideData, SlideLayoutData, SlideShapeDa
 
 //#region src/text-layout.d.ts
 /** What a measurer needs to size one run. Pixels at 96 DPI; the caller has
- *  already applied EMU→px, pt→px and the autofit fontScale. `family` is the
- *  resolved internal family name (see `substituteFamily`), not a CSS list. */
+ *  already applied EMU→px, pt→px and the autofit fontScale. `family` is a
+ *  single family name, not a CSS list: what `RenderSlideOptions.resolveFamily`
+ *  returned, by default a bundled substitute (see `substituteFamily`). The
+ *  text audit passes the authored name instead. */
 interface FontSpec {
   readonly family: string;
   readonly sizePx: number;
@@ -45,6 +47,17 @@ interface RenderSlideOptions {
   /** `false` paints only the slide's own shapes on a transparent surface:
    *  no background fill and no master or layout graphics. Defaults to `true`. */
   readonly background?: boolean;
+  /** Maps an authored font name (a run's font, a bullet font, or the theme
+   *  face; `null` when none applies) to the family written to the SVG's
+   *  `<text font-family>` and handed to `measureText`. Return one family name,
+   *  unquoted; the renderer quotes it in the SVG when CSS requires that. Only consulted when
+   *  `textLayout` is `'svg'`; the foreignObject path writes the authored name
+   *  into a CSS font stack itself. Defaults to `substituteFamily`, which maps
+   *  every family to one of the bundled metric-compatible substitutes. Keep a
+   *  family only when the SVG's viewer can load it (for example through an
+   *  `@font-face` rule the host embeds), and pair it with a `measureText` that
+   *  knows its metrics so line breaks match the glyphs. */
+  readonly resolveFamily?: (family: string | null) => string;
 }
 declare const SANS = "Carlito";
 declare const SERIF = "Caladea";
@@ -95,14 +108,29 @@ interface IssueBase {
   readonly approximate: boolean;
 }
 type TextAuditIssue = (IssueBase & {
-  readonly kind: 'overflow-x' | 'overflow-y'; /** How far the text ink escapes the box, in px at 96 DPI. */
+  readonly kind: 'overflow-x' | 'overflow-y'; /** How far the text ink escapes the text area (the box minus its insets), in px at 96 DPI. */
   readonly overflowPx: number;
+  /** How much ink lies outside the shape itself along that axis, both sides added
+   *  (a centred body spills half above, half below); 0 while it stays within the insets. */
+  readonly shapeOverflowPx: number; /** The tallest line's height in px: about how far one misjudged wrap moves the text. */
+  readonly lineHeightPx: number;
 }) | (IssueBase & {
   readonly kind: 'soft-wrap';
   readonly paragraphIndex: number;
   /** Lines beyond the paragraph's authored line count (1 + explicit
    *  breaks) — i.e. how many times the text wrapped on its own. */
   readonly extraLines: number;
+}) | (IssueBase & {
+  /** A wrap split a word: Latin / Greek / Cyrillic letters or digits, or a katakana run. */readonly kind: 'word-break';
+  readonly paragraphIndex: number; /** The split word, with `|` where the line breaks. */
+  readonly text: string;
+}) | (IssueBase & {
+  /** A wrapped paragraph whose last line holds only a character or two (泣き別れ). */readonly kind: 'short-last-line';
+  readonly paragraphIndex: number; /** The text of that last line. */
+  readonly text: string;
+}) | (IssueBase & {
+  readonly kind: 'small-font'; /** The smallest font size drawn in the shape, after autofit shrinking. */
+  readonly sizePt: number;
 });
 interface AuditTextLayoutOptions {
   /** Measurer for run widths / vertical metrics. Defaults to the heuristic
@@ -116,11 +144,19 @@ interface AuditTextLayoutOptions {
    *  breaks author (段落ち). Off by default: wrapping is normal for body
    *  text, so this is opt-in for single-line-intent content like titles. */
   readonly reportSoftWraps?: boolean;
+  /** Also report wraps that split a word (`word-break`) and wrapped
+   *  paragraphs that end on a line of one or two characters
+   *  (`short-last-line`). Horizontal text only. */
+  readonly reportBadWraps?: boolean;
+  /** Report shapes drawing text below this size in points (`small-font`). */
+  readonly minFontSizePt?: number;
 }
 /**
  * Measures every text body in the deck and reports text that escapes its box
  * (`overflow-x` / `overflow-y`) and, opt-in, paragraphs that soft-wrap
- * (`soft-wrap`, 段落ち).
+ * (`soft-wrap`, 段落ち), wraps that split a word or strand a line of one or
+ * two characters (`word-break`, `short-last-line`), and text below a minimum
+ * size (`small-font`).
  *
  * Table cell text is not audited (v1 covers shape text bodies, including
  * placeholders and shapes inside groups).
@@ -226,7 +262,9 @@ interface ShapeAutoFitScaleOptions {
   };
   /** Measurer for run widths, defaulting to the heuristic one the renderer
    *  uses in a browser. Pass the same measurer the render call uses, or the
-   *  two disagree about how much text fits. */
+   *  two disagree about how much text fits. Families are resolved with
+   *  `substituteFamily`, as the foreignObject render does; an svg render
+   *  with its own `resolveFamily` can measure a different face. */
   readonly measureText?: TextMeasurer;
 }
 /**
@@ -257,4 +295,4 @@ declare function shapeTextAnchorOffset(pres: PresentationData, shape: SlideShape
 declare function textUnderlineStyle(underline: TextFormat['underline'], color: string, includeDecorationColor?: boolean): string;
 //#endregion
 export { substituteFamily as A, RenderSlideOptions as C, TextLayoutMode as D, TIMES as E, TextMeasurer as O, MeasureResult as S, SERIF as T, renderSlideSvg as _, VerticalTextStyle as a, FontSpec as b, TextRectFractions as c, decimalSeparatorOf as d, paragraphNumberLabels as f, renderSlideLayoutSvg as g, auditTextLayout as h, shapeTextAnchorOffset as i, defaultMeasurer as k, resolveTextBodyRect as l, TextAuditIssue as m, ShapeAutoFitScaleOptions as n, textColumnsStyle as o, AuditTextLayoutOptions as p, shapeAutoFitScale as r, verticalTextStyle as s, textUnderlineStyle as t, shapeTextRect as u, renderTextEffectsSvg as v, SANS as w, MONO as x, ARIAL as y };
-//# sourceMappingURL=index-74n14k3Y.d.ts.map
+//# sourceMappingURL=index-C8dvep3H.d.ts.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-74n14k3Y.js";
+import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-C8dvep3H.js";
 export { ARIAL, type AuditTextLayoutOptions, type FontSpec, MONO, type MeasureResult, type RenderSlideOptions, SANS, SERIF, type ShapeAutoFitScaleOptions, TIMES, type TextAuditIssue, type TextLayoutMode, type TextMeasurer, type TextRectFractions, type VerticalTextStyle, auditTextLayout, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-pb3C61GD.js";
+import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-ayE1F9lH.js";
 export { ARIAL, MONO, SANS, SERIF, TIMES, auditTextLayout, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-74n14k3Y.js";
+import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-C8dvep3H.js";
 import { PresentationData, SlideData } from "@office-kit/pptx";
 
 //#region src/measure.d.ts

package/dist/node.js

@@ -1,4 +1,4 @@
-import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, c as AVG_GLYPH_W_RATIO, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, m as isCjk, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-pb3C61GD.js";
+import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, c as AVG_GLYPH_W_RATIO, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, m as isCjk, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-ayE1F9lH.js";
 import { getSlideSize } from "@office-kit/pptx";
 import { Resvg } from "@resvg/resvg-js";
 import * as fontkit from "fontkit";