ooxml-core 1.48.0 → 1.48.1

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.
Files changed (208) hide show
  1. package/dist/pptx/automation/index.d.ts +5 -12
  2. package/dist/pptx/automation/index.d.ts.map +1 -1
  3. package/dist/pptx/automation/schemas/chart-formatting-schemas.d.ts +1 -1
  4. package/dist/pptx/automation/schemas/chart-formatting-schemas.d.ts.map +1 -1
  5. package/dist/pptx/automation/schemas/chart-schemas.d.ts +1 -1
  6. package/dist/pptx/automation/schemas/chart-schemas.d.ts.map +1 -1
  7. package/dist/pptx/automation/schemas/chart-user-shape-schemas.d.ts +1 -1
  8. package/dist/pptx/automation/schemas/chart-user-shape-schemas.d.ts.map +1 -1
  9. package/dist/pptx/automation/schemas/element-schemas.d.ts +1 -1
  10. package/dist/pptx/automation/schemas/element-schemas.d.ts.map +1 -1
  11. package/dist/pptx/automation/schemas/export-schemas.d.ts +1 -1
  12. package/dist/pptx/automation/schemas/export-schemas.d.ts.map +1 -1
  13. package/dist/pptx/automation/schemas/geometry-schemas.d.ts +1 -1
  14. package/dist/pptx/automation/schemas/geometry-schemas.d.ts.map +1 -1
  15. package/dist/pptx/automation/schemas/hyperlink-schemas.d.ts +1 -1
  16. package/dist/pptx/automation/schemas/hyperlink-schemas.d.ts.map +1 -1
  17. package/dist/pptx/automation/schemas/index.d.ts +8 -8
  18. package/dist/pptx/automation/schemas/index.d.ts.map +1 -1
  19. package/dist/pptx/automation/schemas/json-schemas.d.ts +1 -1
  20. package/dist/pptx/automation/schemas/json-schemas.d.ts.map +1 -1
  21. package/dist/pptx/automation/schemas/layout-schemas.d.ts +1 -1
  22. package/dist/pptx/automation/schemas/layout-schemas.d.ts.map +1 -1
  23. package/dist/pptx/automation/schemas/lock-schemas.d.ts +1 -1
  24. package/dist/pptx/automation/schemas/lock-schemas.d.ts.map +1 -1
  25. package/dist/pptx/automation/schemas/metadata-schemas.d.ts +1 -1
  26. package/dist/pptx/automation/schemas/metadata-schemas.d.ts.map +1 -1
  27. package/dist/pptx/automation/schemas/ole-schemas.d.ts +1 -1
  28. package/dist/pptx/automation/schemas/ole-schemas.d.ts.map +1 -1
  29. package/dist/pptx/automation/schemas/presentation-schemas.d.ts +1 -1
  30. package/dist/pptx/automation/schemas/presentation-schemas.d.ts.map +1 -1
  31. package/dist/pptx/automation/schemas/section-schemas.d.ts +1 -1
  32. package/dist/pptx/automation/schemas/section-schemas.d.ts.map +1 -1
  33. package/dist/pptx/automation/schemas/slide-schemas.d.ts +1 -1
  34. package/dist/pptx/automation/schemas/slide-schemas.d.ts.map +1 -1
  35. package/dist/pptx/automation/schemas/smartart-schemas.d.ts +1 -1
  36. package/dist/pptx/automation/schemas/smartart-schemas.d.ts.map +1 -1
  37. package/dist/pptx/automation/schemas/table-style-schemas.d.ts +1 -1
  38. package/dist/pptx/automation/schemas/table-style-schemas.d.ts.map +1 -1
  39. package/dist/pptx/automation/schemas/template-schemas.d.ts +1 -1
  40. package/dist/pptx/automation/schemas/template-schemas.d.ts.map +1 -1
  41. package/dist/pptx/automation/schemas/theme-schemas.d.ts +1 -1
  42. package/dist/pptx/automation/schemas/theme-schemas.d.ts.map +1 -1
  43. package/dist/pptx/automation/schemas/validation-schemas.d.ts +1 -1
  44. package/dist/pptx/automation/schemas/validation-schemas.d.ts.map +1 -1
  45. package/dist/pptx/chunks/color-primitives-DHyz14D9.d.ts +151 -0
  46. package/dist/pptx/chunks/color-primitives-DHyz14D9.d.ts.map +1 -0
  47. package/dist/pptx/chunks/{index-ClHCBGOf.d.ts → index-7tA9HqRL.d.ts} +10057 -1222
  48. package/dist/pptx/chunks/index-7tA9HqRL.d.ts.map +1 -0
  49. package/dist/pptx/chunks/{index-DqkBjVqR.d.ts → index-CAzt1jbx.d.ts} +4 -5
  50. package/dist/pptx/chunks/index-CAzt1jbx.d.ts.map +1 -0
  51. package/dist/pptx/chunks/{schemas-LHsDbVOw.d.ts → index-CyAgQ2zG.d.ts} +6 -2
  52. package/dist/pptx/chunks/index-CyAgQ2zG.d.ts.map +1 -0
  53. package/dist/pptx/chunks/index-cJSPBkU1.d.ts +185 -0
  54. package/dist/pptx/chunks/index-cJSPBkU1.d.ts.map +1 -0
  55. package/dist/pptx/chunks/index-cr_sgz1w.d.ts +94 -0
  56. package/dist/pptx/chunks/index-cr_sgz1w.d.ts.map +1 -0
  57. package/dist/pptx/chunks/presentation-Be108jrz.d.ts +12521 -0
  58. package/dist/pptx/chunks/presentation-Be108jrz.d.ts.map +1 -0
  59. package/dist/pptx/chunks/{inspection-status-TKac7eqb.d.ts → signature-inspection-status-TKac7eqb.d.ts} +1 -1
  60. package/dist/pptx/chunks/signature-inspection-status-TKac7eqb.d.ts.map +1 -0
  61. package/dist/pptx/chunks/text-operations-a1cqBYk9.d.ts +111 -0
  62. package/dist/pptx/chunks/text-operations-a1cqBYk9.d.ts.map +1 -0
  63. package/dist/pptx/cli/index.d.ts +17 -1
  64. package/dist/pptx/cli/index.d.ts.map +1 -1
  65. package/dist/pptx/converter/index.d.ts +1 -1
  66. package/dist/pptx/editor/ai/table-merge.d.ts +16 -0
  67. package/dist/pptx/editor/ai/table-merge.d.ts.map +1 -1
  68. package/dist/pptx/editor/loader/element-patch-walker.d.ts +15 -0
  69. package/dist/pptx/editor/loader/element-patch-walker.d.ts.map +1 -1
  70. package/dist/pptx/editor/loader/lazy-image-resolution.d.ts +15 -0
  71. package/dist/pptx/editor/loader/lazy-image-resolution.d.ts.map +1 -1
  72. package/dist/pptx/editor/loader/load-content-helpers.d.ts +7 -0
  73. package/dist/pptx/editor/loader/load-content-helpers.d.ts.map +1 -1
  74. package/dist/pptx/editor/loader/table-style-image-paths.d.ts +20 -0
  75. package/dist/pptx/editor/loader/table-style-image-paths.d.ts.map +1 -1
  76. package/dist/pptx/editor/loader/text-fill-image-paths.d.ts +19 -0
  77. package/dist/pptx/editor/loader/text-fill-image-paths.d.ts.map +1 -1
  78. package/dist/pptx/editor/render/bullet-autonum.d.ts +14 -0
  79. package/dist/pptx/editor/render/bullet-list.d.ts +8 -0
  80. package/dist/pptx/editor/render/bullet-list.d.ts.map +1 -1
  81. package/dist/pptx/editor/render/bullet-toggle.d.ts +4 -0
  82. package/dist/pptx/editor/render/bullet-toggle.d.ts.map +1 -1
  83. package/dist/pptx/editor/render/chart-user-shape-edit.d.ts +12 -0
  84. package/dist/pptx/editor/render/chart-user-shape-edit.d.ts.map +1 -1
  85. package/dist/pptx/editor/render/clone.d.ts +20 -0
  86. package/dist/pptx/editor/render/clone.d.ts.map +1 -1
  87. package/dist/pptx/editor/render/collaboration-assets.d.ts +17 -0
  88. package/dist/pptx/editor/render/collaboration-live-patch-target.d.ts +9 -0
  89. package/dist/pptx/editor/render/collaboration-live-patch-target.d.ts.map +1 -1
  90. package/dist/pptx/editor/render/collaboration-reconcile.d.ts +21 -0
  91. package/dist/pptx/editor/render/collaboration-reconcile.d.ts.map +1 -1
  92. package/dist/pptx/editor/render/collaboration-sync.d.ts +32 -4
  93. package/dist/pptx/editor/render/collaboration-sync.d.ts.map +1 -1
  94. package/dist/pptx/editor/render/collaboration-text-codec.d.ts +33 -2
  95. package/dist/pptx/editor/render/collaboration-text-codec.d.ts.map +1 -0
  96. package/dist/pptx/editor/render/collaboration-text-merge.d.ts +36 -2
  97. package/dist/pptx/editor/render/collaboration-text-merge.d.ts.map +1 -0
  98. package/dist/pptx/editor/render/collaboration-text-native-edit.d.ts +2 -2
  99. package/dist/pptx/editor/render/collaboration-text-positions.d.ts +34 -2
  100. package/dist/pptx/editor/render/collaboration-text-positions.d.ts.map +1 -0
  101. package/dist/pptx/editor/render/collaboration-text-projection.d.ts +1 -1
  102. package/dist/pptx/editor/render/collaboration-text-session-apply.d.ts +3 -3
  103. package/dist/pptx/editor/render/collaboration-text-session-delta.d.ts +36 -2
  104. package/dist/pptx/editor/render/collaboration-text-session-delta.d.ts.map +1 -0
  105. package/dist/pptx/editor/render/collaboration-text-session-paragraph.d.ts +1 -1
  106. package/dist/pptx/editor/render/collaboration-text-session.d.ts +40 -2
  107. package/dist/pptx/editor/render/collaboration-text-session.d.ts.map +1 -0
  108. package/dist/pptx/editor/render/collaboration-text-snapshot-positions.d.ts +2 -2
  109. package/dist/pptx/editor/render/custom-show-operations.d.ts +14 -0
  110. package/dist/pptx/editor/render/custom-show-operations.d.ts.map +1 -1
  111. package/dist/pptx/editor/render/deck-save-encryption.d.ts +24 -0
  112. package/dist/pptx/editor/render/deck-save-encryption.d.ts.map +1 -1
  113. package/dist/pptx/editor/render/element-locks.d.ts +25 -0
  114. package/dist/pptx/editor/render/element-locks.d.ts.map +1 -1
  115. package/dist/pptx/editor/render/element-operations.d.ts +11 -0
  116. package/dist/pptx/editor/render/element-operations.d.ts.map +1 -1
  117. package/dist/pptx/editor/render/element.d.ts +12 -0
  118. package/dist/pptx/editor/render/element.d.ts.map +1 -1
  119. package/dist/pptx/editor/render/find-replace.d.ts +8 -2
  120. package/dist/pptx/editor/render/find-replace.d.ts.map +1 -1
  121. package/dist/pptx/editor/render/font-family-update.d.ts +32 -1
  122. package/dist/pptx/editor/render/font-family-update.d.ts.map +1 -1
  123. package/dist/pptx/editor/render/group-drill.d.ts +26 -0
  124. package/dist/pptx/editor/render/group-drill.d.ts.map +1 -1
  125. package/dist/pptx/editor/render/group-ops.d.ts +24 -0
  126. package/dist/pptx/editor/render/paragraph-geometry-overrides.d.ts +21 -1
  127. package/dist/pptx/editor/render/paragraph-geometry-overrides.d.ts.map +1 -1
  128. package/dist/pptx/editor/render/remap-text.d.ts +5 -0
  129. package/dist/pptx/editor/render/remap-text.d.ts.map +1 -1
  130. package/dist/pptx/editor/render/section-operations.d.ts +14 -0
  131. package/dist/pptx/editor/render/section-operations.d.ts.map +1 -1
  132. package/dist/pptx/editor/render/slide-background-patch.d.ts +15 -0
  133. package/dist/pptx/editor/render/slide-background-patch.d.ts.map +1 -1
  134. package/dist/pptx/editor/render/slide-operations.d.ts +12 -0
  135. package/dist/pptx/editor/render/slide-operations.d.ts.map +1 -1
  136. package/dist/pptx/editor/render/slide-search.d.ts +6 -0
  137. package/dist/pptx/editor/render/slide-search.d.ts.map +1 -1
  138. package/dist/pptx/editor/render/slide-size-rescale.d.ts +18 -0
  139. package/dist/pptx/editor/render/slide-size-rescale.d.ts.map +1 -1
  140. package/dist/pptx/editor/render/slide-transition-edits.d.ts +15 -0
  141. package/dist/pptx/editor/render/slide-transition-edits.d.ts.map +1 -1
  142. package/dist/pptx/editor/render/table-cell-edit.d.ts +8 -0
  143. package/dist/pptx/editor/render/table-cell-edit.d.ts.map +1 -1
  144. package/dist/pptx/editor/render/table-cell-merge.d.ts +15 -0
  145. package/dist/pptx/editor/render/table-cell-merge.d.ts.map +1 -1
  146. package/dist/pptx/editor/render/table-data-grid-ops.d.ts +26 -0
  147. package/dist/pptx/editor/render/table-data-grid-ops.d.ts.map +1 -1
  148. package/dist/pptx/editor/render/table-layout.d.ts +3 -1
  149. package/dist/pptx/editor/render/table-layout.d.ts.map +1 -1
  150. package/dist/pptx/editor/render/table-merge.d.ts +16 -0
  151. package/dist/pptx/editor/render/table-merge.d.ts.map +1 -1
  152. package/dist/pptx/editor/render/table-style-editor-descriptor.d.ts +13 -0
  153. package/dist/pptx/editor/render/table-style-editor-descriptor.d.ts.map +1 -1
  154. package/dist/pptx/editor/render/table-style-editor-edit.d.ts +13 -0
  155. package/dist/pptx/editor/render/table-style-editor-edit.d.ts.map +1 -1
  156. package/dist/pptx/editor/render/table-style-editor-parts.d.ts +10 -0
  157. package/dist/pptx/editor/render/table-style-editor-parts.d.ts.map +1 -1
  158. package/dist/pptx/editor/render/table-style-map-edits.d.ts +20 -0
  159. package/dist/pptx/editor/render/table-style-map-edits.d.ts.map +1 -1
  160. package/dist/pptx/editor/render/text-content-style.d.ts +2 -1
  161. package/dist/pptx/editor/render/text-content-style.d.ts.map +1 -1
  162. package/dist/pptx/editor/render/text-runs-style-patch.d.ts +2 -2
  163. package/dist/pptx/editor/render/text-segment-paragraph-break.d.ts +23 -0
  164. package/dist/pptx/editor/render/text-segment-paragraph-break.d.ts.map +1 -1
  165. package/dist/pptx/editor/render/text-style-scope.d.ts +20 -2
  166. package/dist/pptx/editor/render/text-style-scope.d.ts.map +1 -1
  167. package/dist/pptx/editor/render/text-theme.d.ts +11 -0
  168. package/dist/pptx/editor/render/text-theme.d.ts.map +1 -1
  169. package/dist/pptx/editor/render/theme-editor-presets.d.ts +9 -0
  170. package/dist/pptx/editor/render/theme-editor-presets.d.ts.map +1 -1
  171. package/dist/pptx/editor/render/update-text-segment-style.d.ts +2 -1
  172. package/dist/pptx/editor/render/update-text-segment-style.d.ts.map +1 -1
  173. package/dist/pptx/index.d.ts +23 -9
  174. package/dist/pptx/node/index.d.ts +17 -1
  175. package/dist/pptx/node/index.d.ts.map +1 -1
  176. package/dist/pptx/signature-node/index.d.ts +8 -1
  177. package/dist/pptx/signature-node/index.d.ts.map +1 -1
  178. package/dist/pptx/smartart-layouts/index.d.ts +8 -1
  179. package/dist/pptx/smartart-layouts/index.d.ts.map +1 -1
  180. package/dist/pptx/ui/index.d.ts +2 -0
  181. package/dist/pptx/ui/index.d.ts.map +1 -1
  182. package/package.json +8 -8
  183. package/dist/pptx/chunks/collaboration-text-codec-1VmwD3yq.d.ts +0 -34
  184. package/dist/pptx/chunks/collaboration-text-codec-1VmwD3yq.d.ts.map +0 -1
  185. package/dist/pptx/chunks/collaboration-text-merge-B-tth-0W.d.ts +0 -19
  186. package/dist/pptx/chunks/collaboration-text-merge-B-tth-0W.d.ts.map +0 -1
  187. package/dist/pptx/chunks/collaboration-text-positions-D-1Jo1Fz.d.ts +0 -34
  188. package/dist/pptx/chunks/collaboration-text-positions-D-1Jo1Fz.d.ts.map +0 -1
  189. package/dist/pptx/chunks/collaboration-text-session-CWHTaWF4.d.ts +0 -41
  190. package/dist/pptx/chunks/collaboration-text-session-CWHTaWF4.d.ts.map +0 -1
  191. package/dist/pptx/chunks/collaboration-text-session-delta-Dxzybssp.d.ts +0 -37
  192. package/dist/pptx/chunks/collaboration-text-session-delta-Dxzybssp.d.ts.map +0 -1
  193. package/dist/pptx/chunks/elements-CValElsy.d.ts +0 -3568
  194. package/dist/pptx/chunks/elements-CValElsy.d.ts.map +0 -1
  195. package/dist/pptx/chunks/index-BaBgJR8i.d.ts +0 -9913
  196. package/dist/pptx/chunks/index-BaBgJR8i.d.ts.map +0 -1
  197. package/dist/pptx/chunks/index-ClHCBGOf.d.ts.map +0 -1
  198. package/dist/pptx/chunks/index-DqkBjVqR.d.ts.map +0 -1
  199. package/dist/pptx/chunks/inspection-status-TKac7eqb.d.ts.map +0 -1
  200. package/dist/pptx/chunks/schemas-LHsDbVOw.d.ts.map +0 -1
  201. package/dist/pptx/chunks/smart-art-DB37AsFP.d.ts +0 -1817
  202. package/dist/pptx/chunks/smart-art-DB37AsFP.d.ts.map +0 -1
  203. package/dist/pptx/chunks/table-DUO1H9-r.d.ts +0 -1798
  204. package/dist/pptx/chunks/table-DUO1H9-r.d.ts.map +0 -1
  205. package/dist/pptx/chunks/text-operations-B3lZjvs_.d.ts +0 -3363
  206. package/dist/pptx/chunks/text-operations-B3lZjvs_.d.ts.map +0 -1
  207. package/dist/pptx/chunks/text-t_wJ2OwM.d.ts +0 -1452
  208. package/dist/pptx/chunks/text-t_wJ2OwM.d.ts.map +0 -1
