@shbernal/pptxgenjs 5.2.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,106 @@
1
+ //#region src/units.ts
2
+ /**
3
+ * Public unit conversion helpers and standard PowerPoint slide-layout constants.
4
+ */
5
+ const EMU_PER_INCH = 914400;
6
+ const EMU_PER_POINT = 12700;
7
+ const POINTS_PER_INCH = 72;
8
+ /** A bare number larger than this (in inches) is almost certainly a mistake — likely a raw EMU
9
+ * value passed where inches are expected. We interpret it as inches (the documented contract) but
10
+ * warn, pointing at the explicit `"<n>emu"` form. ~1000in is far beyond any real slide. */
11
+ const IMPLAUSIBLE_INCHES = 1e3;
12
+ function inchesToEmu(inches) {
13
+ assertFiniteNumber(inches, "inches");
14
+ return Math.round(inches * EMU_PER_INCH);
15
+ }
16
+ function pointsToEmu(points) {
17
+ assertFiniteNumber(points, "points");
18
+ return Math.round(points * EMU_PER_POINT);
19
+ }
20
+ function pixelsToEmu(pixels, dpi) {
21
+ assertFiniteNumber(pixels, "pixels");
22
+ assertPositiveFiniteNumber(dpi, "dpi");
23
+ return inchesToEmu(pixels / dpi);
24
+ }
25
+ /**
26
+ * Resolve a percentage of an axis length to EMU.
27
+ * @param percent - percentage value (e.g. `50` for 50%)
28
+ * @param axisEmu - the axis length in EMU (slide width for x/w, height for y/h)
29
+ */
30
+ function percentToEmu(percent, axisEmu) {
31
+ assertFiniteNumber(percent, "percent");
32
+ assertFiniteNumber(axisEmu, "axisEmu");
33
+ return Math.round(percent / 100 * axisEmu);
34
+ }
35
+ /**
36
+ * The single user-coordinate → EMU boundary. Convert each user-supplied coordinate exactly once.
37
+ *
38
+ * Accepts (see {@link Coord}):
39
+ * - a bare `number` → **always inches** (the documented unit); no magnitude guessing
40
+ * - `"<n>%"` → percentage of `axisEmu`
41
+ * - `"<n>in"` / `"<n>pt"` / `"<n>emu"` → explicit units (the escape hatch for non-inch values)
42
+ *
43
+ * Throws on non-finite or unparseable input rather than silently emitting a degenerate 0-size.
44
+ * @param value - user coordinate
45
+ * @param axisEmu - axis length in EMU, used only to resolve percentages
46
+ */
47
+ function coordToEmu(value, axisEmu) {
48
+ if (typeof value === "number") {
49
+ assertFiniteNumber(value, "coordinate");
50
+ if (Math.abs(value) > IMPLAUSIBLE_INCHES) console.warn(`PptxGenJS: coordinate ${value} interpreted as ${value} inches. A bare number is always inches; if you meant EMU, pass it as a string like "${Math.round(value)}emu".`);
51
+ return inchesToEmu(value);
52
+ }
53
+ const match = /^\s*(-?\d*\.?\d+)\s*(%|in|pt|emu)\s*$/.exec(value);
54
+ if (!match) throw new Error(`PptxGenJS: invalid coordinate "${value}". Expected a number (inches) or a string like "50%", "5in", "72pt", or "914400emu".`);
55
+ const n = Number(match[1]);
56
+ switch (match[2]) {
57
+ case "%": return percentToEmu(n, axisEmu);
58
+ case "in": return inchesToEmu(n);
59
+ case "pt": return pointsToEmu(n);
60
+ default:
61
+ assertFiniteNumber(n, "coordinate");
62
+ return Math.round(n);
63
+ }
64
+ }
65
+ function emuToInches(emu) {
66
+ assertFiniteNumber(emu, "emu");
67
+ return emu / EMU_PER_INCH;
68
+ }
69
+ function emuToPoints(emu) {
70
+ assertFiniteNumber(emu, "emu");
71
+ return emu / EMU_PER_POINT;
72
+ }
73
+ function emuToPixels(emu, dpi) {
74
+ assertFiniteNumber(emu, "emu");
75
+ assertPositiveFiniteNumber(dpi, "dpi");
76
+ return Math.round(emuToInches(emu) * dpi);
77
+ }
78
+ function standardLayout(layout, name, widthIn, heightIn) {
79
+ return Object.freeze({
80
+ layout,
81
+ name,
82
+ width: widthIn,
83
+ height: heightIn,
84
+ widthIn,
85
+ heightIn,
86
+ widthEmu: inchesToEmu(widthIn),
87
+ heightEmu: inchesToEmu(heightIn)
88
+ });
89
+ }
90
+ const STANDARD_LAYOUTS = Object.freeze({
91
+ LAYOUT_4x3: standardLayout("LAYOUT_4x3", "screen4x3", 10, 7.5),
92
+ LAYOUT_16x9: standardLayout("LAYOUT_16x9", "screen16x9", 10, 5.625),
93
+ LAYOUT_16x10: standardLayout("LAYOUT_16x10", "screen16x10", 10, 6.25),
94
+ LAYOUT_WIDE: standardLayout("LAYOUT_WIDE", "custom", 40 / 3, 7.5)
95
+ });
96
+ function assertFiniteNumber(value, name) {
97
+ if (!Number.isFinite(value)) throw new Error(`${name} must be a finite number`);
98
+ }
99
+ function assertPositiveFiniteNumber(value, name) {
100
+ assertFiniteNumber(value, name);
101
+ if (value <= 0) throw new Error(`${name} must be greater than 0`);
102
+ }
103
+ //#endregion
104
+ export { coordToEmu as a, emuToPoints as c, pixelsToEmu as d, pointsToEmu as f, STANDARD_LAYOUTS as i, inchesToEmu as l, EMU_PER_POINT as n, emuToInches as o, POINTS_PER_INCH as r, emuToPixels as s, EMU_PER_INCH as t, percentToEmu as u };
105
+
106
+ //# sourceMappingURL=units-BMrBTU0-.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"units-BMrBTU0-.js","names":[],"sources":["../src/units.ts"],"sourcesContent":["/**\n * Public unit conversion helpers and standard PowerPoint slide-layout constants.\n */\n\nexport const EMU_PER_INCH = 914400\nexport const EMU_PER_POINT = 12700\nexport const POINTS_PER_INCH = 72\n\n/**\n * English Metric Units — the integer unit OOXML serializes geometry in (914400 per inch).\n *\n * Branded so a value that has already been resolved to EMU cannot be silently fed back into a\n * unit converter: {@link coordToEmu} only accepts a user `Coord`, so passing an `Emu` into it is\n * a compile-time error. This replaces the old runtime \"a number ≥ 100 must already be EMU\"\n * magnitude guess, which silently mis-rendered values near the threshold.\n */\nexport type Emu = number & { readonly __unit: 'emu' }\n\n/** A bare number larger than this (in inches) is almost certainly a mistake — likely a raw EMU\n * value passed where inches are expected. We interpret it as inches (the documented contract) but\n * warn, pointing at the explicit `\"<n>emu\"` form. ~1000in is far beyond any real slide. */\nconst IMPLAUSIBLE_INCHES = 1000\n\nexport type StandardLayoutName = 'LAYOUT_4x3' | 'LAYOUT_16x9' | 'LAYOUT_16x10' | 'LAYOUT_WIDE'\n\nexport interface StandardLayout {\n\t/** PptxGenJS layout key used with `pptx.layout`. */\n\treadonly layout: StandardLayoutName\n\t/** PresentationML slide-size preset name, or `custom` for PowerPoint widescreen. */\n\treadonly name: string\n\t/** Slide width in inches. Alias of {@link StandardLayout.widthIn} — inches is PptxGenJS's default coordinate unit, so this is the value to use for `addText`/`addShape` math. */\n\treadonly width: number\n\t/** Slide height in inches. Alias of {@link StandardLayout.heightIn}. */\n\treadonly height: number\n\t/** Slide width in inches. */\n\treadonly widthIn: number\n\t/** Slide height in inches. */\n\treadonly heightIn: number\n\t/** Slide width in English Metric Units. */\n\treadonly widthEmu: number\n\t/** Slide height in English Metric Units. */\n\treadonly heightEmu: number\n}\n\nexport function inchesToEmu(inches: number): Emu {\n\tassertFiniteNumber(inches, 'inches')\n\treturn Math.round(inches * EMU_PER_INCH) as Emu\n}\n\nexport function pointsToEmu(points: number): Emu {\n\tassertFiniteNumber(points, 'points')\n\treturn Math.round(points * EMU_PER_POINT) as Emu\n}\n\nexport function pixelsToEmu(pixels: number, dpi: number): Emu {\n\tassertFiniteNumber(pixels, 'pixels')\n\tassertPositiveFiniteNumber(dpi, 'dpi')\n\treturn inchesToEmu(pixels / dpi)\n}\n\n/**\n * Resolve a percentage of an axis length to EMU.\n * @param percent - percentage value (e.g. `50` for 50%)\n * @param axisEmu - the axis length in EMU (slide width for x/w, height for y/h)\n */\nexport function percentToEmu(percent: number, axisEmu: number): Emu {\n\tassertFiniteNumber(percent, 'percent')\n\tassertFiniteNumber(axisEmu, 'axisEmu')\n\treturn Math.round((percent / 100) * axisEmu) as Emu\n}\n\n/**\n * The single user-coordinate → EMU boundary. Convert each user-supplied coordinate exactly once.\n *\n * Accepts (see {@link Coord}):\n * - a bare `number` → **always inches** (the documented unit); no magnitude guessing\n * - `\"<n>%\"` → percentage of `axisEmu`\n * - `\"<n>in\"` / `\"<n>pt\"` / `\"<n>emu\"` → explicit units (the escape hatch for non-inch values)\n *\n * Throws on non-finite or unparseable input rather than silently emitting a degenerate 0-size.\n * @param value - user coordinate\n * @param axisEmu - axis length in EMU, used only to resolve percentages\n */\nexport function coordToEmu(value: number | string, axisEmu: number): Emu {\n\tif (typeof value === 'number') {\n\t\tassertFiniteNumber(value, 'coordinate')\n\t\tif (Math.abs(value) > IMPLAUSIBLE_INCHES) {\n\t\t\tconsole.warn(\n\t\t\t\t`PptxGenJS: coordinate ${value} interpreted as ${value} inches. A bare number is always inches; ` +\n\t\t\t\t\t`if you meant EMU, pass it as a string like \"${Math.round(value)}emu\".`\n\t\t\t)\n\t\t}\n\t\treturn inchesToEmu(value)\n\t}\n\n\tconst match = /^\\s*(-?\\d*\\.?\\d+)\\s*(%|in|pt|emu)\\s*$/.exec(value)\n\tif (!match) {\n\t\tthrow new Error(\n\t\t\t`PptxGenJS: invalid coordinate \"${value}\". Expected a number (inches) or a string like \"50%\", \"5in\", \"72pt\", or \"914400emu\".`\n\t\t)\n\t}\n\tconst n = Number(match[1])\n\tswitch (match[2]) {\n\t\tcase '%':\n\t\t\treturn percentToEmu(n, axisEmu)\n\t\tcase 'in':\n\t\t\treturn inchesToEmu(n)\n\t\tcase 'pt':\n\t\t\treturn pointsToEmu(n)\n\t\tdefault: // 'emu'\n\t\t\tassertFiniteNumber(n, 'coordinate')\n\t\t\treturn Math.round(n) as Emu\n\t}\n}\n\nexport function emuToInches(emu: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\treturn emu / EMU_PER_INCH\n}\n\nexport function emuToPoints(emu: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\treturn emu / EMU_PER_POINT\n}\n\nexport function emuToPixels(emu: number, dpi: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\tassertPositiveFiniteNumber(dpi, 'dpi')\n\treturn Math.round(emuToInches(emu) * dpi)\n}\n\nfunction standardLayout(layout: StandardLayoutName, name: string, widthIn: number, heightIn: number): StandardLayout {\n\treturn Object.freeze({\n\t\tlayout,\n\t\tname,\n\t\twidth: widthIn,\n\t\theight: heightIn,\n\t\twidthIn,\n\t\theightIn,\n\t\twidthEmu: inchesToEmu(widthIn),\n\t\theightEmu: inchesToEmu(heightIn),\n\t})\n}\n\nexport const STANDARD_LAYOUTS: Readonly<Record<StandardLayoutName, StandardLayout>> = Object.freeze({\n\tLAYOUT_4x3: standardLayout('LAYOUT_4x3', 'screen4x3', 10, 7.5),\n\tLAYOUT_16x9: standardLayout('LAYOUT_16x9', 'screen16x9', 10, 5.625),\n\tLAYOUT_16x10: standardLayout('LAYOUT_16x10', 'screen16x10', 10, 6.25),\n\tLAYOUT_WIDE: standardLayout('LAYOUT_WIDE', 'custom', 40 / 3, 7.5),\n})\n\nfunction assertFiniteNumber(value: number, name: string): void {\n\tif (!Number.isFinite(value)) throw new Error(`${name} must be a finite number`)\n}\n\nfunction assertPositiveFiniteNumber(value: number, name: string): void {\n\tassertFiniteNumber(value, name)\n\tif (value <= 0) throw new Error(`${name} must be greater than 0`)\n}\n"],"mappings":";;;;AAIA,MAAa,eAAe;AAC5B,MAAa,gBAAgB;AAC7B,MAAa,kBAAkB;;;;AAe/B,MAAM,qBAAqB;AAuB3B,SAAgB,YAAY,QAAqB;CAChD,mBAAmB,QAAQ,QAAQ;CACnC,OAAO,KAAK,MAAM,SAAS,YAAY;AACxC;AAEA,SAAgB,YAAY,QAAqB;CAChD,mBAAmB,QAAQ,QAAQ;CACnC,OAAO,KAAK,MAAM,SAAS,aAAa;AACzC;AAEA,SAAgB,YAAY,QAAgB,KAAkB;CAC7D,mBAAmB,QAAQ,QAAQ;CACnC,2BAA2B,KAAK,KAAK;CACrC,OAAO,YAAY,SAAS,GAAG;AAChC;;;;;;AAOA,SAAgB,aAAa,SAAiB,SAAsB;CACnE,mBAAmB,SAAS,SAAS;CACrC,mBAAmB,SAAS,SAAS;CACrC,OAAO,KAAK,MAAO,UAAU,MAAO,OAAO;AAC5C;;;;;;;;;;;;;AAcA,SAAgB,WAAW,OAAwB,SAAsB;CACxE,IAAI,OAAO,UAAU,UAAU;EAC9B,mBAAmB,OAAO,YAAY;EACtC,IAAI,KAAK,IAAI,KAAK,IAAI,oBACrB,QAAQ,KACP,yBAAyB,MAAM,kBAAkB,MAAM,uFACP,KAAK,MAAM,KAAK,EAAE,MACnE;EAED,OAAO,YAAY,KAAK;CACzB;CAEA,MAAM,QAAQ,wCAAwC,KAAK,KAAK;CAChE,IAAI,CAAC,OACJ,MAAM,IAAI,MACT,kCAAkC,MAAM,qFACzC;CAED,MAAM,IAAI,OAAO,MAAM,EAAE;CACzB,QAAQ,MAAM,IAAd;EACC,KAAK,KACJ,OAAO,aAAa,GAAG,OAAO;EAC/B,KAAK,MACJ,OAAO,YAAY,CAAC;EACrB,KAAK,MACJ,OAAO,YAAY,CAAC;EACrB;GACC,mBAAmB,GAAG,YAAY;GAClC,OAAO,KAAK,MAAM,CAAC;CACrB;AACD;AAEA,SAAgB,YAAY,KAAqB;CAChD,mBAAmB,KAAK,KAAK;CAC7B,OAAO,MAAM;AACd;AAEA,SAAgB,YAAY,KAAqB;CAChD,mBAAmB,KAAK,KAAK;CAC7B,OAAO,MAAM;AACd;AAEA,SAAgB,YAAY,KAAa,KAAqB;CAC7D,mBAAmB,KAAK,KAAK;CAC7B,2BAA2B,KAAK,KAAK;CACrC,OAAO,KAAK,MAAM,YAAY,GAAG,IAAI,GAAG;AACzC;AAEA,SAAS,eAAe,QAA4B,MAAc,SAAiB,UAAkC;CACpH,OAAO,OAAO,OAAO;EACpB;EACA;EACA,OAAO;EACP,QAAQ;EACR;EACA;EACA,UAAU,YAAY,OAAO;EAC7B,WAAW,YAAY,QAAQ;CAChC,CAAC;AACF;AAEA,MAAa,mBAAyE,OAAO,OAAO;CACnG,YAAY,eAAe,cAAc,aAAa,IAAI,GAAG;CAC7D,aAAa,eAAe,eAAe,cAAc,IAAI,KAAK;CAClE,cAAc,eAAe,gBAAgB,eAAe,IAAI,IAAI;CACpE,aAAa,eAAe,eAAe,UAAU,KAAK,GAAG,GAAG;AACjE,CAAC;AAED,SAAS,mBAAmB,OAAe,MAAoB;CAC9D,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,GAAG,KAAK,yBAAyB;AAC/E;AAEA,SAAS,2BAA2B,OAAe,MAAoB;CACtE,mBAAmB,OAAO,IAAI;CAC9B,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,GAAG,KAAK,wBAAwB;AACjE"}
@@ -1,13 +1,19 @@
1
1
  //#region src/core-interfaces.d.ts
