@allyhub/sdk 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/node_modules/@allyhub/audio/dist/plan.d.ts +3 -0
  3. package/dist/node_modules/@allyhub/audio/dist/render.js +1 -1
  4. package/dist/node_modules/@allyhub/audio/package.json +1 -1
  5. package/dist/node_modules/@allyhub/chart/dist/chart-file.d.ts +2 -0
  6. package/dist/node_modules/@allyhub/chart/dist/chart-file.js +1 -1
  7. package/dist/node_modules/@allyhub/chart/dist/chart-xml.js +3 -2
  8. package/dist/node_modules/@allyhub/chart/dist/chart.d.ts +5 -12
  9. package/dist/node_modules/@allyhub/chart/dist/chart.js +2 -1
  10. package/dist/node_modules/@allyhub/chart/dist/color.d.ts +37 -0
  11. package/dist/node_modules/@allyhub/chart/dist/color.js +2 -0
  12. package/dist/node_modules/@allyhub/chart/dist/index.d.ts +1 -0
  13. package/dist/node_modules/@allyhub/chart/dist/index.js +1 -1
  14. package/dist/node_modules/@allyhub/chart/dist/svg.js +1 -1
  15. package/dist/node_modules/@allyhub/chart/package.json +1 -1
  16. package/dist/node_modules/@allyhub/diagnostics/package.json +1 -1
  17. package/dist/node_modules/@allyhub/formats/dist/data/deck-code.d.ts +130 -0
  18. package/dist/node_modules/@allyhub/formats/dist/data/deck-code.js +1 -1
  19. package/dist/node_modules/@allyhub/formats/dist/data/gen.d.ts +3 -1
  20. package/dist/node_modules/@allyhub/formats/dist/data/gen.js +1 -1
  21. package/dist/node_modules/@allyhub/formats/dist/data/sheet.d.ts +512 -166
  22. package/dist/node_modules/@allyhub/formats/dist/data/sheet.js +1 -1
  23. package/dist/node_modules/@allyhub/formats/dist/data/slides.d.ts +2523 -136
  24. package/dist/node_modules/@allyhub/formats/dist/data/slides.js +1 -1
  25. package/dist/node_modules/@allyhub/formats/dist/files.d.ts +9 -2
  26. package/dist/node_modules/@allyhub/formats/dist/files.js +1 -1
  27. package/dist/node_modules/@allyhub/formats/dist/note-shape.d.ts +9 -0
  28. package/dist/node_modules/@allyhub/formats/dist/note-shape.js +1 -1
  29. package/dist/node_modules/@allyhub/formats/dist/schemas.d.ts +931 -87
  30. package/dist/node_modules/@allyhub/formats/dist/schemas.js +1 -1
  31. package/dist/node_modules/@allyhub/formats/package.json +1 -1
  32. package/dist/node_modules/@allyhub/image-draw/package.json +1 -1
  33. package/dist/node_modules/@allyhub/image-measure/package.json +1 -1
  34. package/dist/node_modules/@allyhub/image-sdk/package.json +1 -1
  35. package/dist/node_modules/@allyhub/measure/package.json +1 -1
  36. package/dist/node_modules/@allyhub/ooxml/dist/color.d.ts +11 -0
  37. package/dist/node_modules/@allyhub/ooxml/dist/color.js +1 -1
  38. package/dist/node_modules/@allyhub/ooxml/dist/ext.d.ts +43 -0
  39. package/dist/node_modules/@allyhub/ooxml/dist/ext.js +1 -1
  40. package/dist/node_modules/@allyhub/ooxml/dist/index.d.ts +2 -1
  41. package/dist/node_modules/@allyhub/ooxml/dist/index.js +1 -1
  42. package/dist/node_modules/@allyhub/ooxml/dist/transform.d.ts +13 -0
  43. package/dist/node_modules/@allyhub/ooxml/dist/transform.js +2 -0
  44. package/dist/node_modules/@allyhub/ooxml/package.json +5 -1
  45. package/dist/node_modules/@allyhub/piece/dist/gen.d.ts +4 -4
  46. package/dist/node_modules/@allyhub/piece/dist/media.d.ts +2 -2
  47. package/dist/node_modules/@allyhub/piece/package.json +1 -1
  48. package/dist/node_modules/@allyhub/protocol/dist/account.d.ts +35 -0
  49. package/dist/node_modules/@allyhub/protocol/dist/account.js +1 -1
  50. package/dist/node_modules/@allyhub/protocol/dist/cloud.d.ts +19 -0
  51. package/dist/node_modules/@allyhub/protocol/dist/cloud.js +1 -1
  52. package/dist/node_modules/@allyhub/protocol/dist/editor.d.ts +35 -20
  53. package/dist/node_modules/@allyhub/protocol/dist/editor.js +1 -1
  54. package/dist/node_modules/@allyhub/protocol/dist/events.d.ts +3 -3
  55. package/dist/node_modules/@allyhub/protocol/dist/frame.d.ts +28 -2
  56. package/dist/node_modules/@allyhub/protocol/dist/frame.js +1 -1
  57. package/dist/node_modules/@allyhub/protocol/dist/jobs.d.ts +6 -6
  58. package/dist/node_modules/@allyhub/protocol/dist/snapshots.d.ts +73 -10
  59. package/dist/node_modules/@allyhub/protocol/dist/snapshots.js +1 -1
  60. package/dist/node_modules/@allyhub/protocol/dist/tools.d.ts +45 -9
  61. package/dist/node_modules/@allyhub/protocol/dist/tools.js +1 -1
  62. package/dist/node_modules/@allyhub/protocol/package.json +1 -1
  63. package/dist/node_modules/@allyhub/runtimes/package.json +1 -1
  64. package/dist/node_modules/@allyhub/scenery/package.json +1 -1
  65. package/dist/node_modules/@allyhub/sheet/dist/annotations.d.ts +14 -0
  66. package/dist/node_modules/@allyhub/sheet/dist/annotations.js +2 -0
  67. package/dist/node_modules/@allyhub/sheet/dist/api/capabilities.js +1 -1
  68. package/dist/node_modules/@allyhub/sheet/dist/api/index.d.ts +1 -1
  69. package/dist/node_modules/@allyhub/sheet/dist/api/index.js +1 -1
  70. package/dist/node_modules/@allyhub/sheet/dist/api/rules.d.ts +24 -0
  71. package/dist/node_modules/@allyhub/sheet/dist/api/rules.js +1 -1
  72. package/dist/node_modules/@allyhub/sheet/dist/api/styles.d.ts +12 -0
  73. package/dist/node_modules/@allyhub/sheet/dist/api/styles.js +1 -1
  74. package/dist/node_modules/@allyhub/sheet/dist/api/workbook.d.ts +3 -1
  75. package/dist/node_modules/@allyhub/sheet/dist/api/workbook.js +1 -1
  76. package/dist/node_modules/@allyhub/sheet/dist/arrange.d.ts +28 -1
  77. package/dist/node_modules/@allyhub/sheet/dist/arrange.js +1 -1
  78. package/dist/node_modules/@allyhub/sheet/dist/data-tools.d.ts +42 -0
  79. package/dist/node_modules/@allyhub/sheet/dist/data-tools.js +2 -0
  80. package/dist/node_modules/@allyhub/sheet/dist/edit.d.ts +43 -2
  81. package/dist/node_modules/@allyhub/sheet/dist/edit.js +1 -1
  82. package/dist/node_modules/@allyhub/sheet/dist/fill.d.ts +10 -0
  83. package/dist/node_modules/@allyhub/sheet/dist/fill.js +1 -1
  84. package/dist/node_modules/@allyhub/sheet/dist/filter.js +1 -1
  85. package/dist/node_modules/@allyhub/sheet/dist/formula/rewrite.d.ts +14 -0
  86. package/dist/node_modules/@allyhub/sheet/dist/formula/rewrite.js +1 -1
  87. package/dist/node_modules/@allyhub/sheet/dist/html.js +10 -10
  88. package/dist/node_modules/@allyhub/sheet/dist/index.d.ts +6 -1
  89. package/dist/node_modules/@allyhub/sheet/dist/index.js +1 -1
  90. package/dist/node_modules/@allyhub/sheet/dist/outline.d.ts +30 -0
  91. package/dist/node_modules/@allyhub/sheet/dist/outline.js +2 -0
  92. package/dist/node_modules/@allyhub/sheet/dist/rich.d.ts +29 -0
  93. package/dist/node_modules/@allyhub/sheet/dist/rich.js +2 -0
  94. package/dist/node_modules/@allyhub/sheet/dist/rules.js +1 -1
  95. package/dist/node_modules/@allyhub/sheet/dist/table-style.d.ts +6 -0
  96. package/dist/node_modules/@allyhub/sheet/dist/table-style.js +1 -1
  97. package/dist/node_modules/@allyhub/sheet/dist/table-styles.js +1 -1
  98. package/dist/node_modules/@allyhub/sheet/dist/workbook.d.ts +5 -1
  99. package/dist/node_modules/@allyhub/sheet/dist/workbook.js +1 -1
  100. package/dist/node_modules/@allyhub/sheet/dist/xlsx/charts.js +1 -1
  101. package/dist/node_modules/@allyhub/sheet/dist/xlsx/import.js +1 -1
  102. package/dist/node_modules/@allyhub/sheet/dist/xlsx/read.d.ts +17 -1
  103. package/dist/node_modules/@allyhub/sheet/dist/xlsx/read.js +2 -2
  104. package/dist/node_modules/@allyhub/sheet/dist/xlsx/runs.d.ts +56 -0
  105. package/dist/node_modules/@allyhub/sheet/dist/xlsx/runs.js +2 -0
  106. package/dist/node_modules/@allyhub/sheet/dist/xlsx/styles.d.ts +6 -0
  107. package/dist/node_modules/@allyhub/sheet/dist/xlsx/styles.js +1 -1
  108. package/dist/node_modules/@allyhub/sheet/dist/xlsx/write.js +1 -1
  109. package/dist/node_modules/@allyhub/sheet/package.json +1 -1
  110. package/dist/node_modules/@allyhub/slides-core/dist/animation.d.ts +117 -21
  111. package/dist/node_modules/@allyhub/slides-core/dist/animation.js +1 -1
  112. package/dist/node_modules/@allyhub/slides-core/dist/api.d.ts +181 -30
  113. package/dist/node_modules/@allyhub/slides-core/dist/api.js +3 -3
  114. package/dist/node_modules/@allyhub/slides-core/dist/capabilities.js +1 -1
  115. package/dist/node_modules/@allyhub/slides-core/dist/chart-api.d.ts +28 -2
  116. package/dist/node_modules/@allyhub/slides-core/dist/chart-api.js +1 -1
  117. package/dist/node_modules/@allyhub/slides-core/dist/check.js +1 -1
  118. package/dist/node_modules/@allyhub/slides-core/dist/enums.d.ts +222 -4
  119. package/dist/node_modules/@allyhub/slides-core/dist/enums.js +1 -1
  120. package/dist/node_modules/@allyhub/slides-core/dist/file.d.ts +6 -0
  121. package/dist/node_modules/@allyhub/slides-core/dist/file.js +3 -3
  122. package/dist/node_modules/@allyhub/slides-core/dist/generated/table-styles.d.ts +3 -0
  123. package/dist/node_modules/@allyhub/slides-core/dist/generated/table-styles.js +2 -0
  124. package/dist/node_modules/@allyhub/slides-core/dist/index.d.ts +3 -0
  125. package/dist/node_modules/@allyhub/slides-core/dist/index.js +1 -1
  126. package/dist/node_modules/@allyhub/slides-core/dist/merge.js +1 -1
  127. package/dist/node_modules/@allyhub/slides-core/dist/model.d.ts +98 -10
  128. package/dist/node_modules/@allyhub/slides-core/dist/numbering.d.ts +6 -0
  129. package/dist/node_modules/@allyhub/slides-core/dist/numbering.js +2 -0
  130. package/dist/node_modules/@allyhub/slides-core/dist/office.d.ts +53 -0
  131. package/dist/node_modules/@allyhub/slides-core/dist/office.js +1 -1
  132. package/dist/node_modules/@allyhub/slides-core/dist/patterns.d.ts +8 -0
  133. package/dist/node_modules/@allyhub/slides-core/dist/patterns.js +2 -0
  134. package/dist/node_modules/@allyhub/slides-core/dist/resolve.d.ts +36 -6
  135. package/dist/node_modules/@allyhub/slides-core/dist/resolve.js +1 -1
  136. package/dist/node_modules/@allyhub/slides-core/dist/script.d.ts +11 -0
  137. package/dist/node_modules/@allyhub/slides-core/dist/script.js +2 -2
  138. package/dist/node_modules/@allyhub/slides-core/dist/sdk.d.ts +1 -1
  139. package/dist/node_modules/@allyhub/slides-core/dist/sdk.js +1 -1
  140. package/dist/node_modules/@allyhub/slides-core/dist/table-style.d.ts +48 -0
  141. package/dist/node_modules/@allyhub/slides-core/dist/table-style.js +2 -0
  142. package/dist/node_modules/@allyhub/slides-core/package.json +1 -1
  143. package/dist/node_modules/@allyhub/video-core/dist/mix-plan.js +1 -1
  144. package/dist/node_modules/@allyhub/video-core/dist/timeline.d.ts +4 -0
  145. package/dist/node_modules/@allyhub/video-core/package.json +1 -1
  146. package/dist/node_modules/@allyhub/video-sdk/package.json +1 -1
  147. package/docs/defaults.md +78 -4
  148. package/docs/image.md +1 -1
  149. package/docs/pictures.md +1 -1
  150. package/docs/project.md +1 -1
  151. package/docs/sheets.md +19 -9
  152. package/docs/slides.md +30 -16
  153. package/docs/speech.md +1 -1
  154. package/package.json +1 -1