@@ -1,3363 +0,0 @@
1
- import { k as XmlObject, r as TextSegment, v as Pptx3DShape, w as PptxDrawingGuide, x as DrawingScene3D } from "./text-t_wJ2OwM.js";
2
- import { t as PptxThemeColorRef } from "./color-ref-CwUQoKPJ.js";
3
- import { E as ShapeStyle, N as PptxImageProperties, u as ParsedTableStyleMap } from "./table-DUO1H9-r.js";
4
- import { F as PlaceholderTextLevelStyle, m as PptxElement } from "./elements-CValElsy.js";
5
- /**
6
- * Available slide transition effects.
7
- *
8
- * Maps to the OOXML child element names under `<p:transition>` / `<p14:transition>`.
9
- *
10
- * @example
11
- * ```ts
12
- * const t: PptxTransitionType = "morph";
13
- * // => "morph" — one of 40+ transition effects
14
- * ```
15
- */
16
- type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'box' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';
17
- /** Cardinal direction tokens from OOXML transition `@_dir`. */
18
- type PptxTransitionDirection4 = 'l' | 'r' | 'u' | 'd';
19
- /** 8-way direction tokens (cardinal + diagonal) for cover/uncover. */
20
- type PptxTransitionDirection8 = PptxTransitionDirection4 | 'lu' | 'ld' | 'ru' | 'rd';
21
- /** Strip direction tokens from OOXML. */
22
- type PptxStripDirection = 'lu' | 'ld' | 'ru' | 'rd';
23
- /** Split orientation from OOXML `@_orient`. */
24
- type PptxSplitOrientation = 'horz' | 'vert';
25
- /** Split in/out direction from OOXML `@_dir`. */
26
- type PptxSplitDirection = 'in' | 'out';
27
- /** Schema-defined `ST_TransitionSpeed` values. */
28
- type PptxTransitionSpeed = 'slow' | 'med' | 'fast';
29
- /**
30
- * Valid direction sets per transition type.
31
- *
32
- * The p14 (Office 2010+) and p15 (Office 2013+) entries below are COM-verified:
33
- * each direction token was confirmed by enumerating PowerPoint's own
34
- * `PpEntryEffect` constants (reflected off the installed
35
- * `Microsoft.Office.Interop.PowerPoint` type library) and reading back the
36
- * `p:transition` XML PowerPoint itself saved for each one, exactly like the
37
- * `p14-prism-family` and `P15_INVX_PRESETS` measurements. Two findings that
38
- * contradict the naive "4-way cardinal for every named Left/Up/Right/Down
39
- * effect" assumption:
40
- * - `switch` and `flip` each expose four named directions in PowerPoint's UI
41
- * (Left/Up/Right/Down), but the saved XML only ever carries `dir="l"` or
42
- * `dir="r"`: Up and Down both collapse to `dir="r"` on save. Modelling them
43
- * as 4-way here would offer a picker button PowerPoint itself cannot
44
- * persist.
45
- * - `ripple`'s only named directions are the four DIAGONALS (`lu`/`ld`/`ru`/
46
- * `rd`, PowerPoint's "Ripple" gallery calls them Left-Up/Left-Down/etc.);
47
- * there is no cardinal `l`/`r`/`u`/`d` variant, and the unset default is a
48
- * fifth "From Center" state with no `dir` attribute at all.
49
- */
50
- declare const TRANSITION_VALID_DIRECTIONS: Readonly<Partial<Record<PptxTransitionType, readonly string[]>>>;
51
- /**
52
- * Transition types offering a "Pattern" effect option alongside direction
53
- * (COM-verified via `p14:glitter/@pattern` and `p14:shred/@pattern`).
54
- */
55
- declare const TRANSITION_PATTERN_OPTIONS: Readonly<Partial<Record<PptxTransitionType, readonly string[]>>>;
56
- /**
57
- * Transition types offering the "Through Black" checkbox
58
- * (OOXML `@_thruBlk`, `CT_OptionalBlackTransition`). COM-verified: enumerating
59
- * every `PpEntryEffect` constant found a dedicated black variant only for
60
- * `Cut` (`ppEffectCutThroughBlack`) and the legacy `Fade` entry (`ppEffectFade`,
61
- * as opposed to the newer non-black `ppEffectFadeSmoothly`); no Blinds/
62
- * Checkerboard "through black" `PpEntryEffect` constant exists despite the
63
- * `thruBlk` attribute being generically parseable off any standard transition
64
- * child.
65
- */
66
- declare const TRANSITION_THRUBLK_TYPES: ReadonlySet<PptxTransitionType>;
67
- /**
68
- * Slide transition configuration.
69
- *
70
- * @example
71
- * ```ts
72
- * const transition: PptxSlideTransition = {
73
- * type: "fade",
74
- * durationMs: 700,
75
- * advanceOnClick: true,
76
- * advanceAfterMs: 5000,
77
- * };
78
- * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 }
79
- * ```
80
- */
81
- /**
82
- * Morph granularity (`<p159:morph @option>`).
83
- *
84
- * - `byObject` - match whole shapes (PowerPoint's default)
85
- * - `byWord` - additionally morph text word by word
86
- * - `byChar` - additionally morph text character by character
87
- */
88
- type PptxMorphOption = 'byObject' | 'byWord' | 'byChar';
89
- interface PptxSlideTransition {
90
- type: PptxTransitionType;
91
- /** Schema-defined transition speed. Defaults to `fast` when omitted. */
92
- speed?: PptxTransitionSpeed;
93
- durationMs?: number;
94
- direction?: string;
95
- advanceOnClick?: boolean;
96
- advanceAfterMs?: number;
97
- /** Number of spokes for wheel transition (1-8). */
98
- spokes?: number;
99
- /** Pattern type for shred transition. */
100
- pattern?: string;
101
- /**
102
- * Through-black flag (OOXML `@_thruBlk`). COM-verified to actually apply to
103
- * `cut` and `fade` (see {@link TRANSITION_THRUBLK_TYPES}); parsed generically
104
- * off any standard transition child so an unexpected authored value still
105
- * round-trips.
106
- */
107
- thruBlk?: boolean;
108
- /** Split orientation (horz/vert) parsed from `@_orient`. */
109
- orient?: PptxSplitOrientation;
110
- /**
111
- * Morph granularity from `<p159:morph @option>`: how finely PowerPoint
112
- * matches content between the two slides. Only meaningful when
113
- * {@link type} is `morph`; defaults to `byObject` when the attribute is
114
- * absent, matching PowerPoint's own default.
115
- */
116
- morphOption?: PptxMorphOption;
117
- /** Relationship ID of transition sound from `p:sndAc/p:stSnd/@r:embed` when present. */
118
- soundRId?: string;
119
- /** Embedded WAV display name from `p:stSnd/p:snd/@name`. */
120
- soundName?: string;
121
- /** Whether the transition sound repeats until another sound starts. */
122
- soundLoop?: boolean;
123
- /** Resolved transition sound media path within the package. */
124
- soundPath?: string;
125
- /** Human-readable sound file name (extracted from soundPath, or set by the
126
- * UI when a new file is picked, before it has a soundPath at all). */
127
- soundFileName?: string;
128
- /**
129
- * A newly-picked local sound file awaiting embedding, as a `data:` URL.
130
- * Set by the transitions ribbon's Sound picker (`applyTransitionSoundFile`
131
- * in `pptx-viewer-shared`) when the user chooses a file that is not yet
132
- * part of the package; mirrors `imageData`/`mediaData` on picture and media
133
- * elements. The save pipeline (`embedTransitionSound`) writes the bytes to
134
- * `ppt/media/`, mints a relationship, sets `soundRId`/`soundPath`, and
135
- * clears this field so a later save does not re-embed the same bytes.
136
- */
137
- soundData?: string;
138
- /**
139
- * When true, the transition stops the currently-playing sound (OOXML `p:sndAc/p:endSnd`).
140
- * Mutually exclusive with `soundRId`/`soundPath` (which use `p:stSnd`).
141
- */
142
- stopSound?: boolean;
143
- /** Preserved sound-action XML node from `p:sndAc` for lossless round-trip. */
144
- rawSoundAction?: XmlObject;
145
- /** Preserved extension-list XML node from `p:extLst` within the transition for lossless round-trip. */
146
- rawExtLst?: XmlObject;
147
- /** Original transition node, retained to preserve unknown attributes and children. */
148
- rawTransition?: XmlObject;
149
- }
150
- /** Timing of one behaviour, from its own `p:cBhvr/p:cTn`. */
151
- interface PptxAnimationBehaviorTiming {
152
- /** The behavior's own fill, independent of its containing effect. */
153
- fill?: 'remove' | 'freeze' | 'hold' | 'transition';
154
- /** Preserved timing profile cannot be reduced to a finite delayed one-shot set. */
155
- unsupportedSetTiming?: boolean;
156
- /** `p:cTn/@dur` in ms; absent when `indefinite` or unset. */
157
- durationMs?: number;
158
- /** Start offset in ms from `p:stCondLst/p:cond/@delay`, relative to the effect start. */
159
- delayMs?: number;
160
- /** `p:cTn/@accel` as a 0..1 fraction of the behaviour's duration. */
161
- accel?: number;
162
- /** `p:cTn/@decel` as a 0..1 fraction of the behaviour's duration. */
163
- decel?: number;
164
- /** `p:cTn/@autoRev`: play forward, then backward, doubling the active time. */
165
- autoReverse?: boolean;
166
- /** `p:cTn/@repeatCount` in plain iterations (OOXML stores thousandths). */
167
- repeatCount?: number;
168
- /** `p:cTn/@tmFilter`: the raw `"t,v; t,v; ..."` time remapping list. */
169
- tmFilter?: string;
170
- }
171
- interface BehaviorBase {
172
- /** Lower-cased `p:attrNameLst` entries, in document order. */
173
- attrNames: string[];
174
- /** `p:cBhvr/@additive` (`base`, `sum`, `repl`, `mult`, `none`). */
175
- additive?: string;
176
- timing: PptxAnimationBehaviorTiming;
177
- }
178
- /** `p:set`: a discrete value held from the behaviour's start. */
179
- interface PptxSetBehavior extends BehaviorBase {
180
- kind: 'set';
181
- value: string | number | boolean;
182
- }
183
- /** `p:anim`: a `p:tavLst` ramp or a `from`/`to`/`by` formula ramp. */
184
- interface PptxAnimBehavior extends BehaviorBase {
185
- kind: 'anim';
186
- calcMode?: 'discrete' | 'lin' | 'fmla';
187
- valueType?: string;
188
- from?: string;
189
- to?: string;
190
- by?: string;
191
- keyframes: PptxAnimationKeyframe[];
192
- }
193
- /** `p:animEffect`: a filter transition (`fade`, `wipe(down)`...). */
194
- interface PptxAnimEffectBehavior extends BehaviorBase {
195
- kind: 'animEffect';
196
- filter?: string;
197
- transition?: 'in' | 'out' | 'none';
198
- }
199
- /** A `p:animScale` factor pair (1 = unscaled) or a `p:animMotion` offset (slide fractions). */
200
- interface PptxBehaviorPoint {
201
- x: number;
202
- y: number;
203
- }
204
- /** `p:animScale`: scale factors as fractions (OOXML stores percent*1000, so `100000` = 1). */
205
- interface PptxAnimScaleBehavior extends BehaviorBase {
206
- kind: 'animScale';
207
- from?: PptxBehaviorPoint;
208
- to?: PptxBehaviorPoint;
209
- by?: PptxBehaviorPoint;
210
- zoomContents?: boolean;
211
- }
212
- /** `p:animRot`: rotation in degrees (OOXML stores 60000ths). */
213
- interface PptxAnimRotBehavior extends BehaviorBase {
214
- kind: 'animRot';
215
- from?: number;
216
- to?: number;
217
- by?: number;
218
- }
219
- /** `p:animMotion`: a path (slide fractions) or a `from`/`to`/`by` offset. */
220
- interface PptxAnimMotionBehavior extends BehaviorBase {
221
- kind: 'animMotion';
222
- path?: string;
223
- origin?: string;
224
- from?: PptxBehaviorPoint;
225
- to?: PptxBehaviorPoint;
226
- by?: PptxBehaviorPoint;
227
- }
228
- /** One behaviour child of an effect, tagged by its OOXML element. */
229
- type PptxAnimationBehavior = PptxSetBehavior | PptxAnimBehavior | PptxAnimEffectBehavior | PptxAnimScaleBehavior | PptxAnimRotBehavior | PptxAnimMotionBehavior;
230
- /**
231
- * Built-in animation preset names used for entrance, exit, and emphasis effects.
232
- *
233
- * @example
234
- * ```ts
235
- * const preset: PptxAnimationPreset = "fadeIn";
236
- * // => "fadeIn" — one of: none | fadeIn | flyIn | zoomIn | fadeOut | flyOut | zoomOut | spin | pulse | ...
237
- * ```
238
- */
239
- type PptxAnimationPreset = 'none' | 'appear' | 'fadeIn' | 'flyIn' | 'zoomIn' | 'bounceIn' | 'wipeIn' | 'splitIn' | 'dissolveIn' | 'wheelIn' | 'blindsIn' | 'boxIn' | 'floatIn' | 'riseUp' | 'swivel' | 'expandIn' | 'checkerboardIn' | 'flashIn' | 'peekIn' | 'randomBarsIn' | 'spinnerIn' | 'growTurnIn' | 'fadeOut' | 'flyOut' | 'zoomOut' | 'bounceOut' | 'wipeOut' | 'shrinkOut' | 'dissolveOut' | 'disappear' | 'spin' | 'pulse' | 'colorWave' | 'bounce' | 'flash' | 'growShrink' | 'teeter' | 'transparency' | 'boldFlash' | 'wave';
240
- /** Animation timing curve. */
241
- type PptxAnimationTimingCurve = 'ease' | 'ease-in' | 'ease-out' | 'linear';
242
- /** Repeat mode for animations. */
243
- type PptxAnimationRepeatMode = 'untilNextClick' | 'untilEndOfSlide';
244
- /** Animation trigger type from OOXML `p:cTn`. */
245
- type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevious' | 'withPrevious' | 'afterDelay' |
246
- /**
247
- * Starts when a media element's playback reaches a named bookmark
248
- * (PowerPoint's "Trigger > On Bookmark"). The media element is
249
- * {@link PptxElementAnimation.triggerShapeId} and the bookmark
250
- * {@link PptxElementAnimation.triggerBookmark}; saved as an interactive
251
- * sequence gated on `p:cond evt="onMediaBookmark"` with a `p14:bmkTgt`.
252
- */
253
- 'onMediaBookmark';
254
- /**
255
- * Native animation kind. The historic shape-targeted preset animations are
256
- * implicitly the default kind (`undefined`). Media animations (`p:audio`,
257
- * `p:video`) emit dedicated entries so playback order on the slide timeline
258
- * is preserved alongside other animations.
259
- */
260
- type PptxNativeAnimationKind = 'media';
261
- /**
262
- * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34):
263
- * identifies exactly which series/category/element of a chart or diagram
264
- * build a per-stage effect reveals, when a deck authors one effect per stage
265
- * instead of a single staged `p:bldGraphic` reveal.
266
- */
267
- interface PptxAnimationGraphicElementTarget {
268
- /** Which graphic kind: `p:dgm` (diagram) or `p:chart`. */
269
- kind: 'dgm' | 'chart';
270
- /** `@_seriesIdx`, 0-based series index, when the target is series-scoped. */
271
- seriesIdx?: number;
272
- /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */
273
- categoryIdx?: number;
274
- /**
275
- * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL
276
- * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a
277
- * `p:bldDgm` build authors one effect per node instead of a single staged
278
- * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this.
279
- * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a
280
- * diagram renderer can reveal the exact authored node.
281
- */
282
- id?: string;
283
- /**
284
- * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` /
285
- * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep`
286
- * (`sp` / `bg`) for a `dgm`-kind target.
287
- */
288
- bldStep?: string;
289
- }
290
- /**
291
- * `p:spTgt/p:oleChartEl` (CT_TLOleChartTargetElement, ECMA-376 S19.5.44):
292
- * legacy pre-DrawingML OLE Graph chart sub-element targeting.
293
- */
294
- interface PptxAnimationOleChartElementTarget {
295
- /** `@_type` (ST_TLOleChartSubelementType): entireChart / series / category / ... */
296
- subelementType: string;
297
- /** `@_lvl`, optional sub-element level. */
298
- level?: number;
299
- }
300
- /** A target selected by `p:tgtEl` in the PresentationML timing model. */
301
- type PptxAnimationTarget = {
302
- type: 'shape';
303
- shapeId: string;
304
- /** Whether `p:spTgt/p:bg` limits the effect to the shape background. */
305
- backgroundOnly?: boolean;
306
- /**
307
- * `p:spTgt/p:subSp/@_spid`: the id of a shape NESTED inside the group
308
- * named by {@link shapeId} (CT_TLSubShapeId, ECMA-376 S19.5.71).
309
- * PowerPoint authors this when a user animates one member of a group
310
- * without ungrouping it: `shapeId` stays the outer group's id for
311
- * round-trip, but this sub-shape is the real playback target.
312
- */
313
- subShapeId?: string;
314
- /** `p:spTgt/p:graphicEl`: chart/diagram series/category/element target. */
315
- graphicElement?: PptxAnimationGraphicElementTarget;
316
- /** `p:spTgt/p:oleChartEl`: legacy OLE chart sub-element target. */
317
- oleChartElement?: PptxAnimationOleChartElementTarget;
318
- rawXml?: XmlObject;
319
- } | {
320
- type: 'slide';
321
- rawXml?: XmlObject;
322
- } | {
323
- type: 'sound';
324
- relationshipId: string;
325
- name?: string;
326
- rawXml?: XmlObject;
327
- } | {
328
- type: 'ink';
329
- shapeId: string;
330
- rawXml?: XmlObject;
331
- } | {
332
- type: 'unknown';
333
- rawXml: XmlObject;
334
- };
335
- /** Nested build choice carried by `p:bldGraphic`. */
336
- type PptxGraphicBuild = {
337
- mode: 'asOne';
338
- rawXml?: XmlObject;
339
- } | {
340
- mode: 'sub';
341
- kind: 'diagram';
342
- build: string;
343
- reverse: boolean;
344
- rawXml?: XmlObject;
345
- } | {
346
- mode: 'sub';
347
- kind: 'chart';
348
- build: string;
349
- animateBackground: boolean;
350
- rawXml?: XmlObject;
351
- };
352
- /**
353
- * A single `p:tmpl` timing template parsed from a TEXT `p:bldP/p:tmplLst`
354
- * (CT_TLTemplate, ECMA-376 §19.5.85; the list itself is CT_TLTemplateList,
355
- * §19.5.84).
356
- *
357
- * PowerPoint writes these as the timing PowerPoint would apply to a build
358
- * level that does not yet have an instantiated effect, so that promoting or
359
- * demoting an outline paragraph, or adding a new bullet at a level with no
360
- * prior animation, has a default to clone. They are not consulted at
361
- * playback: the animation actually shown for every paragraph level already
362
- * visible on the slide is the real, instantiated `p:tnLst` under
363
- * `p:timing/p:tnLst`, which the rest of this parser already models in full.
364
- *
365
- * The nested time-node tree under each template's own `p:tnLst` is kept as
366
- * a preserved `XmlObject` rather than deep-parsed into
367
- * {@link PptxNativeAnimation} records: it is schema-identical to the
368
- * top-level timing tree but scoped to a template that is never itself
369
- * executed, so structurally modelling it would stand up a second, unused
370
- * parallel animation model. Parsing stops at typed round-trip; see
371
- * `docs/guide/limitations.md`.
372
- */
373
- interface PptxTimingTemplate {
374
- /** Build level this template targets, from `p:tmpl/@lvl` (ST_TLLevel, default 0). */
375
- level: number;
376
- /** Preserved `p:tnLst` (CT_TimeNodeList) subtree, verbatim. */
377
- timeNodeList: XmlObject;
378
- /** Preserved `p:tmpl` XML node (its attributes plus any unmodelled children). */
379
- rawXml?: XmlObject;
380
- }
381
- /**
382
- * Parsed native animation record from `p:timing / p:tnLst`.
383
- *
384
- * Represents a single animation node in the OOXML timing tree,
385
- * including motion paths, scale transforms, and text build settings.
386
- *
387
- * @example
388
- * ```ts
389
- * const anim: PptxNativeAnimation = {
390
- * targetId: "shape_1",
391
- * presetClass: "entr",
392
- * presetId: 10,
393
- * trigger: "afterPrevious",
394
- * durationMs: 500,
395
- * };
396
- * // => { targetId: "shape_1", presetClass: "entr", presetId: 10, trigger: "afterPrevious", durationMs: 500 }
397
- * ```
398
- */
399
- interface PptxNativeAnimation {
400
- /** Target element/shape ID. */
401
- targetId?: string;
402
- /** Full timing target, including sound and ink target variants. */
403
- target?: PptxAnimationTarget;
404
- /** Trigger type. */
405
- trigger?: PptxAnimationTrigger;
406
- /**
407
- * Shape ID that triggers this animation: the clicked shape of an
408
- * interactive sequence, or the media element of an `onMediaBookmark` one.
409
- */
410
- triggerShapeId?: string;
411
- /** Bookmark name an `onMediaBookmark` interactive sequence waits for. */
412
- triggerBookmark?: string;
413
- /** Whether this effect belongs to an OOXML `interactiveSeq`. */
414
- interactiveSequence?: boolean;
415
- /** Whether `p:endSync/p:rtn[@val="all"]` makes that sequence replayable. */
416
- interactiveRestart?: boolean;
417
- /** Effect preset class (entr, exit, emph, path). */
418
- presetClass?: 'entr' | 'exit' | 'emph' | 'path';
419
- /** Effect preset sub-type identifier. */
420
- presetId?: number;
421
- /**
422
- * Effect preset direction/variant code from `p:cTn/@presetSubtype`
423
- * (ECMA-376 CT_TLCommonTimeNodeData). For Fly In/Out this encodes the
424
- * edge/corner the object travels from as a bitmask (1=top, 2=right,
425
- * 4=bottom, 8=left; corners combine bits). Absent means the preset default.
426
- */
427
- presetSubtype?: number;
428
- /** Duration in milliseconds. */
429
- durationMs?: number;
430
- /** Delay in milliseconds. */
431
- delayMs?: number;
432
- /**
433
- * Acceleration fraction in the range 0..1, parsed from `p:cTn/@accel`
434
- * (ST_PositiveFixedPercentage, stored as 1000ths of a percent). A non-zero
435
- * value means the effect eases in (starts slow). Absent means no easing-in.
436
- */
437
- accel?: number;
438
- /**
439
- * Deceleration fraction in the range 0..1, parsed from `p:cTn/@decel`.
440
- * A non-zero value means the effect eases out (ends slow). Absent means no
441
- * easing-out. When both {@link accel} and {@link decel} are set, the effect
442
- * eases in and out.
443
- */
444
- decel?: number;
445
- /** Trigger delay in milliseconds (for afterDelay). */
446
- triggerDelayMs?: number;
447
- /** SVG path string for motion path animations (`p:animMotion/@path`). */
448
- motionPath?: string;
449
- /** Motion origin: "layout" or "parent". */
450
- motionOrigin?: string;
451
- /**
452
- * Whether the element auto-rotates to follow the motion path tangent.
453
- * Viewer-authoring-only hint: OOXML has no such flag (`p:animMotion/@rAng`
454
- * is a plain rotation angle that PowerPoint writes as "0" on every path),
455
- * so the parser never sets this.
456
- */
457
- motionPathRotateAuto?: boolean;
458
- /** Path edit mode from `p:animMotion/@pathEditMode` (e.g. "relative", "fixed"). */
459
- motionPathEditMode?: string;
460
- /** Comma-separated point-types string from `p:animMotion/@ptsTypes`. */
461
- motionPtsTypes?: string;
462
- /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
463
- motionPathRotationAngle?: number;
464
- /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
465
- motionPathRotationCenterX?: number;
466
- /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
467
- motionPathRotationCenterY?: number;
468
- /** Rotation angle in degrees for `p:animRot/@by` (converted from 60000ths). */
469
- rotationBy?: number;
470
- /** Starting rotation angle in degrees for `p:animRot/@from` (converted from 60000ths). */
471
- rotationFrom?: number;
472
- /** Ending rotation angle in degrees for `p:animRot/@to` (converted from 60000ths). */
473
- rotationTo?: number;
474
- /** X scale factor (percentage / 100) for `p:animScale/p:by/@x`. */
475
- scaleByX?: number;
476
- /** Y scale factor (percentage / 100) for `p:animScale/p:by/@y`. */
477
- scaleByY?: number;
478
- /** Starting X scale factor for `p:animScale/p:from/@x`. */
479
- scaleFromX?: number;
480
- /** Starting Y scale factor for `p:animScale/p:from/@y`. */
481
- scaleFromY?: number;
482
- /** Ending X scale factor for `p:animScale/p:to/@x`. */
483
- scaleToX?: number;
484
- /** Ending Y scale factor for `p:animScale/p:to/@y`. */
485
- scaleToY?: number;
486
- /** Whether `p:animScale/@zoomContents` was set ("1"/"true"). */
487
- scaleZoomContents?: boolean;
488
- /** Parsed `p:tav` keyframes from `p:tavLst` (CT_TLAnimVariantList). */
489
- keyframes?: PptxAnimationKeyframe[];
490
- /**
491
- * The attribute {@link keyframes} drives, from the SAME node's
492
- * `p:cBhvr/p:attrNameLst/p:attrName` (ECMA-376 S19.5.4). `p:tavLst` is
493
- * schema-generic: without this, playback could see a numeric ramp but not
494
- * know whether it targeted opacity, position, colour, or something with
495
- * no CSS mapping. Lowercased and trimmed; common values seen in the wild
496
- * (and written by this codebase's own animation writer) include
497
- * `"style.opacity"`, `"style.color"`, `"style.visibility"`, `"fillcolor"`,
498
- * `"stroke.color"`, `"r"` (rotation, only meaningful on `p:animRot`), and
499
- * `"ppt_x"` / `"ppt_y"` (position, normally driven via `p:animMotion`
500
- * instead). Absent when the behaviour carries no `p:attrNameLst`.
501
- */
502
- attrName?: string;
503
- /** Every generic `p:anim` sibling composed by the authored effect. */
504
- attributeAnimations?: PptxAttributeAnimation[];
505
- /** Repeat count (e.g. `2`, `Infinity` for indefinite). */
506
- repeatCount?: number;
507
- /** Whether the animation plays in reverse after completion. */
508
- autoReverse?: boolean;
509
- /** Text build type from `p:bldP/@build` in `p:bldLst`. */
510
- buildType?: PptxTextBuildType;
511
- /** Build level for multi-level lists from `p:bldP/@bldLvl`. */
512
- buildLevel?: number;
513
- /** Group ID linking a `p:bldP` entry to its timing animation node. */
514
- groupId?: string;
515
- /**
516
- * Sound relationship ID to play when animation triggers. Modern PowerPoint
517
- * (COM-verified against 2016) writes this as a `p:audio/p:cMediaNode`
518
- * sibling of the effect's own `p:childTnLst`, targeting `p:sndTgt` rather
519
- * than a shape; the legacy `p:stSnd` form (directly on `p:cTn`) is still
520
- * accepted on load for round-trip of older-authored decks, but PowerPoint
521
- * itself no longer writes it and does not recognise it back
522
- * (`Effect.EffectInformation.SoundEffect` reads empty against it).
523
- */
524
- soundRId?: string;
525
- /** Resolved sound file path from relationship. */
526
- soundPath?: string;
527
- /**
528
- * The embedded sound's `@_name` (from `p:snd`/`p:sndTgt`). For one of
529
- * PowerPoint's 19 built-in stock sounds this is the exact upper-case file
530
- * name PowerPoint itself writes (e.g. `"CHIMES.WAV"`); see
531
- * `pptx-viewer-shared`'s `effect-sound-catalogue.ts`, which matches this
532
- * value back to a gallery entry. Absent for a custom sound with no name,
533
- * or when unresolved.
534
- */
535
- soundName?: string;
536
- /** Whether to stop any currently playing sound (`p:endSnd`). */
537
- stopSound?: boolean;
538
- /**
539
- * End-state behaviour from `p:cTn/@fill` (ST_TLTimeNodeFillType, ECMA-376
540
- * §19.5.27). `hold`/`freeze` mean the effect's final frame persists after
541
- * it finishes; `remove` (the default when absent) means the target reverts
542
- * to its pre-effect appearance. `transition` behaves like `hold` until the
543
- * next time node starts. Absent means the OOXML default (`remove`).
544
- */
545
- fill?: 'remove' | 'freeze' | 'hold' | 'transition';
546
- /**
547
- * Restart behaviour from `p:cTn/@restart` (ST_TLTimeNodeRestartType).
548
- * Absent means the OOXML default (`always`).
549
- */
550
- restart?: 'always' | 'whenNotActive' | 'never';
551
- /**
552
- * Repeat duration in milliseconds from `p:cTn/@repeatDur`. `Infinity`
553
- * represents the literal `"indefinite"` token.
554
- */
555
- repeatDurMs?: number;
556
- /**
557
- * Playback speed multiplier from `p:cTn/@spd` (ST_Percentage, normalized
558
- * from OOXML's 1000ths-of-a-percent storage to a plain percentage, e.g.
559
- * `150` for 150% / double speed). Absent means normal (100%) speed.
560
- */
561
- speedPct?: number;
562
- /**
563
- * Reverse the paragraph build order from `p:bldP/@rev` (TEXT build only).
564
- * Not to be confused with {@link PptxGraphicBuild}'s `reverse` field, which
565
- * carries the unrelated `p:bldDgm`/`@rev` DIAGRAM-build reverse flag.
566
- */
567
- buildReverse?: boolean;
568
- /**
569
- * Auto-advance time in milliseconds from `p:bldP/@advAuto`. `Infinity`
570
- * represents the literal `"indefinite"` token. Absent means the build
571
- * step waits for a click.
572
- */
573
- buildAdvAutoMs?: number;
574
- /**
575
- * Per-build-level timing templates from a TEXT `p:bldP/p:tmplLst`
576
- * (ECMA-376 §19.5.84 CT_TLTemplateList). Parsed for round-trip only; see
577
- * {@link PptxTimingTemplate} for why they are not consulted at playback.
578
- */
579
- buildTemplates?: PptxTimingTemplate[];
580
- /**
581
- * Whether the enclosing `p:seq` allows concurrent play with its siblings,
582
- * from `p:seq/@concurrent`. Parsed for round-trip; not yet honoured by
583
- * playback (see `docs/guide/limitations.md`).
584
- */
585
- seqConcurrent?: boolean;
586
- /** Next-action behaviour from `p:seq/@nextAc` (ST_TLNextActionType). */
587
- seqNextAction?: 'none' | 'seek';
588
- /** Previous-action behaviour from `p:seq/@prevAc` (ST_TLPreviousActionType). */
589
- seqPrevAction?: 'none' | 'skipTimeNode';
590
- /**
591
- * Whether the enclosing click-level group (a direct `p:par` child of the
592
- * `mainSeq`) begins automatically when the slide appears, rather than waiting
593
- * for a click.
594
- *
595
- * PowerPoint gates a click step with a lone `<p:cond delay="indefinite"/>`;
596
- * a group that also carries a time-node condition (`onBegin`/`onEnd` with a
597
- * `@tn`) or a finite delay starts on slide entry ("With/After Previous" as the
598
- * first effect on the slide). The flat animation list cannot express that on
599
- * its own, so the parse layer stamps it here.
600
- */
601
- groupAutoStart?: boolean;
602
- /**
603
- * Index of the enclosing effect-wrapper `p:par` inside the click-level group.
604
- *
605
- * Effects that share a wrapper are OOXML siblings: they all start when that
606
- * wrapper starts, and each `p:cond/@delay` is measured from the wrapper's
607
- * start, NOT chained off the effect before it. Playback uses this to place
608
- * simultaneous effects at their true offsets instead of accumulating delays.
609
- */
610
- parGroupIndex?: number;
611
- /**
612
- * Absolute start offset of the enclosing effect-wrapper from its click group.
613
- *
614
- * Structural `p:par` wrappers can carry their own start conditions. Keeping
615
- * this offset separate from the effect's delay prevents playback from
616
- * replacing an authored absolute start with a duration-based approximation.
617
- */
618
- parGroupDelayMs?: number;
619
- /** Structured start conditions parsed from `p:stCondLst`. */
620
- startConditions?: AnimationCondition[];
621
- /** Structured end conditions parsed from `p:endCondLst`. */
622
- endConditions?: AnimationCondition[];
623
- /** Preserved raw `p:endCondLst` XML node for lossless round-trip. */
624
- rawEndCondLst?: XmlObject;
625
- /** Color animation data from `p:animClr`. */
626
- colorAnimation?: PptxColorAnimation;
627
- /** Text-level target: character range or paragraph range from `p:txEl`. */
628
- textTarget?: PptxTextAnimationTarget;
629
- /** Whether this animation is inside an exclusive container (`p:excl`). */
630
- exclusive?: boolean;
631
- /**
632
- * Identifies which `p:excl` container this animation belongs to, when
633
- * {@link exclusive} is set. ECMA-376 S19.5.24 CT_TLExclusiveTimeNode: at
634
- * most one direct child of an exclusive container may be active at a
635
- * time, so starting one child stops any other currently-playing child of
636
- * the SAME container. Two different `p:excl` containers on the same slide
637
- * are independent groups; this id (assigned per container encountered
638
- * during parsing, stable only within one parse's animation list) lets
639
- * playback tell them apart. Absent when {@link exclusive} is unset.
640
- */
641
- exclGroupId?: number;
642
- /** Command type from `p:cmd` (@_type: call/evt/verb). */
643
- commandType?: string;
644
- /** Command string from `p:cmd` (@_cmd). */
645
- commandString?: string;
646
- /** Iteration configuration from `p:iterate`. */
647
- iterate?: PptxAnimationIterate;
648
- /**
649
- * Discriminator for non-preset animation kinds. When `undefined`, the
650
- * entry represents the default shape-effect animation. The `'media'`
651
- * kind represents a `p:audio` / `p:video` timing node, captured here so
652
- * playback order in the timeline is preserved alongside other animations.
653
- */
654
- kind?: PptxNativeAnimationKind;
655
- /**
656
- * For `kind === 'media'`, identifies whether this is an audio or video
657
- * media node so writers know which OOXML element to re-emit.
658
- */
659
- mediaType?: 'audio' | 'video';
660
- /**
661
- * SmartArt build attribute (`p:bldDgm/@bld`) when this animation is
662
- * associated with a SmartArt diagram build. Common values include
663
- * `whole`, `one`, `lvlOne`, `lvlAtOnce`.
664
- */
665
- smartArtBuild?: string;
666
- /**
667
- * Graphic-frame build attribute (`p:bldGraphic/@bld`) when this animation
668
- * is associated with a generic graphic frame build (charts, tables, etc.
669
- * that aren't OLE charts).
670
- */
671
- graphicBuild?: string;
672
- /**
673
- * OLE-embedded chart build attribute (`p:bldOleChart/@bld`) when this
674
- * animation stages an OLE chart graphic frame. Values follow
675
- * ST_TLOleChartBuildType: `allAtOnce`, `series`, `category`, `seriesEl`,
676
- * `categoryEl`. Lets a staged-reveal renderer build the chart by series /
677
- * category / element to match PowerPoint, rather than as one whole element.
678
- */
679
- oleChartBuild?: string;
680
- /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */
681
- graphicBuildProperties?: PptxGraphicBuild;
682
- /**
683
- * Opaque map of `p:cTn` attributes that don't have a typed home on this
684
- * interface but must round-trip through parse → save. Keys are stored
685
- * verbatim including the `@_` prefix used by the underlying XML parser
686
- * (e.g. `@_evtFilter`, `@_display`, `@_masterRel`, `@_nodePh`,
687
- * `@_endSync`, `@_progress`). The `subTnLst` child element is also
688
- * preserved here under the literal key `p:subTnLst`. The `afterEffect`
689
- * attribute is surfaced separately as a typed boolean ({@link afterEffect})
690
- * because it changes write semantics for subsequent timing nodes.
691
- */
692
- cTnAttributes?: Record<string, unknown>;
693
- /** Parent timing cannot be reduced to the bounded fixed-opacity interval. */
694
- unsupportedOpacitySetTiming?: boolean;
695
- /** Admitted isolated held whole-shape visibility flip from native preset zero. */
696
- visibilitySetTiming?: PptxVisibilitySetTiming;
697
- /** A retained preset-zero visibility body has an unmeasured target, value or clock. */
698
- unsupportedVisibilitySet?: boolean;
699
- /**
700
- * Whether the OOXML `p:cTn/@afterEffect` flag is set. Indicates this node
701
- * runs after the parent effect's main body has completed; affects how
702
- * subsequent peer nodes are sequenced when serialised back to OOXML.
703
- */
704
- afterEffect?: boolean;
705
- /**
706
- * "After animation" end-state behaviour: dim-to-colour, hide-after-
707
- * animation, or hide-on-next-click. Populated directly by the
708
- * native-timing parser (`native-animation-after-effect.ts`) when the
709
- * effect's `p:cTn/p:subTnLst` carries PowerPoint's genuine after-effect
710
- * shape, so a real-world deck's build shows up here even with no
711
- * `pptx:editorMeta`. `applyAfterAnimationFromEditorList` in
712
- * `pptx-viewer-shared` overrides this from the matching
713
- * {@link PptxElementAnimation.afterAnimation} entry when the editor's
714
- * per-element animation list has one (the model the animation panel
715
- * writes `afterAnimation` into), so an edit through our own UI always wins.
716
- */
717
- afterAnimationAction?: PptxAfterAnimationAction;
718
- /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor` AND the dim target is an already-resolved `a:srgbClr`. */
719
- afterAnimationColor?: string;
720
- /**
721
- * The typed theme reference when a `dimToColor` target is an `a:schemeClr`
722
- * (e.g. `accent2`) instead of `a:srgbClr`: this parse layer has no theme to
723
- * resolve it to sRGB with (see {@link afterAnimationColor}'s doc), so a
724
- * playback consumer resolves this against the deck's theme colour map.
725
- * Mutually exclusive with {@link afterAnimationColor} being set.
726
- */
727
- afterAnimationColorRef?: PptxThemeColorRef;
728
- /**
729
- * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain
730
- * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`);
731
- * this is the fallback used when a preset table lookup misses (unmapped or
732
- * absent `presetId`), which happens for decks authored by tools other than
733
- * PowerPoint that only emit the SMIL-style filter string.
734
- */
735
- effectFilter?: PptxAnimationEffectFilter;
736
- /**
737
- * This effect's own `p:cTn/@_id` (a raw OOXML time-node id, not a shape
738
- * id). Lets playback resolve a `p:cond/@tn` dependency (see
739
- * {@link AnimationCondition.targetTimeNodeId}) against the SPECIFIC node
740
- * it names rather than assuming it is always the positionally-previous
741
- * effect. Absent when the node carried no `@_id`.
742
- */
743
- nodeId?: number;
744
- /**
745
- * Interpolation mode for this effect's PRIMARY `p:anim`-family behaviour
746
- * (the same node {@link keyframes}/{@link attrName} were read from), from
747
- * `@_calcmode` (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2). See
748
- * {@link PptxAttributeAnimation.calcMode} for the per-component version.
749
- */
750
- calcMode?: 'discrete' | 'lin' | 'fmla';
751
- /**
752
- * `p:cBhvr/@_additive` (ST_TLBehaviorAdditiveType, ECMA-376 S19.5.4):
753
- * controls how this behaviour's value composites with sibling behaviours
754
- * driving the same attribute on the same target. `sum` accumulates
755
- * (e.g. a combined scale+rotate), `repl`/`base`/`none`/`mult` replace or
756
- * otherwise combine. Absent means the OOXML default (`base`).
757
- */
758
- cBhvrAdditive?: 'base' | 'sum' | 'repl' | 'mult' | 'none';
759
- /**
760
- * `p:cBhvr/@_accumulate` (ST_TLBehaviorAccumulateType): `always` means
761
- * each `p:cTn/@repeatCount` repeat starts from the PREVIOUS repeat's end
762
- * value (e.g. a 3x Spin totals 1080deg instead of replaying 0-360 three
763
- * times); `none` (the OOXML default) resets every repeat.
764
- */
765
- cBhvrAccumulate?: 'none' | 'always';
766
- /**
767
- * `p:cBhvr/@_xfrmType` (only meaningful on `p:animMotion`): `point`
768
- * (default) or `img`, a legacy compatibility hint. Round-tripped only.
769
- */
770
- cBhvrXfrmType?: 'point' | 'img';
771
- /**
772
- * `p:cBhvr/@_override` (ST_TLBehaviorOverrideType): `normal` (default) or
773
- * `childStyle`, a legacy compatibility hint. Round-tripped only.
774
- */
775
- cBhvrOverride?: 'normal' | 'childStyle';
776
- /**
777
- * `p:set` discrete attribute assignments composed alongside this effect
778
- * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated)
779
- * value change, as opposed to {@link attributeAnimations}'s `p:anim`
780
- * keyframe ramps. PowerPoint authors several font-style emphasis effects
781
- * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since
782
- * "on/off" or "size N" has nothing to interpolate. Not yet consulted by
783
- * shared playback (round-trip/typed-model only so far).
784
- */
785
- setAnimations?: PptxSetAnimation[];
786
- /**
787
- * Every behaviour child of this effect (`p:set`, `p:anim`, `p:animEffect`,
788
- * `p:animScale`, `p:animRot`, `p:animMotion`) with its own timing, as
789
- * authored. The single-valued fields above flatten a composed preset;
790
- * this keeps the whole tree so playback can follow what PowerPoint wrote
791
- * (see `animation-behavior-player` in `pptx-viewer-shared`).
792
- */
793
- behaviors?: PptxAnimationBehavior[];
794
- }
795
- /**
796
- * One `p:set` discrete (non-interpolated) attribute assignment composed
797
- * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}.
798
- *
799
- * @see ECMA-376 S19.5.79 CT_TLSetBehavior
800
- */
801
- interface PptxSetAnimation {
802
- /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */
803
- attrName: string;
804
- /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */
805
- value: string | boolean | number;
806
- /** Discriminant indicating which `p:to` child carried the value. */
807
- valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
808
- /** Duration from this behaviour's nested `p:cTn/@dur`. */
809
- durationMs?: number;
810
- /** Start offset from this behaviour's nested `p:stCondLst`. */
811
- delayMs?: number;
812
- }
813
- /**
814
- * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
815
- * describes `@filter` as a free-form string of the form `family(subtype)`,
816
- * optionally followed by `;`-separated fallback candidates (only the first
817
- * is honoured, per ECMA-376 S19.5.3's "first supported filter wins" rule).
818
- *
819
- * @example
820
- * ```ts
821
- * const f: PptxAnimationEffectFilter = { family: 'wipe', subtype: 'up', transition: 'in', raw: 'wipe(up)' };
822
- * ```
823
- */
824
- interface PptxAnimationEffectFilter {
825
- /** Filter family name (e.g. `"wipe"`, `"barn"`, `"checkerboard"`), lowercased. */
826
- family: string;
827
- /**
828
- * Parenthesised subtype/direction token verbatim (e.g. `"up"`,
829
- * `"inVertical"`, `"across"`, `"4"`). Absent when the filter has no
830
- * subtype (e.g. bare `"dissolve"`).
831
- */
832
- subtype?: string;
833
- /**
834
- * `p:animEffect/@transition`: `"in"` reveals the target (the OOXML
835
- * default when the attribute is omitted), `"out"` conceals it, `"none"`
836
- * applies the filter without a visibility change (a static filter pass).
837
- */
838
- transition?: 'in' | 'out' | 'none';
839
- /** Raw filter string exactly as authored, for round-trip/debugging. */
840
- raw: string;
841
- }
842
- /**
843
- * Single keyframe parsed from a `p:tav` element (CT_TLTimeAnimateValue).
844
- *
845
- * Each entry in a `p:tavLst` has a time fraction (`@_tm`, in 1000ths of the
846
- * total duration; or the literal "indefinite" / "large") and a typed value
847
- * child under `p:val/p:strVal|p:boolVal|p:intVal|p:fltVal|p:clrVal`.
848
- *
849
- * @see ECMA-376 §19.5.30 CT_TLAnimVariantList / §19.5.92 CT_TLTimeAnimateValue
850
- */
851
- interface PptxAnimationKeyframe {
852
- /**
853
- * Time fraction. A finite number is the OOXML `@_tm` integer (0–100000
854
- * for percentage, where 100000 = 100% of duration). A string preserves
855
- * special tokens ("indefinite", "large").
856
- */
857
- tm: number | string;
858
- /** Decoded keyframe value. */
859
- value: string | boolean | number;
860
- /** Discriminant indicating which `p:val` child carried the value. */
861
- valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
862
- /**
863
- * Optional formula carried on `p:tav/@_fmla`. Preserved for round-trip
864
- * fidelity; consumers may use it to drive computed animation values.
865
- */
866
- fmla?: string;
867
- /**
868
- * The typed theme reference when a `p:val/p:clrVal` stop is an
869
- * `a:schemeClr` (e.g. `accent1`), including any `tint`/`shade`/`lumMod`/
870
- * `lumOff`/`alpha` children. {@link value} keeps the bare scheme name for
871
- * round-trip; a playback consumer needs this ref (resolved against the
872
- * deck's theme colour map) to turn the stop into a real CSS colour, which
873
- * the bare name alone cannot do. Absent for an `a:srgbClr` stop, whose
874
- * {@link value} is already a resolved `#rrggbb` hex string.
875
- */
876
- colorRef?: PptxThemeColorRef;
877
- }
878
- /** One generic `p:anim` behaviour inside a composed PowerPoint effect. */
879
- interface PptxAttributeAnimation {
880
- /** Lowercased target attribute from `p:attrNameLst`. */
881
- attrName: string;
882
- /**
883
- * Authored value stops from this behaviour's `p:tavLst`. Empty when the
884
- * behaviour instead uses the simpler `from`/`to`/`by` attribute form (see
885
- * below); at least one of `keyframes`, `from`/`to`, or `by` is present.
886
- */
887
- keyframes: PptxAnimationKeyframe[];
888
- /**
889
- * `p:anim/@_from` (a formula string, ECMA-376 S19.5.4 CT_TLAnimateBehavior):
890
- * the absolute starting value, used instead of `p:tavLst` when the
891
- * behaviour only has two endpoints. PowerPoint writes this form for some
892
- * built-in presets (e.g. "Grow And Turn"'s `ppt_x` fly-in): a bare
893
- * `p:anim from="..." to="..."` with no `p:tavLst` child at all. See
894
- * `animation-ppt-formula-ground-truth.md` in `pptx-viewer-shared` for the
895
- * real-PowerPoint sample this was found in.
896
- */
897
- from?: string;
898
- /** `p:anim/@_to`: the absolute ending value. See {@link from}. */
899
- to?: string;
900
- /**
901
- * `p:anim/@_by`: a DELTA formula added to wherever the attribute already
902
- * stands (as opposed to `from`/`to`'s absolute values), typically paired
903
- * with `p:cBhvr/@_additive="sum"` so it composites with a sibling
904
- * behaviour driving the same attribute instead of replacing it.
905
- */
906
- by?: string;
907
- /** Duration from this behaviour's nested `p:cTn/@dur`. */
908
- durationMs?: number;
909
- /** Start offset from this behaviour's nested `p:stCondLst`. */
910
- delayMs?: number;
911
- /**
912
- * Interpolation mode from this behaviour's own `@_calcmode`
913
- * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to
914
- * each `p:tav` stop with no interpolation, `lin` (the OOXML default)
915
- * interpolates linearly. `fmla` as the WHOLE behaviour's calc mode has
916
- * never been observed in a real PowerPoint file and is not consulted at
917
- * playback; what PowerPoint actually writes is `calcmode="lin"` with a
918
- * per-stop `p:tav/@fmla` (see {@link PptxAnimationKeyframe.fmla}), which
919
- * IS consulted regardless of this field's value. Absent means `lin`.
920
- */
921
- calcMode?: 'discrete' | 'lin' | 'fmla';
922
- /**
923
- * `p:anim/@_p14:bounceEnd` (Office 2010 `p14` extension attribute,
924
- * MS-OI29500), normalized to a 0-1 fraction of this behaviour's own
925
- * duration. PowerPoint's "Bounce End" effect option (COM:
926
- * `Effect.Timing.BounceEnd` + `BounceEndIntensity`) writes this on the
927
- * position-ramp `p:anim` node(s): the share of the duration spent
928
- * BOUNCING at the end. Measured from PowerPoint's own CreateVideo frames,
929
- * the travel completes at `1 - bounceEnd` and the rest is a damped
930
- * oscillation about the final value (see shared's `animation-bounce-end`).
931
- * Mirrored verbatim by PowerPoint onto the enclosing
932
- * `p:cTn/@_p14:presetBounceEnd`. Absent for every animation that doesn't
933
- * use this effect option (the overwhelming majority).
934
- */
935
- bounceEnd?: number;
936
- }
937
- /** Signed HSL channel deltas parsed from `p:animClr/p:by/p:hsl`. */
938
- interface PptxHslColorDelta {
939
- /** Hue offset in degrees. OOXML stores this in 60000ths of a degree. */
940
- hue: number;
941
- /** Saturation offset in percentage points. */
942
- saturation: number;
943
- /** Lightness offset in percentage points. */
944
- lightness: number;
945
- }
946
- /** Color animation data parsed from `p:animClr`. */
947
- interface PptxColorAnimation {
948
- /** Color interpolation space: "hsl" or "rgb". */
949
- colorSpace: 'hsl' | 'rgb';
950
- /** Direction for HSL interpolation: "cw" (clockwise) or "ccw". */
951
- direction?: 'cw' | 'ccw';
952
- /**
953
- * Optional `p:animClr/@path` value preserved for round-trip. When set,
954
- * the colour sweep follows a path-based interpolation rather than the
955
- * straight cw/ccw arc. ECMA-376 §19.5.13 documents this attribute as a
956
- * companion to `@dir` for HSL colour-space animations.
957
- */
958
- path?: string;
959
- /** Starting color as hex string, or the bare scheme name (e.g. `accent1`) for a theme colour; see {@link fromColorRef}. */
960
- fromColor?: string;
961
- /** Ending color as hex string, or the bare scheme name; see {@link toColorRef}. */
962
- toColor?: string;
963
- /**
964
- * Color delta (for "by" animations) as hex string, or the bare scheme name;
965
- * see {@link byColorRef}. For HSL colour-space animations this retains the
966
- * historical byte-packed compatibility value; consumers should prefer
967
- * {@link hslDelta}, which preserves signed values.
968
- */
969
- byColor?: string;
970
- /**
971
- * The typed theme reference when {@link fromColor} is an `a:schemeClr`
972
- * (including `tint`/`shade`/`lumMod`/`lumOff`/`alpha`), so playback can
973
- * resolve it against the deck's theme colour map. Absent when `fromColor`
974
- * is already a resolved `#rrggbb` hex (an `a:srgbClr` stop).
975
- */
976
- fromColorRef?: PptxThemeColorRef;
977
- /** The typed theme reference for {@link toColor}; see {@link fromColorRef}. */
978
- toColorRef?: PptxThemeColorRef;
979
- /**
980
- * The typed theme reference for {@link byColor} (RGB colour space only; an
981
- * HSL `by` is a signed delta, never a theme colour). See {@link fromColorRef}.
982
- */
983
- byColorRef?: PptxThemeColorRef;
984
- /**
985
- * Typed HSL delta from `p:by/p:hsl`. This preserves signed values and their
986
- * OOXML units without forcing them through the legacy byte-packed `byColor`
987
- * representation.
988
- */
989
- hslDelta?: PptxHslColorDelta;
990
- /**
991
- * Target attribute from `p:attrNameLst` (e.g. "fillcolor", "style.color",
992
- * "stroke.color"). Used to determine which CSS property to animate.
993
- */
994
- targetAttribute?: string;
995
- /**
996
- * All sibling `p:animClr` behaviours authored for the same timing node.
997
- * The top-level fields continue to mirror the first behaviour for backwards
998
- * compatibility; this list is present only when there is more than one.
999
- */
1000
- components?: readonly PptxColorAnimation[];
1001
- }
1002
- /** Text-level animation target from `p:txEl`. */
1003
- interface PptxTextAnimationTarget {
1004
- /** Target type: character range or paragraph range. */
1005
- type: 'charRg' | 'pRg';
1006
- /** Start index (0-based). */
1007
- start: number;
1008
- /** End index (exclusive). */
1009
- end: number;
1010
- }
1011
- /**
1012
- * Event types for animation conditions from `p:cond/@evt`.
1013
- *
1014
- * These map directly to OOXML condition event attribute values
1015
- * (ISO/IEC 29500-1 S19.5.28 CT_TLTimeCondition).
1016
- */
1017
- type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio' | 'onDblClick' | 'onMediaBookmark';
1018
- /**
1019
- * `p14:bmkTgt` (Office 2010 `p14` extension, MS-OI29500): names the specific
1020
- * media element and bookmark an `evt="onMediaBookmark"` condition fires for.
1021
- * `bookmarkName` matches a `p14:bmk/@_name` on that media element's own
1022
- * `p14:bmkLst` (see `MediaBookmark.label` in `core/types/elements.ts`).
1023
- */
1024
- interface PptxMediaBookmarkTarget {
1025
- /** `p14:bmkTgt/@_spid`: the media element's shape id. */
1026
- shapeId: string;
1027
- /** `p14:bmkTgt/@_bmkName`: the bookmark's name. */
1028
- bookmarkName: string;
1029
- }
1030
- /**
1031
- * Structured representation of a single OOXML animation condition
1032
- * from `p:cond` elements inside `p:stCondLst` or `p:endCondLst`.
1033
- *
1034
- * Conditions control when an animation starts or ends, and can reference
1035
- * events, time delays, and target time node IDs.
1036
- *
1037
- * @example
1038
- * ```ts
1039
- * const cond: AnimationCondition = {
1040
- * event: "onClick",
1041
- * delay: 0,
1042
- * targetShapeId: "shape_5",
1043
- * };
1044
- * ```
1045
- */
1046
- interface AnimationCondition {
1047
- /** Event that triggers the condition. */
1048
- event?: AnimationConditionEvent;
1049
- /**
1050
- * The media element/bookmark this condition fires for, when
1051
- * {@link event} is `onMediaBookmark`. See {@link PptxMediaBookmarkTarget}.
1052
- */
1053
- bookmarkTarget?: PptxMediaBookmarkTarget;
1054
- /** Delay in milliseconds (from `@_delay`). "indefinite" is represented as -1. */
1055
- delay?: number;
1056
- /** Target time node ID reference (from `@_tn`). */
1057
- targetTimeNodeId?: number;
1058
- /** Target shape ID from `p:tgtEl/p:spTgt/@spid`. */
1059
- targetShapeId?: string;
1060
- /** Whether the condition targets a slide (from `p:tgtEl/p:sldTgt`). */
1061
- targetSlide?: boolean;
1062
- /** Full target choice, including `p:sndTgt` and `p:inkTgt`. */
1063
- target?: PptxAnimationTarget;
1064
- }
1065
- /** Iteration configuration from `p:iterate`. */
1066
- interface PptxAnimationIterate {
1067
- /** Iteration type: el (element), lt (letter), wd (word). */
1068
- type: 'el' | 'lt' | 'wd';
1069
- /** Whether to iterate backwards. */
1070
- backwards?: boolean;
1071
- /** Timing interval (percentage of total duration, in 1000ths). */
1072
- tmPct?: number;
1073
- /** Absolute timing interval in ms. */
1074
- tmAbs?: number;
1075
- }
1076
- /** Build type for text build (paragraph/word/letter) animations from `p:bldP/@build`. */
1077
- type PptxTextBuildType = 'allAtOnce' | 'byParagraph' | 'byWord' | 'byChar';
1078
- /** Direction for fly-in / fly-out / wipe effects. */
1079
- type PptxAnimationDirection = 'fromLeft' | 'fromRight' | 'fromTop' | 'fromBottom' | 'fromTopLeft' | 'fromTopRight' | 'fromBottomLeft' | 'fromBottomRight';
1080
- /** Sequence mode for paragraph-level animations. */
1081
- type PptxAnimationSequence = 'asOne' | 'byParagraph' | 'byWord' | 'byLetter';
1082
- /** Behavior after animation finishes. */
1083
- type PptxAfterAnimationAction = 'none' | 'hideOnNextClick' | 'hideAfterAnimation' | 'dimToColor';
1084
- /**
1085
- * High-level animation data associated with a slide element.
1086
- *
1087
- * Combines entrance, exit, and emphasis presets with timing and
1088
- * trigger configuration. Used by the editor’s animation panel
1089
- * and the `setPptxElementAnimation` tool.
1090
- *
1091
- * @example
1092
- * ```ts
1093
- * const anim: PptxElementAnimation = {
1094
- * elementId: "title_1",
1095
- * entrance: "fadeIn",
1096
- * durationMs: 600,
1097
- * order: 1,
1098
- * trigger: "afterPrevious",
1099
- * };
1100
- * // => { elementId: "title_1", entrance: "fadeIn", durationMs: 600, order: 1, trigger: "afterPrevious" }
1101
- * ```
1102
- */
1103
- interface PptxElementAnimation {
1104
- elementId: string;
1105
- entrance?: PptxAnimationPreset;
1106
- exit?: PptxAnimationPreset;
1107
- emphasis?: PptxAnimationPreset;
1108
- durationMs?: number;
1109
- delayMs?: number;
1110
- order?: number;
1111
- /**
1112
- * The {@link order} the loader derived from the slide's `p:timing` tree for
1113
- * an entry whose `pptx:editorMeta` record authored no `@order`. The tree
1114
- * already expresses that position (and every load re-derives it), so the
1115
- * writer omits `@order` while `order` still equals this value; a reorder
1116
- * changes `order` and the attribute is written again. Load-time bookkeeping
1117
- * only; never set it by hand.
1118
- */
1119
- orderFromTimeline?: number;
1120
- trigger?: PptxAnimationTrigger;
1121
- /**
1122
- * Shape ID that triggers this animation: the shape clicked for
1123
- * `onShapeClick`, or the media element whose bookmark fires it for
1124
- * `onMediaBookmark`.
1125
- */
1126
- triggerShapeId?: string;
1127
- /** Bookmark name (`p14:bmk/@name`) an `onMediaBookmark` trigger waits for. */
1128
- triggerBookmark?: string;
1129
- timingCurve?: PptxAnimationTimingCurve;
1130
- repeatCount?: number;
1131
- repeatMode?: PptxAnimationRepeatMode;
1132
- /** Direction for directional effects (fly in/out, wipe, etc.). */
1133
- direction?: PptxAnimationDirection;
1134
- /** Sequence mode — animate as one object or by paragraph/word/letter. */
1135
- sequence?: PptxAnimationSequence;
1136
- /** What happens after the animation finishes playing. */
1137
- afterAnimation?: PptxAfterAnimationAction;
1138
- /** Dim-to color hex (used when afterAnimation is "dimToColor"). */
1139
- afterAnimationColor?: string;
1140
- /** Imported after-state for controls, not an authored override or serialized extension. */
1141
- nativeAfterAnimation?: PptxAfterAnimationAction;
1142
- nativeAfterAnimationColor?: string;
1143
- /** SVG motion path string for custom motion path animations. */
1144
- motionPath?: string;
1145
- /**
1146
- * Path edit mode for `p:animMotion/@pathEditMode`. Defaults to "relative"
1147
- * when emitted without an explicit value.
1148
- */
1149
- motionPathEditMode?: string;
1150
- /** Comma-separated point-types string for `p:animMotion/@ptsTypes`. */
1151
- motionPtsTypes?: string;
1152
- /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
1153
- motionPathRotationAngle?: number;
1154
- /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
1155
- motionPathRotationCenterX?: number;
1156
- /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
1157
- motionPathRotationCenterY?: number;
1158
- /**
1159
- * Sound relationship ID to play when animation triggers. Written on save
1160
- * as a `p:audio/p:cMediaNode` sibling of the effect's own `p:childTnLst`
1161
- * (see `PptxNativeAnimation.soundRId` for the COM-verified detail).
1162
- */
1163
- soundRId?: string;
1164
- /** Resolved sound file path from relationship. */
1165
- soundPath?: string;
1166
- /**
1167
- * The `@_name` to write on the embedded sound (`p:sndTgt`). For a stock
1168
- * gallery pick this is the exact PowerPoint file name (e.g.
1169
- * `"CHIMES.WAV"`), which is what makes PowerPoint itself recognise the
1170
- * sound as that built-in entry when it reopens the saved deck (there is no
1171
- * separate "built-in" flag anywhere in the schema). Set by
1172
- * `pptx-viewer-shared`'s `setEffectSound` when the pick carries a
1173
- * `soundName`; absent for a custom file with no meaningful name.
1174
- */
1175
- soundName?: string;
1176
- /** Whether to stop any currently playing sound (`p:endSnd`). */
1177
- stopSound?: boolean;
1178
- /**
1179
- * Pending, not-yet-embedded sound chosen in the authoring UI, as a
1180
- * `data:audio/...;base64,...` URL. Mirrors the `imageData` /
1181
- * `mediaData` pending-embed convention used elsewhere in the typed model:
1182
- * on save, the writer converts this to real bytes under `ppt/media/`,
1183
- * mints a relationship, and replaces this field with the resolved
1184
- * {@link soundRId} / {@link soundPath}. Cleared once embedded.
1185
- */
1186
- soundData?: string;
1187
- /**
1188
- * Display name for the chosen sound (e.g. the uploaded file's name),
1189
- * shown by the authoring UI's sound picker. Purely cosmetic; has no
1190
- * OOXML equivalent and is not required for playback. For a stock gallery
1191
- * pick, the UI derives its label from {@link soundName} via the catalogue
1192
- * instead of this field.
1193
- */
1194
- soundFileName?: string;
1195
- /**
1196
- * Per-build-level timing template(s) from the {@link sequence}'s own
1197
- * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded
1198
- * `PptxNativeAnimation.buildTemplates` this element animation was derived
1199
- * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s
1200
- * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit
1201
- * them instead of silently dropping the deck's authored per-level
1202
- * defaults. Absent when {@link sequence} carries no such template.
1203
- */
1204
- buildTemplates?: PptxTimingTemplate[];
1205
- }
1206
- /**
1207
- * A read-only anchor representing one of the deck's own effect groups: a
1208
- * top-level click group (`p:par` under `p:timing`'s main sequence) that this
1209
- * app did not author, so it is never exposed as an editable
1210
- * {@link PptxElementAnimation}.
1211
- *
1212
- * The authoring UI merges these anchors alongside `PptxSlide.animations` to
1213
- * render the FULL animation sequence (editor-authored and deck-native
1214
- * effects together) and lets an editor-authored entry be dragged to any
1215
- * position relative to them. `order` is the anchor's position among ALL
1216
- * top-level click groups (editor-owned and native) at load time, in the same
1217
- * numbering space as {@link PptxElementAnimation.order}, so the two
1218
- * populations sort into one coherent timeline.
1219
- *
1220
- * Anchors are never written back: on save, an untouched anchor's own click
1221
- * group is repositioned (if an editor-authored effect was dragged past it)
1222
- * but never mutated, so the deck's own effect stays byte-identical apart
1223
- * from its position in the sequence.
1224
- */
1225
- interface PptxAnimationTimelineAnchor {
1226
- /**
1227
- * Position of this group among all top-level click groups in the main
1228
- * animation sequence at load time (dense, shared with editor entries'
1229
- * `order`).
1230
- */
1231
- order: number;
1232
- /** Shape id(s) this group's effects target, for a readable UI label. */
1233
- targetIds: string[];
1234
- /** Effect preset classes present in the group (entr/exit/emph/path). */
1235
- presetClasses: Array<'entr' | 'exit' | 'emph' | 'path'>;
1236
- }
1237
- interface PptxVisibilitySetTiming {
1238
- /** Delay from effect start until the shape becomes visible. */
1239
- delayMs: number;
1240
- /** Native one-millisecond visibility behavior interval. */
1241
- durationMs: number;
1242
- }
1243
- /**
1244
- * A single `@`-mention inside a modern comment body.
1245
- *
1246
- * Offsets index into the comment's FLATTENED plain text: every `a:t` value
1247
- * below `p188:txBody` concatenated, with paragraphs joined by `\n`. That is the
1248
- * same string `PptxComment.text` carries, so an edit to `text` invalidates
1249
- * every offset after the edit point and the serializer re-bases them.
1250
- *
1251
- * The markup Office uses for a mention is `CT_Mention` (documented for the
1252
- * SpreadsheetML `2018/threadedcomments` part): `mentionpersonId`, `mentionId`,
1253
- * `startIndex` and `length`. The PowerPoint `2018/8/main` schema does not
1254
- * publish a mention element at all, so `rawXml` is retained and re-emitted
1255
- * attribute-for-attribute: a producer that spells the attributes differently
1256
- * still round-trips.
1257
- *
1258
- * @example
1259
- * ```ts
1260
- * const mention: PptxCommentMention = {
1261
- * personId: "{2CB2E9D0-D392-EB21-5D46-FBA34C1295E6}",
1262
- * authorName: "Bob Example",
1263
- * startIndex: 3,
1264
- * length: 11,
1265
- * };
1266
- * // => "Hi Bob Example can you check this".slice(3, 14) === "Bob Example"
1267
- * ```
1268
- */
1269
- interface PptxCommentMention {
1270
- /** `mentionId`: GUID identifying this mention instance. */
1271
- id?: string;
1272
- /** `mentionpersonId`: the `p188:author` id of the mentioned person. */
1273
- personId: string;
1274
- /** Display name resolved from the author list at parse time, when known. */
1275
- authorName?: string;
1276
- /** Character offset of the mentioned span in the flattened plain text. */
1277
- startIndex: number;
1278
- /** Character length of the mentioned span. */
1279
- length: number;
1280
- /**
1281
- * `uri` of the `p188:ext` this mention list was read from. Undefined means
1282
- * the list is a direct child of `p188:cm`, which is where it is written for
1283
- * newly authored mentions.
1284
- */
1285
- containerUri?: string;
1286
- /** Original `p188:mention` node, retained for unknown-attribute preservation. */
1287
- rawXml?: XmlObject;
1288
- }
1289
- /**
1290
- * A slide comment — may be a legacy positional comment or a modern
1291
- * threaded comment with replies.
1292
- *
1293
- * @example
1294
- * ```ts
1295
- * const comment: PptxComment = {
1296
- * id: "c1",
1297
- * text: "Please update this chart.",
1298
- * author: "Alice",
1299
- * createdAt: "2024-06-01T10:00:00Z",
1300
- * resolved: false,
1301
- * };
1302
- * // => satisfies PptxComment
1303
- * ```
1304
- */
1305
- interface PptxComment {
1306
- id: string;
1307
- text: string;
1308
- /** Storage vocabulary used by this comment. Omitted means legacy PresentationML. */
1309
- format?: 'legacy' | 'modern';
1310
- /** Stable GUID author identifier used by Office 2021 modern comments. */
1311
- authorId?: string;
1312
- /** Optional parent comment id for reply threading metadata. */
1313
- parentId?: string;
1314
- author?: string;
1315
- createdAt?: string;
1316
- x?: number;
1317
- y?: number;
1318
- /** Whether this comment has been resolved/marked done. */
1319
- resolved?: boolean;
1320
- /** Native p188 status token. */
1321
- status?: 'active' | 'resolved' | 'closed';
1322
- /** Modern comment classification tags and author IDs that liked the comment. */
1323
- tags?: string[];
1324
- likes?: string[];
1325
- startDate?: string;
1326
- dueDate?: string;
1327
- assignedTo?: string[];
1328
- /** Task completion in thousandths of a percent, from 0 through 100000. */
1329
- complete?: number;
1330
- priority?: number;
1331
- title?: string;
1332
- /** Modern threaded comment support (p15:threadingInfo). */
1333
- threadId?: string;
1334
- /** `@`-mentions, indexed into `text` (see {@link PptxCommentMention}). */
1335
- mentions?: PptxCommentMention[];
1336
- /** Replies to this comment (for modern threaded comments). */
1337
- replies?: PptxComment[];
1338
- /** ID of the element this comment is associated with (if any). */
1339
- elementId?: string;
1340
- /** Original `p:cm` subtree, retained for unknown child and extension preservation. */
1341
- rawXml?: XmlObject;
1342
- }
1343
- /** Office 2021 comment author from the p188 Author part. */
1344
- interface PptxModernCommentAuthor {
1345
- id: string;
1346
- name: string;
1347
- initials?: string;
1348
- userId: string;
1349
- providerId: string;
1350
- rawXml?: XmlObject;
1351
- }
1352
- /**
1353
- * A comment author from `ppt/commentAuthors.xml`.
1354
- *
1355
- * Stores all attributes needed for lossless round-trip serialization
1356
- * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx).
1357
- *
1358
- * @see ECMA-376 Part 1, §19.4.2 (cmAuthor)
1359
- *
1360
- * @example
1361
- * ```ts
1362
- * const author: PptxCommentAuthor = {
1363
- * id: "0",
1364
- * name: "John Doe",
1365
- * initials: "JD",
1366
- * lastIdx: 3,
1367
- * clrIdx: 0,
1368
- * };
1369
- * // => satisfies PptxCommentAuthor
1370
- * ```
1371
- */
1372
- interface PptxCommentAuthor {
1373
- /** Unique numeric author identifier (`@_id`). */
1374
- id: string;
1375
- /** Author display name (`@_name`). */
1376
- name: string;
1377
- /** Author initials (`@_initials`). */
1378
- initials: string;
1379
- /** Last comment index used by this author (`@_lastIdx`). */
1380
- lastIdx: number;
1381
- /** Colour index assigned to this author (`@_clrIdx`). */
1382
- clrIdx: number;
1383
- /** Original `p:cmAuthor` subtree, retained for unknown attribute preservation. */
1384
- rawXml?: XmlObject;
1385
- }
1386
- /**
1387
- * A compatibility warning generated during parse or save when the
1388
- * file uses features not fully supported by the editor.
1389
- *
1390
- * @example
1391
- * ```ts
1392
- * const warning: PptxCompatibilityWarning = {
1393
- * code: "UNSUPPORTED_3D",
1394
- * message: "3D rotation effects may not render accurately.",
1395
- * severity: "warning",
1396
- * scope: "element",
1397
- * slideId: "slide-1",
1398
- * elementId: "elem-42",
1399
- * };
1400
- * // => satisfies PptxCompatibilityWarning
1401
- * ```
1402
- */
1403
- interface PptxCompatibilityWarning {
1404
- code: string;
1405
- message: string;
1406
- severity: 'info' | 'warning';
1407
- scope: 'presentation' | 'slide' | 'element' | 'save';
1408
- slideId?: string;
1409
- elementId?: string;
1410
- xmlPath?: string;
1411
- }
1412
- /**
1413
- * A single name–value tag from `ppt/tags/*.xml`.
1414
- *
1415
- * @example
1416
- * ```ts
1417
- * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
1418
- * // => satisfies PptxTag
1419
- * ```
1420
- */
1421
- interface PptxTag {
1422
- name: string;
1423
- value: string;
1424
- }
1425
- /**
1426
- * A collection of tags from a single tags XML part.
1427
- *
1428
- * @example
1429
- * ```ts
1430
- * const coll: PptxTagCollection = {
1431
- * path: "ppt/tags/tag1.xml",
1432
- * tags: [{ name: "CUSTOM_ID", value: "12345" }],
1433
- * };
1434
- * // => satisfies PptxTagCollection
1435
- * ```
1436
- */
1437
- interface PptxTagCollection {
1438
- /** File path within the PPTX archive. */
1439
- path?: string;
1440
- /** Package owner of the tags relationship. New collections default to presentation. */
1441
- owner?: 'presentation' | 'slide' | 'part';
1442
- /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */
1443
- sourcePartPath?: string;
1444
- /** Durable relationship identifier from the owning part. */
1445
- relationshipId?: string;
1446
- /** Tags in this collection. */
1447
- tags: PptxTag[];
1448
- /** Parsed tag-list XML retained for unknown-node preservation. */
1449
- rawXml?: XmlObject;
1450
- }
1451
- /**
1452
- * A custom document property from `docProps/custom.xml`.
1453
- *
1454
- * @example
1455
- * ```ts
1456
- * const prop: PptxCustomProperty = {
1457
- * name: "Project",
1458
- * value: "pptx",
1459
- * type: "lpwstr",
1460
- * };
1461
- * // => satisfies PptxCustomProperty
1462
- * ```
1463
- */
1464
- interface PptxCustomProperty {
1465
- /** Property name. */
1466
- name: string;
1467
- /** Property value (always stringified). */
1468
- value: string;
1469
- /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
1470
- type: string;
1471
- }
1472
- /**
1473
- * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
1474
- *
1475
- * @example
1476
- * ```ts
1477
- * const core: PptxCoreProperties = {
1478
- * title: "Q4 Business Review",
1479
- * creator: "Alice",
1480
- * created: "2024-01-15T08:00:00Z",
1481
- * modified: "2024-06-01T12:30:00Z",
1482
- * lastModifiedBy: "Bob",
1483
- * };
1484
- * // => satisfies PptxCoreProperties
1485
- * ```
1486
- */
1487
- interface PptxCoreProperties {
1488
- /** dc:title */
1489
- title?: string;
1490
- /** dc:subject */
1491
- subject?: string;
1492
- /** dc:creator */
1493
- creator?: string;
1494
- /** cp:keywords */
1495
- keywords?: string;
1496
- /** dc:description */
1497
- description?: string;
1498
- /** cp:lastModifiedBy */
1499
- lastModifiedBy?: string;
1500
- /** cp:revision */
1501
- revision?: string;
1502
- /** dcterms:created (ISO 8601) */
1503
- created?: string;
1504
- /** dcterms:modified (ISO 8601) */
1505
- modified?: string;
1506
- /** cp:category */
1507
- category?: string;
1508
- /** cp:contentStatus */
1509
- contentStatus?: string;
1510
- }
1511
- /**
1512
- * Extended (application) properties from `docProps/app.xml`.
1513
- *
1514
- * @example
1515
- * ```ts
1516
- * const app: PptxAppProperties = {
1517
- * application: "Microsoft Office PowerPoint",
1518
- * appVersion: "16.0000",
1519
- * slides: 24,
1520
- * words: 1500,
1521
- * company: "Acme Corp",
1522
- * };
1523
- * // => satisfies PptxAppProperties
1524
- * ```
1525
- */
1526
- interface PptxAppProperties {
1527
- /** Application name (e.g. "Microsoft Office PowerPoint"). */
1528
- application?: string;
1529
- /** Application version string. */
1530
- appVersion?: string;
1531
- /** Presentation format (e.g. "On-screen Show (16:9)"). */
1532
- presentationFormat?: string;
1533
- /** Total number of slides. */
1534
- slides?: number;
1535
- /** Number of hidden slides. */
1536
- hiddenSlides?: number;
1537
- /** Number of notes slides. */
1538
- notes?: number;
1539
- /** Total editing time in minutes. */
1540
- totalTime?: number;
1541
- /** Number of words. */
1542
- words?: number;
1543
- /** Number of paragraphs. */
1544
- paragraphs?: number;
1545
- /** Company name. */
1546
- company?: string;
1547
- /** Manager name. */
1548
- manager?: string;
1549
- /** Template name. */
1550
- template?: string;
1551
- /** Hyperlink base URL. */
1552
- hyperlinkBase?: string;
1553
- /** Document security bitmask (`<DocSecurity>`). */
1554
- docSecurity?: number;
1555
- /** Number of multimedia clips (`<MMClips>`). */
1556
- mmClips?: number;
1557
- /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
1558
- scaleCrop?: boolean;
1559
- /** Whether hyperlinks are current (`<LinksUpToDate>`). */
1560
- linksUpToDate?: boolean;
1561
- /** Whether the document is shared (`<SharedDoc>`). */
1562
- sharedDoc?: boolean;
1563
- /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
1564
- hyperlinksChanged?: boolean;
1565
- }
1566
- /**
1567
- * Theme object model — colour scheme, font scheme, and format scheme
1568
- * parsed from `ppt/theme/theme1.xml`.
1569
- *
1570
- * The colour scheme provides the 12 canonical OOXML colour slots.
1571
- * The font scheme defines major (heading) and minor (body) typefaces.
1572
- * The format scheme holds fill, line, and effect style matrices at
1573
- * three intensity levels (subtle, moderate, intense).
1574
- *
1575
- * @module pptx-types/theme
1576
- */
1577
- /**
1578
- * The 12 OOXML theme colour scheme keys in canonical order.
1579
- *
1580
- * @example
1581
- * ```ts
1582
- * for (const key of THEME_COLOR_SCHEME_KEYS) {
1583
- * console.log(key, theme.colorScheme?.[key]);
1584
- * }
1585
- * // => e.g. "dk1 #000000", "lt1 #FFFFFF", "accent1 #4F81BD", …
1586
- * ```
1587
- */
1588
- declare const THEME_COLOR_SCHEME_KEYS: readonly ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
1589
- /**
1590
- * Resolved hex values for the 12 theme colour slots.
1591
- *
1592
- * @example
1593
- * ```ts
1594
- * const scheme: PptxThemeColorScheme = {
1595
- * dk1: "#000000", lt1: "#FFFFFF",
1596
- * dk2: "#1F497D", lt2: "#EEECE1",
1597
- * accent1: "#4F81BD", accent2: "#C0504D",
1598
- * accent3: "#9BBB59", accent4: "#8064A2",
1599
- * accent5: "#4BACC6", accent6: "#F79646",
1600
- * hlink: "#0000FF", folHlink: "#800080",
1601
- * };
1602
- * // => satisfies PptxThemeColorScheme
1603
- * ```
1604
- */
1605
- interface PptxThemeColorScheme {
1606
- dk1: string;
1607
- lt1: string;
1608
- dk2: string;
1609
- lt2: string;
1610
- accent1: string;
1611
- accent2: string;
1612
- accent3: string;
1613
- accent4: string;
1614
- accent5: string;
1615
- accent6: string;
1616
- hlink: string;
1617
- folHlink: string;
1618
- }
1619
- /**
1620
- * A font-family triplet for major or minor theme fonts.
1621
- *
1622
- * Supports Latin, East Asian, and Complex Script font families.
1623
- *
1624
- * @example
1625
- * ```ts
1626
- * const fonts: PptxThemeFontGroup = {
1627
- * latin: "Calibri Light",
1628
- * eastAsia: "MS PGothic",
1629
- * complexScript: "Arial",
1630
- * };
1631
- * // => satisfies PptxThemeFontGroup
1632
- * ```
1633
- */
1634
- interface PptxThemeFontGroup {
1635
- latin?: string;
1636
- eastAsia?: string;
1637
- complexScript?: string;
1638
- /**
1639
- * Per-script typeface overrides (`<a:font script="Hans|Hant|Arab|Hebr|
1640
- * Thai|Beng|Gujr|Khmr|Knda|…"/>` per ECMA-376 §20.1.4.1.16). Keyed by
1641
- * the four-letter ISO 15924 script tag from the `script` attribute.
1642
- *
1643
- * Phase 4 Stream A / M4.
1644
- */
1645
- byScript?: Record<string, string>;
1646
- }
1647
- /**
1648
- * Theme font scheme — major (headings) and minor (body) font families.
1649
- *
1650
- * @example
1651
- * ```ts
1652
- * const scheme: PptxThemeFontScheme = {
1653
- * majorFont: { latin: "Calibri Light" },
1654
- * minorFont: { latin: "Calibri", eastAsia: "MS PGothic" },
1655
- * };
1656
- * // => satisfies PptxThemeFontScheme
1657
- * ```
1658
- */
1659
- interface PptxThemeFontScheme {
1660
- majorFont?: PptxThemeFontGroup;
1661
- minorFont?: PptxThemeFontGroup;
1662
- }
1663
- /**
1664
- * A single fill style entry from the theme format scheme.
1665
- * Each entry is one of: solid, gradient, pattern, or no fill.
1666
- * The raw XML node is also stored so that `phClr` substitution can happen
1667
- * at resolution time.
1668
- *
1669
- * @example
1670
- * ```ts
1671
- * const solidFill: PptxThemeFillStyle = {
1672
- * kind: "solid",
1673
- * color: "#4F81BD",
1674
- * opacity: 1,
1675
- * };
1676
- *
1677
- * const gradientFill: PptxThemeFillStyle = {
1678
- * kind: "gradient",
1679
- * gradientAngle: 90,
1680
- * gradientType: "linear",
1681
- * gradientStops: [
1682
- * { color: "#4F81BD", position: 0 },
1683
- * { color: "#1F497D", position: 1 },
1684
- * ],
1685
- * };
1686
- * // => satisfies PptxThemeFillStyle
1687
- * ```
1688
- */
1689
- interface PptxThemeFillStyle {
1690
- /**
1691
- * Discriminator for the fill type.
1692
- *
1693
- * `'group'` corresponds to `<a:grpFill/>` — a fill that inherits the
1694
- * containing group shape's fill at render time. Captured for round-trip
1695
- * preservation in `fmtScheme/fillStyleLst`.
1696
- */
1697
- kind: 'solid' | 'gradient' | 'pattern' | 'none' | 'group';
1698
- /** Pre-resolved colour (may be `undefined` when `phClr`-dependent). */
1699
- color?: string;
1700
- opacity?: number;
1701
- /** Gradient-specific fields (only present when `kind === "gradient"`). */
1702
- gradientStops?: Array<{
1703
- color: string;
1704
- position: number;
1705
- opacity?: number;
1706
- }>;
1707
- gradientAngle?: number;
1708
- gradientType?: 'linear' | 'radial';
1709
- gradientCss?: string;
1710
- /** Pattern-specific fields (only present when `kind === "pattern"`). */
1711
- patternPreset?: string;
1712
- patternBackgroundColor?: string;
1713
- /** Raw XML node preserved for `phClr` re-resolution. */
1714
- rawNode?: unknown;
1715
- }
1716
- /**
1717
- * A single line style entry from `a:lnStyleLst`.
1718
- * Provides width, dash, join, cap, and optional fill colour.
1719
- *
1720
- * @example
1721
- * ```ts
1722
- * const line: PptxThemeLineStyle = {
1723
- * width: 1.5,
1724
- * color: "#4F81BD",
1725
- * dash: "solid",
1726
- * lineJoin: "round",
1727
- * lineCap: "flat",
1728
- * };
1729
- * // => satisfies PptxThemeLineStyle
1730
- * ```
1731
- */
1732
- interface PptxThemeLineStyle {
1733
- /** Line width in pixels (converted from EMU). */
1734
- width?: number;
1735
- color?: string;
1736
- opacity?: number;
1737
- dash?: string;
1738
- lineJoin?: 'round' | 'bevel' | 'miter';
1739
- lineCap?: 'flat' | 'rnd' | 'sq';
1740
- compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
1741
- /** Raw XML node preserved for `phClr` re-resolution. */
1742
- rawNode?: unknown;
1743
- }
1744
- /**
1745
- * A single effect style entry from `a:effectStyleLst`.
1746
- * Each entry may define shadow, glow, soft-edge, reflection, blur,
1747
- * and optionally a 3-D scene/shape.
1748
- *
1749
- * @example
1750
- * ```ts
1751
- * const dropShadow: PptxThemeEffectStyle = {
1752
- * shadowColor: "#000000",
1753
- * shadowBlur: 4,
1754
- * shadowOffsetX: 2,
1755
- * shadowOffsetY: 3,
1756
- * shadowOpacity: 0.4,
1757
- * };
1758
- * // => satisfies PptxThemeEffectStyle
1759
- * ```
1760
- */
1761
- interface PptxThemeEffectStyle {
1762
- shadowColor?: string;
1763
- shadowBlur?: number;
1764
- shadowOffsetX?: number;
1765
- shadowOffsetY?: number;
1766
- shadowOpacity?: number;
1767
- glowColor?: string;
1768
- glowRadius?: number;
1769
- glowOpacity?: number;
1770
- softEdgeRadius?: number;
1771
- innerShadowColor?: string;
1772
- innerShadowOpacity?: number;
1773
- innerShadowBlur?: number;
1774
- innerShadowOffsetX?: number;
1775
- innerShadowOffsetY?: number;
1776
- reflectionBlurRadius?: number;
1777
- reflectionStartOpacity?: number;
1778
- reflectionEndOpacity?: number;
1779
- reflectionEndPosition?: number;
1780
- reflectionDirection?: number;
1781
- reflectionRotation?: number;
1782
- reflectionDistance?: number;
1783
- /** 3D scene/camera from `a:scene3d` on the effect style (idx 3 typically). */
1784
- scene3d?: DrawingScene3D;
1785
- /** 3D shape extrusion/bevel from `a:sp3d` on the effect style (idx 3 typically). */
1786
- shape3d?: Pptx3DShape;
1787
- /** Raw XML node preserved for `phClr` re-resolution. */
1788
- rawNode?: unknown;
1789
- }
1790
- /**
1791
- * The full parsed format scheme from `a:fmtScheme` inside `a:themeElements`.
1792
- * Contains three fill style lists and one line/effect style list each,
1793
- * at three intensity levels: subtle (idx 1), moderate (idx 2), intense (idx 3).
1794
- *
1795
- * OOXML reference indices:
1796
- * - fillStyleLst: idx 1-3 (used by `a:fillRef @idx` 1-3)
1797
- * - lnStyleLst: idx 1-3 (used by `a:lnRef @idx` 1-3)
1798
- * - effectStyleLst: idx 1-3 (used by `a:effectRef @idx` 1-3)
1799
- * - bgFillStyleLst: idx 1-3 (used by `a:fillRef @idx` 1001-1003)
1800
- *
1801
- * @example
1802
- * ```ts
1803
- * const fmt: PptxThemeFormatScheme = {
1804
- * name: "Office",
1805
- * fillStyles: [solidFill, gradientFill, intenseFill],
1806
- * lineStyles: [thinLine, mediumLine, thickLine],
1807
- * effectStyles: [subtle, moderate, intense],
1808
- * backgroundFillStyles: [solidBg, gradientBg, intenseBg],
1809
- * };
1810
- * // => satisfies PptxThemeFormatScheme
1811
- * ```
1812
- */
1813
- interface PptxThemeFormatScheme {
1814
- /** The `@name` attribute of the format scheme. */
1815
- name?: string;
1816
- /** Fill styles at indices 1-3 (subtle, moderate, intense). */
1817
- fillStyles: PptxThemeFillStyle[];
1818
- /** Line styles at indices 1-3. */
1819
- lineStyles: PptxThemeLineStyle[];
1820
- /** Effect styles at indices 1-3. */
1821
- effectStyles: PptxThemeEffectStyle[];
1822
- /** Background fill styles at indices 1-3 (referenced via idx 1001-1003). */
1823
- backgroundFillStyles: PptxThemeFillStyle[];
1824
- }
1825
- /**
1826
- * Full parsed theme object available to renderers.
1827
- *
1828
- * @example
1829
- * ```ts
1830
- * const theme: PptxTheme = {
1831
- * name: "Office Theme",
1832
- * colorScheme: { dk1: "#000", lt1: "#FFF", /* … *\/ },
1833
- * fontScheme: {
1834
- * majorFont: { latin: "Calibri Light" },
1835
- * minorFont: { latin: "Calibri" },
1836
- * },
1837
- * };
1838
- * // => satisfies PptxTheme
1839
- * ```
1840
- */
1841
- interface PptxTheme {
1842
- /** Theme name from `a:theme @name`. */
1843
- name?: string;
1844
- /** Resolved colour scheme. */
1845
- colorScheme?: PptxThemeColorScheme;
1846
- /** Resolved font scheme. */
1847
- fontScheme?: PptxThemeFontScheme;
1848
- /** Format scheme — fill, line, effect and background fill style matrices. */
1849
- formatScheme?: PptxThemeFormatScheme;
1850
- }
1851
- /**
1852
- * The colour, font and format schemes and the name one theme part of the package carries, read
1853
- * without changing the loaded theme (`PptxHandler.getThemePartSchemes`).
1854
- */
1855
- interface PptxThemePartSchemes {
1856
- /** The theme part's path in the package (e.g. `ppt/theme/theme2.xml`). */
1857
- path: string;
1858
- /** Theme name from `a:theme @name`, when present. */
1859
- name?: string;
1860
- colorScheme: PptxThemeColorScheme;
1861
- fontScheme: PptxThemeFontScheme;
1862
- /** The part's format scheme (`a:fmtScheme`), when it has one. */
1863
- formatScheme?: PptxThemeFormatScheme;
1864
- }
1865
- /**
1866
- * Snapshot of `<a:objectDefaults>` (ECMA-376 §20.1.6.7). Each child
1867
- * (`spDef`, `lnDef`, `txDef`) carries `<a:spPr>`, `<a:bodyPr>`,
1868
- * `<a:lstStyle>`, `<a:style>`. We capture them as raw parser objects so
1869
- * round-trip is byte-stable regardless of schema-walking depth.
1870
- *
1871
- * Phase 4 Stream A / M5.
1872
- */
1873
- interface PptxThemeObjectDefaults {
1874
- /** Raw `<a:spDef>` parser object, or `undefined` if absent. */
1875
- spDef?: unknown;
1876
- /** Raw `<a:lnDef>` parser object, or `undefined` if absent. */
1877
- lnDef?: unknown;
1878
- /** Raw `<a:txDef>` parser object, or `undefined` if absent. */
1879
- txDef?: unknown;
1880
- }
1881
- /**
1882
- * A real theme variant read from the package's `themeVariants/` parts (see `loadThemeVariants`).
1883
- */
1884
- interface PptxThemeVariant {
1885
- /** The variant's `vid` GUID. */
1886
- id: string;
1887
- /** Display name (the theme family's). */
1888
- name: string;
1889
- colorScheme: PptxThemeColorScheme;
1890
- fontScheme: PptxThemeFontScheme;
1891
- /** The variant's `a:fmtScheme`, as the text its theme part carries. */
1892
- formatSchemeXml?: string;
1893
- /** The Background Styles preset (1 to 12) the variant's master uses, when it is one. */
1894
- backgroundStyleIndex?: number;
1895
- }
1896
- /**
1897
- * Design > Variants > Background Styles: the twelve theme background styles.
1898
- *
1899
- * PowerPoint offers a 4 by 3 grid. Each row is one entry of the theme's `a:bgFillStyleLst`
1900
- * (`bgRef idx` 1001, 1002, 1003). Each column is a colour: the theme's light background (`bg1`),
1901
- * its light alternate (`bg2`), then the dark pair, which PowerPoint writes as the same
1902
- * `bgRef` with the colour map swapped (`bg1="dk1" tx1="lt1" bg2="dk2" tx2="lt2"`), so text flips
1903
- * to the light colour. Verified against PowerPoint's `Slide.BackgroundStyle` and
1904
- * `SlideMaster.BackgroundStyle` output.
1905
- *
1906
- * @module pptx-types/background-style
1907
- */
1908
- /** One cell of the Background Styles grid. */
1909
- interface PptxBackgroundStylePreset {
1910
- /** 1 to 12, row by row (PowerPoint's `msoBackgroundStylePreset1` to `12`). */
1911
- index: number;
1912
- /** `bgRef idx`: 1001, 1002 or 1003 into `a:bgFillStyleLst`. */
1913
- idx: 1001 | 1002 | 1003;
1914
- /** The scheme colour the fill style takes as `phClr`. */
1915
- scheme: 'bg1' | 'bg2';
1916
- /** True when the colour map is swapped to the dark pair (text turns light). */
1917
- dark: boolean;
1918
- }
1919
- /** The twelve background styles in gallery order. */
1920
- declare const BACKGROUND_STYLE_PRESETS: readonly PptxBackgroundStylePreset[];
1921
- /** The preset at `index` (1 to 12), or `undefined`. */
1922
- declare function backgroundStylePreset(index: number): PptxBackgroundStylePreset | undefined;
1923
- /** The preset a `bgRef` (idx and scheme colour) and a dark flag describe, or `undefined`. */
1924
- declare function backgroundStylePresetFor(idx: number, scheme: string, dark: boolean): PptxBackgroundStylePreset | undefined;
1925
- /** The twelve-entry colour map for the light (`false`) or dark (`true`) background pair. */
1926
- declare function backgroundStyleColorMap(dark: boolean): Record<string, string>;
1927
- /** True when a colour map (`bg1` routed to `dk1`) is the dark pair. */
1928
- declare function isDarkColorMap(map: Readonly<Record<string, string>> | null | undefined): boolean;
1929
- /**
1930
- * A slide's theme background style, as the editor applied it or the loader read it.
1931
- *
1932
- * `kind: 'preset'` is `<p:bg><p:bgRef idx scheme/></p:bg>`; `kind: 'inherit'` is no `p:bg` at all
1933
- * ("Follow master background"). The resolved values pin the reference to the flat
1934
- * `backgroundColor`/`backgroundGradient` it produced: when a later edit (Format Background) moves
1935
- * them the reference is stale and ignored on save.
1936
- */
1937
- interface PptxSlideBackgroundStyleRef {
1938
- kind: 'preset' | 'inherit';
1939
- /** `bgRef idx` (preset only). */
1940
- idx?: number;
1941
- /** `bgRef` scheme colour (preset only). */
1942
- scheme?: 'bg1' | 'bg2';
1943
- /** `backgroundColor` the style resolved to when it was set. */
1944
- resolvedColor?: string;
1945
- /** `backgroundGradient` the style resolved to when it was set. */
1946
- resolvedGradient?: string;
1947
- }
1948
- /**
1949
- * A placeholder slot declared on a master or layout.
1950
- *
1951
- * The geometry fields are in CSS pixels (EMU / {@link EMU_PER_PX}) and are only
1952
- * present when the shape carried an explicit `a:xfrm`. Placeholders that
1953
- * inherit their frame from the master leave them undefined, so consumers that
1954
- * draw placeholder outlines (the layout gallery) must skip those entries
1955
- * rather than assume a zero-sized box at the origin.
1956
- *
1957
- * @example
1958
- * ```ts
1959
- * const frame: PptxPlaceholderFrame = { type: "body", idx: "1", x: 63, y: 130 };
1960
- * // => satisfies PptxPlaceholderFrame
1961
- * ```
1962
- */
1963
- interface PptxPlaceholderFrame {
1964
- /** `p:ph/@type`, lower-cased by the parser; defaults to `body` when omitted. */
1965
- type: string;
1966
- /** `p:ph/@idx`, when present. */
1967
- idx?: string;
1968
- /** Left offset in CSS pixels, when the shape declares `a:off`. */
1969
- x?: number;
1970
- /** Top offset in CSS pixels, when the shape declares `a:off`. */
1971
- y?: number;
1972
- /** Width in CSS pixels, when the shape declares `a:ext`. */
1973
- width?: number;
1974
- /** Height in CSS pixels, when the shape declares `a:ext`. */
1975
- height?: number;
1976
- }
1977
- /**
1978
- * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
1979
- *
1980
- * @example
1981
- * ```ts
1982
- * const notes: PptxNotesMaster = {
1983
- * path: "ppt/notesMasters/notesMaster1.xml",
1984
- * backgroundColor: "#FFFFFF",
1985
- * placeholders: [{ type: "body" }, { type: "sldImg" }],
1986
- * };
1987
- * // => satisfies PptxNotesMaster
1988
- * ```
1989
- */
1990
- interface PptxNotesMaster {
1991
- /** File path within the PPTX archive. */
1992
- path: string;
1993
- /** Background colour of the notes master. */
1994
- backgroundColor?: string;
1995
- /** Background image data URL. */
1996
- backgroundImage?: string;
1997
- /** Crop, tiling and image effects authored on the background blip fill. */
1998
- backgroundImageProperties?: PptxImageProperties;
1999
- /** Placeholder shapes found on the notes master. */
2000
- placeholders?: PptxPlaceholderFrame[];
2001
- /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
2002
- elements?: PptxElement[];
2003
- /** Header/footer flags from `<p:hf>` on the notes master (P-H3). */
2004
- headerFooter?: PptxHeaderFooterFlags;
2005
- /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
2006
- clrMap?: Record<string, string>;
2007
- /**
2008
- * Notes text defaults from `<p:notesStyle>` (`CT_TextListStyle`, ECMA-376
2009
- * §19.3.1.34): the same `a:defPPr` + `a:lvl1pPr`..`a:lvl9pPr` shape as
2010
- * {@link PptxMasterTextStyles}'s per-category styles, keyed 0-8 with the
2011
- * default at `-1`. Governs the notes body placeholder's font size, indent
2012
- * levels, and bullet style wherever a notes slide does not override them.
2013
- * Parsed read-only for the render cascade; the save side preserves the
2014
- * original `<p:notesStyle>` XML verbatim rather than re-serialising this.
2015
- */
2016
- notesStyle?: PptxTextStyleLevels;
2017
- }
2018
- /**
2019
- * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
2020
- *
2021
- * @example
2022
- * ```ts
2023
- * const handout: PptxHandoutMaster = {
2024
- * path: "ppt/handoutMasters/handoutMaster1.xml",
2025
- * slidesPerPage: 6,
2026
- * };
2027
- * // => satisfies PptxHandoutMaster
2028
- * ```
2029
- */
2030
- interface PptxHandoutMaster {
2031
- /** File path within the PPTX archive. */
2032
- path: string;
2033
- /** Background colour of the handout master. */
2034
- backgroundColor?: string;
2035
- /** Background image data URL. */
2036
- backgroundImage?: string;
2037
- /** Crop, tiling and image effects authored on the background blip fill. */
2038
- backgroundImageProperties?: PptxImageProperties;
2039
- /** Placeholder shapes found on the handout master. */
2040
- placeholders?: PptxPlaceholderFrame[];
2041
- /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
2042
- elements?: PptxElement[];
2043
- /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
2044
- slidesPerPage?: number;
2045
- /** Header/footer flags from `<p:hf>` on the handout master (P-H3). */
2046
- headerFooter?: PptxHeaderFooterFlags;
2047
- /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
2048
- clrMap?: Record<string, string>;
2049
- }
2050
- /**
2051
- * Active tab within the master view sidebar.
2052
- *
2053
- * @example
2054
- * ```ts
2055
- * const tab: MasterViewTab = "slides";
2056
- * // => "slides" — one of: "slides" | "notes" | "handout"
2057
- * ```
2058
- */
2059
- type MasterViewTab = 'slides' | 'notes' | 'handout';
2060
- /**
2061
- * Structured slide master data.
2062
- *
2063
- * @example
2064
- * ```ts
2065
- * const master: PptxSlideMaster = {
2066
- * path: "ppt/slideMasters/slideMaster1.xml",
2067
- * name: "Office Theme",
2068
- * backgroundColor: "#FFFFFF",
2069
- * themePath: "ppt/theme/theme1.xml",
2070
- * };
2071
- * // => satisfies PptxSlideMaster
2072
- * ```
2073
- */
2074
- interface PptxSlideMaster {
2075
- /** File path within the PPTX archive. */
2076
- path: string;
2077
- /** Human-readable name if available. */
2078
- name?: string;
2079
- /** Background colour of the slide master. */
2080
- backgroundColor?: string;
2081
- /** Background image data URL for the slide master. */
2082
- backgroundImage?: string;
2083
- /** Crop, tiling and image effects authored on the background blip fill. */
2084
- backgroundImageProperties?: PptxImageProperties;
2085
- /** Theme file path this master references. */
2086
- themePath?: string;
2087
- /** Layout paths associated with this master. */
2088
- layoutPaths?: string[];
2089
- /** Placeholder shapes on the master. */
2090
- placeholders?: PptxPlaceholderFrame[];
2091
- /** Parsed element shapes on the master slide (for master view rendering). */
2092
- elements?: PptxElement[];
2093
- /** Parsed slide layout objects associated with this master. */
2094
- layouts?: PptxSlideLayout[];
2095
- /** Text styles from `p:txStyles` — title, body, and other text defaults. */
2096
- txStyles?: PptxMasterTextStyles;
2097
- /** Header/footer flags from `<p:hf>` on this master (P-H3). */
2098
- headerFooter?: PptxHeaderFooterFlags;
2099
- /**
2100
- * Colour map from `<p:clrMap>` (12 alias attributes: bg1/tx1/bg2/tx2,
2101
- * accent1-6, hlink, folHlink). Applied at save time when present.
2102
- */
2103
- clrMap?: Record<string, string>;
2104
- /**
2105
- * Whether the master is marked as preserved (prevent auto-deletion,
2106
- * `@preserve`). Mirrors {@link PptxSlideLayout.preserve}: PowerPoint
2107
- * silently drops an unused master unless this is set.
2108
- *
2109
- * ECMA-376 §19.3.1.38 (CT_SlideMaster).
2110
- */
2111
- preserve?: boolean;
2112
- }
2113
- /**
2114
- * Per-level paragraph properties for a text style category.
2115
- * Each entry maps a 0-based level index to its style defaults.
2116
- */
2117
- type PptxTextStyleLevels = Record<number, PlaceholderTextLevelStyle>;
2118
- /**
2119
- * Text styles parsed from `p:txStyles` on a slide master.
2120
- * Provides cascading defaults for title, body, and other text.
2121
- */
2122
- interface PptxMasterTextStyles {
2123
- /** Title text style (`p:titleStyle`). */
2124
- titleStyle?: PptxTextStyleLevels;
2125
- /** Body text style (`p:bodyStyle`). */
2126
- bodyStyle?: PptxTextStyleLevels;
2127
- /** Other text style (`p:otherStyle`). */
2128
- otherStyle?: PptxTextStyleLevels;
2129
- }
2130
- /**
2131
- * Per-part header/footer flags from `<p:hf>` (CT_HeaderFooter, ECMA-376
2132
- * §19.3.1.21). Defaults are "all true" — fields are only set on the typed
2133
- * model when they were explicitly read, so callers can distinguish "unset"
2134
- * (preserve original XML) from "false" (override).
2135
- */
2136
- interface PptxHeaderFooterFlags {
2137
- /** `@hdr` — show header placeholder. Spec default: `true`. */
2138
- hasHeader?: boolean;
2139
- /** `@ftr` — show footer placeholder. Spec default: `true`. */
2140
- hasFooter?: boolean;
2141
- /** `@dt` — show date/time placeholder. Spec default: `true`. */
2142
- hasDateTime?: boolean;
2143
- /** `@sldNum` — show slide-number placeholder. Spec default: `true`. */
2144
- hasSlideNumber?: boolean;
2145
- }
2146
- /**
2147
- * A slide layout associated with a slide master.
2148
- *
2149
- * @example
2150
- * ```ts
2151
- * const layout: PptxSlideLayout = {
2152
- * path: "ppt/slideLayouts/slideLayout2.xml",
2153
- * name: "Title and Content",
2154
- * };
2155
- * // => satisfies PptxSlideLayout
2156
- * ```
2157
- */
2158
- interface PptxSlideLayout {
2159
- /** File path within the PPTX archive. */
2160
- path: string;
2161
- /** Human-readable layout name. */
2162
- name?: string;
2163
- /** Background colour of the layout. */
2164
- backgroundColor?: string;
2165
- /** Background image data URL for the layout. */
2166
- backgroundImage?: string;
2167
- /** Crop, tiling and image effects authored on the background blip fill. */
2168
- backgroundImageProperties?: PptxImageProperties;
2169
- /** Parsed element shapes on the layout. */
2170
- elements?: PptxElement[];
2171
- /** Placeholder shapes on the layout. */
2172
- placeholders?: PptxPlaceholderFrame[];
2173
- /** Matching name attribute for layout identification (`@matchingName`). */
2174
- matchingName?: string;
2175
- /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
2176
- preserve?: boolean;
2177
- /** Whether master placeholder animations should play (`@showMasterPhAnim`). */
2178
- showMasterPhAnim?: boolean;
2179
- /** Whether this layout is user-drawn (`@userDrawn`). */
2180
- userDrawn?: boolean;
2181
- /** Colour map override from `p:clrMapOvr`. */
2182
- clrMapOverride?: Record<string, string>;
2183
- /** Header/footer flags from `<p:hf>` on this layout (P-H3). */
2184
- headerFooter?: PptxHeaderFooterFlags;
2185
- }
2186
- /**
2187
- * Rendered content of a single layout, used to draw gallery thumbnails.
2188
- *
2189
- * Produced on demand rather than during load: materialising every layout's
2190
- * artwork (and decoding its images) up front costs a noticeable amount of time
2191
- * on decks with many masters, and most sessions never open the layout gallery
2192
- * at all.
2193
- *
2194
- * @example
2195
- * ```ts
2196
- * const preview: PptxLayoutPreview = {
2197
- * path: "ppt/slideLayouts/slideLayout2.xml",
2198
- * width: 960,
2199
- * height: 540,
2200
- * elements: [],
2201
- * placeholders: [{ type: "title" }],
2202
- * };
2203
- * // => satisfies PptxLayoutPreview
2204
- * ```
2205
- */
2206
- interface PptxLayoutPreview {
2207
- /** ZIP path of the layout this preview belongs to. */
2208
- path: string;
2209
- /** Slide width in CSS pixels, so a thumbnail can compute its own scale. */
2210
- width: number;
2211
- /** Slide height in CSS pixels. */
2212
- height: number;
2213
- /** Background resolved from the layout, falling back to its master's. */
2214
- backgroundColor?: string;
2215
- /** Background image data URL, when the layout or master declares one. */
2216
- backgroundImage?: string;
2217
- /** Crop, tiling and image effects authored on the resolved background image. */
2218
- backgroundImageProperties?: PptxImageProperties;
2219
- /** The layout's own artwork (pictures, shapes and static text). */
2220
- elements: PptxElement[];
2221
- /** Placeholder slots, drawn as outlined frames in the gallery. */
2222
- placeholders: PptxPlaceholderFrame[];
2223
- }
2224
- /**
2225
- * A theme part available in the presentation package.
2226
- *
2227
- * @example
2228
- * ```ts
2229
- * const opt: PptxThemeOption = {
2230
- * path: "ppt/theme/theme1.xml",
2231
- * name: "Office Theme",
2232
- * };
2233
- * // => satisfies PptxThemeOption
2234
- * ```
2235
- */
2236
- interface PptxThemeOption {
2237
- /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */
2238
- path: string;
2239
- /** Human-readable theme name from `a:theme/@name`, when present. */
2240
- name?: string;
2241
- }
2242
- interface PptxEmbeddedFontDataId {
2243
- /** Required relationship identifier from `r:id`. */
2244
- relationshipId?: string | null;
2245
- /** Original leaf retained for unknown attribute preservation. */
2246
- rawXml?: XmlObject;
2247
- }
2248
- interface PptxEmbeddedFontDescriptor {
2249
- typeface?: string | null;
2250
- panose?: string | null;
2251
- pitchFamily?: string | null;
2252
- charset?: string | null;
2253
- rawXml?: XmlObject;
2254
- }
2255
- interface PptxEmbeddedFontListEntry {
2256
- font: PptxEmbeddedFontDescriptor;
2257
- regular?: PptxEmbeddedFontDataId | null;
2258
- bold?: PptxEmbeddedFontDataId | null;
2259
- italic?: PptxEmbeddedFontDataId | null;
2260
- boldItalic?: PptxEmbeddedFontDataId | null;
2261
- rawXml?: XmlObject;
2262
- }
2263
- interface PptxEmbeddedFontList {
2264
- fonts: PptxEmbeddedFontListEntry[];
2265
- /** Original list retained for unknown attribute and child preservation. */
2266
- rawXml?: XmlObject;
2267
- }
2268
- type PptxPrintOutput = 'slides' | 'handouts1' | 'handouts2' | 'handouts3' | 'handouts4' | 'handouts6' | 'handouts9' | 'notes' | 'outline';
2269
- type PptxPrintColorMode = 'bw' | 'gray' | 'clr';
2270
- /** PresentationML `CT_PrintProperties` (`p:prnPr`). */
2271
- interface PptxPresentationPrintProperties {
2272
- printWhat?: PptxPrintOutput | null;
2273
- colorMode?: PptxPrintColorMode | null;
2274
- hiddenSlides?: boolean | null;
2275
- scaleToFitPaper?: boolean | null;
2276
- frameSlides?: boolean | null;
2277
- /** Original subtree retained for unknown attributes and `p:extLst`. */
2278
- rawXml?: XmlObject;
2279
- }
2280
- /**
2281
- * View properties types parsed from `ppt/viewProps.xml`.
2282
- *
2283
- * Models the `p:viewPr` element and its child views:
2284
- * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr,
2285
- * sorterViewPr, notesViewPr.
2286
- *
2287
- * @module pptx-types/view-properties
2288
- */
2289
- /**
2290
- * Scale factor for a view (numerator / denominator percentage).
2291
- */
2292
- interface PptxViewScale {
2293
- /** Numerator of the scale percentage (e.g. 100 for 100%). */
2294
- n: number;
2295
- /** Denominator of the scale percentage (e.g. 100 for 100%). */
2296
- d: number;
2297
- /** Optional independent vertical scale. When absent, the X scale is used. */
2298
- sy?: {
2299
- n: number;
2300
- d: number;
2301
- };
2302
- }
2303
- /**
2304
- * Origin point for a view (x, y in twips or EMU).
2305
- */
2306
- interface PptxViewOrigin {
2307
- x: number;
2308
- y: number;
2309
- }
2310
- /** A horizontal or vertical drawing guide in slide coordinates. */
2311
- interface PptxViewGuide {
2312
- orientation?: 'horz' | 'vert';
2313
- position?: number;
2314
- }
2315
- /** Positive grid spacing from `p:gridSpacing`. */
2316
- interface PptxGridSpacing {
2317
- cx: number;
2318
- cy: number;
2319
- }
2320
- /**
2321
- * Restored region dimensions for normal view splitter.
2322
- * Represents `p:restoredLeft` or `p:restoredTop`.
2323
- */
2324
- interface PptxRestoredRegion {
2325
- /** Size as a percentage of the available space (thousandths of a percent). */
2326
- sz: number;
2327
- /** Whether auto-adjust is enabled. */
2328
- autoAdjust?: boolean;
2329
- }
2330
- /**
2331
- * Normal view properties (`p:normalViewPr`).
2332
- * Controls the splitter positions in normal (editing) view.
2333
- */
2334
- interface PptxNormalViewProperties {
2335
- /** Whether to show outline icons in the slide panel. */
2336
- showOutlineIcons?: boolean;
2337
- /** Whether the outline/slide panel is snapped closed. */
2338
- snapVertSplitter?: boolean;
2339
- /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */
2340
- vertBarState?: string;
2341
- /** Horizontal splitter bar state. */
2342
- horzBarState?: string;
2343
- /** Whether to prefer single-slide view in the panel. */
2344
- preferSingleView?: boolean;
2345
- /** Restored left region (slide panel width). */
2346
- restoredLeft?: PptxRestoredRegion;
2347
- /** Restored top region (notes panel height). */
2348
- restoredTop?: PptxRestoredRegion;
2349
- }
2350
- /**
2351
- * Common slide view properties shared by slideViewPr, outlineViewPr,
2352
- * notesTextViewPr, and notesViewPr.
2353
- */
2354
- interface PptxCommonSlideViewProperties {
2355
- /** Whether snap-to-grid is enabled. */
2356
- snapToGrid?: boolean;
2357
- /** Whether snap-to-objects is enabled. */
2358
- snapToObjects?: boolean;
2359
- /** Whether drawing guides are shown. */
2360
- showGuides?: boolean;
2361
- /** Whether the application may vary the scale automatically. */
2362
- variableScale?: boolean;
2363
- /** Drawing guides shown in this slide view. */
2364
- guides?: PptxViewGuide[];
2365
- /** View origin (scroll position). */
2366
- origin?: PptxViewOrigin;
2367
- /** View scale. */
2368
- scale?: PptxViewScale;
2369
- }
2370
- /**
2371
- * Full view properties from `ppt/viewProps.xml`.
2372
- */
2373
- interface PptxViewProperties {
2374
- /** Last used view type (`p:viewPr/@lastView`). */
2375
- lastView?: string;
2376
- /** Whether comments are shown (`p:viewPr/@showComments`). */
2377
- showComments?: boolean;
2378
- /** Normal view properties (splitter positions). */
2379
- normalViewPr?: PptxNormalViewProperties;
2380
- /** Slide view properties. */
2381
- slideViewPr?: PptxCommonSlideViewProperties;
2382
- /** Outline view properties. */
2383
- outlineViewPr?: PptxCommonSlideViewProperties;
2384
- /** Notes text view properties. */
2385
- notesTextViewPr?: PptxCommonSlideViewProperties;
2386
- /** Sorter view scale. */
2387
- sorterViewPr?: {
2388
- scale?: PptxViewScale;
2389
- };
2390
- /** Notes view properties. */
2391
- notesViewPr?: PptxCommonSlideViewProperties;
2392
- /** Grid spacing in positive DrawingML coordinates. */
2393
- gridSpacing?: PptxGridSpacing;
2394
- /** Raw XML preserved for lossless round-trip of unparsed attributes. */
2395
- rawXml?: Record<string, unknown>;
2396
- }
2397
- /**
2398
- * A customer data reference from `p:custDataLst / p:custData`.
2399
- *
2400
- * Enterprise add-ins and integrations store custom data parts in the
2401
- * package and reference them via relationship IDs in the slide or
2402
- * presentation XML.
2403
- *
2404
- * @see ECMA-376 Part 1, §19.2.1.3 (custDataLst), §19.3.1.6 (custData)
2405
- */
2406
- interface PptxCustomerData {
2407
- /** Resolved part path inside the package (e.g. `customXml/item1.xml`). */
2408
- id?: string;
2409
- /** Relationship ID referencing the custom data part. */
2410
- relId?: string;
2411
- /** Raw string content of the custom data part (if resolvable). */
2412
- data?: string;
2413
- /** OPC content type for the custom data part. */
2414
- contentType?: string;
2415
- /** Raw `p:custData` XML retained for unknown-node preservation. */
2416
- rawXml?: XmlObject;
2417
- }
2418
- /**
2419
- * An ActiveX control reference from `p:controls / p:control`.
2420
- *
2421
- * ActiveX form controls (buttons, text boxes, check boxes, combo boxes, etc.)
2422
- * are embedded via OLE parts and referenced by relationship ID in the slide XML.
2423
- *
2424
- * @see ECMA-376 Part 1, §19.3.1.3 (controls), §19.3.1.2 (control)
2425
- */
2426
- interface PptxActiveXControl {
2427
- /** Relationship ID referencing the ActiveX binary part. */
2428
- relId: string;
2429
- /** Control name from @name attribute. */
2430
- name?: string;
2431
- /** Shape ID this control is linked to (from @spid). */
2432
- shapeId?: string;
2433
- /**
2434
- * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the
2435
- * control renders as its static icon rather than its live appearance.
2436
- * `undefined` when the source authored no explicit value (schema default
2437
- * `false`).
2438
- */
2439
- showAsIcon?: boolean;
2440
- /**
2441
- * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host
2442
- * reserves for the control's icon/preview image. Distinct from
2443
- * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px;
2444
- * `imgW`/`imgH` are direct attributes on `p:control` itself.
2445
- */
2446
- imgWidthEmu?: number;
2447
- /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */
2448
- imgHeightEmu?: number;
2449
- /** X position (px) of the control's fallback picture, if present. */
2450
- x?: number;
2451
- /** Y position (px) of the control's fallback picture, if present. */
2452
- y?: number;
2453
- /** Width (px) of the control's fallback picture, if present. */
2454
- width?: number;
2455
- /** Height (px) of the control's fallback picture, if present. */
2456
- height?: number;
2457
- /**
2458
- * Relationship ID of the control's static fallback picture
2459
- * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`).
2460
- * Renderers resolve this to an image so a control shows its last static
2461
- * frame instead of a blank area (the live ActiveX cannot run in a viewer).
2462
- */
2463
- fallbackImageRelId?: string;
2464
- /** Raw XML for round-trip preservation. */
2465
- rawXml?: XmlObject;
2466
- }
2467
- /**
2468
- * Pattern fill on a slide background.
2469
- *
2470
- * Mirrors the `<a:pattFill>` choice inside `<p:bgPr>`. Renderers should
2471
- * draw a 2-colour preset pattern (e.g. `dkDnDiag`, `pct50`).
2472
- *
2473
- * ECMA-376 §20.1.8.47.
2474
- *
2475
- * @example
2476
- * ```ts
2477
- * const pattern: PptxSlideBackgroundPattern = {
2478
- * preset: "ltDnDiag",
2479
- * fgColor: "#4472C4",
2480
- * bgColor: "#FFFFFF",
2481
- * };
2482
- * // => satisfies PptxSlideBackgroundPattern
2483
- * ```
2484
- */
2485
- interface PptxSlideBackgroundPattern {
2486
- /** DrawingML preset pattern token (`@_prst`). */
2487
- preset: string;
2488
- /** Foreground colour resolved to `#RRGGBB`. */
2489
- fgColor?: string;
2490
- /** Background colour resolved to `#RRGGBB`. */
2491
- bgColor?: string;
2492
- }
2493
- /**
2494
- * A slide background gradient in the shape-fill model (the gradient fields
2495
- * of {@link ShapeStyle}), so the save path writes it with the same
2496
- * `a:gradFill` writer as a shape's gradient. Stop positions are 0-100 and the
2497
- * angle follows `a:lin/@ang` (degrees clockwise from the positive x-axis).
2498
- */
2499
- type PptxSlideBackgroundGradient = Pick<ShapeStyle, 'fillGradientStops' | 'fillGradientType' | 'fillGradientAngle' | 'fillGradientPathType' | 'fillGradientFillToRect'>;
2500
- /**
2501
- * A single slide in a parsed PPTX presentation.
2502
- *
2503
- * Contains the element tree, background settings, notes, comments,
2504
- * transition / animation data, and metadata like layout path and section.
2505
- *
2506
- * @example
2507
- * ```ts
2508
- * const slide: PptxSlide = {
2509
- * id: "slide1",
2510
- * rId: "rId2",
2511
- * slideNumber: 1,
2512
- * elements: [titleTextBox, subtitleTextBox],
2513
- * backgroundColor: "#FFFFFF",
2514
- * notes: "Remember to mention quarterly goals.",
2515
- * };
2516
- * // => satisfies PptxSlide
2517
- * ```
2518
- */
2519
- interface PptxSlide {
2520
- id: string;
2521
- rId: string;
2522
- /**
2523
- * `p:sldIdLst/p:sldId/@id` (ST_SlideId, 256..2147483647): the numeric key
2524
- * that sections (`p14:sldIdLst/p14:sldId/@id`) and section/summary zooms
2525
- * name slides by.
2526
- *
2527
- * It lives in `presentation.xml`, NOT in the slide part, so it cannot be
2528
- * recovered from `rawXml`. Without it on the model, code that writes a
2529
- * section's membership has nothing correct to write and falls back to the
2530
- * slide NUMBER, which is 1-based and therefore never matches a real deck's
2531
- * ids: the section reloads with no slides in it.
2532
- */
2533
- slideId?: string;
2534
- sourceSlideId?: string;
2535
- /**
2536
- * The slide name, `p:cSld/@name`: loaded from the part, written back on
2537
- * save (an empty string clears the attribute), and settable via
2538
- * `SlideBuilder.setName`.
2539
- */
2540
- name?: string;
2541
- layoutPath?: string;
2542
- layoutName?: string;
2543
- slideNumber: number;
2544
- hidden?: boolean;
2545
- sectionName?: string;
2546
- sectionId?: string;
2547
- elements: PptxElement[];
2548
- backgroundColor?: string;
2549
- backgroundImage?: string;
2550
- /** Crop, tiling and image effects authored on the background blip fill. */
2551
- backgroundImageProperties?: PptxImageProperties;
2552
- backgroundGradient?: string;
2553
- /**
2554
- * The structured form of {@link backgroundGradient}, set by
2555
- * `SlideBuilder.setBackground`. Saved as `p:bg/p:bgPr/a:gradFill` while
2556
- * `backgroundGradient` is still the CSS built from it
2557
- * (`slideBackgroundGradientCss`); an edit that replaces or clears the CSS
2558
- * gradient wins over a stale structured one.
2559
- */
2560
- backgroundGradientFill?: PptxSlideBackgroundGradient;
2561
- /**
2562
- * The theme background style (Design > Background Styles) this slide uses: a
2563
- * `<p:bgRef idx="1001..1003">` on `bg1`/`bg2`, or `kind: 'inherit'` for "follow master".
2564
- * Read at load; set by the Background Styles gallery and written back on save. The flat
2565
- * `backgroundColor`/`backgroundGradient` stay the painted values.
2566
- */
2567
- backgroundStyleRef?: PptxSlideBackgroundStyleRef;
2568
- /**
2569
- * Pattern fill on the slide background (`<a:pattFill>` inside `<p:bgPr>`).
2570
- *
2571
- * When present, renderers should draw a real two-colour pattern using
2572
- * the named DrawingML preset (e.g. `"ltDnDiag"`, `"pct50"`). The flat
2573
- * `backgroundColor` field is left set to the foreground colour for
2574
- * fallback rendering paths that don't understand patterns.
2575
- *
2576
- * ECMA-376 §20.1.8.47.
2577
- */
2578
- backgroundPattern?: PptxSlideBackgroundPattern;
2579
- /**
2580
- * `<p:bgPr/@shadeToTitle>`: boolean flag instructing the renderer to
2581
- * anchor the background gradient on the title placeholder as a
2582
- * rectangular path gradient (COM-measured against real PowerPoint;
2583
- * it does NOT recolour toward the title's text colour, despite the
2584
- * attribute's name). Parsed and round-tripped here on the core model;
2585
- * the actual visual effect is applied by `pptx-viewer-shared`'s
2586
- * `getSlideBackgroundStyle` (see `render/background-shade-to-title.ts`),
2587
- * consumed by all five bindings, not by core itself. Legacy PowerPoint
2588
- * 97-2003 hint, not observed in any real-world corpus file this project
2589
- * has collected and not settable from any modern PowerPoint UI; see
2590
- * `docs/guide/limitations.md`.
2591
- *
2592
- * ECMA-376 §19.3.1.2 (CT_BackgroundProperties).
2593
- */
2594
- backgroundShadeToTitle?: boolean;
2595
- transition?: PptxSlideTransition;
2596
- animations?: PptxElementAnimation[];
2597
- /**
2598
- * Read-only anchors for the deck's own (non-editor-authored) effect
2599
- * groups, merged with `animations` by the authoring UI so drag-to-reorder
2600
- * can target any position in the full sequence. See
2601
- * {@link PptxAnimationTimelineAnchor}.
2602
- */
2603
- animationTimelineAnchors?: PptxAnimationTimelineAnchor[];
2604
- /** Native OOXML animation data parsed from `p:timing`. */
2605
- nativeAnimations?: PptxNativeAnimation[];
2606
- /** Preserved raw `p:timing` XML for lossless round-trip of native animations. */
2607
- rawTiming?: XmlObject;
2608
- notes?: string;
2609
- /** Rich text segments for the slide notes (preserves formatting). */
2610
- notesSegments?: TextSegment[];
2611
- /**
2612
- * Parsed shapes from the notes slide's `<p:cSld>/<p:spTree>` so the full
2613
- * notes-page shape tree can be inspected and mutated, not just the body
2614
- * placeholder text. When undefined, the existing notes XML is left
2615
- * untouched on save and only `notes` / `notesSegments` are written.
2616
- */
2617
- notesShapes?: PptxElement[];
2618
- /**
2619
- * Per-notes-slide colour map override parsed from `<p:notes>/<p:clrMapOvr>`.
2620
- * Captured for lossless round-trip of the notes-slide's colour scheme.
2621
- */
2622
- notesClrMapOverride?: Record<string, string>;
2623
- /** Optional `<p:cSld @name>` value of the notes slide, for round-trip. */
2624
- notesCSldName?: string;
2625
- comments?: PptxComment[];
2626
- /** Source package metadata for an Office 2021 p188 comment part. */
2627
- modernCommentPart?: PptxModernCommentPart;
2628
- warnings?: PptxCompatibilityWarning[];
2629
- rawXml?: XmlObject;
2630
- /** Per-slide colour map override parsed from `p:clrMapOvr`. */
2631
- clrMapOverride?: Record<string, string>;
2632
- /** Whether background animations should play (`p:bg/@showAnimation`). */
2633
- backgroundShowAnimation?: boolean;
2634
- /** Whether master slide shapes should be shown on this slide (`p:sld/@showMasterSp`). */
2635
- showMasterShapes?: boolean;
2636
- /**
2637
- * Whether inherited master placeholder animations should replay on this
2638
- * slide (`p:sld/@showMasterPhAnim`). Distinct from {@link showMasterShapes}:
2639
- * this governs animation timing, not shape visibility. Mirrors
2640
- * `p:sldLayout/@showMasterPhAnim`, ECMA-376 §19.3.1.38.
2641
- */
2642
- showMasterPhAnim?: boolean;
2643
- /** Drawing guides parsed from slide extension list. */
2644
- guides?: PptxDrawingGuide[];
2645
- /** When explicitly `false`, the slide is unmodified and save can skip re-serialization. */
2646
- isDirty?: boolean;
2647
- /** Customer data references from `p:custDataLst` on this slide. */
2648
- customerData?: PptxCustomerData[];
2649
- /** ActiveX control references from `p:controls` on this slide. */
2650
- activeXControls?: PptxActiveXControl[];
2651
- /**
2652
- * Shapes parsed from a referenced legacy VML drawing part
2653
- * (`ppt/drawings/vmlDrawing*.vml`, linked via a `legacyDrawing`
2654
- * relationship). These are read-only render hints: the VML part itself is
2655
- * preserved verbatim on save, so this field is not re-serialized.
2656
- */
2657
- legacyVmlElements?: PptxElement[];
2658
- /** Per-slide header/footer flags from `<p:hf>` (P-H3). */
2659
- headerFooterFlags?: PptxHeaderFooterFlags;
2660
- /** Server-backed slide synchronization metadata stored in a related OPC part. */
2661
- slideSynchronization?: PptxSlideSyncProperties;
2662
- }
2663
- interface PptxModernCommentPart {
2664
- path: string;
2665
- relationshipId: string;
2666
- /** Original p188:cmLst root, including unknown attributes and extensions. */
2667
- rawXml?: XmlObject;
2668
- }
2669
- /** Metadata from a `p:sldSyncPr` slide synchronization data part. */
2670
- interface PptxSlideSyncProperties {
2671
- serverSlideId: string;
2672
- serverSlideModifiedTime: string;
2673
- clientInsertedTime: string;
2674
- extensionList?: XmlObject;
2675
- rawXml?: XmlObject;
2676
- partPath?: string;
2677
- relationshipId?: string;
2678
- }
2679
- /**
2680
- * A slide layout available in the loaded presentation.
2681
- *
2682
- * Each entry maps to a `<p:sldLayout>` inside `ppt/slideLayouts/`.
2683
- *
2684
- * @example
2685
- * ```ts
2686
- * const layout: PptxLayoutOption = {
2687
- * path: "ppt/slideLayouts/slideLayout2.xml",
2688
- * name: "Title and Content",
2689
- * };
2690
- * // => satisfies PptxLayoutOption
2691
- * ```
2692
- */
2693
- interface PptxLayoutOption {
2694
- path: string;
2695
- name: string;
2696
- /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */
2697
- type?: string;
2698
- /** ZIP path of the slide master this layout belongs to. */
2699
- masterPath?: string;
2700
- }
2701
- /**
2702
- * Header, footer, date-time, and slide-number placeholders.
2703
- *
2704
- * Parsed from `ppt/presProps.xml` and individual slide layouts.
2705
- *
2706
- * @example
2707
- * ```ts
2708
- * const hf: PptxHeaderFooter = {
2709
- * hasFooter: true,
2710
- * footerText: "Confidential",
2711
- * hasSlideNumber: true,
2712
- * };
2713
- * // => satisfies PptxHeaderFooter
2714
- * ```
2715
- */
2716
- interface PptxHeaderFooter {
2717
- hasHeader?: boolean;
2718
- headerText?: string;
2719
- hasFooter?: boolean;
2720
- footerText?: string;
2721
- hasDateTime?: boolean;
2722
- dateTimeText?: string;
2723
- dateTimeAuto?: boolean;
2724
- /**
2725
- * The master date placeholder's own `a:fld/@type` (e.g. "datetime2"), NOT a
2726
- * format pattern. It is one of the predefined OOXML datetime field types
2727
- * (`datetime1`-`datetime13`); the display pattern for each is resolved by
2728
- * `resolveFieldDateText` in `packages/shared/src/render/text-field-substitution.ts`.
2729
- */
2730
- dateFormat?: string;
2731
- hasSlideNumber?: boolean;
2732
- }
2733
- /**
2734
- * Presentation-level properties parsed from `presentationPr.xml`.
2735
- *
2736
- * Controls slideshow behaviour, print settings, custom colours, and grid.
2737
- *
2738
- * @example
2739
- * ```ts
2740
- * const props: PptxPresentationProperties = {
2741
- * showType: "presented",
2742
- * loopContinuously: false,
2743
- * advanceMode: "useTimings",
2744
- * };
2745
- * // => satisfies PptxPresentationProperties
2746
- * ```
2747
- */
2748
- interface PptxPresentationProperties {
2749
- /** Show type: presented, browsed, kiosk. */
2750
- showType?: 'presented' | 'browsed' | 'kiosk';
2751
- /** Whether to loop the slideshow continuously. */
2752
- loopContinuously?: boolean;
2753
- /** Whether to show without narration. */
2754
- showWithNarration?: boolean;
2755
- /** Whether to show without animation. */
2756
- showWithAnimation?: boolean;
2757
- /** Advance slides mode: manual click or use stored timings. */
2758
- advanceMode?: 'manual' | 'useTimings';
2759
- /** Show slides: 'all', a custom show id, or a from-to range. */
2760
- showSlidesMode?: 'all' | 'customShow' | 'range';
2761
- /** Custom show id to use when showSlidesMode is 'customShow'. */
2762
- showSlidesCustomShowId?: string;
2763
- /** Slide range start (1-based) when showSlidesMode is 'range'. */
2764
- showSlidesFrom?: number;
2765
- /** Slide range end (1-based) when showSlidesMode is 'range'. */
2766
- showSlidesTo?: number;
2767
- /** Whether to show subtitles/captions during presentation mode. */
2768
- showSubtitles?: boolean;
2769
- /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
2770
- printProperties?: PptxPresentationPrintProperties | null;
2771
- /** Most-recently-used colours from the presentation palette. */
2772
- mruColors?: string[];
2773
- /**
2774
- * Pen colour for presentation mode annotations (from `p:showPr/p:penClr`).
2775
- * `p:penClr` is a full `EG_ColorChoice` (P1-G2): a scheme/preset/system
2776
- * swatch resolves to a hex string here just like a direct `a:srgbClr`.
2777
- */
2778
- penColor?: string;
2779
- /**
2780
- * The resolved hex value {@link penColor} had at parse time, and the
2781
- * original `p:penClr` colour-choice XML node, preserved so a save that
2782
- * never touches the pen colour re-emits the original scheme/preset
2783
- * reference verbatim instead of flattening it to a baked `a:srgbClr`.
2784
- * Internal round-trip bookkeeping; not meant to be set by API callers.
2785
- */
2786
- penColorOriginal?: string;
2787
- /** @see penColorOriginal */
2788
- penColorXml?: XmlObject;
2789
- /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
2790
- kioskRestartTime?: number;
2791
- /**
2792
- * `p:showPr/p:browse/@showScrollbar` (CT_ShowInfoBrowse §19.2.1.10 /
2793
- * §19.3.1.43), the "Show scrollbar" checkbox in PowerPoint's Set Up Show
2794
- * dialog. Only meaningful when `showType` is `"browsed"`; the schema
2795
- * default is `true`. `undefined` means the source authored no explicit
2796
- * value (or `showType` is not `"browsed"`).
2797
- */
2798
- showScrollbar?: boolean;
2799
- }
2800
- /**
2801
- * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39).
2802
- *
2803
- * @example
2804
- * ```ts
2805
- * const size: PptxSlideSize = { widthEmu: 9144000, heightEmu: 6858000, type: 'screen4x3' };
2806
- * // => satisfies PptxSlideSize
2807
- * ```
2808
- */
2809
- interface PptxSlideSize {
2810
- /** `@cx` in EMU. Omitted or non-positive values leave the loaded width alone. */
2811
- widthEmu?: number;
2812
- /** `@cy` in EMU. Omitted or non-positive values leave the loaded height alone. */
2813
- heightEmu?: number;
2814
- /**
2815
- * `@type` (ST_SlideSizeType). The schema default is `custom`, which is
2816
- * why PowerPoint omits the attribute for a non-preset size.
2817
- */
2818
- type?: string;
2819
- }
2820
- /**
2821
- * A named custom slide show (`p:custShowLst / p:custShow`).
2822
- *
2823
- * Custom shows define ordered subsets of slides that can be presented
2824
- * independently of the full deck.
2825
- *
2826
- * @example
2827
- * ```ts
2828
- * const show: PptxCustomShow = {
2829
- * name: "Executive Summary",
2830
- * id: "0",
2831
- * slideRIds: ["rId2", "rId5", "rId8"],
2832
- * };
2833
- * // => satisfies PptxCustomShow
2834
- * ```
2835
- */
2836
- interface PptxCustomShow {
2837
- /** Custom show name. */
2838
- name: string;
2839
- /** Custom show id. */
2840
- id: string;
2841
- /** Ordered list of slide relationship IDs included in this custom show. */
2842
- slideRIds: string[];
2843
- /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
2844
- rawXml?: XmlObject;
2845
- }
2846
- /**
2847
- * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
2848
- *
2849
- * Sections group consecutive slides under a named heading (visible
2850
- * in the PowerPoint slide sorter).
2851
- *
2852
- * @example
2853
- * ```ts
2854
- * const section: PptxSection = {
2855
- * id: "sec_1",
2856
- * name: "Introduction",
2857
- * slideIds: ["256", "257"],
2858
- * };
2859
- * // => satisfies PptxSection
2860
- * ```
2861
- */
2862
- interface PptxSection {
2863
- /** Section unique identifier (GUID or synthetic). */
2864
- id: string;
2865
- /** Human-readable section name. */
2866
- name: string;
2867
- /** Ordered list of numeric slide IDs that belong to this section. */
2868
- slideIds: string[];
2869
- /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
2870
- collapsed?: boolean;
2871
- /** Section highlight color hex (from p15:sectionPr/@clr). */
2872
- color?: string;
2873
- /** Original section subtree used to preserve unmodelled attributes and extensions. */
2874
- rawXml?: XmlObject;
2875
- }
2876
- /**
2877
- * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
2878
- *
2879
- * When present, the presentation is marked as "read-only recommended" or
2880
- * write-protected with a password hash. The hash parameters follow the
2881
- * ECMA-376 Part 1, section 19.2.1.22 specification.
2882
- *
2883
- * @example
2884
- * ```ts
2885
- * const verifier: PptxModifyVerifier = {
2886
- * algorithmName: "SHA-512",
2887
- * hashData: "base64EncodedHash==",
2888
- * saltData: "base64EncodedSalt==",
2889
- * spinValue: 100000,
2890
- * };
2891
- * // => satisfies PptxModifyVerifier
2892
- * ```
2893
- */
2894
- interface PptxModifyVerifier {
2895
- /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
2896
- algorithmName?: string;
2897
- /** Base64-encoded hash value. */
2898
- hashData?: string;
2899
- /** Base64-encoded salt value. */
2900
- saltData?: string;
2901
- /** Number of hash iterations (spin count). */
2902
- spinValue?: number;
2903
- /** Legacy algorithm ID extension. */
2904
- algIdExt?: string;
2905
- /** Legacy algorithm ID. */
2906
- cryptAlgorithmSid?: number;
2907
- /** Cryptographic algorithm type (e.g. "typeAny"). */
2908
- cryptAlgorithmType?: string;
2909
- /** Cryptographic provider name. */
2910
- cryptProvider?: string;
2911
- /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
2912
- cryptProviderType?: string;
2913
- /** Cryptographic algorithm class (e.g. "hash"). */
2914
- cryptAlgorithmClass?: string;
2915
- }
2916
- /**
2917
- * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
2918
- *
2919
- * Stores settings for presentations created via Insert > Photo Album.
2920
- *
2921
- * @see ECMA-376 Part 1, §19.2.1.27
2922
- */
2923
- interface PptxPhotoAlbum {
2924
- /** Whether photos are displayed in black-and-white. */
2925
- bw?: boolean;
2926
- /** Whether captions are shown below each photo. */
2927
- showCaptions?: boolean;
2928
- /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
2929
- layout?: string;
2930
- /** Frame style applied to each photo (e.g. "frameStyle1"). */
2931
- frame?: string;
2932
- /**
2933
- * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether
2934
- * the pictures placed by the album wizard are real photographs, as
2935
- * opposed to clip art or other embedded images. `undefined` when the
2936
- * source authored no explicit value (schema default `false`); this is a
2937
- * purely declarative wizard-provenance flag, not something this library
2938
- * gates any layout/frame behaviour on.
2939
- */
2940
- isPhoto?: boolean;
2941
- }
2942
- /**
2943
- * A recognizer-owned `p:smartTags` reference from `presentation.xml`
2944
- * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a
2945
- * legacy Office "Smart Tags" recognizer part, distinct from the
2946
- * user-authored `p:tags` construct (see {@link PptxTagCollection}).
2947
- *
2948
- * This library has no data model for recognizer part CONTENT (there is no
2949
- * way to create, inspect, or edit one through the public API), so this type
2950
- * only captures enough to preserve an authored reference losslessly: the
2951
- * relationship id and, when resolvable, the target part path.
2952
- */
2953
- interface PptxSmartTagsReference {
2954
- /** Relationship id from `p:smartTags/@r:id`. */
2955
- relId: string;
2956
- /** Resolved ZIP path of the referenced recognizer part, when resolvable. */
2957
- targetPath?: string;
2958
- /** Raw `p:smartTags` XML retained for lossless round-trip. */
2959
- rawXml?: XmlObject;
2960
- }
2961
- /**
2962
- * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
2963
- *
2964
- * Defines forbidden start/end characters for a given language so that
2965
- * line-breaking follows East Asian typographic rules.
2966
- *
2967
- * @see ECMA-376 Part 1, §19.2.1.17
2968
- */
2969
- interface PptxKinsoku {
2970
- /** Language code (e.g. "ja-JP", "zh-CN"). */
2971
- lang?: string | null;
2972
- /** Characters that cannot begin a line. */
2973
- invalStChars?: string;
2974
- /** Characters that cannot end a line. */
2975
- invalEndChars?: string;
2976
- /** Original leaf retained for unknown attribute preservation. */
2977
- rawXml?: XmlObject;
2978
- }
2979
- /**
2980
- * Root data structure returned by {@link PptxHandlerCore.load}.
2981
- *
2982
- * Contains every slide, canvas dimensions, theme data, layout options,
2983
- * metadata, and optional features (custom shows, sections, macros,
2984
- * digital signatures, embedded fonts).
2985
- *
2986
- * @example
2987
- * ```ts
2988
- * const data: PptxData = await handler.load(buffer);
2989
- * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
2990
- * // => e.g. "24 slides, 960×540"
2991
- * ```
2992
- */
2993
- interface PptxData {
2994
- slides: PptxSlide[];
2995
- width: number;
2996
- height: number;
2997
- /** Slide width in EMU (for save round-trip). */
2998
- widthEmu?: number;
2999
- /** Slide height in EMU (for save round-trip). */
3000
- heightEmu?: number;
3001
- /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
3002
- slideSizeType?: string;
3003
- /** Notes page width in EMU (from `p:notesSz`). */
3004
- notesWidthEmu?: number;
3005
- /** Notes page height in EMU (from `p:notesSz`). */
3006
- notesHeightEmu?: number;
3007
- layoutOptions?: PptxLayoutOption[];
3008
- headerFooter?: PptxHeaderFooter;
3009
- /** Presentation-level properties parsed from `presentationPr.xml`. */
3010
- presentationProperties?: PptxPresentationProperties;
3011
- /** Named custom slide shows from `p:custShowLst`. */
3012
- customShows?: PptxCustomShow[];
3013
- /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
3014
- sections?: PptxSection[];
3015
- warnings?: PptxCompatibilityWarning[];
3016
- /** Map of theme colour scheme keys to resolved hex values. */
3017
- themeColorMap?: Record<string, string>;
3018
- /** Full parsed theme object with colours, fonts, and name. */
3019
- theme?: PptxTheme;
3020
- /** Available theme parts discovered in `ppt/theme/`. */
3021
- themeOptions?: PptxThemeOption[];
3022
- /** Real theme variants from the package's `themeVariants/` parts, when it has any. */
3023
- themeVariants?: PptxThemeVariant[];
3024
- /** Parsed table style definitions from `ppt/tableStyles.xml`. */
3025
- tableStyleMap?: ParsedTableStyleMap;
3026
- /**
3027
- * The current default table style GUID (`ppt/tableStyles.xml`'s
3028
- * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted
3029
- * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call
3030
- * that omits it can fall back to what was loaded.
3031
- */
3032
- tableStylesDefaultId?: string;
3033
- /** Whether the presentation is password-protected. */
3034
- isPasswordProtected?: boolean;
3035
- /** Embedded font data (name + binary data URL) extracted from the presentation. */
3036
- embeddedFonts?: PptxEmbeddedFont[];
3037
- /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */
3038
- embeddedFontList?: PptxEmbeddedFontList;
3039
- /**
3040
- * `p:presentation/@embedTrueTypeFonts` (ECMA-376 §19.2.1.26): the author's
3041
- * saved preference that TrueType fonts referenced by the deck be embedded.
3042
- * `undefined` when the attribute is absent (spec default `false`).
3043
- *
3044
- * This is purely declarative in this library: fonts are only ever embedded
3045
- * when the caller explicitly supplies `embeddedFontList`/`embeddedFonts`
3046
- * (there is no automatic embed-on-save), so toggling this flag does not
3047
- * gate any embedding behaviour of its own here - it only round-trips the
3048
- * author's stated preference, the same way real PowerPoint reads it back
3049
- * as a checkbox state rather than a trigger. See `@saveSubsetFonts`,
3050
- * which is a separate, deliberately unimplemented flag (no glyph
3051
- * subsetting) that does not interact with this one.
3052
- */
3053
- embedTrueTypeFonts?: boolean;
3054
- /**
3055
- * `p:presentation/@firstSlideNum`: a `slidenum` field on slide `i` (0-based)
3056
- * shows `firstSlideNumber + i`. Absent means the spec default, 1.
3057
- */
3058
- firstSlideNumber?: number;
3059
- /**
3060
- * Presentation-level default text style (`p:defaultTextStyle`): the
3061
- * last-resort paragraph/run-property fallback for every shape (placeholder
3062
- * or not) whose local and inherited cascade leaves a field undefined.
3063
- * Keyed the same way as {@link PptxMasterTextStyles} categories: `-1` is
3064
- * `a:defPPr`, `0`-`8` are `a:lvl1pPr`-`a:lvl9pPr`.
3065
- */
3066
- defaultTextStyle?: PptxTextStyleLevels;
3067
- /** Most-recently-used colour list from presentation properties. */
3068
- mruColors?: string[];
3069
- /** Parsed notes master data if present in the PPTX. */
3070
- notesMaster?: PptxNotesMaster;
3071
- /** Parsed handout master data if present in the PPTX. */
3072
- handoutMaster?: PptxHandoutMaster;
3073
- /** Structured slide master data for each master in the presentation. */
3074
- slideMasters?: PptxSlideMaster[];
3075
- /** Parsed tag collections attached to the presentation or slides. */
3076
- tags?: PptxTagCollection[];
3077
- /** Custom document properties from `docProps/custom.xml`. */
3078
- customProperties?: PptxCustomProperty[];
3079
- /** Core document properties from `docProps/core.xml`. */
3080
- coreProperties?: PptxCoreProperties;
3081
- /** Extended (application) properties from `docProps/app.xml`. */
3082
- appProperties?: PptxAppProperties;
3083
- /** Whether the presentation contains VBA macros (is a .pptm file). */
3084
- hasMacros?: boolean;
3085
- /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */
3086
- hasDigitalSignatures?: boolean;
3087
- /** Number of digital signatures found. */
3088
- digitalSignatureCount?: number;
3089
- /** Presentation-level drawing guides from `p:extLst`. */
3090
- presentationGuides?: PptxDrawingGuide[];
3091
- /** View properties from `ppt/viewProps.xml`. */
3092
- viewProperties?: PptxViewProperties;
3093
- /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */
3094
- modifyVerifier?: PptxModifyVerifier;
3095
- /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
3096
- photoAlbum?: PptxPhotoAlbum;
3097
- /**
3098
- * Legacy Smart Tags recognizer reference from `p:smartTags` in
3099
- * `presentation.xml`. Read-only: there is no data model for the
3100
- * recognizer part's own content, so this exists to make the reference
3101
- * inspectable and to prove it survives a save (the owning part and its
3102
- * relationship are preserved passively, like any other unmodelled part).
3103
- */
3104
- smartTags?: PptxSmartTagsReference;
3105
- /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
3106
- kinsoku?: PptxKinsoku;
3107
- /** Custom XML data parts from `customXml/` in the OPC package. */
3108
- customXmlParts?: PptxCustomXmlPart[];
3109
- /** Customer data references from `p:custDataLst` in `presentation.xml`. */
3110
- customerData?: PptxCustomerData[];
3111
- /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */
3112
- thumbnailData?: Uint8Array;
3113
- /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */
3114
- commentAuthors?: PptxCommentAuthor[];
3115
- /** Office 2021 p188 authors from the modern Author part. */
3116
- modernCommentAuthors?: PptxModernCommentAuthor[];
3117
- /**
3118
- * OOXML conformance class of the loaded file.
3119
- * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
3120
- * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
3121
- *
3122
- * When saving, if the save option `conformance` is `'preserve'` (default),
3123
- * the file will be saved using the same conformance class as the original.
3124
- */
3125
- conformance?: 'strict' | 'transitional';
3126
- }
3127
- /**
3128
- * Target format for slide export.
3129
- *
3130
- * @see {@link PptxExportOptions}
3131
- */
3132
- type PptxExportFormat = 'pdf' | 'png' | 'svg';
3133
- /**
3134
- * Options controlling slide export to raster or vector formats.
3135
- *
3136
- * @example
3137
- * ```ts
3138
- * const opts: PptxExportOptions = {
3139
- * format: "png",
3140
- * slideIndices: [0, 2, 4],
3141
- * dpi: 300,
3142
- * };
3143
- * // => satisfies PptxExportOptions
3144
- * ```
3145
- */
3146
- interface PptxExportOptions {
3147
- /** Target format. */
3148
- format: PptxExportFormat;
3149
- /** Slide indices to export (0-based). If omitted, all slides are exported. */
3150
- slideIndices?: number[];
3151
- /** Output width in pixels (for PNG). Height is derived from aspect ratio. */
3152
- width?: number;
3153
- /** DPI for raster export (default 150). */
3154
- dpi?: number;
3155
- /** Whether to include hidden slides. */
3156
- includeHidden?: boolean;
3157
- }
3158
- /**
3159
- * Embedded font data extracted from a PPTX file.
3160
- *
3161
- * Used to register `@font-face` rules so the renderer can display
3162
- * the correct typeface even when the system font is missing.
3163
- *
3164
- * @example
3165
- * ```ts
3166
- * const font: PptxEmbeddedFont = {
3167
- * name: "CustomSans",
3168
- * dataUrl: "data:font/truetype;base64,AAEAK...",
3169
- * format: "truetype",
3170
- * };
3171
- * // => satisfies PptxEmbeddedFont
3172
- * ```
3173
- */
3174
- /**
3175
- * A single Custom XML Data Part stored in `customXml/` within the OPC package.
3176
- *
3177
- * These parts are used by add-ins, data-binding, and enterprise templates
3178
- * to store structured data alongside the presentation.
3179
- *
3180
- * @see ECMA-376 Part 1, §15.2.5
3181
- */
3182
- interface PptxCustomXmlPart {
3183
- /** Item number (e.g. "1" for `customXml/item1.xml`). */
3184
- id: string;
3185
- /** Raw XML string content of the custom XML item. */
3186
- data: string;
3187
- /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
3188
- schemaUri?: string;
3189
- /** Raw XML string content of the associated `itemProps` file. */
3190
- properties?: string;
3191
- /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
3192
- rels?: string;
3193
- }
3194
- interface PptxEmbeddedFont {
3195
- name: string;
3196
- /**
3197
- * `data:` URL of the clear-text font. On a font returned by
3198
- * `PptxHandler.load()` this is decoded on first read (see {@link load});
3199
- * it is an empty string when the part cannot be decoded.
3200
- */
3201
- dataUrl: string;
3202
- /**
3203
- * Decode this variant, if it has not been decoded yet, and resolve to the
3204
- * same descriptor, or to `null` when its part cannot be decoded. Repeated
3205
- * calls share one promise. Present on fonts returned by
3206
- * `PptxHandler.load()` without `eagerDecodeEmbeddedFonts`; absent on
3207
- * eagerly decoded and host-supplied fonts. Not enumerable, so it is not
3208
- * part of spread, cloned or serialised font data. Decoding runs on the
3209
- * calling thread.
3210
- */
3211
- load?: () => Promise<PptxEmbeddedFont | null>;
3212
- /**
3213
- * Whether a deferred variant has been decoded (successfully or not).
3214
- * `undefined` on fonts that are not deferred. Not enumerable.
3215
- */
3216
- readonly isLoaded?: boolean;
3217
- bold?: boolean;
3218
- italic?: boolean;
3219
- /** CSS font format hint (e.g. "truetype", "opentype"). */
3220
- format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
3221
- /**
3222
- * Deobfuscated (clear-text) font binary data preserved from load
3223
- * for round-trip re-embedding on save. When present, the save
3224
- * pipeline will re-obfuscate and write this data back into the ZIP.
3225
- * Decoded on first read for deferred fonts, like {@link dataUrl}; saving
3226
- * a deferred font that was never decoded writes its original part bytes.
3227
- */
3228
- rawFontData?: Uint8Array;
3229
- /**
3230
- * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
3231
- * Preserved from load for round-trip.
3232
- */
3233
- partPath?: string;
3234
- /**
3235
- * The GUID used for obfuscation, either from the `fontKey` attribute
3236
- * or extracted from the part path. Preserved from load for round-trip.
3237
- */
3238
- fontGuid?: string;
3239
- /**
3240
- * Relationship ID (e.g. `rId21`) of the font part in
3241
- * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save
3242
- * pipeline can reuse the original part/rel instead of minting a new
3243
- * GUID-named copy alongside the stale original.
3244
- */
3245
- originalRId?: string;
3246
- /**
3247
- * Raw bytes of the original obfuscated font part exactly as they were
3248
- * stored in the source ZIP. When the loader could not determine a
3249
- * usable GUID (e.g. EOT extraction path), the save pipeline preserves
3250
- * these bytes verbatim under the original path/rel.
3251
- */
3252
- originalPartBytes?: Uint8Array;
3253
- }
3254
- /**
3255
- * Options controlling how slides are merged from source into target.
3256
- */
3257
- interface MergeOptions {
3258
- /** Which slides to take from source (0-based indices). Default: all */
3259
- slideIndices?: number[];
3260
- /** Where to insert in target (0-based). Default: end */
3261
- insertAt?: number;
3262
- /** Whether to keep source theme (false = use target theme). Default: false */
3263
- keepSourceTheme?: boolean;
3264
- }
3265
- /**
3266
- * Merge slides from a source presentation into a target.
3267
- *
3268
- * This is a data-level merge that operates on {@link PptxData} objects.
3269
- * Slides are deep-cloned from the source, re-numbered to avoid ID
3270
- * conflicts, and inserted into the target's slides array.
3271
- *
3272
- * Media embedded as data URLs (imageData, mediaData, backgroundImage,
3273
- * posterFrameData) travel with the cloned elements automatically.
3274
- *
3275
- * @param targetData - The target presentation data (will be modified in place).
3276
- * @param sourceData - The source presentation data (read-only — slides are cloned).
3277
- * @param options - Merge configuration.
3278
- * @returns Number of slides merged.
3279
- *
3280
- * @example
3281
- * ```ts
3282
- * const target = await handler.load(targetBuffer);
3283
- * const source = await handler.load(sourceBuffer);
3284
- *
3285
- * const count = mergePresentation(target, source, {
3286
- * slideIndices: [0, 2],
3287
- * insertAt: 1,
3288
- * });
3289
- * console.log(`Merged ${count} slides`);
3290
- * ```
3291
- */
3292
- declare function mergePresentation(targetData: PptxData, sourceData: PptxData, options?: MergeOptions): number;
3293
- /**
3294
- * A single text match result returned by {@link findText}.
3295
- */
3296
- interface FindResult {
3297
- /** 0-based slide index. */
3298
- slideIndex: number;
3299
- /** ID of the element containing the match. */
3300
- elementId: string;
3301
- /** Index of the text segment within the element. */
3302
- segmentIndex: number;
3303
- /** The matched text. */
3304
- text: string;
3305
- /** Character offset within the segment where the match starts. */
3306
- matchIndex: number;
3307
- }
3308
- /**
3309
- * Search for text across all slides in the presentation.
3310
- *
3311
- * Searches through all text segments in all elements (including
3312
- * group children recursively). Supports both plain string and
3313
- * RegExp patterns.
3314
- *
3315
- * @param slides - Array of slides to search.
3316
- * @param search - Plain string or RegExp to search for.
3317
- * @returns Array of match results with location information.
3318
- *
3319
- * @example
3320
- * ```ts
3321
- * const results = findText(data.slides, /Q[1-4] \d{4}/);
3322
- * console.log(`Found ${results.length} date references`);
3323
- * ```
3324
- */
3325
- declare function findText(slides: PptxSlide[], search: string | RegExp): FindResult[];
3326
- /**
3327
- * Replace all occurrences of a search pattern in a single slide's elements.
3328
- *
3329
- * Mutates the slide's elements in place. Searches through all
3330
- * text segments including group children recursively.
3331
- *
3332
- * @param slide - The slide to perform replacements on.
3333
- * @param search - Plain string or RegExp to search for.
3334
- * @param replacement - The replacement string (supports `$1`, `$&` etc. for RegExp).
3335
- * @returns The number of replacements made.
3336
- *
3337
- * @example
3338
- * ```ts
3339
- * const count = replaceTextInSlide(data.slides[0], "2025", "2026");
3340
- * console.log(`Updated ${count} occurrences on slide 1`);
3341
- * ```
3342
- */
3343
- declare function replaceTextInSlide(slide: PptxSlide, search: string | RegExp, replacement: string): number;
3344
- /**
3345
- * Replace all occurrences of a search pattern across all slides.
3346
- *
3347
- * Mutates slides' elements in place. Searches through all text
3348
- * segments including group children recursively.
3349
- *
3350
- * @param slides - Array of slides to perform replacements on.
3351
- * @param search - Plain string or RegExp to search for.
3352
- * @param replacement - The replacement string.
3353
- * @returns The total number of replacements made across all slides.
3354
- *
3355
- * @example
3356
- * ```ts
3357
- * const count = replaceText(data.slides, "Acme Corp", "NewCo Inc");
3358
- * console.log(`Rebranded ${count} occurrences`);
3359
- * ```
3360
- */
3361
- declare function replaceText(slides: PptxSlide[], search: string | RegExp, replacement: string): number;
3362
- export { PptxTextStyleLevels as $, PptxNativeAnimationKind as $t, PptxGridSpacing as A, AnimationCondition as At, PptxEmbeddedFontDataId as B, PptxAnimationRepeatMode as Bt, PptxSlide as C, TRANSITION_PATTERN_OPTIONS as Cn, PptxCompatibilityWarning as Ct, PptxSlideSyncProperties as D, PptxTag as Dt, PptxSlideSize as E, PptxModernCommentAuthor as Et, PptxViewProperties as F, PptxAnimationGraphicElementTarget as Ft, PptxHandoutMaster as G, PptxAnimationTrigger as Gt, PptxEmbeddedFontList as H, PptxAnimationTarget as Ht, PptxViewScale as I, PptxAnimationIterate as It, PptxMasterTextStyles as J, PptxElementAnimation as Jt, PptxHeaderFooterFlags as K, PptxAttributeAnimation as Kt, PptxPresentationPrintProperties as L, PptxAnimationKeyframe as Lt, PptxRestoredRegion as M, PptxAfterAnimationAction as Mt, PptxViewGuide as N, PptxAnimationDirection as Nt, PptxSmartTagsReference as O, PptxTagCollection as Ot, PptxViewOrigin as P, PptxAnimationEffectFilter as Pt, PptxSlideMaster as Q, PptxNativeAnimation as Qt, PptxPrintColorMode as R, PptxAnimationOleChartElementTarget as Rt, PptxSection as S, PptxTransitionType as Sn, PptxCommentAuthor as St, PptxSlideBackgroundPattern as T, TRANSITION_VALID_DIRECTIONS as Tn, PptxCustomProperty as Tt, PptxEmbeddedFontListEntry as U, PptxAnimationTimelineAnchor as Ut, PptxEmbeddedFontDescriptor as V, PptxAnimationSequence as Vt, MasterViewTab as W, PptxAnimationTimingCurve as Wt, PptxPlaceholderFrame as X, PptxHslColorDelta as Xt, PptxNotesMaster as Y, PptxGraphicBuild as Yt, PptxSlideLayout as Z, PptxMediaBookmarkTarget as Zt, PptxLayoutOption as _, PptxSplitOrientation as _n, PptxThemePartSchemes as _t, MergeOptions as a, PptxAnimBehavior as an, backgroundStylePreset as at, PptxPhotoAlbum as b, PptxTransitionDirection8 as bn, PptxAppProperties as bt, PptxCustomShow as c, PptxAnimRotBehavior as cn, PptxTheme as ct, PptxData as d, PptxAnimationBehaviorTiming as dn, PptxThemeFillStyle as dt, PptxSetAnimation as en, PptxThemeOption as et, PptxEmbeddedFont as f, PptxBehaviorPoint as fn, PptxThemeFontGroup as ft, PptxKinsoku as g, PptxSplitDirection as gn, PptxThemeObjectDefaults as gt, PptxHeaderFooter as h, PptxSlideTransition as hn, PptxThemeLineStyle as ht, replaceTextInSlide as i, PptxVisibilitySetTiming as in, backgroundStyleColorMap as it, PptxNormalViewProperties as j, AnimationConditionEvent as jt, PptxCommonSlideViewProperties as k, PptxCommentMention as kt, PptxCustomXmlPart as l, PptxAnimScaleBehavior as ln, PptxThemeColorScheme as lt, PptxExportOptions as m, PptxMorphOption as mn, PptxThemeFormatScheme as mt, findText as n, PptxTextBuildType as nn, PptxBackgroundStylePreset as nt, mergePresentation as o, PptxAnimEffectBehavior as on, backgroundStylePresetFor as ot, PptxExportFormat as p, PptxSetBehavior as pn, PptxThemeFontScheme as pt, PptxLayoutPreview as q, PptxColorAnimation as qt, replaceText as r, PptxTimingTemplate as rn, PptxSlideBackgroundStyleRef as rt, PptxActiveXControl as s, PptxAnimMotionBehavior as sn, isDarkColorMap as st, FindResult as t, PptxTextAnimationTarget as tn, BACKGROUND_STYLE_PRESETS as tt, PptxCustomerData as u, PptxAnimationBehavior as un, PptxThemeEffectStyle as ut, PptxModernCommentPart as v, PptxStripDirection as vn, PptxThemeVariant as vt, PptxSlideBackgroundGradient as w, TRANSITION_THRUBLK_TYPES as wn, PptxCoreProperties as wt, PptxPresentationProperties as x, PptxTransitionSpeed as xn, PptxComment as xt, PptxModifyVerifier as y, PptxTransitionDirection4 as yn, THEME_COLOR_SCHEME_KEYS as yt, PptxPrintOutput as z, PptxAnimationPreset as zt };
3363
- //# sourceMappingURL=text-operations-B3lZjvs_.d.ts.map