2
2
  /**
3
- * Coordinate number - either:
4
- * - Inches (0-n)
5
- * - Percentage (0-100)
3
+ * Coordinate value. A bare `number` is **always inches** — there is no magnitude-based unit
4
+ * guessing. For other units use an explicit string suffix:
5
+ * - `number` → inches (e.g. `10.25`)
6
+ * - `"<n>%"` → percentage of the slide axis (e.g. `"75%"`)
7
+ * - `"<n>in"` → inches (e.g. `"10.25in"`)
8
+ * - `"<n>pt"` → points (e.g. `"72pt"` = 1 inch)
9
+ * - `"<n>emu"` → raw EMU, the escape hatch for exact OOXML units (e.g. `"914400emu"` = 1 inch)
6
10
  *
7
- * @example 10.25 // coordinate in inches
8
- * @example '75%' // coordinate as percentage of slide size
11
+ * @example 10.25 // inches
12
+ * @example '75%' // percentage of slide size
13
+ * @example '72pt' // points
14
+ * @example '914400emu' // raw EMU
9
15
  */
10
- type Coord = number | `${number}%`;
16
+ type Coord = number | `${number}%` | `${number}in` | `${number}pt` | `${number}emu`;
11
17
  interface PositionProps {
12
18
  /**
13
19
  * Horizontal position
@@ -205,6 +211,11 @@ interface BorderProps {
205
211
  * @default 1
206
212
  */
207
213
  pt?: number;
214
+ /**
215
+ * Line end cap style
216
+ * @default 'flat'
217
+ */
218
+ cap?: LineCap;
208
219
  }