package/docs/sheets.md CHANGED
@@ -58,7 +58,7 @@ Its JSON Schema is `https://allyhub.com/schemas/sheet.schema.json`.
58
58
  | `title` | The workbook's title |
59
59
  | `names` | Defined names: a constant, or a place or formula after `=`; `hidden_names` lists those Excel's Name Manager does not show |
60
60
  | `sheets[]` | `name`, at most 31 characters, none of `\ / ? * [ ] :`; `hidden`; `freeze`, the first cell that scrolls; `gridlines: false`; `tab`, its tab's colour; `names`, its own, read on it before the workbook's and from elsewhere as `Sheet!name` |
61
- | `sheets[].tables[]` | `name`, `at` (its header's top left), `rows` (a CSV file from the sheet's folder), `key`, `style` (Excel's, `TableStyleMedium2` unless it says, `none` for none), `columns` (by name: `formula`, `format`, a look, `width`, `files`) |
61
+ | `sheets[].tables[]` | `name`, `at` (its header's top left), `rows` (a CSV file from the sheet's folder), `key`, `style` (Excel's, `TableStyleMedium2` unless it says, `none` for none), Table Style Options `banded_rows` (unless `false`), `banded_columns`, `first_column`, `last_column`, `columns` (by name: `formula`, `format`, a look, `width`, `files`) |
62
62
  | `sheets[].columns` | By letter: `width` in pixels, `hidden`, `format`, a look, `files` (see [Files in a cell](#files-in-a-cell)) |
63
63
  | `sheets[].charts[]` | A chart over the cells: see [Charts](#charts) |
64
64
  | `sheets[].rows` | By number: `height` in pixels, `hidden`, `format`, a look |
@@ -66,20 +66,29 @@ Its JSON Schema is `https://allyhub.com/schemas/sheet.schema.json`.
66
66
  | `sheets[].format` | A list of `{ range, format, …look }`: later entries win over earlier ones, a cell's own look wins over them |
67
67
  | `sheets[].merges` | Merged ranges |
68
68
  | `sheets[].blocks` | `{ at, rows }`: a CSV file of typed cells, from a cell |
69
- | `sheets[].filter` | An AutoFilter on a range: `{ range, columns }`, its columns by letter, each `{ values, blanks }`: what it keeps, as the column shows it. A table's is `tables[].filter`, `{ columns }` by column name, or `false` for no buttons. What it hides is worked out, never written |
69
+ | `sheets[].filter` | An AutoFilter on a range: `{ range, columns }`, its columns by letter, each `{ values, blanks }`, what it keeps as the column shows it, or Excel's Custom AutoFilter `{ conditions: [{ operator, value }], or }` (`equal`, `notEqual`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`; text with `*` and `?`), Top 10 `{ top: { count, percent, bottom } }`, `{ average: above }` or `below`, or `{ color: { fill } }` or `{ font }`. A table's is `tables[].filter`, `{ columns }` by column name, or `false` for no buttons. What it hides is worked out, never written |
70
70
  | `sheets[].conditional` | Conditional formats, the first the strongest: `{ range, type, …, stop }`; ranges apart by spaces. See below |
71
71
  | `sheets[].validations` | Data validation: `{ range, type, operator, formula, values, blank, dropdown, prompt, error }`. See below |
72
72
  | `checks` | `{ name, formula }`: a formula that must hold. One that is false, 0 or an error is a problem (AK-M009) |
73
73
  | `scenarios` | Named sets of inputs, each what names hold instead: see [Scenarios](#scenarios) |
74
74
  | `iteration` | Excel's iterative calculation: `true`, or `{ max_iterations, max_change }` (Excel's 100 and 0.001 unless it says). A circular reference is then computed again until it settles |
75
75
 
76
- A **cell** is YAML's value: a number, `true`, text; text that starts with `=` is a formula. In a `{ … }` a formula with a comma or a bracket is quoted. Its long form is `{ value | formula, format, name, start, …look }`: `name` is a defined name for that cell; `start` is what a formula's cell holds before it is computed, where [iterative calculation](#formulas) starts, as an Excel cell keeps its last value.
76
+ A **cell** is YAML's value: a number, `true`, text; text that starts with `=` is a formula. In a `{ … }` a formula with a comma or a bracket is quoted. Its long form is `{ value | formula | runs, format, name, start, …look }`: `name` is a defined name for that cell; `start` is what a formula's cell holds before it is computed, where [iterative calculation](#formulas) starts, as an Excel cell keeps its last value.
77
+
78
+ **Rich text** is a cell's `runs` in place of its `value`: its text in parts, each `{ text, bold, italic, underline, strike, font, size, color, script }` (`script` is `superscript` or `subscript`), what a run does not say being the cell's look. The cell's value is the runs' text joined, and it is text whatever it reads as. Runs are a loose cell's, never a range key's, a table's or a CSV block's, whose cells are plain text.
79
+
80
+ ```yaml
81
+ A1:
82
+ runs:
83
+ - text: "Revenue "
84
+ - { text: "(USD, millions)", italic: true, color: "#808080" }
85
+ ```
77
86
 
78
87
  A **range key** (`B3:M3`) gives one value or formula to every cell in it. A formula is written for its first cell and moved as a fill moves it: relative references shift, `$` ones stay. A single cell's key wins over a range's, and a later range over an earlier one; `B5: null` keeps a cell of a range empty.
79
88
 
80
- `format` is Excel's number format code. A **look** is `bold`, `italic`, `underline` (`true` or Excel's `single`, `double`, `singleAccounting`, `doubleAccounting`), `strike`, `font`, `size`, `color` and `fill` (`#RRGGBB`; a fill may be `{ pattern, color, background }`), `align`, `valign`, `wrap`, `shrink`, `indent`, `rotation`, `border` (`left`, `right`, `top`, `bottom`, each `{ style, color }`). Later `format` entries win field by field, and a `border` side by side, so `{ style: none }` takes one side away.
89
+ `format` is Excel's number format code. A **look** is `bold`, `italic`, `underline` (`true` or Excel's `single`, `double`, `singleAccounting`, `doubleAccounting`), `strike`, `font`, `size`, `color` and `fill` (`#RRGGBB`; a fill may be `{ pattern, color, background }`), `align`, `valign`, `wrap`, `shrink`, `indent`, `rotation`, `border` (`left`, `right`, `top`, `bottom`, each `{ style, color }`), and Format Cells › Protection's `locked` (a cell is locked unless it says `false`, which lets a person change it on a protected sheet) and `hide_formula` (its formula not shown on a protected sheet). Later `format` entries win field by field, and a `border` side by side, so `{ style: none }` takes one side away.
81
90
 
82
- **Conditional formats.** A `type` is Excel's, and a rule that gives a look says it in the rule: `bold`, `italic`, `underline`, `strike`, `color`, `fill`, `border`.
91
+ **Conditional formats.** A `type` is Excel's, and a rule that gives a look says it in the rule: `bold`, `italic`, `underline`, `strike`, `color`, `fill`, `border`, and `format`, the number format the cell shows while it holds.
83
92
 
84
93
  | `type` | With |
85
94
  | ------------------------------------ | -------------------------------------------------------------------------------------------- |
@@ -106,7 +115,7 @@ They are text, so a formula counts one with a wildcard, `=COUNTIF(D:D,"*vip*")`,
106
115
 
107
116
  ### For the file
108
117
 
109
- A worksheet holds what Excel prints and shows around its cells. Each goes in the `.xlsx`. A PDF prints by `print` as Excel does; the grid and a PDF do not draw links, notes, pictures and outlines yet.
118
+ A worksheet holds what Excel prints and shows around its cells. Each goes in the `.xlsx`. A PDF prints by `print` as Excel does, and its links are links; the editor shows notes, links and outlines as Excel does, and a PDF, like Excel's, prints no notes.
110
119
 
111
120
  ```yaml
112
121
  sheets:
@@ -125,12 +134,13 @@ sheets:
125
134
  pictures:
126
135
  - { file: files/logo.png, at: B1, x: 4, y: 4, height: 40 } # over the cells; pixels
127
136
  rows: { 12: { level: 1 } } # grouped, 1 to 7; columns too
128
- protect: true # Protect Sheet, with no password
137
+ outline: { summary_below: false } # a group's summary row above it; summary_right for columns
138
+ protect: true # Protect Sheet, with no password; a cell's look `locked: false` lets it change
129
139
  ```
130
140
 
131
141
  `allyhub render` says, with each Excel file, how each sheet prints (its pages across and down and its scale), the cells whose text its column and the empty cells after it cannot hold (Excel cuts it where the next cell starts), the numbers wider than their column (Excel shows ####), counted in characters of Calibri 11's digit as Excel counts a column's width, and the numbers of 1,000 or more with no number format.
132
142
 
133
- In a script: `ws.page_setup.orientation`, `.paperSize`, `.fitToWidth`, `.fitToHeight`, `ws.page_margins.left`, `ws.print_area`, `ws.print_title_rows`, `ws.print_title_cols`, `ws.oddFooter.right.text`, `cell.hyperlink`, `cell.comment = new Comment("Check", "Finance")`, `ws.add_image(new Image("files/logo.png"), "B1")`, `ws.row_dimensions[12].outlineLevel`, `ws.protection.sheet`.
143
+ In a script: `ws.page_setup.orientation`, `.paperSize`, `.fitToWidth`, `.fitToHeight`, `ws.page_margins.left`, `ws.print_area`, `ws.print_title_rows`, `ws.print_title_cols`, `ws.oddFooter.right.text`, `cell.hyperlink`, `cell.comment = new Comment("Check", "Finance")`, `ws.add_image(new Image("files/logo.png"), "B1")`, `ws.row_dimensions[12].outlineLevel`, `ws.protection.sheet`, `cell.protection = new Protection({ locked: false })`.
134
144
 
135
145
  ### Files in a cell
136
146
 
@@ -414,7 +424,7 @@ A name of openpyxl's that is not held throws where it is used, naming what the c
414
424
  **In.** `allyhub sheet import <file.xlsx>` reads a file whatever wrote it and writes what it means as short text: neighbours with one formula as one range key, a table as a table, a column of one formula as a calculated column, a large rectangle of typed cells as a CSV file, looks as rectangles. It prints:
415
425
 
416
426
  - Excel's scenarios come in by the names of the cells they set; a cell with no name is said, and a `Base case` that holds what the cells hold is left out.
417
- - `Not carried over:` VBA, pivot tables, a chart of a kind a sheet has none of (radar, stock, surface, bubble, 3-D, a pie or a scatter among other kinds) or whose numbers are written in it, shapes, links to other workbooks, a protection's password, page breaks, rich text (kept as text), filters by condition, kinds of rule the format has no place for, and so on, with where. Notes, links, pictures (beside the workbook file), outlines, Page Layout, protection, a sheet's own names and hidden names come in.
427
+ - `Not carried over:` VBA, pivot tables, a chart of a kind a sheet has none of (radar, stock, surface, bubble, 3-D, a pie or a scatter among other kinds) or whose numbers are written in it, shapes, links to other workbooks, a protection's password, rich text in a table (kept as text), filters by date, kinds of rule the format has no place for, a chart's trendlines and error bars, the names of cell styles, and so on, with where. Notes, links, pictures (beside the workbook file), outlines, Page Layout with its scale and page breaks, protection with each cell's Locked and Hidden, Table Style Options, a sheet's own names and hidden names come in.
418
428
  - A formula that cannot be computed here (a function the engine does not have, another workbook) keeps its value, listed with its cell and why. An array formula over several cells is its first cell's, and the others spill from it.
419
429
  - `Computed here against the file:` every formula's result compared with the value the file holds, each difference with its cell (`--tolerance` is how close numbers must be, `--all` lists every one; a formula that reads the clock or a random number is not compared). JSON has every difference.
420
430
 
package/docs/slides.md CHANGED
@@ -110,13 +110,13 @@ python-pptx opens these from a template; here code makes them.
110
110
  - `prs.slide_masters.add(name)`: a master, with PowerPoint's Office text styles (`master.text_styles.title_style`, `body_style`, `other_style`, nine levels each) and no placeholders yet.
111
111
  - `master.slide_layouts.add(name)`: a layout; its name is what the slides file's slides name, unique in the deck.
112
112
  - `placeholders.add(PP_PLACEHOLDER.X, left, top, width, height, { name })` on a master or a layout. A layout's placeholder given no frame takes its master's of its base type, as python-pptx reads it (a centre title the title's, a subtitle, picture, media or object the body's). Its name is its type's (`title`, `subtitle`, `body`, `picture`, `content`…) unless given: the slides file and the script name it. Its idx is PowerPoint's: a title 0, a date, footer and slide number 10, 11 and 12, the rest from 1.
113
- - Beyond python-pptx's `add_shape` and `add_connector` (`MSO_CONNECTOR.STRAIGHT`, `ELBOW`, `CURVE`, or a connector's preset by name, `straightConnector1`, `bentConnector2` to `5`, `curvedConnector2` to `5`; an elbow's middle is its `adjustments[0]`; `begin_connect(shape, site)` and `end_connect` glue its ends to a shape of the same slide, layout or master, at a site of the shape's geometry, numbered as its preset's `cxnLst` in ECMA-376 (most count counter-clockwise from the top: a rectangle's, a rounded rectangle's, a diamond's and a freeform's 0 top, 1 left, 2 bottom, 3 right; an ellipse's eight 0 top, 2 left, 4 bottom, 6 right; a hexagon's six start at its right), and its ends then follow the shape; `begin_x`, `begin_y`, `end_x` and `end_y` read and move them), `shapes.build_freeform(start_x, start_y, scale)` draws an outline in local units, `scale` EMU each, its start and every point after in those units (with `scale` 1 they are EMU) (`add_line_segments(vertices, close)`, which closes the outline back to its start unless `close` is `false`, as python-pptx's; `move_to`, `convert_to_shape`, and `add_curve_segment(x1, y1, x2, y2, x, y)`, a cubic curve python-pptx lacks), filled by its style as PowerPoint fills it, an open one too: `fill.background()` leaves a line; `line.dash_style` takes `MSO_LINE`, and `line.begin_arrow` and `end_arrow` take `MSO_ARROWHEAD`, each head's size `line.begin_arrow_width`, `begin_arrow_length`, `end_arrow_width` and `end_arrow_length` `MSO_ARROWHEAD_SIZE` (`SMALL`, `MEDIUM`, `LARGE`: two, three and five times the line's width, never less than 0.7 mm's; a freeform's open ends take heads too); `shapes.add_group_shape()` groups what is added to its `.shapes`, and a group is its shapes, listed and drawn as they are, holding no group; `shapes.add_table(rows, cols, left, top, width, height).table` has `cell(r, c)` with `text`, `text_frame`, `fill`, `borders` (`{ bottom: { color, width } }`), `merge`, margins and `vertical_anchor`. `layout.display_master_shapes = false` hides its master's shapes.
114
- - A placeholder shrinks its text to fit its frame unless told not to (`MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE`, as PowerPoint's Office master's do; `text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps its sizes), and the type in use shows what it shrank to. A text box `add_textbox` makes does not wrap and grows to its text, as python-pptx's, so its frame has no room for its `vertical_anchor` to move it (`text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps the frame it was given); a shape `add_shape` makes starts with one centred paragraph, its text light 1 (white, on its accent 1 fill) by its style as PowerPoint's (a run's `font.color` sets its own), and `text_frame.text` replaces it with paragraphs aligned as the text style says (left), as python-pptx's.
113
+ - Beyond python-pptx's `add_shape` and `add_connector` (`MSO_CONNECTOR.STRAIGHT`, `ELBOW`, `CURVE`, or a connector's preset by name, `straightConnector1`, `bentConnector2` to `5`, `curvedConnector2` to `5`; an elbow's middle is its `adjustments[0]`; `begin_connect(shape, site)` and `end_connect` glue its ends to a shape of the same slide, layout or master, at a site of the shape's geometry, numbered as its preset's `cxnLst` in ECMA-376 (most count counter-clockwise from the top: a rectangle's, a rounded rectangle's, a diamond's and a freeform's 0 top, 1 left, 2 bottom, 3 right; an ellipse's eight 0 top, 2 left, 4 bottom, 6 right; a hexagon's six start at its right), and its ends then follow the shape; `begin_x`, `begin_y`, `end_x` and `end_y` read and move them), `shapes.build_freeform(start_x, start_y, scale)` draws an outline in local units, `scale` EMU each, its start and every point after in those units (with `scale` 1 they are EMU) (`add_line_segments(vertices, close)`, which closes the outline back to its start unless `close` is `false`, as python-pptx's; `move_to`, `convert_to_shape`, and `add_curve_segment(x1, y1, x2, y2, x, y)`, a cubic curve python-pptx lacks), filled by its style as PowerPoint fills it, an open one too: `fill.background()` leaves a line; `line.dash_style` takes `MSO_LINE`, and `line.begin_arrow` and `end_arrow` take `MSO_ARROWHEAD`, each head's size `line.begin_arrow_width`, `begin_arrow_length`, `end_arrow_width` and `end_arrow_length` `MSO_ARROWHEAD_SIZE` (`SMALL`, `MEDIUM`, `LARGE`: two, three and five times the line's width, never less than 0.7 mm's; a freeform's open ends take heads too); `shapes.add_group_shape()` groups what is added to its `.shapes`, and a group is its shapes, listed and drawn as they are, holding no group; `shape.inner_shadow` (a `ShadowFormat` with `visible`), `shape.glow` (`visible`, `radius`, `transparency`, `color`), `shape.soft_edge.radius` and `shape.reflection` (`visible`, `transparency`, `size`, `offset`, `blur`), Office's names, set them; `fill.gradient_path` (`"linear"`, `"circle"`, `"rect"`, `"shape"`) and `fill.gradient_focus` set a gradient's kind and focus; `fill.patterned()` with `fill.pattern` (`MSO_PATTERN_TYPE`), `fill.fore_color` and `fill.back_color`, and `fill.picture(image_file, { tile, transparency })` (a path from the deck's module's folder; `tile` `{ scale_x, scale_y, offset_x, offset_y, align }`, `TILE_ALIGNMENT`) fill a shape as the slides file's `pattern` and `picture_fill` do; `shapes.add_table(rows, cols, left, top, width, height).table` has `cell(r, c)` with `text`, `text_frame`, `fill`, `borders` (`{ bottom: { color, width } }`), `merge`, margins and `vertical_anchor`. `layout.display_master_shapes = false` hides its master's shapes.
114
+ - A placeholder shrinks its text to fit its frame unless told not to (`MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE`, as PowerPoint's Office master's do; `text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps its sizes), and the type in use shows what it shrank to. A text box `add_textbox` makes does not wrap and grows to its text, as python-pptx's, so its frame has no room for its `vertical_anchor` to move it (`text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps the frame it was given); a shape `add_shape` makes starts with one centred paragraph, its text light 1 (white, on its accent 1 fill) by its style as PowerPoint's (a run's `font.color` sets its own), and `text_frame.text` replaces it with paragraphs aligned as the text style says (left), as python-pptx's. `text_frame.orientation` (`MSO_TEXT_ORIENTATION`, PowerPoint's Text Direction, `a:bodyPr@vert`, which python-pptx has no name for) turns its text: `HORIZONTAL`, `DOWNWARD` (every line turned 90°), `UPWARD` (270°), `VERTICAL_FAR_EAST` (East Asian vertical: CJK upright, other letters turned, columns right to left), `VERTICAL` (stacked, every letter upright), `VERTICAL_RIGHT_TO_LEFT`, `MONGOLIAN`; a layout's placeholder passes it to its slides, and `placeholders.add(type, …, { orient: "vert" })` makes a vertical placeholder (`p:ph@orient`, what PowerPoint matches layouts by). A vertical text keeps its frame (one that would grow to its text grows down, not across). A run's `font.underline` is python-pptx's: `true`, `false`, or an `MSO_UNDERLINE` style (`DOUBLE_LINE`, `WAVY_LINE`, `DOTTED_HEAVY_LINE`…, all 17 of DrawingML's); `font.strike` is `true` or `MSO_TEXT_STRIKE.DOUBLE`; `font.caps` is `MSO_TEXT_CAPS.SMALL` or `ALL` (none of them python-pptx's). The stage draws underlines with CSS's styles: a dash and dot is dashed, a double wavy line one wavy line, words alone all of it underlined, and a strike takes its run's underline's style where it has both.
115
115
  - A run's `font.baseline` raises it by a share of its size (`0.3`, a superscript) or, below 0, lowers it (`-0.25`, a subscript): PowerPoint's `baseline`, which python-pptx has no name for.
116
116
  - `shape.adjustments[i]` is the file's value over 100,000, as python-pptx's: most are a share of the shape's shorter side (`roundRect`'s `[0.16667]`); an angle's is in 60,000ths of a degree, so 0.6 a degree (`blockArc`'s first, 108, is 180°, measured clockwise from 3 o'clock). Reading `adjustments` gives a preset's defaults, each in its own scale.
