@allyhub/sdk 0.2.0 → 0.4.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.
- package/dist/free.d.ts +2 -2
- package/dist/index.d.ts +2 -9
- package/dist/index.js +1 -1
- package/dist/module.d.ts +2 -3
- package/dist/module.js +1 -1
- package/dist/parts.d.ts +2 -2
- package/dist/piece.d.ts +7 -32
- package/dist/piece.js +1 -1
- package/dist/props.d.ts +53 -10
- package/dist/slides.d.ts +8 -0
- package/dist/slides.js +2 -0
- package/docs/README.md +1 -1
- package/docs/batches.md +2 -2
- package/docs/defaults.md +106 -3
- package/docs/docs.md +1 -1
- package/docs/layers.md +1 -1
- package/docs/modeling.md +6 -6
- package/docs/project.md +7 -6
- package/docs/scenery.md +1 -1
- package/docs/sheets.md +1 -1
- package/docs/slides.md +182 -80
- package/node_modules/@allyhub-next/audio/package.json +1 -1
- package/node_modules/@allyhub-next/formats/dist/data/script.d.ts +22 -0
- package/node_modules/@allyhub-next/formats/dist/data/script.js +1 -1
- package/node_modules/@allyhub-next/formats/dist/data/slides.d.ts +1494 -0
- package/node_modules/@allyhub-next/formats/dist/data/slides.js +2 -0
- package/node_modules/@allyhub-next/formats/dist/index.d.ts +2 -0
- package/node_modules/@allyhub-next/formats/dist/index.js +1 -1
- package/node_modules/@allyhub-next/formats/dist/items.d.ts +26 -0
- package/node_modules/@allyhub-next/formats/dist/items.js +1 -1
- package/node_modules/@allyhub-next/formats/dist/layout.d.ts +2 -0
- package/node_modules/@allyhub-next/formats/dist/layout.js +1 -1
- package/node_modules/@allyhub-next/formats/dist/note-shape.d.ts +39 -0
- package/node_modules/@allyhub-next/formats/dist/note-shape.js +2 -0
- package/node_modules/@allyhub-next/formats/dist/schemas.d.ts +418 -0
- package/node_modules/@allyhub-next/formats/dist/schemas.js +1 -1
- package/node_modules/@allyhub-next/formats/package.json +1 -1
- package/node_modules/@allyhub-next/protocol/dist/app.d.ts +1 -62
- package/node_modules/@allyhub-next/protocol/dist/app.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/auth.d.ts +17 -17
- package/node_modules/@allyhub-next/protocol/dist/auth.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/cli.d.ts +1 -5
- package/node_modules/@allyhub-next/protocol/dist/cli.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/editor.d.ts +13 -26
- package/node_modules/@allyhub-next/protocol/dist/editor.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/index.d.ts +1 -0
- package/node_modules/@allyhub-next/protocol/dist/index.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/notes.d.ts +163 -0
- package/node_modules/@allyhub-next/protocol/dist/notes.js +2 -0
- package/node_modules/@allyhub-next/protocol/dist/registry.d.ts +4 -2
- package/node_modules/@allyhub-next/protocol/dist/registry.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/routes.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/runtimes.d.ts +3 -0
- package/node_modules/@allyhub-next/protocol/dist/runtimes.js +1 -1
- package/node_modules/@allyhub-next/protocol/dist/tools.d.ts +38 -0
- package/node_modules/@allyhub-next/protocol/dist/tools.js +1 -1
- package/node_modules/@allyhub-next/protocol/package.json +1 -1
- package/node_modules/@allyhub-next/runtimes/dist/errors.d.ts +5 -1
- package/node_modules/@allyhub-next/runtimes/dist/index.d.ts +1 -0
- package/node_modules/@allyhub-next/runtimes/dist/index.js +1 -1
- package/node_modules/@allyhub-next/runtimes/dist/node-program.d.ts +3 -0
- package/node_modules/@allyhub-next/runtimes/dist/node-program.js +2 -0
- package/node_modules/@allyhub-next/runtimes/dist/packages.d.ts +65 -0
- package/node_modules/@allyhub-next/runtimes/dist/packages.js +4 -0
- package/node_modules/@allyhub-next/runtimes/dist/runtimes.js +2 -2
- package/node_modules/@allyhub-next/runtimes/dist/unpack.d.ts +7 -0
- package/node_modules/@allyhub-next/runtimes/dist/unpack.js +1 -1
- package/node_modules/@allyhub-next/runtimes/package.json +5 -1
- package/node_modules/@allyhub-next/runtimes/pins/docx/package-lock.json +67 -0
- package/node_modules/@allyhub-next/runtimes/pins/docx/package.json +9 -0
- package/node_modules/@allyhub-next/runtimes/pins/exceljs/package-lock.json +2533 -0
- package/node_modules/@allyhub-next/runtimes/pins/exceljs/package.json +8 -0
- package/node_modules/@allyhub-next/runtimes/pins/gltf-tools/package-lock.json +753 -0
- package/node_modules/@allyhub-next/runtimes/pins/gltf-tools/package.json +14 -0
- package/node_modules/@allyhub-next/runtimes/pins/manifold-3d/package-lock.json +950 -0
- package/node_modules/@allyhub-next/runtimes/pins/manifold-3d/package.json +8 -0
- package/node_modules/@allyhub-next/runtimes/pins/onnxruntime-node/package-lock.json +227 -0
- package/node_modules/@allyhub-next/runtimes/pins/onnxruntime-node/package.json +8 -0
- package/node_modules/@allyhub-next/runtimes/pins/sherpa-onnx-node/package-lock.json +105 -0
- package/node_modules/@allyhub-next/runtimes/pins/sherpa-onnx-node/package.json +8 -0
- package/node_modules/@allyhub-next/runtimes/pins/tesseract.js/package-lock.json +128 -0
- package/node_modules/@allyhub-next/runtimes/pins/tesseract.js/package.json +9 -0
- package/node_modules/@allyhub-next/runtimes/schemas/runtimes.schema.json +5 -24
- package/node_modules/@allyhub-next/scenery/package.json +1 -1
- package/node_modules/@allyhub-next/slides-core/LICENSE +241 -0
- package/node_modules/@allyhub-next/slides-core/dist/animation.d.ts +129 -0
- package/node_modules/@allyhub-next/slides-core/dist/animation.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/api.d.ts +649 -0
- package/node_modules/@allyhub-next/slides-core/dist/api.js +4 -0
- package/node_modules/@allyhub-next/slides-core/dist/capabilities.d.ts +18 -0
- package/node_modules/@allyhub-next/slides-core/dist/capabilities.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart-api.d.ts +165 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart-api.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart-file.d.ts +11 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart-file.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart.d.ts +184 -0
- package/node_modules/@allyhub-next/slides-core/dist/chart.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/check.d.ts +7 -0
- package/node_modules/@allyhub-next/slides-core/dist/check.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/enums.d.ts +146 -0
- package/node_modules/@allyhub-next/slides-core/dist/enums.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/file.d.ts +109 -0
- package/node_modules/@allyhub-next/slides-core/dist/file.js +4 -0
- package/node_modules/@allyhub-next/slides-core/dist/index.d.ts +21 -0
- package/node_modules/@allyhub-next/slides-core/dist/index.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/measure.d.ts +34 -0
- package/node_modules/@allyhub-next/slides-core/dist/measure.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/model.d.ts +278 -0
- package/node_modules/@allyhub-next/slides-core/dist/model.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/office.d.ts +58 -0
- package/node_modules/@allyhub-next/slides-core/dist/office.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/path.d.ts +6 -0
- package/node_modules/@allyhub-next/slides-core/dist/path.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/placeholders.d.ts +7 -0
- package/node_modules/@allyhub-next/slides-core/dist/placeholders.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/resolve.d.ts +181 -0
- package/node_modules/@allyhub-next/slides-core/dist/resolve.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/script.d.ts +43 -0
- package/node_modules/@allyhub-next/slides-core/dist/script.js +3 -0
- package/node_modules/@allyhub-next/slides-core/dist/stage.d.ts +63 -0
- package/node_modules/@allyhub-next/slides-core/dist/stage.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/strict.d.ts +23 -0
- package/node_modules/@allyhub-next/slides-core/dist/strict.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/theme.d.ts +72 -0
- package/node_modules/@allyhub-next/slides-core/dist/theme.js +2 -0
- package/node_modules/@allyhub-next/slides-core/dist/units.d.ts +35 -0
- package/node_modules/@allyhub-next/slides-core/dist/units.js +2 -0
- package/node_modules/@allyhub-next/slides-core/package.json +14 -0
- package/node_modules/@allyhub-next/video-core/dist/export.d.ts +6 -5
- package/node_modules/@allyhub-next/video-core/dist/export.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/fact.d.ts +173 -4
- package/node_modules/@allyhub-next/video-core/dist/fact.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/formats.d.ts +6 -13
- package/node_modules/@allyhub-next/video-core/dist/formats.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/index.d.ts +0 -1
- package/node_modules/@allyhub-next/video-core/dist/index.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/measure.d.ts +83 -0
- package/node_modules/@allyhub-next/video-core/dist/piece.d.ts +8 -9
- package/node_modules/@allyhub-next/video-core/dist/piece.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/problem.d.ts +9 -1
- package/node_modules/@allyhub-next/video-core/dist/problem.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/schema.d.ts +0 -2
- package/node_modules/@allyhub-next/video-core/dist/script-edit.d.ts +4 -0
- package/node_modules/@allyhub-next/video-core/dist/script.d.ts +8 -0
- package/node_modules/@allyhub-next/video-core/dist/script.js +1 -1
- package/node_modules/@allyhub-next/video-core/dist/timeline.d.ts +34 -1
- package/node_modules/@allyhub-next/video-core/package.json +1 -1
- package/package.json +15 -8
- package/node_modules/@allyhub-next/video-core/dist/slides.d.ts +0 -37
- package/node_modules/@allyhub-next/video-core/dist/slides.js +0 -2
package/docs/slides.md
CHANGED
|
@@ -1,111 +1,213 @@
|
|
|
1
1
|
# Slides
|
|
2
2
|
|
|
3
|
-
A deck is
|
|
3
|
+
A deck is PowerPoint's model, made by code with python-pptx's API. An item whose entry is `slides.ts` holds:
|
|
4
|
+
|
|
5
|
+
- `slides.ts`: the presentation's slide masters, layouts and placeholders, components and generators.
|
|
6
|
+
- `slides.yaml`: the slides in order, each on a layout, and what a person (or you) placed or changed on a slide. A value there overrides the layout's, as a placeholder moved on a slide does in PowerPoint.
|
|
7
|
+
- `script.<locale>.yaml`: each slide's words, by shape name, and its speaker notes, a file per language.
|
|
8
|
+
|
|
9
|
+
The API is python-pptx 1.0.2's, by its names and behaviour; its documentation (python-pptx.readthedocs.io) is the reference. `allyhub slides capabilities` lists which of its classes, names and enumerations are held, where they differ, and what is added. A name that is not held throws where it is written, naming what its class holds. This page is what is AllyHub's own.
|
|
4
10
|
|
|
5
11
|
```ts file=launch/deck/slides.ts
|
|
6
|
-
import {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
12
|
+
import {
|
|
13
|
+
Inches,
|
|
14
|
+
MSO_ANCHOR,
|
|
15
|
+
PP_PLACEHOLDER,
|
|
16
|
+
Pt,
|
|
17
|
+
presentation,
|
|
18
|
+
} from "@allyhub/sdk/slides";
|
|
19
|
+
|
|
20
|
+
export default presentation({ size: "16:9" }, (prs) => {
|
|
21
|
+
prs.theme.colors = { accent1: "#2F5BEA" };
|
|
22
|
+
const master = prs.slide_masters.add("Brand");
|
|
23
|
+
const title = master.placeholders.add(
|
|
24
|
+
PP_PLACEHOLDER.TITLE,
|
|
25
|
+
Inches(0.6),
|
|
26
|
+
Inches(0.4),
|
|
27
|
+
Inches(12),
|
|
28
|
+
Inches(1.2),
|
|
29
|
+
);
|
|
30
|
+
title.text_frame.vertical_anchor = MSO_ANCHOR.MIDDLE;
|
|
31
|
+
title.text_frame.list_style[0].font.size = Pt(40);
|
|
32
|
+
master.placeholders.add(
|
|
33
|
+
PP_PLACEHOLDER.BODY,
|
|
34
|
+
Inches(0.6),
|
|
35
|
+
Inches(1.8),
|
|
36
|
+
Inches(12),
|
|
37
|
+
Inches(5),
|
|
38
|
+
);
|
|
39
|
+
master.shapes.add_picture(
|
|
40
|
+
"../../../assets/media/logo.png",
|
|
41
|
+
Inches(12.2),
|
|
42
|
+
Inches(6.9),
|
|
43
|
+
Inches(0.9),
|
|
44
|
+
Inches(0.4),
|
|
45
|
+
).name = "logo";
|
|
46
|
+
|
|
47
|
+
const cover = master.slide_layouts.add("Title Slide");
|
|
48
|
+
cover.placeholders.add(
|
|
49
|
+
PP_PLACEHOLDER.CENTER_TITLE,
|
|
50
|
+
Inches(1),
|
|
51
|
+
Inches(2.5),
|
|
52
|
+
Inches(11.3),
|
|
53
|
+
Inches(1.5),
|
|
54
|
+
);
|
|
55
|
+
cover.placeholders.add(PP_PLACEHOLDER.SUBTITLE);
|
|
56
|
+
|
|
57
|
+
const content = master.slide_layouts.add("Title and Content");
|
|
58
|
+
content.placeholders.add(PP_PLACEHOLDER.TITLE);
|
|
59
|
+
content.placeholders.add(PP_PLACEHOLDER.BODY);
|
|
36
60
|
});
|
|
37
61
|
```
|
|
38
62
|
|
|
39
|
-
|
|
63
|
+
```yaml
|
|
64
|
+
# launch/deck/slides.yaml
|
|
65
|
+
slides:
|
|
66
|
+
- id: cover
|
|
67
|
+
layout: Title Slide
|
|
68
|
+
- id: how
|
|
69
|
+
layout: Title and Content
|
|
70
|
+
shapes:
|
|
71
|
+
hero:
|
|
72
|
+
{ picture: ./media/hero.png, frame: { x: 560, y: 120, w: 360, h: 300 } }
|
|
73
|
+
title: { text: { size: 44 } }
|
|
74
|
+
```
|
|
40
75
|
|
|
41
|
-
|
|
76
|
+
```yaml
|
|
77
|
+
# launch/deck/script.en.yaml
|
|
78
|
+
title: Launch deck
|
|
79
|
+
slides:
|
|
80
|
+
- id: cover
|
|
81
|
+
text: { title: Tidyform, subtitle: Contracts, read for you }
|
|
82
|
+
notes: Thank the partners first.
|
|
83
|
+
- id: how
|
|
84
|
+
text:
|
|
85
|
+
title: How it works
|
|
86
|
+
body: [Drop a file, It is read, You sign]
|
|
87
|
+
```
|
|
42
88
|
|
|
43
|
-
|
|
44
|
-
| --- | --- | --- | --- |
|
|
45
|
-
| `pages` | `(ctx) => PartSpec[]` (or a promise) | required | The pages, in order; `ctx` is the one a video's parts function gets (`s`, `combo`, `asset`…) |
|
|
46
|
-
| `notes` | boolean | false | Each page's speaker notes are the message `<prefix>.<page key>.notes` |
|
|
47
|
-
| `prefix` | message key | the piece's id with `/` as `.` | The prefix of the notes' keys |
|
|
48
|
-
| `look` | string | `"clean"` | The look's name |
|
|
49
|
-
| `loadLimit` | seconds | 10 | How long loading may take (AK-P002) |
|
|
50
|
-
| `seekLimit` | seconds | 30 | How long one page may take to draw (AK-P003) |
|
|
89
|
+
## `presentation()`
|
|
51
90
|
|
|
52
|
-
`
|
|
91
|
+
`presentation(options, (prs) => { … })` is the default export of an item's `slides.ts`; its function is given python-pptx's `Presentation` and makes the deck's masters, layouts, components and generators. Paths are from the module's folder; lengths are EMU (`Inches`, `Pt`, `Cm`, `Mm`, `Emu`).
|
|
53
92
|
|
|
54
|
-
|
|
93
|
+
| Option | Default | What it is |
|
|
94
|
+
| ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
95
|
+
| `size` | `"16:9"` | A slide size by name (`16:9`, `16:10`, `4:3` as PowerPoint's; `a4`, `a4-portrait`, `letter`, `letter-portrait` the paper's own; `1:1`, `4:5`, `9:16`) or `{ width, height }` in EMU |
|
|
96
|
+
| `title` | none | Its name for people, what lists show it by |
|
|
97
|
+
| `theme` | the project's look's colours, standard fonts | `{ colors, fonts }`: theme colours by PresentationML's names (`dk1`, `lt1`, `dk2`, `lt2`, `accent1`…`accent6`, `hlink`, `folHlink`), over the project's look (`dk1` its foreground, `lt1` its background, `accent1` its accent); fonts (`major`, `minor`, `major_east_asian`, `minor_east_asian`, and `code`, Courier New unless set, which the script's `` `code` `` is set in: PowerPoint's theme has no such font, so in the file it is a run's own), Arial and Microsoft YaHei unless set: fonts every PowerPoint, Keynote and Google Slides has, drawn here by fonts of the same metrics (Arimo, Noto Sans SC), so a line breaks in the file where it breaks here. Any other font the config's `fonts` lists goes in the PowerPoint file, a face each for regular, bold, italic and bold italic, unless its own licence bits (`fsType`) forbid it or it is a variable font; `allyhub render` says what did not go in. An app that does not read a file's fonts replaces them, and its lines may break elsewhere |
|
|
55
98
|
|
|
56
|
-
|
|
57
|
-
- A deck has no clock to hear: a page's speech, sounds and transition are not played. A layer's `render(t)` is called at the still only. `footage(file)` on a page shows the file's frame at that moment; `footage()` without a file has no take to show (AK-A001).
|
|
58
|
-
- Layers lay out in the page's pixels with `layout(ctx)` and `ctx.dims`, as a video's do.
|
|
99
|
+
## Masters, layouts and placeholders
|
|
59
100
|
|
|
60
|
-
|
|
101
|
+
python-pptx opens these from a template; here code makes them.
|
|
61
102
|
|
|
62
|
-
|
|
103
|
+
- `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.
|
|
104
|
+
- `master.slide_layouts.add(name)`: a layout; its name is what `slides.yaml`'s slides name, unique in the deck.
|
|
105
|
+
- `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: `slides.yaml` 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.
|
|
106
|
+
- Beyond python-pptx's `add_shape` and `add_connector`, `shapes.build_freeform()` draws an outline (`add_line_segments`, `move_to`, `convert_to_shape`, and `add_curve_segment`, a cubic curve python-pptx lacks); `line.dash_style` takes `MSO_LINE`, and `line.begin_arrow` and `end_arrow` take `MSO_ARROWHEAD`; `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.
|
|
107
|
+
- 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; a shape `add_shape` makes starts with one centred paragraph, and `text_frame.text` replaces it with paragraphs aligned as the text style says (left), as python-pptx's.
|
|
108
|
+
- 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`. 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.
|
|
63
109
|
|
|
64
|
-
|
|
65
|
-
| --- | --- | --- |
|
|
66
|
-
| `a4` | 1240 × 1754 | 210 × 297 mm, at 150 dpi |
|
|
67
|
-
| `letter` | 1275 × 1650 | 8.5 × 11 in, at 150 dpi |
|
|
110
|
+
## Components
|
|
68
111
|
|
|
69
|
-
`
|
|
112
|
+
`prs.components.add(name, { props, layers })` is a shape drawn by code: `layers(props, { width, height, slide })` returns layers of the layer contract ([layers.md](layers.md): `custom()`, a component), laid out in the shape's frame; `width` and `height` are the frame's size in the slide's pixels (a 16:9 slide is drawn 1920 × 1080, 2 px a point). Its `render(t)` is given seconds into the slide; a still of the slide is drawn when what moves has settled. `props` lists the props a person may change in the editor, by the prop types (`text()`, `number()`…); `slides.yaml` places it as `{ component: name, props, frame }`, or code with `shapes.add_component(name, left, top, width, height, props)`.
|
|
70
113
|
|
|
71
|
-
|
|
114
|
+
## Generators
|
|
72
115
|
|
|
73
|
-
|
|
74
|
-
import { slides } from "@allyhub/sdk";
|
|
116
|
+
`prs.generators.add(name, (g) => { … })` makes slides from data: `g.data(path)` reads a data file (CSV rows, YAML, JSON) from the deck's folder; `g.slides.add_slide(layout, id)` adds a slide on a layout (an object, or a name) with its id in the block, and the slide is python-pptx's (`shapes.title`, `placeholders[idx]`, `shapes.add_*`, `notes_slide.notes_text_frame.text`). A generated slide's words are its code's (from its data), not the script's. `slides.yaml` places the block as `- id: stories, generate: name`; its slide is `stories/<id>`, hidden by `hidden: [<id>]`, and a shape on it is changed as `shapes: { <id>/<shape>: … }`.
|
|
75
117
|
|
|
76
|
-
|
|
118
|
+
## slides.yaml
|
|
77
119
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
120
|
+
| Field | What it is |
|
|
121
|
+
| ------------------- | ------------------------------------------------------------------------------------ |
|
|
122
|
+
| `slides[].id` | Unique in the deck: its row in the script |
|
|
123
|
+
| `slides[].layout` | One of the deck's layouts, by name |
|
|
124
|
+
| `slides[].generate` | One of the deck's generators: its slides stand here |
|
|
125
|
+
| `slides[].hidden` | `true`: left out when presenting and exporting; a block's: a list of its slides' ids |
|
|
126
|
+
| `slides[].shapes` | Its shapes by name: what it changes of its layout's placeholders, and its own |
|
|
127
|
+
|
|
128
|
+
A shape there changes a placeholder of the slide's layout (or a generated shape) with `frame` (`{ x, y, w, h }` in points), `text` (`size` in points, `bold`, `color`, `font`, a family, `align`: `l`, `ctr`, `r`, `just`, on all of its text), `fill`, `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`), `z`; or is the slide's own with one of `textbox: true` (its words are the script's; it wraps and grows to its text), `picture`, `movie` (a file, or a video item's folder), `geometry` (`rect`, `roundRect`, `ellipse`, `triangle`, `rightArrow`, `line`), `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 a `frame`. `group`, a name a slide's own shapes share, makes them one group in PowerPoint. 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`…) or `#RRGGBB`. `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 folder.
|
|
129
|
+
|
|
130
|
+
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:
|
|
131
|
+
|
|
132
|
+
| Field | Default | What it is |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| `effect` | | Entrances `appear`, `fade`, `wipe`, `fly-in`, `zoom`; exits `disappear`, `fade-out`, `wipe-out`, `fly-out`, `zoom-out`; `pulse`; `path` |
|
|
135
|
+
| `start` | `on-click` | `on-click`, `with-previous`, `after-previous`. What starts with no click before it plays as the slide opens |
|
|
136
|
+
| `direction` | `from-bottom` | A wipe's or a fly's side: `from-bottom`, `from-top`, `from-left`, `from-right` |
|
|
137
|
+
| `duration` | 0.5 (`appear`, `disappear` 0; `path` 2) | Seconds |
|
|
138
|
+
| `delay` | 0 | Seconds |
|
|
139
|
+
| `path` | | A `path` effect's, in points from where the shape stands, in SVG's `M`, `L` and `C`, absolute: `M0 0 L200 0` |
|
|
140
|
+
|
|
141
|
+
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)`.
|
|
85
142
|
|
|
86
|
-
|
|
143
|
+
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 4 seconds, which plays as it comes on (as the slide opens, if it has no entrance); one that does not move is a picture.
|
|
87
144
|
|
|
88
|
-
|
|
145
|
+
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`.
|
|
146
|
+
|
|
147
|
+
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`. There is no 3D, scatter, 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:
|
|
89
148
|
|
|
90
149
|
```yaml
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
150
|
+
revenue:
|
|
151
|
+
frame: { x: 80, y: 120, w: 640, h: 340 }
|
|
152
|
+
chart:
|
|
153
|
+
type: column-clustered
|
|
154
|
+
data: ../sales/sheet.csv # from the deck's folder: a sheet's CSV, a CSV, or a data file of rows
|
|
155
|
+
categories: Quarter # the column of names
|
|
156
|
+
series: [Revenue, { name: Cost, color: accent3 }] # the columns of numbers
|
|
157
|
+
legend: bottom
|
|
97
158
|
```
|
|
98
159
|
|
|
99
|
-
|
|
160
|
+
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.
|
|
161
|
+
|
|
162
|
+
| Field | Default | What it is |
|
|
163
|
+
| --- | --- | --- |
|
|
164
|
+
| `legend` | none | `bottom`, `top`, `left`, `right` |
|
|
165
|
+
| `labels` | none | `true`: each value. Or `value`, `percentage` (a pie's and a doughnut's), `category`, `series`, `format`, `position`, `size`, `color` |
|
|
166
|
+
| `labels.position` | a clustered bar's `outEnd`, a stacked bar's and a pie's `ctr`, a line's `t` | `outEnd` (clustered bars and pies), `inEnd`, `ctr`, `inBase` (bars), `t`, `b`, `l`, `r` (lines). An area and a doughnut have none: a position a chart's kind cannot have is AK-M011, since PowerPoint would repair the file |
|
|
167
|
+
| `gap_width`, `overlap` | 150; 0 (stacked 100) | Bars: the gap as a share of a bar's width, how far one covers the next, in % |
|
|
168
|
+
| `vary_by_categories` | a pie's and a doughnut's | A colour per category |
|
|
169
|
+
| `hole_size` | 50 | A doughnut's, in % |
|
|
170
|
+
| `value_axis`, `category_axis` | automatic | `min`, `max`, `major`, `gridlines` (the value axis's are on), `visible`, `format` (Excel's), `reverse`, `gridline_color`, `line_color` |
|
|
171
|
+
| `size`, `title_size`, `color` | 12, 14.4, `dk1` | Its text's points, its title's, and their colour |
|
|
172
|
+
| a series' `color`, `format`, `smooth`, `line_width`, `marker_size` | the accents in turn, `General`, off, 2.25, 5 | |
|
|
173
|
+
|
|
174
|
+
In code, `shapes.add_chart(XL_CHART_TYPE.X, left, top, width, height, chart_data)` makes one from a `CategoryChartData`, 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.
|
|
175
|
+
|
|
176
|
+
What `slides.yaml` 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.
|
|
177
|
+
|
|
178
|
+
## The script
|
|
179
|
+
|
|
180
|
+
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 theme colour or `#RRGGBB`, a font of their own, or both, are runs, as in a doc) and its `notes`. A key is `<prefix>.<slide>.<shape>` (the prefix is the deck's id with `/` as `.`), `<prefix>.<slide>.notes`. A placeholder with no words in the script is empty, and an empty placeholder is not drawn.
|
|
181
|
+
|
|
182
|
+
## What a person changes in the editor
|
|
183
|
+
|
|
184
|
+
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 `slides.yaml` or the script; everything else (masters, layouts, components, generators, style beyond these) is yours, in `slides.ts`. When you and the person change these files at once, both changes stand, the person's where you changed the same value, and the person keeps or undoes each of yours.
|
|
185
|
+
|
|
186
|
+
## Importing a PowerPoint file
|
|
187
|
+
|
|
188
|
+
`allyhub slides import <file.pptx> --to <folder>` makes a deck of a PowerPoint file: its masters and layouts as `slides.ts` (python-pptx's calls, only what differs from Office's text styles), its slides on their layouts as `slides.yaml` (what each moves, its own text boxes, shapes, pictures and lines), each slide's words and notes as the script (bold and italic as `**…**` and `*…*`, a deeper level as a list in the list), its pictures and videos in `media/`. What does not carry over (a table, a chart, a group, SmartArt, animations, a gradient, a run's own font) is listed, a line each; `--lang` names the script's language.
|
|
189
|
+
|
|
190
|
+
## Measuring a deck
|
|
191
|
+
|
|
192
|
+
The check measures every slide as the stage draws it, and `allyhub inspect` lists what it found as facts: numbers for you to judge, never problems. Besides a video's text facts (text the slide's edge cuts, text over text), a deck has:
|
|
193
|
+
|
|
194
|
+
- `text-overflow`: a shape's text past its box, by its lines' glyphs.
|
|
195
|
+
- `shape-off-slide`, `shape-overlap`, `shape-hidden`: a shape past the slide's edge, two over each other (what shows of each: a filled shape or a picture whole, a text's glyphs), one covered whole.
|
|
196
|
+
- `near-alignment`: edges and centres of two shapes, or of a shape and the slide's centre, nearly in line and not (`allyhub inspect layout --within <pt>`).
|
|
197
|
+
- `placement-drift`: a shape of one name at different places on slides of one layout (`--drift <pt>`).
|
|
198
|
+
- `type-in-use`, `read-size`, `words-on-slide`: the sizes and weights in use, each text's size on a phone (with `--room`, on a room's screen too), the words on each slide.
|
|
199
|
+
- `picture-resolution`: a picture drawn larger than its pixels, or stretched.
|
|
200
|
+
|
|
201
|
+
`allyhub frames <deck> --overlay` draws each shape's box and name over its slide, and the lines nearly in line; `allyhub inspect contrast` measures text against what is behind it.
|
|
100
202
|
|
|
101
203
|
## What a deck renders to
|
|
102
204
|
|
|
103
|
-
`allyhub render` makes a deck's files in `.allyhub/out/<piece>/` (`slides.<combo key>.<ext>`), each
|
|
205
|
+
`allyhub render` makes a deck's files in `.allyhub/out/<piece>/` (`slides.<combo key>.<ext>`), each slide drawn at its still, hidden ones left out; `allyhub help render` lists the options.
|
|
104
206
|
|
|
105
|
-
| Type
|
|
106
|
-
|
|
|
107
|
-
| `pdf` (the default) |
|
|
108
|
-
| `png`
|
|
109
|
-
| `pptx`
|
|
207
|
+
| Type | What it is |
|
|
208
|
+
| ------------------- | --------------------------------------------------------- |
|
|
209
|
+
| `pdf` (the default) | A page per slide, the slide's size, the text kept as text |
|
|
210
|
+
| `png` | A picture per slide, numbered from 1 |
|
|
211
|
+
| `pptx` | PowerPoint's own file: the deck's theme, masters with their text styles, layouts with their placeholders, each slide's placeholders, text, shapes, pictures, videos and notes, editable as any deck. A component (or a coded video) is a picture of it as drawn. `--param pptx=picture` makes each slide a picture instead |
|
|
110
212
|
|
|
111
|
-
Every combo of the deck
|
|
213
|
+
Every combo of the deck (its languages) renders its own files. `allyhub frames` draws every slide's still on one sheet.
|
|
@@ -16,6 +16,19 @@ export declare const ScriptPartSchema: z.ZodObject<{
|
|
|
16
16
|
}, z.core.$strict>]>>;
|
|
17
17
|
screen: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ScriptText, unknown, z.core.$ZodTypeInternals<ScriptText, unknown>>>>;
|
|
18
18
|
}, z.core.$strict>;
|
|
19
|
+
/**
|
|
20
|
+
* A deck's slide in its script: the words of its shapes by their names
|
|
21
|
+
* (a list is a shape's paragraphs) and its speaker notes.
|
|
22
|
+
*/
|
|
23
|
+
export declare const ScriptSlideSchema: z.ZodObject<{
|
|
24
|
+
id: z.ZodString;
|
|
25
|
+
text: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ScriptText, unknown, z.core.$ZodTypeInternals<ScriptText, unknown>>>>;
|
|
26
|
+
notes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
27
|
+
declarations: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
28
|
+
selectors: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
29
|
+
match: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
30
|
+
}, z.core.$strict>]>>;
|
|
31
|
+
}, z.core.$strict>;
|
|
19
32
|
export declare const ScriptFileSchema: z.ZodObject<{
|
|
20
33
|
title: z.ZodOptional<z.ZodString>;
|
|
21
34
|
text: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ScriptText, unknown, z.core.$ZodTypeInternals<ScriptText, unknown>>>>;
|
|
@@ -28,6 +41,15 @@ export declare const ScriptFileSchema: z.ZodObject<{
|
|
|
28
41
|
}, z.core.$strict>]>>;
|
|
29
42
|
screen: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ScriptText, unknown, z.core.$ZodTypeInternals<ScriptText, unknown>>>>;
|
|
30
43
|
}, z.core.$strict>>>;
|
|
44
|
+
slides: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
45
|
+
id: z.ZodString;
|
|
46
|
+
text: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<ScriptText, unknown, z.core.$ZodTypeInternals<ScriptText, unknown>>>>;
|
|
47
|
+
notes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
48
|
+
declarations: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
49
|
+
selectors: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
50
|
+
match: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
51
|
+
}, z.core.$strict>]>>;
|
|
52
|
+
}, z.core.$strict>>>;
|
|
31
53
|
}, z.core.$strict>;
|
|
32
54
|
export type ScriptFile = z.infer<typeof ScriptFileSchema>;
|
|
33
55
|
/** The script of an item in a language. */
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
|
|
2
|
-
import{z as t}from"zod";import{SpokenSchema as
|
|
2
|
+
import{z as t}from"zod";import{SpokenSchema as d,VariantsSchema as i}from"./messages.js";export const SCRIPT_NAME=/^[A-Za-z0-9_-]+$/u;const s=t.string().regex(SCRIPT_NAME,"A name is letters, digits, _ and -.");export const ScriptTextSchema=t.lazy(()=>t.union([t.string(),d,i,t.array(ScriptTextSchema),t.record(s,ScriptTextSchema)])),ScriptPartSchema=t.strictObject({id:s,say:t.union([t.string(),i]).optional(),screen:t.record(s,ScriptTextSchema).optional()}),ScriptSlideSchema=t.strictObject({id:s,text:t.record(s,ScriptTextSchema).optional(),notes:t.union([t.string(),i]).optional()}),ScriptFileSchema=t.strictObject({title:t.string().optional(),text:t.record(s,ScriptTextSchema).optional(),parts:t.array(ScriptPartSchema).default([]),slides:t.array(ScriptSlideSchema).default([])}).superRefine((r,o)=>{const c=new Set;r.parts.forEach((e,a)=>{c.has(e.id)&&o.addIssue({code:"custom",path:["parts",a,"id"],message:`Two parts are "${e.id}".`}),c.add(e.id)});const n=new Set;r.slides.forEach((e,a)=>{n.has(e.id)&&o.addIssue({code:"custom",path:["slides",a,"id"],message:`Two slides are "${e.id}".`}),n.add(e.id)})}),scriptFileFor=(r,o)=>`${r}/script.${o}.yaml`;export function scriptLocale(r){return/(?:^|\/)script\.([A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)\.yaml$/u.exec(r)?.[1]}
|