209
220
  interface HyperlinkProps {
210
221
  _rId?: number;
@@ -307,6 +318,11 @@ interface ShapeLineProps extends ShapeFillProps {
307
318
  * @default 'solid'
308
319
  */
309
320
  dashType?: 'solid' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot';
321
+ /**
322
+ * Line end cap style
323
+ * @default 'flat'
324
+ */
325
+ cap?: LineCap;
310
326
  /**
311
327
  * Begin arrow type
312
328
  * @since v3.3.0
@@ -548,6 +564,56 @@ interface ObjectNameProps {
548
564
  * @example 'Quarterly revenue bar chart'
549
565
  */
550
566
  altText?: string;
567
+ /**
568
+ * Object lock flags (DrawingML `a:spLocks` / `a:picLocks` / `a:graphicFrameLocks`)
569
+ * - restrict how the object can be manipulated in PowerPoint (e.g. prevent moving, resizing, or grouping)
570
+ * - each flag maps 1:1 to the OOXML attribute of the same name; only flags set to `true` are emitted
571
+ * - PowerPoint UI: Selection Pane / right-click protections (most locks are honored at edit time, not as a password)
572
+ * - flags only apply to the object types that support them (see each flag); flags set on an unsupported
573
+ * object type are ignored with a console warning
574
+ * @since v4.0.0
575
+ * @example { noMove: true, noResize: true } // pin an object in place
576
+ * @example { noGrp: true } // exclude from grouping
577
+ */
578
+ objectLock?: ObjectLockProps;
579
+ }
580
+ /**
581
+ * Object lock flags. Maps to DrawingML locking elements:
582
+ * - shapes / text boxes / placeholders → `a:spLocks`
583
+ * - images / media → `a:picLocks`
584
+ * - tables → `a:graphicFrameLocks`
585
+ *
586
+ * Each property mirrors the OOXML attribute name. A flag is only serialized for object types whose
587
+ * locking element defines it (noted per-flag); setting an unsupported flag logs a warning and is ignored.
588
+ * @since v4.0.0
589
+ */
590
+ interface ObjectLockProps {
591
+ /** Disallow grouping/ungrouping with other objects. (shapes, images, tables) */
592
+ noGrp?: boolean;
593
+ /** Disallow selecting the object. (shapes, images, tables) */
594
+ noSelect?: boolean;
595
+ /** Disallow moving the object. (shapes, images, tables) */
596
+ noMove?: boolean;
597
+ /** Disallow resizing the object. (shapes, images, tables) */
598
+ noResize?: boolean;
599
+ /** Disallow changing the aspect ratio. (shapes, images, tables) */
600
+ noChangeAspect?: boolean;
601
+ /** Disallow rotating the object. (shapes, images) */
602
+ noRot?: boolean;
603
+ /** Disallow editing the freeform/custom-geometry points. (shapes, images) */
604
+ noEditPoints?: boolean;
605
+ /** Disallow moving the shape's adjustment handles. (shapes, images) */
606
+ noAdjustHandles?: boolean;
607
+ /** Disallow changing arrowheads. (shapes, images) */
608
+ noChangeArrowheads?: boolean;
609
+ /** Disallow changing the shape type (preset geometry). (shapes, images) */
610
+ noChangeShapeType?: boolean;
611
+ /** Disallow editing the text body. (shapes / text boxes) */
612
+ noTextEdit?: boolean;
613
+ /** Disallow cropping the picture. (images) */
614
+ noCrop?: boolean;
615
+ /** Disallow drilling down into the graphical object (e.g. chart data). (tables) */
616
+ noDrilldown?: boolean;
551
617
  }
552
618
  interface ThemeProps {
553
619
  /**
@@ -565,6 +631,15 @@ interface ThemeProps {
565
631
  }
566
632
  type MediaType = 'audio' | 'online' | 'video';
567
633
  interface ImageBaseProps extends PositionProps, ObjectNameProps {
634
+ /**
635
+ * Sizing note (`w`/`h` inherited from {@link PositionProps}):
636
+ * - When a `data` (base64) image is supplied and `w`/`h` are omitted, the natural pixel
637
+ * size is read from the image header (PNG/JPEG/GIF/BMP/WebP) and used at 96 DPI
638
+ * (natural pixels / 96 = inches).
639
+ * - When only one of `w`/`h` is given, the other is derived from the natural aspect ratio.
640
+ * - `path` images and vector (SVG) data cannot be measured synchronously, so an omitted
641
+ * dimension falls back to 1 inch.
642
+ */
568
643
  /**
569
644
  * Alt Text value ("How would you describe this object and its contents to someone who is blind?")
570
645
  * - PowerPoint: [right-click on an image] > "Edit Alt Text..."
@@ -624,6 +699,14 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
624
699
  * @default 0
625
700
  */
626
701
  rectRadius?: number;
702
+ /**
703
+ * Preset-geometry adjustment handles (`<a:avLst>` guides) for the clip `shape`.
704
+ * - tune adjustment handles that lack a dedicated option, e.g. chevron point depth
705
+ * - accepts a single guide or an array; each `value` is a `0.0–1.0` fraction (see {@link ShapeAdjustValue})
706
+ * @since v4.0.0
707
+ * @example { name: 'adj', value: 0.25 }
708
+ */
709
+ shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
627
710
  /**
628
711
  * Shadow Props
629
712
  * - MS-PPT > Format Picture > Shadow
@@ -747,6 +830,21 @@ type MediaProps = MediaBaseProps & ((DataOrPathRequiredProps & {
747
830
  */
748
831
  link: string;
749
832
  }));