117
- - A colour in code is python-pptx's `ColorFormat`: `shape.fill.solid()` then `shape.fill.fore_color.rgb = RGBColor.from_string("1F4E79")` (or `"#1F4E79"`), `.theme_color = MSO_THEME_COLOR.ACCENT_1`, and the same on `line.color` and a run's `font.color`; a gradient's stops are each `color` and `position`, or set whole as `fill.gradient_stops = [{ at, color }, …]`.
117
+ - A colour in code is python-pptx's `ColorFormat`: `shape.fill.solid()` then `shape.fill.fore_color.rgb = RGBColor.from_string("1F4E79")` (or `"#1F4E79"`), `.theme_color = MSO_THEME_COLOR.ACCENT_1`, and the same on `line.color` and a run's `font.color`; a gradient's stops are each `color` and `position`, or set whole as `fill.gradient_stops = [{ at, color }, …]`. `MSO_THEME_COLOR.TEXT_1`, `BACKGROUND_1`, `TEXT_2` and `BACKGROUND_2` are `tx1`, `bg1`, `tx2` and `bg2`, which the master's colour map makes theme colours: `master.color_map` (PowerPoint's `p:clrMap`, which python-pptx has no name for) is Office's `{ bg1: "lt1", tx1: "dk1", bg2: "lt2", tx2: "dk2" }` unless set, a dark master's `{ bg1: "dk1", tx1: "lt1", bg2: "dk2", tx2: "lt2" }`, and a layout's `color_map` overrides its master's (`p:clrMapOvr`); Office's master writes its text in `tx1` and its background in `bg1`, as PowerPoint's does. `ColorFormat.transforms` holds DrawingML's transforms in order, `[{ name, value }]`: `tint`, `shade`, `lumMod`, `lumOff`, `lum`, `satMod`, `satOff`, `sat`, `hueMod`, `hueOff`, `hue`, `alpha`, `alphaMod`, `alphaOff`, each `value` a share (`0.75` is 75 %), degrees for `hue` and `hueOff`; set, they take a brightness's place, and `brightness = 0` takes them away.
118
118
  - A shape is named by its kind and a number (`shape-3`) unless code names it; two shapes of one slide by one name are AK-M011, as the slides file and the script find a shape by its name.
119
- - A text style is a list style's level, `ListLevel`: `alignment`, `line_spacing`, `space_before`, `space_after`, `font` (with `font.spacing`, the space between letters, a length, negative to tighten, which python-pptx has no name for), `bullet` (a character, or `null` for none), `bullet_font`, `margin_left`, `indent`. No bullet keeps the level's `margin_left` and `indent`, as PowerPoint's `a:buNone` does: Office's body levels hang their wrapped lines a quarter inch in, so text with no bullets sets both to `0` to stand flush. A placeholder's `text_frame.list_style[n]` is what the text a slide gives it takes at level n, over its master's placeholder and its master's text style for its type.
119
+ - A text style is a list style's level, `ListLevel`: `alignment`, `line_spacing`, `space_before`, `space_after`, `font` (with `font.spacing`, the space between letters, a length, negative to tighten, which python-pptx has no name for), `bullet` (a character, or `null` for none), `bullet_font`, `bullet_color` (a colour as the slides file writes one, or `null` for its text's, `a:buClrTx`), `bullet_size` (a share of its text's size, 0.25 to 4, `a:buSzPct`), `numbered` (any of ECMA-376's 41 schemes: `arabicPeriod`, `arabicParenBoth`, `alphaLcParenR`, `romanUcPeriod`, `circleNumDbPlain`, `arabicDbPeriod`, `ea1ChsPeriod`, `thaiNumPeriod`, `hindiNumPeriod`…; the stage draws the Thai and Hindi letters and the Arabic and Hebrew alphabetic counts as `arabicPeriod`'s and writes them as they are, and the East Asian ones as PowerPoint draws them: the Chinese counted in numerals (`十一.`, `一百零五.`), the Japanese and Korean digit by digit (`一〇.`), every period a full-width `.`, where ECMA-376's words say a single-byte period for all but `ea1JpnChsDbPeriod`), `start_at` (the number its list starts at), `margin_left`, `indent`. `space_before` and `space_after` are a Length, or a number of lines at the paragraph's size (`0.5`, PowerPoint's Before and After in lines, `a:spcPct`), as `line_spacing` is. No bullet keeps the level's `margin_left` and `indent`, as PowerPoint's `a:buNone` does: Office's body levels hang their wrapped lines a quarter inch in, so text with no bullets sets both to `0` to stand flush. A placeholder's `text_frame.list_style[n]` is what the text a slide gives it takes at level n, over its master's placeholder and its master's text style for its type.
120
120
 