833
+ /**
834
+ * A single preset-geometry adjustment guide (`<a:gd>` inside `<a:avLst>`).
835
+ * - `name` is the guide name the preset defines, e.g. `'adj'`, `'adj1'`, `'adj2'`.
836
+ * PowerPoint shows these handles as the yellow drag dots on a selected shape.
837
+ * - `value` is a fraction `0.0–1.0` of the handle's range, emitted as a percentage
838
+ * guide formula (`val`, in 1/100000 units, so `0.25` → `fmla="val 25000"`).
839
+ * Most adjustment handles (corner radius, chevron point, callout depth, bevel
840
+ * width, …) are percentage-based and map directly; some shapes accept values
841
+ * beyond `1.0`. For angle-based handles, prefer the `angleRange` shortcut.
842
+ * @since v4.0.0
843
+ */
844
+ interface ShapeAdjustValue {
845
+ name: string;
846
+ value: number;
847
+ }
750
848
  interface ShapeProps extends PositionProps, ObjectNameProps {
751
849
  /**
752
850
  * Horizontal alignment
@@ -761,6 +859,19 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
761
859
  * @default [270, 0]
762
860
  */
763
861
  angleRange?: [number, number];
862
+ /**
863
+ * Preset-geometry adjustment handles (`<a:avLst>` guides) for any preset shape.
864
+ * - Use this to tune adjustment handles that lack a dedicated shortcut option,
865
+ * e.g. chevron/arrow point depth, callout pointer, bevel/frame thickness.
866
+ * - Accepts a single guide or an array; each `value` is a `0.0–1.0` fraction of
867
+ * the handle's range (see {@link ShapeAdjustValue}).
868
+ * - `rectRadius` / `angleRange` remain friendly shortcuts; any `shapeAdjust`
869
+ * guide that does not collide with a shortcut name is emitted in addition.
870
+ * @since v4.0.0
871
+ * @example { name: 'adj', value: 0.25 } // set the single adjust handle to 25%
872
+ * @example [{ name: 'adj1', value: 0.5 }, { name: 'adj2', value: 0.25 }] // two handles
873
+ */
874
+ shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
764
875
  /**
765
876
  * Radius (only for pptx.shapes.BLOCK_ARC)
766
877
  * - You have to setup the angleRange values too
@@ -1213,6 +1324,9 @@ interface TableCell {
1213
1324
  _hmerge?: boolean;
1214
1325
  _vmerge?: boolean;
1215
1326
  _rowContinue?: number;
1327
+ /** origin cell of a colspan/rowspan span, set on the dummy `_hmerge`/`_vmerge` cells so they can
1328
+ * inherit the origin's border/fill and render the merged region's outer edges (Issue #680) */
1329
+ _spanOrigin?: TableCell;
1216
1330
  _optImp?: any;
1217
1331
  text?: string | number | TableCell[];
1218
1332
  options?: TableCellProps;
@@ -1238,6 +1352,27 @@ interface TextGlowProps {
1238
1352
  */
1239
1353
  size: number;
1240
1354
  }
1355
+ interface TextFitShrinkProps {
1356
+ /**
1357
+ * Shrink text on overflow (`<a:normAutofit>`)
1358
+ */
1359
+ type: 'shrink';
1360
+ /**
1361
+ * Font scale as a percent (0-100), mapped to `<a:normAutofit fontScale="..">`.
1362
+ *
1363
+ * PowerPoint normally calculates this dynamically when text overflows; set it
1364
+ * explicitly to bake the scale into the generated file.
1365
+ * @example 85 // render text at 85% of its nominal size
1366
+ * @default undefined // attribute omitted (PowerPoint defaults to 100%)
1367
+ */
1368
+ fontScale?: number;
1369
+ /**
1370
+ * Line-space reduction as a percent (0-100), mapped to `<a:normAutofit lnSpcReduction="..">`.
1371
+ * @example 20 // reduce line spacing by 20%
1372
+ * @default undefined // attribute omitted (PowerPoint defaults to 0%)
1373
+ */
1374
+ lnSpcReduction?: number;
1375
+ }
1241
1376
  interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps, ObjectNameProps {
1242
1377
  _bodyProp?: {
1243
1378
  autoFit?: boolean;
@@ -1247,6 +1382,8 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
1247
1382
  rIns?: number;
1248
1383
  tIns?: number;
1249
1384
  bIns?: number;
1385
+ numCol?: number;
1386
+ spcCol?: number;
1250
1387
  vert?: TextVertType;
1251
1388
  wrap?: boolean;
1252
1389
  };
@@ -1256,6 +1393,24 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
1256
1393
  * Character spacing
1257
1394
  */
1258
1395
  charSpacing?: number;
1396
+ /**
1397
+ * Number of text columns in the text body
1398
+ * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Number"
1399
+ * - range: 1-16
1400
+ * @since v5.3.0
1401
+ * @default 1
1402
+ * @example 2 // flow text into two columns
1403
+ */
1404
+ columns?: number;
1405
+ /**
1406
+ * Spacing between text columns (points)
1407
+ * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Spacing"
1408
+ * - only applies when `columns` > 1
1409
+ * @since v5.3.0
1410
+ * @default 0
1411
+ * @example 10 // 10pt gap between columns
1412
+ */
1413
+ columnSpacing?: number;
1259
1414
  /**
1260
1415
  * Text fit options
1261
1416
  *
@@ -1267,11 +1422,15 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
1267
1422
  * **Note** 'shrink' and 'resize' only take effect after editing text/resize shape.
1268
1423
  * Both PowerPoint and Word dynamically calculate a scaling factor and apply it when edit/resize occurs.
1269
1424
  *
1270
- * There is no way for this library to trigger that behavior, sorry.
1425
+ * There is no way for this library to trigger that behavior, sorry. As a workaround,
1426
+ * pass an object form of 'shrink' to bake explicit `fontScale`/`lnSpcReduction` values
1427
+ * into the file so the text renders pre-shrunk without an edit/resize.
1271
1428
  * @since v3.3.0
1429
+ * @example 'shrink' // emit a bare <a:normAutofit/>
1430
+ * @example { type: 'shrink', fontScale: 85, lnSpcReduction: 20 } // pre-shrink text
1272
1431
  * @default "none"
1273
1432
  */
1274
- fit?: 'none' | 'shrink' | 'resize';
1433
+ fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
1275
1434
  /**
1276
1435
  * Shape fill
1277
1436
  * @example { color:'FF0000' } // hex color (red)
@@ -1401,7 +1560,12 @@ declare function textRun(text: string | number, options?: TextPropsOptions): Tex
1401
1560
  /** Wraps a run array so TypeScript accepts it as `TextProps[]` without a cast. */
1402
1561
  declare function textRuns(runs: TextProps[]): TextProps[];
1403
1562
  type ChartAxisTickMark = 'none' | 'inside' | 'outside' | 'cross';
1404
- type ChartLineCap = 'flat' | 'round' | 'square';
1563
+ /**
1564
+ * Line end cap style. Maps to the OOXML `cap` attribute on `<a:ln>` (`flat`/`sq`/`rnd`).
1565
+ */
1566
+ type LineCap = 'flat' | 'round' | 'square';
1567
+ /** @deprecated use `LineCap` (the cap type is not chart-specific) */
1568
+ type ChartLineCap = LineCap;
1405
1569
  type ChartLineDash = 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'solid' | 'sysDash' | 'sysDot';
1406
1570
  interface OptsChartData {
1407
1571
  _dataIndex?: number;
@@ -1427,6 +1591,45 @@ interface OptsChartData {
1427
1591
  * @example [2000, 2010, 2020]
1428
1592
  */
1429
1593
  values?: number[];
1594
+ /**
1595
+ * Custom text label per data point, replacing the auto-generated value label.
1596
+ * Index aligns with `values[]`. Empty string or missing entries fall back to the chart-level label settings.
1597
+ * Supported for BAR, LINE, AREA, RADAR, PIE, and DOUGHNUT chart types.
1598
+ * @example ['Low', '', 'High'] // only points 0 and 2 get custom labels
1599
+ */
1600
+ customLabels?: string[];
1601
+ /**
1602
+ * Per-data-point visual overrides (border / fill), index-aligned with `values[]`.
1603
+ * Empty (`{}`) or missing entries fall back to series/chart styling.
1604
+ * Supported for BAR, LINE, AREA, SCATTER, PIE, and DOUGHNUT chart types.
1605
+ * @example
1606
+ * pointStyles: [
1607
+ * { border: { pt: 2, color: 'FF0000' } }, // point 0: red 2pt border
1608
+ * {}, // point 1: default
1609
+ * { fill: '00B050', border: { type: 'dash', color: '404040' } }, // point 2
1610
+ * ]
1611
+ * @since v5.3.0
1612
+ */
1613
+ pointStyles?: ChartDataPointStyle[];
1614
+ }
1615
+ /**
1616
+ * Per-data-point style override for a chart series.
1617
+ * Each entry applies to the data point at the same index in `values[]`.
1618
+ * Unset fields fall back to the series/chart-level styling.
1619
+ */
1620
+ interface ChartDataPointStyle {
1621
+ /**
1622
+ * Data-point border (line). Reuses {@link BorderProps}.
1623
+ * - `type: 'none'` hides the border; `'dash'` draws a dashed border.
1624
+ * @example { pt: 2, color: 'FF0000' }
1625
+ */
1626
+ border?: BorderProps;
1627
+ /**
1628
+ * Data-point fill color (hex), overriding `chartColors[idx]`.
1629
+ * Most meaningful on fill-based charts (BAR, AREA, PIE, DOUGHNUT).
1630
+ * @example '00B050'
1631
+ */
1632
+ fill?: HexColor;
1430
1633
  }
1431
1634
  interface IOptsChartData extends OptsChartData {
1432
1635
  labels?: string[][];
@@ -1497,6 +1700,12 @@ interface IChartPropsBase {
1497
1700
  lang?: string;
1498
1701
  layout?: PositionProps;
1499
1702
  shadow?: ShadowProps;
1703
+ /**
1704
+ * Show each bubble's size value as a data label (bubble / bubble3D charts only).
1705
+ * Has no effect on other chart types.
1706
+ * @default false
1707
+ */
1708
+ showBubbleSize?: boolean;
1500
1709
  /**
1501
1710
  * @default false
1502
1711
  */
@@ -1735,6 +1944,20 @@ interface IChartPropsChartBar {
1735
1944
  * @default 0
1736
1945
  */
1737
1946
  barOverlapPct?: number;
1947
+ /**
1948
+ * Draw connector lines between data points across stacked bar/column series
1949
+ * ("Series Lines" in PowerPoint). Emits `<c:serLines>` in the bar chart.
1950
+ *
1951
+ * - `true` uses PowerPoint's automatic line styling.
1952
+ * - An {@link OptsChartGridLine} object customizes color/size/style/cap.
1953
+ * - Omit (or pass an object with `style: 'none'`) to disable.
1954
+ *
1955
+ * Bar (`bar`) charts only; ignored for 3D bar charts.
1956
+ * @default undefined
1957
+ * @example true
1958
+ * @example { color: '777777', size: 1, style: 'dash' }
1959
+ */
1960
+ barSeriesLine?: boolean | OptsChartGridLine;
1738
1961
  }
1739
1962
  interface IChartPropsChartDoughnut {
1740
1963
  dataNoEffects?: boolean;
@@ -1891,9 +2114,16 @@ interface IChartPropsTitle extends TextBaseProps {
1891
2114
  titleColor?: string;
1892
2115
  titleFontFace?: string;
1893
2116
  titleFontSize?: number;
2117
+ titleItalic?: boolean;
2118
+ titleUnderline?: boolean;
2119
+ /**
2120
+ * Manual title position (inches), relative to the chart.
2121
+ * Each axis is independent: omit `x` to keep automatic horizontal centering,
2122
+ * or omit `y` to keep automatic vertical placement. Provide at least one.
2123
+ */
1894
2124
  titlePos?: {
1895
- x: number;
1896
- y: number;
2125
+ x?: number;
2126
+ y?: number;
1897
2127
  };
1898
2128
  titleRotate?: number;
1899
2129
  }
@@ -2224,14 +2454,7 @@ declare const DEF_SHAPE_SHADOW: {
2224
2454
  };
2225
2455
  declare const DEF_SLIDE_BKGD = "FFFFFF";
2226
2456
  declare const DEF_SLIDE_MARGIN_IN: [number, number, number, number];
2227
- declare const DEF_TEXT_SHADOW: {
2228
- type: string;
2229
- blur: number;
2230
- offset: number;
2231
- angle: number;
2232
- color: string;
2233
- opacity: number;
2234
- };
2457
+ declare const DEF_TEXT_SHADOW: ShadowProps;
2235
2458
  declare const DEF_TEXT_GLOW: {
2236
2459
  size: number;
2237
2460
  color: string;
@@ -2370,7 +2593,7 @@ declare enum ShapeType {
2370
2593
  'flowChartSort' = "flowChartSort",
2371
2594
  'flowChartSummingJunction' = "flowChartSummingJunction",
2372
2595
  'flowChartTerminator' = "flowChartTerminator",
2373
- 'folderCorner' = "folderCorner",
2596
+ 'foldedCorner' = "foldedCorner",
2374
2597
  'frame' = "frame",
2375
2598
  'funnel' = "funnel",
2376
2599
  'gear6' = "gear6",
@@ -2569,7 +2792,7 @@ declare enum SHAPE_TYPE {
2569
2792
  FLOWCHART_STORED_DATA = "flowChartOnlineStorage",
2570
2793
  FLOWCHART_SUMMING_JUNCTION = "flowChartSummingJunction",
2571
2794
  FLOWCHART_TERMINATOR = "flowChartTerminator",
2572
- FOLDED_CORNER = "folderCorner",
2795
+ FOLDED_CORNER = "foldedCorner",
2573
2796
  FRAME = "frame",
2574
2797
  FUNNEL = "funnel",
2575
2798
  GEAR_6 = "gear6",
@@ -2604,10 +2827,6 @@ declare enum SHAPE_TYPE {
2604
2827
  LINE_CALLOUT_3_ACCENT_BAR = "accentCallout3",
2605
2828
  LINE_CALLOUT_3_BORDER_AND_ACCENT_BAR = "accentBorderCallout3",
2606
2829
  LINE_CALLOUT_3_NO_BORDER = "callout3",
2607
- LINE_CALLOUT_4 = "borderCallout4",
2608
- LINE_CALLOUT_4_ACCENT_BAR = "accentCallout3=4",
2609
- LINE_CALLOUT_4_BORDER_AND_ACCENT_BAR = "accentBorderCallout4",
2610
- LINE_CALLOUT_4_NO_BORDER = "callout4",
2611
2830
  LINE = "line",
2612
2831
  LINE_INVERSE = "lineInv",
2613
2832
  MATH_DIVIDE = "mathDivide",
@@ -2674,7 +2893,16 @@ declare enum SHAPE_TYPE {
2674
2893
  VERTICAL_SCROLL = "verticalScroll",
2675
2894
  WAVE = "wave"
2676
2895
  }
2677
- type SHAPE_NAME = 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'actionButtonBackPrevious' | 'actionButtonBeginning' | 'actionButtonBlank' | 'actionButtonDocument' | 'actionButtonEnd' | 'actionButtonForwardNext' | 'actionButtonHelp' | 'actionButtonHome' | 'actionButtonInformation' | 'actionButtonMovie' | 'actionButtonReturn' | 'actionButtonSound' | 'arc' | 'bentArrow' | 'bentUpArrow' | 'bevel' | 'blockArc' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'bracePair' | 'bracketPair' | 'callout1' | 'callout2' | 'callout3' | 'can' | 'chartPlus' | 'chartStar' | 'chartX' | 'chevron' | 'chord' | 'circularArrow' | 'cloud' | 'cloudCallout' | 'corner' | 'cornerTabs' | 'cube' | 'curvedDownArrow' | 'curvedLeftArrow' | 'curvedRightArrow' | 'curvedUpArrow' | 'custGeom' | 'decagon' | 'diagStripe' | 'diamond' | 'dodecagon' | 'donut' | 'doubleWave' | 'downArrow' | 'downArrowCallout' | 'ellipse' | 'ellipseRibbon' | 'ellipseRibbon2' | 'flowChartAlternateProcess' | 'flowChartCollate' | 'flowChartConnector' | 'flowChartDecision' | 'flowChartDelay' | 'flowChartDisplay' | 'flowChartDocument' | 'flowChartExtract' | 'flowChartInputOutput' | 'flowChartInternalStorage' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartMagneticTape' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartMerge' | 'flowChartMultidocument' | 'flowChartOfflineStorage' | 'flowChartOffpageConnector' | 'flowChartOnlineStorage' | 'flowChartOr' | 'flowChartPredefinedProcess' | 'flowChartPreparation' | 'flowChartProcess' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSort' | 'flowChartSummingJunction' | 'flowChartTerminator' | 'folderCorner' | 'frame' | 'funnel' | 'gear6' | 'gear9' | 'halfFrame' | 'heart' | 'heptagon' | 'hexagon' | 'homePlate' | 'horizontalScroll' | 'irregularSeal1' | 'irregularSeal2' | 'leftArrow' | 'leftArrowCallout' | 'leftBrace' | 'leftBracket' | 'leftCircularArrow' | 'leftRightArrow' | 'leftRightArrowCallout' | 'leftRightCircularArrow' | 'leftRightRibbon' | 'leftRightUpArrow' | 'leftUpArrow' | 'lightningBolt' | 'line' | 'lineInv' | 'mathDivide' | 'mathEqual' | 'mathMinus' | 'mathMultiply' | 'mathNotEqual' | 'mathPlus' | 'moon' | 'noSmoking' | 'nonIsoscelesTrapezoid' | 'notchedRightArrow' | 'octagon' | 'parallelogram' | 'pentagon' | 'pie' | 'pieWedge' | 'plaque' | 'plaqueTabs' | 'plus' | 'quadArrow' | 'quadArrowCallout' | 'rect' | 'ribbon' | 'ribbon2' | 'rightArrow' | 'rightArrowCallout' | 'rightBrace' | 'rightBracket' | 'round1Rect' | 'round2DiagRect' | 'round2SameRect' | 'roundRect' | 'rtTriangle' | 'smileyFace' | 'snip1Rect' | 'snip2DiagRect' | 'snip2SameRect' | 'snipRoundRect' | 'squareTabs' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'stripedRightArrow' | 'sun' | 'swooshArrow' | 'teardrop' | 'trapezoid' | 'triangle' | 'upArrow' | 'upArrowCallout' | 'upDownArrow' | 'upDownArrowCallout' | 'uturnArrow' | 'verticalScroll' | 'wave' | 'wedgeEllipseCallout' | 'wedgeRectCallout' | 'wedgeRoundRectCallout';
2896
+ type SHAPE_NAME = 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'actionButtonBackPrevious' | 'actionButtonBeginning' | 'actionButtonBlank' | 'actionButtonDocument' | 'actionButtonEnd' | 'actionButtonForwardNext' | 'actionButtonHelp' | 'actionButtonHome' | 'actionButtonInformation' | 'actionButtonMovie' | 'actionButtonReturn' | 'actionButtonSound' | 'arc' | 'bentArrow' | 'bentUpArrow' | 'bevel' | 'blockArc' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'bracePair' | 'bracketPair' | 'callout1' | 'callout2' | 'callout3' | 'can' | 'chartPlus' | 'chartStar' | 'chartX' | 'chevron' | 'chord' | 'circularArrow' | 'cloud' | 'cloudCallout' | 'corner' | 'cornerTabs' | 'cube' | 'curvedDownArrow' | 'curvedLeftArrow' | 'curvedRightArrow' | 'curvedUpArrow' | 'custGeom' | 'decagon' | 'diagStripe' | 'diamond' | 'dodecagon' | 'donut' | 'doubleWave' | 'downArrow' | 'downArrowCallout' | 'ellipse' | 'ellipseRibbon' | 'ellipseRibbon2' | 'flowChartAlternateProcess' | 'flowChartCollate' | 'flowChartConnector' | 'flowChartDecision' | 'flowChartDelay' | 'flowChartDisplay' | 'flowChartDocument' | 'flowChartExtract' | 'flowChartInputOutput' | 'flowChartInternalStorage' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartMagneticTape' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartMerge' | 'flowChartMultidocument' | 'flowChartOfflineStorage' | 'flowChartOffpageConnector' | 'flowChartOnlineStorage' | 'flowChartOr' | 'flowChartPredefinedProcess' | 'flowChartPreparation' | 'flowChartProcess' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSort' | 'flowChartSummingJunction' | 'flowChartTerminator' | 'foldedCorner' | 'frame' | 'funnel' | 'gear6' | 'gear9' | 'halfFrame' | 'heart' | 'heptagon' | 'hexagon' | 'homePlate' | 'horizontalScroll' | 'irregularSeal1' | 'irregularSeal2' | 'leftArrow' | 'leftArrowCallout' | 'leftBrace' | 'leftBracket' | 'leftCircularArrow' | 'leftRightArrow' | 'leftRightArrowCallout' | 'leftRightCircularArrow' | 'leftRightRibbon' | 'leftRightUpArrow' | 'leftUpArrow' | 'lightningBolt' | 'line' | 'lineInv' | 'mathDivide' | 'mathEqual' | 'mathMinus' | 'mathMultiply' | 'mathNotEqual' | 'mathPlus' | 'moon' | 'noSmoking' | 'nonIsoscelesTrapezoid' | 'notchedRightArrow' | 'octagon' | 'parallelogram' | 'pentagon' | 'pie' | 'pieWedge' | 'plaque' | 'plaqueTabs' | 'plus' | 'quadArrow' | 'quadArrowCallout' | 'rect' | 'ribbon' | 'ribbon2' | 'rightArrow' | 'rightArrowCallout' | 'rightBrace' | 'rightBracket' | 'round1Rect' | 'round2DiagRect' | 'round2SameRect' | 'roundRect' | 'rtTriangle' | 'smileyFace' | 'snip1Rect' | 'snip2DiagRect' | 'snip2SameRect' | 'snipRoundRect' | 'squareTabs' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'stripedRightArrow' | 'sun' | 'swooshArrow' | 'teardrop' | 'trapezoid' | 'triangle' | 'upArrow' | 'upArrowCallout' | 'upDownArrow' | 'upDownArrowCallout' | 'uturnArrow' | 'verticalScroll' | 'wave' | 'wedgeEllipseCallout' | 'wedgeRectCallout' | 'wedgeRoundRectCallout';
2897
+ /**
2898
+ * Every shape geometry name PptxGenJS can serialize without corrupting the
2899
+ * package: the OOXML preset geometries (`ST_ShapeType` — `SHAPE_TYPE` values
2900
+ * plus the unexposed connectors above) and `custGeom` (freeform paths, emitted
2901
+ * as `<a:custGeom>` rather than `<a:prstGeom>`). Used to reject bogus presets
2902
+ * before they become an invalid `<a:prstGeom prst="...">` that triggers
2903
+ * PowerPoint's "needs repair" dialog and drops the shape.
2904
+ */
2905
+ declare const VALID_SHAPE_PRESETS: ReadonlySet<string>;
2678
2906
  declare enum CHART_TYPE {
2679
2907
  'AREA' = "area",
2680
2908
  'BAR' = "bar",
@@ -2839,6 +3067,17 @@ declare const IMG_PLAYBTN = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB4AAA
2839
3067
  declare const EMU_PER_INCH = 914400;
2840
3068
  declare const EMU_PER_POINT = 12700;
2841
3069
  declare const POINTS_PER_INCH = 72;
3070
+ /**
3071
+ * English Metric Units — the integer unit OOXML serializes geometry in (914400 per inch).
3072
+ *
3073
+ * Branded so a value that has already been resolved to EMU cannot be silently fed back into a
3074
+ * unit converter: {@link coordToEmu} only accepts a user `Coord`, so passing an `Emu` into it is
3075
+ * a compile-time error. This replaces the old runtime "a number ≥ 100 must already be EMU"
3076
+ * magnitude guess, which silently mis-rendered values near the threshold.
3077
+ */
3078
+ type Emu = number & {
3079
+ readonly __unit: 'emu';
3080
+ };
2842
3081
  type StandardLayoutName = 'LAYOUT_4x3' | 'LAYOUT_16x9' | 'LAYOUT_16x10' | 'LAYOUT_WIDE';
2843
3082
  interface StandardLayout {
2844
3083
  /** PptxGenJS layout key used with `pptx.layout`. */
@@ -2858,13 +3097,32 @@ interface StandardLayout {
2858
3097
  /** Slide height in English Metric Units. */
2859
3098
  readonly heightEmu: number;
2860
3099
  }
2861
- declare function inchesToEmu(inches: number): number;
2862
- declare function pointsToEmu(points: number): number;
2863
- declare function pixelsToEmu(pixels: number, dpi: number): number;
3100
+ declare function inchesToEmu(inches: number): Emu;
3101
+ declare function pointsToEmu(points: number): Emu;
3102
+ declare function pixelsToEmu(pixels: number, dpi: number): Emu;
3103
+ /**
3104
+ * Resolve a percentage of an axis length to EMU.
3105
+ * @param percent - percentage value (e.g. `50` for 50%)
3106
+ * @param axisEmu - the axis length in EMU (slide width for x/w, height for y/h)
3107
+ */
3108
+ declare function percentToEmu(percent: number, axisEmu: number): Emu;
3109
+ /**
3110
+ * The single user-coordinate → EMU boundary. Convert each user-supplied coordinate exactly once.
3111
+ *
3112
+ * Accepts (see {@link Coord}):
3113
+ * - a bare `number` → **always inches** (the documented unit); no magnitude guessing
3114
+ * - `"<n>%"` → percentage of `axisEmu`
3115
+ * - `"<n>in"` / `"<n>pt"` / `"<n>emu"` → explicit units (the escape hatch for non-inch values)
3116
+ *
3117
+ * Throws on non-finite or unparseable input rather than silently emitting a degenerate 0-size.
3118
+ * @param value - user coordinate
3119
+ * @param axisEmu - axis length in EMU, used only to resolve percentages
3120
+ */
3121
+ declare function coordToEmu(value: number | string, axisEmu: number): Emu;
2864
3122
  declare function emuToInches(emu: number): number;
2865
3123
  declare function emuToPoints(emu: number): number;
2866
3124
  declare function emuToPixels(emu: number, dpi: number): number;
2867
3125
  declare const STANDARD_LAYOUTS: Readonly<Record<StandardLayoutName, StandardLayout>>;
2868
3126
  //#endregion
2869
- export { OutputType as $, WriteProps as $n, IPresentationProps as $t, DEF_CHART_BORDER as A, SlideMasterChartProps as An, HAlign as At, DEF_SLIDE_MARGIN_IN as B, TableStyleProps as Bn, IChartPropsBase as Bt, CHART_TYPE as C, ShadowProps as Cn, Coord as Ct, DEF_CELL_BORDER as D, SlideBaseProps as Dn, GeometryPoint as Dt, DEF_BULLET_MARGIN as E, ShapeProps as En, DataOrPathRequiredProps as Et, DEF_PRES_LAYOUT as F, TableCellProps as Fn, IChartOpts as Ft, IMG_PLAYBTN as G, TextProps as Gn, IChartPropsChartRadar as Gt, DEF_TEXT_SHADOW as H, TableToSlidesProps as Hn, IChartPropsChartDoughnut as Ht, DEF_PRES_LAYOUT_NAME as I, TableProps as In, IChartOptsLib as It, LAYOUT_IDX_SERIES_BASE as J, ThemeColor as Jn, IChartPropsFillLine as Jt, IMG_SVG_PLACEHOLDER as K, TextPropsOptions as Kn, IChartPropsDataLabel as Kt, DEF_SHAPE_LINE_COLOR as L, TableRow as Ln, IChartPropsAxisCat as Lt, DEF_FONT_COLOR as M, SlideMasterProps as Mn, HyperlinkProps as Mt, DEF_FONT_SIZE as N, SlideNumberProps as Nn, IChartAreaProps as Nt, DEF_CELL_MARGIN_IN as O, SlideLayout as On, GradientFillProps as Ot, DEF_FONT_TITLE_SIZE as P, TableCell as Pn, IChartMulti as Pt, ONEPT as Q, WriteFileProps as Qn, IOptsChartData as Qt, DEF_SHAPE_SHADOW as R, TableRowSlide as Rn, IChartPropsAxisSer as Rt, CHART_NAME as S, SectionProps as Sn, Color as St, ChartType as T, ShapeLineProps as Tn, DataOrPathProps as Tt, EMU as U, TextBaseProps as Un, IChartPropsChartLine as Ut, DEF_TEXT_GLOW as V, TableStyleRegionProps as Vn, IChartPropsChartBar as Vt, IMG_BROKEN as W, TextGlowProps as Wn, IChartPropsChartPie as Wt, LINEH_MODIFIER as X, VAlign as Xn, IChartPropsTitle as Xt, LETTERS as Y, ThemeProps as Yn, IChartPropsLegend as Yt, MASTER_OBJECTS as Z, WriteBaseProps as Zn, IChartSeriesOpts as Zt, AXIS_ID_VALUE_SECONDARY as _, PresLayout as _n, BackgroundProps as _t, StandardLayout as a, LinearGradientFillProps as an, SCHEME_COLOR_NAMES as at, BARCHART_COLORS as b, PresentationProps as bn, ChartLineCap as bt, emuToPixels as c, MediaType as cn, SLDNUMFLDID as ct, pixelsToEmu as d, OptsChartData as dn, ShapeType as dt, ISlideObject as en, textRun as er, PIECHART_COLORS as et, pointsToEmu as f, OptsChartGridLine as fn, TABLE_STYLE as ft, AXIS_ID_VALUE_PRIMARY as g, PositionProps as gn, AddSlideProps as gt, AXIS_ID_SERIES_PRIMARY as h, PlaceholderProps as hn, WRITE_OUTPUT_TYPE as ht, STANDARD_LAYOUTS as i, ImageProps as in, SCHEME_COLORS as it, DEF_CHART_GRIDLINE as j, SlideMasterObject as jn, HexColor as jt, DEF_CELL_MARGIN_PT as k, SlideLayoutInternal as kn, GradientStopProps as kt, emuToPoints as l, ObjectNameProps as ln, SLIDE_OBJECT_TYPES as lt, AXIS_ID_CATEGORY_SECONDARY as m, PatternPreset as mn, TEXT_VALIGN as mt, EMU_PER_POINT as n, ISlideRelChart as nn, PLACEHOLDER_TYPES as nt, StandardLayoutName as o, Margin as on, SHAPE_NAME as ot, AXIS_ID_CATEGORY_PRIMARY as p, PatternFillProps as pn, TEXT_HALIGN as pt, JSZIP_OUTPUT_TYPE as q, TextVertType as qn, IChartPropsDataTable as qt, POINTS_PER_INCH as r, ISlideRelMedia as rn, REGEX_HEX_COLOR as rt, emuToInches as s, MediaProps as sn, SHAPE_TYPE as st, EMU_PER_INCH as t, ISlideRel as tn, textRuns as tr, PLACEHOLDER_TYPE as tt, inchesToEmu as u, ObjectOptions as un, SchemeColor as ut, AlignH as v, PresSlide as vn, BorderProps as vt, CRLF as w, ShapeFillProps as wn, CustomPropertyValue as wt, BULLET_TYPES as x, SectionInternalProps as xn, ChartLineDash as xt, AlignV as y, PresSlideInternal as yn, ChartAxisTickMark as yt, DEF_SLIDE_BKGD as z, TableStyleInternal as zn, IChartPropsAxisVal as zt };
2870
- //# sourceMappingURL=units-y594YyBo.d.ts.map
3127
+ export { LINEH_MODIFIER as $, TextGlowProps as $n, IChartPropsFillLine as $t, DEF_CELL_BORDER as A, ShadowProps as An, DataOrPathProps as At, DEF_SHAPE_LINE_COLOR as B, SlideMasterProps as Bn, IChartOpts as Bt, BARCHART_COLORS as C, PositionProps as Cn, ChartAxisTickMark as Ct, CRLF as D, PresentationProps as Dn, Color as Dt, CHART_TYPE as E, PresSlideInternal as En, ChartLineDash as Et, DEF_FONT_COLOR as F, SlideBaseProps as Fn, HAlign as Ft, DEF_TEXT_SHADOW as G, TableRow as Gn, IChartPropsBase as Gt, DEF_SLIDE_BKGD as H, TableCell as Hn, IChartPropsAxisCat as Ht, DEF_FONT_SIZE as I, SlideLayout as In, HexColor as It, IMG_PLAYBTN as J, TableStyleProps as Jn, IChartPropsChartLine as Jt, EMU as K, TableRowSlide as Kn, IChartPropsChartBar as Kt, DEF_FONT_TITLE_SIZE as L, SlideLayoutInternal as Ln, HyperlinkProps as Lt, DEF_CELL_MARGIN_PT as M, ShapeFillProps as Mn, GeometryPoint as Mt, DEF_CHART_BORDER as N, ShapeLineProps as Nn, GradientFillProps as Nt, ChartType as O, SectionInternalProps as On, Coord as Ot, DEF_CHART_GRIDLINE as P, ShapeProps as Pn, GradientStopProps as Pt, LETTERS as Q, TextFitShrinkProps as Qn, IChartPropsDataTable as Qt, DEF_PRES_LAYOUT as R, SlideMasterChartProps as Rn, IChartAreaProps as Rt, AlignV as S, PlaceholderProps as Sn, BorderProps as St, CHART_NAME as T, PresSlide as Tn, ChartLineCap as Tt, DEF_SLIDE_MARGIN_IN as U, TableCellProps as Un, IChartPropsAxisSer as Ut, DEF_SHAPE_SHADOW as V, SlideNumberProps as Vn, IChartOptsLib as Vt, DEF_TEXT_GLOW as W, TableProps as Wn, IChartPropsAxisVal as Wt, JSZIP_OUTPUT_TYPE as X, TableToSlidesProps as Xn, IChartPropsChartRadar as Xt, IMG_SVG_PLACEHOLDER as Y, TableStyleRegionProps as Yn, IChartPropsChartPie as Yt, LAYOUT_IDX_SERIES_BASE as Z, TextBaseProps as Zn, IChartPropsDataLabel as Zt, AXIS_ID_CATEGORY_SECONDARY as _, ObjectOptions as _n, TEXT_VALIGN as _t, STANDARD_LAYOUTS as a, ISlideObject as an, VAlign as ar, PLACEHOLDER_TYPES as at, AXIS_ID_VALUE_SECONDARY as b, PatternFillProps as bn, AddSlideProps as bt, coordToEmu as c, ISlideRelMedia as cn, WriteProps as cr, SCHEME_COLOR_NAMES as ct, emuToPoints as d, LinearGradientFillProps as dn, SLDNUMFLDID as dt, IChartPropsLegend as en, TextProps as er, MASTER_OBJECTS as et, inchesToEmu as f, Margin as fn, SLIDE_OBJECT_TYPES as ft, AXIS_ID_CATEGORY_PRIMARY as g, ObjectNameProps as gn, TEXT_HALIGN as gt, pointsToEmu as h, ObjectLockProps as hn, TABLE_STYLE as ht, POINTS_PER_INCH as i, IPresentationProps as in, ThemeProps as ir, PLACEHOLDER_TYPE as it, DEF_CELL_MARGIN_IN as j, ShapeAdjustValue as jn, DataOrPathRequiredProps as jt, DEF_BULLET_MARGIN as k, SectionProps as kn, CustomPropertyValue as kt, emuToInches as l, ImageProps as ln, textRun as lr, SHAPE_NAME as lt, pixelsToEmu as m, MediaType as mn, ShapeType as mt, EMU_PER_POINT as n, IChartSeriesOpts as nn, TextVertType as nr, OutputType as nt, StandardLayout as o, ISlideRel as on, WriteBaseProps as or, REGEX_HEX_COLOR as ot, percentToEmu as p, MediaProps as pn, SchemeColor as pt, IMG_BROKEN as q, TableStyleInternal as qn, IChartPropsChartDoughnut as qt, Emu as r, IOptsChartData as rn, ThemeColor as rr, PIECHART_COLORS as rt, StandardLayoutName as s, ISlideRelChart as sn, WriteFileProps as sr, SCHEME_COLORS as st, EMU_PER_INCH as t, IChartPropsTitle as tn, TextPropsOptions as tr, ONEPT as tt, emuToPixels as u, LineCap as un, textRuns as ur, SHAPE_TYPE as ut, AXIS_ID_SERIES_PRIMARY as v, OptsChartData as vn, VALID_SHAPE_PRESETS as vt, BULLET_TYPES as w, PresLayout as wn, ChartDataPointStyle as wt, AlignH as x, PatternPreset as xn, BackgroundProps as xt, AXIS_ID_VALUE_PRIMARY as y, OptsChartGridLine as yn, WRITE_OUTPUT_TYPE as yt, DEF_PRES_LAYOUT_NAME as z, SlideMasterObject as zn, IChartMulti as zt };
3128
+ //# sourceMappingURL=units-BPRPrYRg.d.ts.map