121
121
  ## Components
122
122
 
@@ -179,26 +179,39 @@ slides: []
179
179
  | `slides[].shapes` | Its shapes by name: what it changes of its layout's placeholders, and its own |
180
180
  | `slides[].background` | Its own background over its layout's: one of `fill` (a colour), `gradient` (as a shape's) or `picture` (a file, stretched over the slide) |
181
181
 
182
- A shape there changes a placeholder of the slide's layout (or a generated shape) with `frame` (`{ x, y, w, h }` in points), `text` (on all of its text, every level, as PowerPoint sets a selected shape's: `size` in points, `bold`, `italic`, `underline`, `strike`, `color`, `font`, a family, `align`: `l`, `ctr`, `r`, `just`, `line_spacing`, a multiple of single spacing, `1.5`, `space_before` and `space_after` in points, `anchor`, where the text stands in its shape: `t`, `ctr`, `b`, `bullet`, a character, `"•"`, or `false` for none, `numbered`, its paragraphs counted in place of a bullet: `arabicPeriod`, `arabicParenR`, `alphaLcPeriod`, `alphaUcPeriod`, `romanLcPeriod`, `romanUcPeriod`; given both, `numbered` stands; a bullet or a number in text with no indent hangs as PowerPoint's does), `fill` (a colour, or `none`), `fill_transparency` (a share that shows through), `gradient` (`angle`, degrees clockwise from left to right, and `stops`, each `at`, a share of the way, `color` and `transparency`), `shadow` (`blur` and `distance` in points, `angle`, `color`, `transparency`), `line` (its outline: a colour, or `none`), `line_width` in points, `line_dash` (`solid`, `sysDash`, `sysDot`, `dash`, `dashDot`, `lgDash`, `lgDashDot`, `lgDashDotDot`), `line_begin` and `line_end` (`none`, `triangle`, `arrow`, `stealth`, `diamond`, `oval`), `line_begin_size` and `line_end_size` (`{ w, len }`, each `sm`, `med` or `lg`: the head's width and length, PowerPoint's Arrow size), `rotation` (degrees clockwise about its centre, 0 up to 360, python-pptx's `rotation`), `flip_h` and `flip_v` (`true`: mirrored left to right, top to bottom; a line runs from its frame's other corner; its text reads as it is), `crop` (a picture's: `left`, `top`, `right` and `bottom`, the share of it cut from each side, PowerPoint's `a:srcRect`; a negative share is space left beside it; the editor's Crop menu writes Fill and Fit, [pictures.md](pictures.md#a-decks-pictures)), `z`; or is the slide's own with one of `textbox: true` (its words are the script's; it wraps, and grows from its frame's `h` to its text, so its frame still has all four of `x`, `y`, `w` and `h`), `picture`, `movie` (a video file of the project; a video item goes on a slide as its render, `allyhub render`), `geometry` (any of PowerPoint's 187 preset shapes by its `prst` name, ECMA-376's `ST_ShapeType`: `rect`, `roundRect`, `ellipse`, `triangle`, `star5`, `chevron`, `rightArrow`, `wedgeRectCallout`, `heart`, `cloud`, `donut`, `flowChartProcess`…, drawn from ECMA-376's preset shape definitions as PowerPoint draws them; a connector, `line`, `straightConnector1`, `bentConnector2` to `5` or `curvedConnector2` to `5`, has the connector's line, no fill and no text, and its `line_begin` and `line_end` face along its path, and `connect: { begin: { shape, site }, end: { shape, site } }` glues its ends to shapes of the slide by name, at sites of their geometries (a rectangle's 0 top, 1 left, 2 bottom, 3 right; PowerPoint's `a:stCxn` and `a:endCxn`): its frame is then where its ends sit, and they follow the shapes; `none` lets go of an end the code glued, as dragging the end off its shape does; with `adjustments`, its handles' values in the definition's order as python-pptx's `adjustments` has them, a share each: `roundRect`'s `[0.1]` is a corner of a tenth of its shorter side), `path` (a freeform: `{ w, h, d }`, its outline in a box of `w` × `h` units stretched to its frame, `d` in SVG's `M`, `L`, `C` and `Z`, absolute, so a logo or a cursor is a real shape), `table` (`columns`, widths in points, and `rows`, each a `height` with its `fill`, `text` and `line`, a rule at its foot; stretched to its frame, its words the script's, a list of rows, each a list of cells) or `component` (with `props`, and `dur`, how long it moves), and a `frame`. `group`, a name a slide's own shapes share, makes them one group in PowerPoint, standing together where the topmost of them stands. A table here has no style of its own, unlike python-pptx's: its look is what its rows and cells say. A picture or a movie put in a picture, media or object placeholder fills it. Colours are the theme's (`accent1`…); the theme's lighter or darker, in PowerPoint's words (`accent1 lighter 40%`, `dk1 darker 25%`, a share over 0 up to 100 %), which follows a change of theme as PowerPoint's picker's tints and shades do; or `#RRGGBB`. In code a colour (`ColorFormat`) has python-pptx's `brightness`, -1 to 1 (`0.4` is lighter 40 %), on a theme colour only. `z` orders a shape among the slide's shapes and placeholders, so a negative `z` puts one under a placeholder's words. Paths are from the deck's module's folder.
182
+ A shape there changes a placeholder of the slide's layout (or a generated shape) with `frame` (`{ x, y, w, h }` in points), `text` (on all of its text, every level, as PowerPoint sets a selected shape's: `size` in points, `bold`, `italic`, `underline`, `strike`, `color`, `font`, a family, `align`: `l`, `ctr`, `r`, `just`, `line_spacing`, a multiple of single spacing, `1.5`, `space_before` and `space_after` in points, or `{ lines: 0.5 }`, a share of a line at the text's size, `anchor`, where the text stands in its shape: `t`, `ctr`, `b`, `orientation`, which way it runs (PowerPoint's Text Direction): `horz`, `vert` (turned 90°), `vert270`, `eaVert` (East Asian vertical), `wordArtVert` (stacked), `wordArtVertRtl`, `mongolianVert`, `underline`, `true` or a style (`dbl`, `heavy`, `dotted`, `dottedHeavy`, `dash`, `dashHeavy`, `dashLong`, `dashLongHeavy`, `dotDash`, `dotDashHeavy`, `dotDotDash`, `dotDotDashHeavy`, `wavy`, `wavyHeavy`, `wavyDbl`, `words`), `strike`, `true` or `dblStrike`, `caps`, `small` or `all` (`none` over a level that has them), `bullet`, a character, `"•"`, or `false` for none, `numbered`, its paragraphs counted in place of a bullet, any of ECMA-376's 41 schemes (`arabicPeriod`, `arabicParenR`, `arabicParenBoth`, `arabicPlain`, `alphaLcPeriod`, `alphaUcParenR`, `romanUcPeriod`, `circleNumDbPlain`, `ea1ChsPeriod`…), `start_at`, the number it starts at, `bullet_color`, its bullets' or numbers' colour, `bullet_size`, their size, a share of the text's (`0.75`); given both, `numbered` stands; a bullet or a number in text with no indent hangs as PowerPoint's does, and one wider than its hanging indent pushes its line's text on to the next of PowerPoint's default tab stops, an inch apart from the text's inset, as PowerPoint's does: the slides file holds no tab stops of its own), `fill` (a colour, or `none`), `fill_transparency` (a share that shows through), `gradient` (`angle`, degrees clockwise from left to right, and `stops`, each `at`, a share of the way, `color` and `transparency`; or `path`, out from a focus instead of along a line, `circle` (PowerPoint's Radial), `rect` (Rectangular) or `shape` (Path), its first stop at the focus, and `focus`, `{ left, top, right, bottom }`, the share in from each side, the middle unless said: `{ left: 0, top: 0, right: 1, bottom: 1 }` is From Top Left Corner, and a share below 0 or above 1 is beyond that side, as some files have it; a circle reaches the farthest corner, and the stage draws a rectangle's and a path's contours as an ellipse reaching the farthest side, which is what CSS has), `pattern` (PowerPoint's Pattern Fill: `preset`, any of ECMA-376's 54 (`pct5` to `pct90`, `horz`, `vert`, `ltHorz`, `dkVert`, `narHorz`, `dashHorz`, `cross`, `dnDiag`, `upDiag`, `wdDnDiag`, `dashUpDiag`, `diagCross`, `smCheck`, `lgCheck`, `smGrid`, `lgGrid`, `dotGrid`, `smConfetti`, `lgConfetti`, `horzBrick`, `diagBrick`, `solidDmnd`, `openDmnd`, `dotDmnd`, `plaid`, `sphere`, `weave`, `divot`, `shingle`, `wave`, `trellis`, `zigZag`…), `fg` and `bg` colours, `accent1` over `bg1` unless said; drawn as 8 × 8 cells a pixel each at 100%, the percentages, lines, grids, checks and diamonds as their names say, the pictorial ones near PowerPoint's), `picture_fill` (PowerPoint's Picture or Texture Fill: `path`, an image of the project from the deck's folder, stretched over the shape, or with `tile` tiled: `scale_x` and `scale_y`, shares of its own size, a pixel of it a 96th of an inch, `x` and `y` in points from where `align` puts its first tile, `tl` (the default), `t`, `tr`, `l`, `ctr`, `r`, `bl`, `b`, `br`; `transparency`, a share; a tile's mirroring in a file is drawn unmirrored, said); a shape has one fill, the first of `picture_fill`, `pattern`, `gradient` and `fill` it says, and a slide's fill of any kind stands over its placeholder's, `shadow` (`blur` and `distance` in points, `angle`, `color`, `transparency`), `inner_shadow` (a shadow inside it, the same fields, PowerPoint's Inner shadows), `glow` (`color`, `size` in points, `transparency`), `soft_edges` (points its edges fade over), `reflection` (`transparency` where it starts and `size`, the share of the shape it shows, `distance` below and `blur` in points; mirrored under the shape as PowerPoint's touching reflections; the stage draws it with CSS's reflection, which does not blur, and every effect over the shape's outline and its text as SVG's and CSS's filters), `line` (its outline: a colour, or `none`), `line_width` in points, `line_dash` (`solid`, `sysDot`, `sysDash`, `dash`, `dashDot`, `lgDash`, `lgDashDot`, `lgDashDotDot`, PowerPoint's Dashes, and `dot`, `sysDashDot`, `sysDashDotDot`, Word's; a file's own dashes, `a:custDash`, come in as `dash`), `line_cap` (how its ends and dashes end: `flat`, the default, `rnd` or `sq`), `line_join` (how its corners meet: `miter`, the default, as the Office theme's lines, `round` or `bevel`), `line_compound` (`sng`, the default, `dbl`, `thickThin`, `thinThick` or `tri`: PowerPoint's Compound type, drawn as its lines look in PowerPoint, a thick line twice a thin one; on a line with no inside, a connector or an open freeform, `thickThin` and `thinThick` are drawn as `dbl`), a line's transparency being its colour's `alpha` (`accent1 alpha 50%`), `line_begin` and `line_end` (`none`, `triangle`, `arrow`, `stealth`, `diamond`, `oval`), `line_begin_size` and `line_end_size` (`{ w, len }`, each `sm`, `med` or `lg`: the head's width and length, PowerPoint's Arrow size), `rotation` (degrees clockwise about its centre, 0 up to 360, python-pptx's `rotation`), `flip_h` and `flip_v` (`true`: mirrored left to right, top to bottom; a line runs from its frame's other corner; its text reads as it is), `crop` (a picture's: `left`, `top`, `right` and `bottom`, the share of it cut from each side, PowerPoint's `a:srcRect`; a negative share is space left beside it; the editor's Crop menu writes Fill and Fit, [pictures.md](pictures.md#a-decks-pictures)), `z`; or is the slide's own with one of `textbox: true` (its words are the script's; it wraps, and grows from its frame's `h` to its text, so its frame still has all four of `x`, `y`, `w` and `h`), `picture`, `movie` (a video file of the project; a video item goes on a slide as its render, `allyhub render`), `geometry` (any of PowerPoint's 187 preset shapes by its `prst` name, ECMA-376's `ST_ShapeType`: `rect`, `roundRect`, `ellipse`, `triangle`, `star5`, `chevron`, `rightArrow`, `wedgeRectCallout`, `heart`, `cloud`, `donut`, `flowChartProcess`…, drawn from ECMA-376's preset shape definitions as PowerPoint draws them; a connector, `line`, `straightConnector1`, `bentConnector2` to `5` or `curvedConnector2` to `5`, has the connector's line, no fill and no text, and its `line_begin` and `line_end` face along its path, and `connect: { begin: { shape, site }, end: { shape, site } }` glues its ends to shapes of the slide by name, at sites of their geometries (a rectangle's 0 top, 1 left, 2 bottom, 3 right; PowerPoint's `a:stCxn` and `a:endCxn`): its frame is then where its ends sit, and they follow the shapes; `none` lets go of an end the code glued, as dragging the end off its shape does; with `adjustments`, its handles' values in the definition's order as python-pptx's `adjustments` has them, a share each: `roundRect`'s `[0.1]` is a corner of a tenth of its shorter side), `path` (a freeform: `{ w, h, d }`, its outline in a box of `w` × `h` units stretched to its frame, `d` in SVG's `M`, `L`, `C` and `Z`, absolute, so a logo or a cursor is a real shape), `table` (`columns`, widths in points, and `rows`, each a `height` with its `fill`, `text` and `line`, a rule at its foot; `merged`, cells merged as PowerPoint's Merge Cells, each `{ row, column, rows, columns }`, its first cell from 0 and how many rows and columns it takes, one unless said, inside the table and taking no cell another merge takes, its words its first cell's; stretched to its frame, its words the script's, a list of rows, each a list of cells; `style`, one of PowerPoint's 74 built-in table styles by the name its Table Styles gallery shows (`Medium Style 2 - Accent 1`, `Light Style 1`, `Themed Style 2 - Accent 3`, `Dark Style 2 - Accent 1/Accent 2`, `No Style, Table Grid`) or its id (`{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`), drawn under what its rows set, and Table Design's options for it, `first_row` (Header Row), `last_row` (Total Row), `first_col`, `last_col`, `horz_banding` (Banded Rows) and `vert_banding`, each `true`) or `component` (with `props`, and `dur`, how long it moves), and a `frame`. `group`, a name a slide's own shapes share, makes them one group in PowerPoint, standing together where the topmost of them stands; a group in a group is the outer's name, a slash and its own (`card/lines`: those shapes are a group inside `card`, whose other shapes say `card`), as deep as wanted. A table's look is its style's under what its rows and cells say; `add_table` starts one as python-pptx and PowerPoint do, Medium Style 2 - Accent 1 with `first_row` and `horz_banding`, and `table.style` sets another by name or id (the styles' look is PowerPoint's as far as their definitions are known: their colours, bands and rules; a Dark style with no accent, which no public definition gives, is approximated). A picture or a movie put in a picture, media or object placeholder fills it. Colours are the theme's (`accent1`…) or the colour map's (`tx1`, `bg1`, `tx2`, `bg2`, which the master's map makes a theme colour: text and background on a light master, the other way on a dark one); the theme's lighter or darker, in PowerPoint's words (`accent1 lighter 40%`, `dk1 darker 25%`, a share over 0 up to 100 %), which follows a change of theme as PowerPoint's picker's tints and shades do; `#RRGGBB`; or one of them with DrawingML's transforms after it, in order (`accent1 lumMod 75% lumOff 25%`, `tx1 tint 50%`, `#4472C4 alpha 50%`, `accent2 hueOff 30°`; `tint`, `shade`, `lumMod`, `lumOff`, `lum`, `satMod`, `satOff`, `sat`, `hueMod`, `hueOff`, `hue`, `alpha`, `alphaMod`, `alphaOff`, a share in `%`, `hue` and `hueOff` in degrees), as a file PowerPoint wrote has them. In code a colour (`ColorFormat`) has python-pptx's `brightness`, -1 to 1 (`0.4` is lighter 40 %), on a theme colour only. `z` orders a shape among the slide's shapes and placeholders, so a negative `z` puts one under a placeholder's words. Paths are from the deck's module's folder.
183
183
 
184
184
  A slide's `animations` are PowerPoint's Animation Pane, in order, each on one of the slide's own shapes (`shape`, by name; in a block, `<slide>/<shape>`), or one `paragraph` of its text, from 0:
185
185
 
186
186
  | Field | Default | What it is |
187
187
  | --- | --- | --- |
188
- | `effect` | | Entrances `appear`, `fade`, `wipe`, `fly-in`, `zoom`; exits `disappear`, `fade-out`, `wipe-out`, `fly-out`, `zoom-out`; `pulse`; `path` |
188
+ | `effect` | | PowerPoint's: entrances `appear`, `fade`, `fly-in`, `float-in`, `split`, `wipe`, `zoom`; exits `disappear`, `fade-out`, `fly-out`, `float-out`, `split-out`, `wipe-out`, `zoom-out`; emphasis `pulse`, `grow-shrink` (Grow/Shrink), `spin`, `transparency`; `path` |
189
189
  | `start` | `on-click` | `on-click`, `with-previous`, `after-previous`. What starts with no click before it plays as the slide opens |
190
- | `direction` | `from-bottom` | A wipe's or a fly's side: `from-bottom`, `from-top`, `from-left`, `from-right` |
191
- | `duration` | 0.5 (`appear`, `disappear` 0; `path` 2) | Seconds |
190
+ | `direction` | the effect's first | Its Effect Options' way: a wipe's or a fly's side, `from-bottom`, `from-top`, `from-left`, `from-right` (a fly out's is where it goes); a split's `vertical-out`, `vertical-in`, `horizontal-out`, `horizontal-in`; a float's `up` or `down`; a spin's `clockwise` or `counterclockwise`; a Grow/Shrink's `both`, `horizontal` or `vertical`. A way the effect has not is said and drawn as its first |
191
+ | `amount` | 1.5, 360, 0.5 | A Grow/Shrink's size, a share of its own (PowerPoint's Tiny 1.1, Smaller 0.5, Larger 1.5, Huge 4; under 1 shrinks); a spin's degrees (Quarter 90, Half 180, Full 360, Two Spins 720); a Transparency's share that shows through, up to 1. An emphasis stays at its amount after it |
192
+ | `duration` | 0.5 (`appear`, `disappear` 0; `float-in`, `float-out` 1; `grow-shrink`, `spin`, `path` 2) | Seconds |
192
193
  | `delay` | 0 | Seconds |
193
194
  | `path` | | A `path` effect's, in points from where the shape stands, in SVG's `M`, `L` and `C`, absolute: `M0 0 L200 0` |
195
+ | `animate_text` | | `word` or `letter`: its text a word or a letter at a time, PowerPoint's Animate text (each word is what stands between spaces, each letter a character but a space; what has no text plays as one, said) |
196
+ | `text_delay` | 0.1 | By word or letter, how far apart each starts, a share of `duration`: the effect lasts `duration` × (1 + (words − 1) × `text_delay`) |
197
+ | `repeat` | 1 | How many times it plays (a fraction stops partway), or `until-next-click` or `until-end-of-slide`: PowerPoint's Repeat. A count is that many rounds on the slide's clock; until something, one round, and it goes on repeating till its step's still (the next click) or the slide's last |
198
+ | `rewind` | | `true`: once played, back as it was before it (an entrance hidden again, an emphasis undone), PowerPoint's Rewind when done playing |
194
199
 
195
200
  Each click is a step: its still, a page of a PDF, is drawn once what it started has ended, and `allyhub frames` has a tile for each. What a shape comes on by an entrance is not drawn before it. A component's `render(t)` is given the seconds since its shape came on, and a step that brings one on rests once it has settled. A PowerPoint file has them as PowerPoint's own. A generated slide adds them with `slide.animations.add(shape, effect, options)`.
196
201
 
197
202
  A video on a slide plays from when its shape comes on, to its end, when presenting. In a PowerPoint file a component that moves is a video of what its code draws, from when its shape comes on, for as long as it moves (its `dur`, 4 seconds when absent), which plays as it comes on (as the slide opens, if it has no entrance); one that does not move is a picture.
198
203
 
199
- A slide's `transition` is how it comes on from the slide before: `type` (`fade`, `push`, `wipe`, or `morph`), `direction` for a push or a wipe (`from-right` unless said), `duration` in seconds (0.7 for a fade, 1 for a push or a wipe, 2 for a morph). What is on the slide starts when it is over, and presenting plays it. A morph moves each shape the two slides share by name from the one's place and size to the other's, as PowerPoint's Morph; what only one has fades. So name a shape the same on both slides to carry it across. A PowerPoint file has them as its own, with a fade for a PowerPoint too old for Morph. A generated slide sets `slide.transition`.
204
+ A slide's `transition` is how it comes on from the slide before, PowerPoint's: `type` (`fade`, `push`, `wipe`, `split`, `reveal`, `cut`, `cover`, `uncover`, `zoom` or `morph`), `direction`, its Effect Options (a push's, a wipe's, a cover's and an uncover's side, `from-right` unless said, `from-left`, `from-top`, `from-bottom`, and a cover's and an uncover's corners, `from-top-right`, `from-bottom-right`, `from-top-left`, `from-bottom-left`; a reveal's `from-right` or `from-left`; a split's `vertical-out` unless said, `vertical-in`, `horizontal-out`, `horizontal-in`; a zoom's `in` unless said, `out`, or `rotate`, PowerPoint's Zoom and Rotate; a way its type has not is said and drawn as its default), `through_black: true` (a fade's, a cut's or a reveal's Through Black, to a black screen and from it), and `duration` in seconds (PowerPoint's: 0.7 for a fade, 1 for a push, a wipe, a cover, an uncover or a zoom, 1.5 for a split, 2 for a reveal or a morph; a cut has none, and through black is black as long as its `duration` says). What is on the slide starts when it is over, and presenting plays it. A cover comes over the slide before, an uncover takes that one away over this, a reveal slides it off as it fades. A morph moves each shape the two slides share by name from the one's place and size to the other's, as PowerPoint's Morph; what only one has fades. So name a shape the same on both slides to carry it across. A PowerPoint file has them as its own (a reveal and a zoom as PowerPoint 2010's, a morph as 2016's), with a fade for a PowerPoint too old for them. A generated slide sets `slide.transition`.
200
205
 
201
- A shape's `chart` is PowerPoint's own chart, with its numbers in a workbook a person opens with Edit Data. `type` is python-pptx's, in lower case: `column-clustered`, `column-stacked`, `column-stacked-100`, the same three of `bar`, `line`, `line-markers`, `area`, `area-stacked`, `area-stacked-100`, `pie`, `doughnut`, and XY's `scatter`, `scatter-lines` and `scatter-smooth`, each series with an `x` beside its `values`, or with `data`, `categories` naming the column across. There is no 3D, bubble, radar or second axis. Its numbers are written in it, or read from a project file, so a slide shows what the sheet says:
206
+ A shape's `link` is where a click on it goes in a slide show (PowerPoint's Link on a shape, `p:cNvPr/a:hlinkClick`): an address (`https://…`), `#<slide id>` (Place in This Document; a generated slide's `#<block>/<id>`), or one of PowerPoint's show jumps, `ppaction://hlinkshowjump?jump=` and `firstslide`, `lastslide`, `nextslide`, `previousslide` or `endshow`; a slide or a jump the deck has not is AK-M011. Presenting follows a shape's link on a click anywhere on it, and a link in its words on a click anywhere on the shape too (PowerPoint's only on the words); a PDF keeps an address's link.
207
+
208
+ A shape's `audio` is a sound file of the project (`mp3`, `m4a`, `wav`, `aac` play in PowerPoint), PowerPoint's Insert Audio: drawn as a speaker filling its frame (half an inch is PowerPoint's), playing with the same `playback` as a movie's, its `hide` hiding the icon through the show (Hide During Show). A render of the deck mixes it from where it starts at its volume, the whole file (its trim and loop are presenting's and PowerPoint's). In code, `shapes.add_audio(path, left, top)`.
209
+
210
+ A `movie`'s `playback` is how it plays, PowerPoint's Playback tab: `start`, `auto` (as it comes on, the default) or `on-click` (a click of its own after the slide's animations, In Click Sequence), `trim` (`start` and `end`, seconds into the file it plays between), `loop` (again from its start until the slide goes), `volume` (a share, 0 mutes it; PowerPoint's 80 % unless said, which presenting and a render play at full), `fullscreen` (over the whole slide while it plays) and `hide` (not shown while it does not play). A PowerPoint file has them as its own (`p14:trim`, the timing's `p:video`). Presenting plays them; a render of the deck draws the trim, the loop and the start, and mixes a movie's sound at its volume (a movie's sound is in a render now, as PowerPoint plays it); past its trim's end a movie that does not loop is no longer drawn, and one that starts on a click while its first frame is not its file's first shows the seconds before its trim until it plays. In code, `add_movie`'s `playback`.
211
+
212
+ A slide's `section` starts a section there, by its name (PowerPoint's Add Section, `p14:sectionLst`; a name the editor's rail and PowerPoint's thumbnails show and no slide does, so the slides file's, not the script's): it holds that slide and those after it up to the next slide with a `section`; a block's is at its first slide. Slides before the first are PowerPoint's Default Section, which a PowerPoint file names so. A section of a file with no slides is said on import.
213
+
214
+ A shape's `chart` is PowerPoint's own chart, with its numbers in a workbook a person opens with Edit Data. `type` is python-pptx's, in lower case: `column-clustered`, `column-stacked`, `column-stacked-100`, the same three of `bar`, `line`, `line-markers`, `area`, `area-stacked`, `area-stacked-100`, `pie`, `doughnut`, and XY's `scatter`, `scatter-lines` and `scatter-smooth`, each series with an `x` beside its `values`, or with `data`, `categories` naming the column across. A chart of columns, lines or areas combines them (PowerPoint's Combo): a series' `type` draws it as another of those (`line` among columns), and its `secondary: true` puts it on a second value axis at the right, `secondary_axis`; a pie's, a bar's or a scatter's series with either is AK-M011. There is no 3D, bubble or radar. Its numbers are written in it, or read from a project file, so a slide shows what the sheet says:
202
215
 
203
216
  ```yaml
204
217
  revenue:
@@ -211,7 +224,7 @@ revenue:
211
224
  legend: bottom
212
225
  ```
213
226
 
214
- Without `data`, `categories` is a list of names and each series has its `values` (one per category, `null` for none). A value read from a file is a plain number. A column that is not there, a cell that is not a number, or values that do not fit the categories are AK-M011, with what the file has. The chart's title is the script's: the shape's words.
227
+ Without `data`, `categories` is a list of names and each series has its `values` (one per category, `null` for none). A value read from a file is a plain number. A column that is not there, a cell that is not a number, or values that do not fit the categories are AK-M011, with what the file has. The chart's title and its axes' titles are the script's, as every word a slide shows is: the shape's words, its title as a line (`sales: Revenue by quarter`), or by name when an axis has one (`sales: { title: Revenue by quarter, category_axis: Quarter, value_axis: Dollars (k), secondary_axis: Margin }`, PowerPoint's Axis Titles; a second axis's at the right). Its categories and its series' names are the slides file's, as its numbers are, since they come with them from a data file.
215
228
 
216
229
  | Field | Default | What it is |
217
230
  | --- | --- | --- |
@@ -222,25 +235,26 @@ Without `data`, `categories` is a list of names and each series has its `values`
222
235
  | `vary_by_categories` | a pie's and a doughnut's | A colour per category |
223
236
  | `category_colors` | the accents in turn | Where it varies by categories, each category's colour in order (a slice's): a theme colour or `#RRGGBB`. In code, a series' `points[i].format.fill`, as python-pptx's |
224
237
  | `hole_size` | 50 | A doughnut's, in % |
225
- | `value_axis`, `category_axis` | automatic | `min`, `max`, `major`, `gridlines` (the value axis's are on), `visible`, `format` (Excel's), `reverse`, `gridline_color`, `line_color` |
238
+ | `value_axis`, `category_axis`, `secondary_axis` | automatic | `min`, `max`, `major`, `gridlines` (the value axis's are on), `visible`, `format` (Excel's), `reverse`, `gridline_color`, `line_color` |
226
239
  | `size`, `title_size`, `color` | 12, 14.4, `dk1` | Its text's points, its title's, and their colour |
227
240
  | a series' `color`, `format`, `smooth`, `line_width`, `marker_size` | the accents in turn, `General`, off, 2.25, 5 | |
241
+ | a series' `type`, `secondary` | the chart's, off | A combination chart's: `column-clustered`, `column-stacked`, `column-stacked-100`, `line`, `line-markers`, `area`, `area-stacked`, `area-stacked-100`; on the second axis. Drawn and written as Excel's: areas behind columns behind lines, the second axis's over the first's |
228
242
 
229
- In code, `shapes.add_chart(XL_CHART_TYPE.X, left, top, width, height, chart_data)` makes one from a `CategoryChartData`, or an `XyChartData` (`add_series(name)`, `add_data_point(x, y)`), as python-pptx's does, with its `.chart`. A scale left automatic is PowerPoint's in the file and drawn here by the same rules, so a number a person changes moves it; set `min`, `max` and `major` to fix it. Where the plot sits is written in the file, so every app puts it where the stage does. `allyhub inspect --kind chart-data` lists each chart's numbers and the file they came from.
243
+ In code, `shapes.add_chart(XL_CHART_TYPE.X, left, top, width, height, chart_data)` makes one from a `CategoryChartData`, or an `XyChartData` (`add_series(name)`, `add_data_point(x, y)`), as python-pptx's does, with its `.chart`: `series[i].chart_type` and `series[i].on_secondary_axis` combine it, `chart.plots` is a plot per kind and axis as python-pptx reads a combination chart, `chart.secondary_value_axis` is the second axis, and each axis's `has_title` and `axis_title.text_frame.text` its title. A scale left automatic is PowerPoint's in the file and drawn here by the same rules, so a number a person changes moves it; set `min`, `max` and `major` to fix it. Where the plot sits is written in the file, so every app puts it where the stage does. `allyhub inspect --kind chart-data` lists each chart's numbers and the file they came from.
230
244
 
231
245
  What the slides file names that the deck does not have (a layout, a generator, a component or its prop, a shape to change or animate, a file) is AK-M011, at its line; an exception in a generator, at the line of the deck's module that threw it. A slide that is not the format is left out, so one check finds every problem.
232
246
 
233
247
  ## The script
234
248
 
235
- A deck's script has a row per slide under `slides`: its `text` by shape name (a placeholder's or a text box's; a list is paragraphs, a list in it a level deeper; `**bold**`, `*italic*`, `` `code` ``, in the theme's `code` font, `<span color="accent1" font="Inter Tight">words</span>`, in a colour as the slides file writes one (`accent1`, `accent1 lighter 40%`, `#RRGGBB`), a font of their own, or both, are runs, as in a doc; a span also takes `size="24"`, in points, `bold="false"` and `italic="false"`, plain words in a bold or italic level, `underline="true"`, `link="https://…"`, `strike="true"`, `highlight="#FFFF00"` and `baseline="0.3"`, raised or, below 0, lowered, a share of the size. A slide number placeholder writes its own text, a number PowerPoint keeps up to date) its `alt`, each picture's or shape's alternative text by name (what a screen reader says, PowerPoint's Alt Text), and its `notes`. A key is `<prefix>.<slide>.<shape>` (the prefix is the deck's id with `/` as `.`), `<prefix>.<slide>.alt.<shape>`, `<prefix>.<slide>.notes`. A placeholder with no words in the script is empty, and an empty placeholder is not drawn. A layout's date, footer and slide number placeholders are on a slide only where it names them in the slides file (`slide-number: {}`), as PowerPoint's Header & Footer and python-pptx's `add_slide` have it. Words are in the script's language, and in Japanese where they have kana, Korean where they have hangul, on the stage and in an exported file: Han characters take that language's forms.
249
+ A deck's script has a row per slide under `slides`: its `text` by shape name (a placeholder's or a text box's; a list is paragraphs, a list in it a level deeper; `**bold**`, `*italic*`, `` `code` ``, in the theme's `code` font, `<span color="accent1" font="Inter Tight">words</span>`, in a colour as the slides file writes one (`accent1`, `accent1 lighter 40%`, `#RRGGBB`), a font of their own, or both, are runs, as in a doc; a span also takes `size="24"`, in points, `bold="false"` and `italic="false"`, plain words in a bold or italic level, `underline="true"`, `link="https://…"` (or `link="#<slide id>"`, a slide of the deck, or one of PowerPoint's show jumps, as a shape's `link`), `strike="true"`, `highlight="#FFFF00"`, `baseline="0.3"`, raised or, below 0, lowered, a share of the size (PowerPoint's Superscript is `0.3`, Subscript `-0.25`), `spacing="3"`, points between its letters, below 0 tighter (PowerPoint's Character Spacing), `underline="wavy"`, an underline's style (as the slides file's), `strike="dblStrike"`, and `caps="small"` or `caps="all"`. A slide number placeholder writes its own text, a number PowerPoint keeps up to date) its `alt`, each picture's or shape's alternative text by name (what a screen reader says, PowerPoint's Alt Text), and its `notes`. A key is `<prefix>.<slide>.<shape>` (the prefix is the deck's id with `/` as `.`), `<prefix>.<slide>.alt.<shape>`, `<prefix>.<slide>.notes`. A placeholder with no words in the script is empty, and an empty placeholder is not drawn. A layout's date, footer and slide number placeholders are on a slide only where it names them in the slides file (`slide-number: {}`), as PowerPoint's Header & Footer and python-pptx's `add_slide` have it. Words are in the script's language, and in Japanese where they have kana, Korean where they have hangul, on the stage and in an exported file: Han characters take that language's forms.
236
250
 
237
251
  ## What a person changes in the editor
238
252
 
239
- The slides' order, a slide's layout, hidden, added, duplicated or removed; text typed in place and the notes; a shape moved and sized, brought forward or sent back, removed; a text box, picture, video or basic shape placed; a theme colour for a fill or a text, a text's size, bold and alignment; a shape reset to its layout. Every one of these is an edit of the slides file or the script; everything else (masters, layouts, components, generators, style beyond these) is yours, in the deck's module. When you and the person change these files at once, both changes stand: a frame, a shape and an animation merge field by field, the slides' order and a shape's paragraphs line by line, and where you both changed one value the person's stands; a slide or shape one of you removed while the other changed it stays, changed. The person keeps or undoes each of your changes. A slide the person adds is `slide-` and four letters (`slide-k3f9`), so give yours ids by what they are.
253
+ The slides' order, a slide's layout, hidden, added, duplicated, copied and pasted (here or from another deck, under a new id) or removed; when it goes on by itself (`advance_after`); its section, added, renamed and removed (a section whose first slide moves or goes stays where it was, on the slide after it); a shape's alt text, a table's merged cells, a run's character spacing and superscript or subscript; a slide's animations from PowerPoint's gallery (every effect the slides file has, the basic motion paths as `path`s), their direction, delay and by paragraph; text typed in place and the notes; a shape moved and sized, brought forward or sent back, removed; a text box, picture, video or basic shape placed; a theme colour for a fill or a text, a text's size, bold and alignment; a shape reset to its layout. Every one of these is an edit of the slides file or the script; everything else (masters, layouts, components, generators, style beyond these) is yours, in the deck's module. When you and the person change these files at once, both changes stand: a frame, a shape and an animation merge field by field, a table's merges by their first cell, the slides' order and a shape's paragraphs line by line, and where you both changed one value the person's stands; a slide or shape one of you removed while the other changed it stays, changed. The person keeps or undoes each of your changes. A slide the person adds is `slide-` and four letters (`slide-k3f9`), so give yours ids by what they are.
240
254
 
241
255
  ## Importing a PowerPoint file
242
256
 
243
- `allyhub slides import <file.pptx> --to reviews/q3.ts` makes a deck of a PowerPoint file: its masters and layouts as the deck's module, `reviews/q3.ts` (python-pptx's calls, only what differs from Office's text styles; by default the file's name, `.ts`), its slides on their layouts as its slides file, `reviews/q3.yaml` (what each moves, its own shapes, pictures, videos, tables, charts and lines, their rotation, flips and groups, its background, animations and transition), each slide's words, alternative text and notes as the script, `reviews/q3.<lang>.yaml` (bold and italic as `**…**` and `*…*`, a run's own bold or italic off as `bold="false"` or `italic="false"`, a link, a highlight, a baseline, a colour, a font, a size, an underline or a strike of their own as spans, what all of a shape's text has as its `text` in the slides file, a deeper level as a list in the list), its pictures and videos beside them, by their files' names (another where a file there has it). A slide's and a shape's name is kept where it is a name (letters, digits, `_`, `-`), so a deck AllyHub wrote reads back with its own. A table's style is resolved into its rows' fills, text and rules; a theme colour lightened or darkened as PowerPoint's picker does it is that theme colour (`accent1 lighter 40%`), one changed otherwise the colour it makes.
257
+ `allyhub slides import <file.pptx> --to reviews/q3.ts` makes a deck of a PowerPoint file: its masters and layouts as the deck's module, `reviews/q3.ts` (python-pptx's calls, only what differs from Office's text styles; by default the file's name, `.ts`), its slides on their layouts as its slides file, `reviews/q3.yaml` (what each moves, its own shapes, pictures, videos, tables with their merged cells, charts and lines, their rotation, flips and groups, its background, animations and transition), each slide's words, alternative text and notes as the script, `reviews/q3.<lang>.yaml` (bold and italic as `**…**` and `*…*`, a run's own bold or italic off as `bold="false"` or `italic="false"`, a link, a highlight, a baseline, a character spacing, a colour, a font, a size, an underline or a strike of their own as spans, what all of a shape's text has as its `text` in the slides file, a deeper level as a list in the list), its pictures and videos beside them, by their files' names (another where a file there has it). A slide's and a shape's name is kept where it is a name (letters, digits, `_`, `-`), so a deck AllyHub wrote reads back with its own. A table's style is kept by name where it is one of PowerPoint's built-in styles, its Table Design options with it, and one the file defines itself is resolved into its rows' fills, text and rules; a theme colour lightened or darkened as PowerPoint's picker does it is that theme colour (`accent1 lighter 40%`), one changed by other transforms that theme colour with them (`accent1 tint 50% satMod 120%`), `tx1` and `bg1` kept by name with the master's colour map; one inverted, greyed, or changed by gamma or a channel is the colour it makes.
244
258
 
245
259
  Everything the file holds that the deck does not carry over as it is is reported, grouped (what, why, how many, where), all of it with `--json`: what nothing read, an extension of Office's, a part, what the deck cannot hold, what is held another way, what is missing from the file. Nothing is dropped without a line. `--lang` names the script's language.
246
260
 
package/docs/speech.md CHANGED
@@ -50,7 +50,7 @@ Alone, a take is the whole recording, from its first word to its last. Each meth
50
50
  - `.roomTone(tone)`: how the part's lead and tail are filled where the take has no silence of its own round the part's words ([Room tone](#room-tone)).
51
51
  - `.speed(times)`: plays it `times` as fast, its pitch kept (0.5 to 2); its words, the part's length and everything timed by them follow. The file is not changed. A part whose `footage()` shows the take's own picture cannot change its speed (`part()` throws).
52
52
 
53
- With `.edits()`, `range` and `saying` look only at the words the edits keep: a phrase or line said only in removed words is AK-T006. A take a voice tool generated keeps the text it was made from in its `.gen.json`: a part whose line is not in that text is AK-T007.
53
+ With `.edits()`, `range` and `saying` look only at the words the edits keep: a phrase or line said only in removed words is AK-T006. A take a voice tool generated keeps the text it was made from in its `.provenance`: a part whose line is not in that text is AK-T007.
54
54
 
55
55
  ### Room tone
56
56
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allyhub/sdk",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "description": "What an agent writes videos, decks and workbooks with: each built-in kind's authoring API, re-exported from its extension. The root, /dom, /media and /scenery are the video's: video(), parts with their speech, footage and sounds, defineComponent() and custom() layers, the layout, motion and input helpers, the scenery() layer's options; /slides is the deck's, python-pptx's API; /image is the image's, its boards each its own size; /sheets is the sheet's, openpyxl's API. Nothing a host needs.",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "homepage": "https://allyhub.com",