@allyhub/sdk 0.9.0 → 0.11.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/CHANGELOG.md +16 -0
- package/dist/node_modules/@allyhub/audio/package.json +1 -1
- package/dist/node_modules/@allyhub/chart/dist/chart-xml.d.ts +3 -0
- package/dist/node_modules/@allyhub/chart/dist/chart-xml.js +2 -2
- package/dist/node_modules/@allyhub/chart/dist/chart.d.ts +22 -0
- package/dist/node_modules/@allyhub/chart/dist/chart.js +1 -1
- package/dist/node_modules/@allyhub/chart/package.json +1 -1
- package/dist/node_modules/@allyhub/diagnostics/dist/problem.d.ts +7 -0
- package/dist/node_modules/@allyhub/diagnostics/package.json +1 -1
- package/dist/node_modules/@allyhub/formats/dist/data/faces.d.ts +1 -1
- package/dist/node_modules/@allyhub/formats/dist/data/sheet.d.ts +87 -1
- package/dist/node_modules/@allyhub/formats/dist/data/sheet.js +1 -1
- package/dist/node_modules/@allyhub/formats/dist/data/slides.d.ts +89 -0
- package/dist/node_modules/@allyhub/formats/dist/data/slides.js +1 -1
- package/dist/node_modules/@allyhub/formats/dist/note-shape.d.ts +20 -0
- package/dist/node_modules/@allyhub/formats/dist/note-shape.js +1 -1
- package/dist/node_modules/@allyhub/formats/dist/schemas.d.ts +50 -0
- package/dist/node_modules/@allyhub/formats/package.json +1 -1
- package/dist/node_modules/@allyhub/image-draw/package.json +1 -1
- package/dist/node_modules/@allyhub/image-measure/package.json +1 -1
- package/dist/node_modules/@allyhub/image-sdk/dist/index.d.ts +1 -1
- package/dist/node_modules/@allyhub/image-sdk/package.json +1 -1
- package/dist/node_modules/@allyhub/measure/package.json +1 -1
- package/dist/node_modules/@allyhub/ooxml/dist/geometry/index.js +1 -1
- package/dist/node_modules/@allyhub/ooxml/package.json +1 -1
- package/dist/node_modules/@allyhub/piece/dist/layer.d.ts +2 -0
- package/dist/node_modules/@allyhub/piece/dist/layout.d.ts +16 -0
- package/dist/node_modules/@allyhub/piece/dist/page/index.d.ts +1 -1
- package/dist/node_modules/@allyhub/piece/dist/page/index.js +1 -1
- package/dist/node_modules/@allyhub/piece/dist/page/locate.d.ts +14 -1
- package/dist/node_modules/@allyhub/piece/dist/page/locate.js +1 -1
- package/dist/node_modules/@allyhub/piece/dist/stage.d.ts +18 -0
- package/dist/node_modules/@allyhub/piece/package.json +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/account.d.ts +140 -0
- package/dist/node_modules/@allyhub/protocol/dist/account.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/auth.d.ts +19 -1
- package/dist/node_modules/@allyhub/protocol/dist/auth.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/cloud.d.ts +157 -0
- package/dist/node_modules/@allyhub/protocol/dist/cloud.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/editor.d.ts +10 -2
- package/dist/node_modules/@allyhub/protocol/dist/editor.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/frame.d.ts +101 -186
- package/dist/node_modules/@allyhub/protocol/dist/frame.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/mail.d.ts +1 -0
- package/dist/node_modules/@allyhub/protocol/dist/mail.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/notes.d.ts +92 -94
- package/dist/node_modules/@allyhub/protocol/dist/notes.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/snapshots.d.ts +17 -0
- package/dist/node_modules/@allyhub/protocol/dist/snapshots.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/teams.d.ts +7 -0
- package/dist/node_modules/@allyhub/protocol/dist/teams.js +1 -1
- package/dist/node_modules/@allyhub/protocol/dist/tools.d.ts +15 -3
- package/dist/node_modules/@allyhub/protocol/dist/tools.js +1 -1
- package/dist/node_modules/@allyhub/protocol/package.json +1 -1
- package/dist/node_modules/@allyhub/runtimes/package.json +1 -1
- package/dist/node_modules/@allyhub/scenery/dist/index.d.ts +2 -2
- package/dist/node_modules/@allyhub/scenery/dist/index.js +1 -1
- package/dist/node_modules/@allyhub/scenery/dist/moire.d.ts +45 -5
- package/dist/node_modules/@allyhub/scenery/dist/moire.js +2 -2
- package/dist/node_modules/@allyhub/scenery/dist/phone.d.ts +4 -3
- package/dist/node_modules/@allyhub/scenery/dist/phone.js +1 -1
- package/dist/node_modules/@allyhub/scenery/package.json +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/coerce.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/engine.d.ts +70 -0
- package/dist/node_modules/@allyhub/sheet/dist/calc/engine.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/criteria.d.ts +6 -0
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/criteria.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/date.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/define.d.ts +3 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/define.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/info.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/kernels.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/lookup.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/maths.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/functions/text.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/indexes.d.ts +9 -0
- package/dist/node_modules/@allyhub/sheet/dist/calc/indexes.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/calc/types.d.ts +6 -0
- package/dist/node_modules/@allyhub/sheet/dist/calc/types.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/chart.d.ts +9 -0
- package/dist/node_modules/@allyhub/sheet/dist/chart.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/export.d.ts +0 -8
- package/dist/node_modules/@allyhub/sheet/dist/export.js +2 -4
- package/dist/node_modules/@allyhub/sheet/dist/formula/ast.d.ts +12 -1
- package/dist/node_modules/@allyhub/sheet/dist/formula/move.d.ts +5 -1
- package/dist/node_modules/@allyhub/sheet/dist/formula/move.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/formula/parse.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/formula/print.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/index.d.ts +3 -2
- package/dist/node_modules/@allyhub/sheet/dist/index.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/inspect.d.ts +12 -2
- package/dist/node_modules/@allyhub/sheet/dist/inspect.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/printed.d.ts +19 -0
- package/dist/node_modules/@allyhub/sheet/dist/printed.js +2 -0
- package/dist/node_modules/@allyhub/sheet/dist/values.d.ts +2 -0
- package/dist/node_modules/@allyhub/sheet/dist/values.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/workbook.d.ts +2 -0
- package/dist/node_modules/@allyhub/sheet/dist/workbook.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/write.js +15 -15
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/charts.d.ts +6 -2
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/charts.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/formula.js +2 -2
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/import.d.ts +0 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/import.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/read.d.ts +3 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/read.js +2 -2
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/sax.d.ts +7 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/sax.js +3 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/styles.d.ts +6 -0
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/styles.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/write.d.ts +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/write.js +1 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/xml.d.ts +12 -1
- package/dist/node_modules/@allyhub/sheet/dist/xlsx/xml.js +3 -2
- package/dist/node_modules/@allyhub/sheet/package.json +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/api.d.ts +57 -7
- package/dist/node_modules/@allyhub/slides-core/dist/api.js +2 -2
- package/dist/node_modules/@allyhub/slides-core/dist/capabilities.js +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/enums.d.ts +24 -0
- package/dist/node_modules/@allyhub/slides-core/dist/enums.js +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/fact.d.ts +15 -0
- package/dist/node_modules/@allyhub/slides-core/dist/measure.js +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/model.d.ts +6 -2
- package/dist/node_modules/@allyhub/slides-core/dist/resolve.d.ts +3 -1
- package/dist/node_modules/@allyhub/slides-core/dist/resolve.js +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/sdk.d.ts +1 -1
- package/dist/node_modules/@allyhub/slides-core/dist/sdk.js +1 -1
- package/dist/node_modules/@allyhub/slides-core/package.json +1 -1
- package/dist/node_modules/@allyhub/video-core/dist/piece.d.ts +2 -2
- package/dist/node_modules/@allyhub/video-core/dist/schema.d.ts +2 -2
- package/dist/node_modules/@allyhub/video-core/dist/schema.js +1 -1
- package/dist/node_modules/@allyhub/video-core/package.json +1 -1
- package/dist/node_modules/@allyhub/video-sdk/dist/phone.d.ts +12 -5
- package/dist/node_modules/@allyhub/video-sdk/dist/phone.js +1 -1
- package/dist/node_modules/@allyhub/video-sdk/package.json +1 -1
- package/docs/README.md +4 -0
- package/docs/canvas.md +28 -0
- package/docs/defaults.md +30 -4
- package/docs/docs.md +10 -10
- package/docs/image.md +3 -3
- package/docs/linkedin.md +96 -0
- package/docs/reports.md +89 -0
- package/docs/scenery.md +3 -4
- package/docs/sheets.md +23 -6
- package/docs/slides.md +50 -4
- package/docs/speech.md +1 -1
- package/docs/x.md +73 -0
- package/package.json +1 -1
package/docs/linkedin.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# LinkedIn posts and articles
|
|
2
|
+
|
|
3
|
+
Two kinds in LinkedIn's own model, each a file listed in `allyhub.yaml` ([project.md](project.md#items)): a `linkedin-post` and a `linkedin-article`.
|
|
4
|
+
|
|
5
|
+
## A LinkedIn post
|
|
6
|
+
|
|
7
|
+
A `linkedin-post` is a YAML file (`- { kind: linkedin-post, file: launch/post.yaml }`). Its fields are the Posts API's own (`POST /rest/posts`):
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
commentary: |
|
|
11
|
+
We shipped the new editor.
|
|
12
|
+
|
|
13
|
+
#launch
|
|
14
|
+
visibility: PUBLIC # or CONNECTIONS
|
|
15
|
+
content:
|
|
16
|
+
media: { file: ./carousel.ts, title: What changed } # a picture, a video or a document
|
|
17
|
+
isReshareDisabledByAuthor: false
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`content` is one of these, or none (a post of words alone):
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
content:
|
|
24
|
+
media: { file: ./demo.mp4, title: The demo } # one picture (altText), one video, or one document (title)
|
|
25
|
+
---
|
|
26
|
+
content:
|
|
27
|
+
multiImage:
|
|
28
|
+
images: # 2 to 20 pictures
|
|
29
|
+
- { file: ./a.png, altText: The editor. }
|
|
30
|
+
- { file: ./shots.ts#chart, altText: The chart. }
|
|
31
|
+
---
|
|
32
|
+
content:
|
|
33
|
+
poll:
|
|
34
|
+
question: Which do you use?
|
|
35
|
+
options: [{ text: Light }, { text: Dark }]
|
|
36
|
+
settings: { duration: SEVEN_DAYS } # ONE_DAY, THREE_DAYS, SEVEN_DAYS (the default, as LinkedIn's composer) or FOURTEEN_DAYS
|
|
37
|
+
---
|
|
38
|
+
content:
|
|
39
|
+
article: # a link's card: LinkedIn fetches nothing through the API, so its fields are set here
|
|
40
|
+
source: https://allyhub.com/blog/editor
|
|
41
|
+
title: The new editor
|
|
42
|
+
description: How we rebuilt it.
|
|
43
|
+
thumbnail: ./card.png
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
- **Length is LinkedIn's composer's count**: UTF-16 units, so an emoji is 2, a CJK character 1 and a line break 1. At most 3,000 (measured on linkedin.com; the API states none).
|
|
47
|
+
- **"… more"**: the feed shows a post's first three lines (14 on 20 px, a 526 px column, its line breaks kept) and folds the rest. "… more" goes right after the last word on those lines that leaves room for it, and the fold moves up to that word's line: a post whose third line is blank shows two lines, and one when its second is blank too. Characters do not decide it: a post of short lines folds sooner than 200 characters, one of long lines later. (From LinkedIn's feed code, checked on 107 posts; an ad folds the same way from two lines.) On a phone's width the rule is the same and the column narrower (the screen less 26 px: 364 px on a 390 px phone), so a post folds sooner in its words. `allyhub frames` draws the post folded on a computer (`feed`, 552 px), on a phone (`phone`, 390 px) and opened (`open`); the fold is drawn in Inter, near LinkedIn's face, not identical to it, so it can land a word earlier or later on a reader's screen. LinkedIn's phone apps were not measured and may fold elsewhere.
|
|
48
|
+
- **Plain text.** A post holds no bold or italics. `#word` is a hashtag. A mention needs a member's or a page's URN, so it waits for a connected account.
|
|
49
|
+
- **The commentary as a block (`|`) or in quotes** when it holds ` #` (YAML reads the rest of the line as a comment), starts with `#`, `@` or a quote, or holds `: `. The line break a block ends in is not posted.
|
|
50
|
+
- **Media**: a picture is JPG, PNG or GIF, under 36,152,320 pixels, its alt text at most 4,086 characters; a video is MP4, 3 seconds to 30 minutes, 75 KB to 5 GB; a document is PDF, PPT, PPTX, DOC or DOCX, at most 100 MB and 300 pages (its pages are not counted here). LinkedIn publishes no picture size, crop or safe area.
|
|
51
|
+
- **A carousel** is a document: `media: { file: ./carousel.ts, title: … }` names an image whose boards are its pages, made as one PDF when the post is rendered; a deck (`../q3.ts`) is made as its PDF. A board (`./shots.ts#hero`) is a picture; a video item's file is its first version. Its bytes are checked when it is made.
|
|
52
|
+
|
|
53
|
+
## A LinkedIn article
|
|
54
|
+
|
|
55
|
+
A `linkedin-article` is a Markdown file (`- { kind: linkedin-article, file: launch/story.md }`), its title and cover in its front matter, its body in LinkedIn's article blocks alone:
|
|
56
|
+
|
|
57
|
+
````markdown
|
|
58
|
+
---
|
|
59
|
+
title: Why we rebuilt the editor
|
|
60
|
+
cover: ./cover.png # a picture or a video, or another item's (./shots.ts#cover); or { file, alt }
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
Paragraphs with **bold**, _italic_ and [links](https://example.com).
|
|
64
|
+
|
|
65
|
+
# A Heading
|
|
66
|
+
|
|
67
|
+
## A Subheading
|
|
68
|
+
|
|
69
|
+
- a list, one level deep
|
|
70
|
+
|
|
71
|
+
1. or numbered
|
|
72
|
+
|
|
73
|
+
> A quote.
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
a code snippet
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+

|
|
82
|
+
|
|
83
|
+
https://www.youtube.com/watch?v=…
|
|
84
|
+
|
|
85
|
+
<br />
|
|
86
|
+
````
|
|
87
|
+
|
|
88
|
+
- **Each element is one of LinkedIn's blocks** (its editor's: Normal, Heading, Subheading, bold, italic, link, bulleted and numbered lists, quote, code snippet, divider, image with its caption, embed): an address alone on its line is an embed; `<br />` alone on a line is an empty line. A third level of heading, a list inside a list, a table, an equation, inline code, strikethrough, a footnote, a picture inside a line and other HTML are not: each is a problem at its line.
|
|
89
|
+
- **Pictures** are JPG, PNG or GIF; a video goes in as an embed (its address). The cover is a picture or a video. LinkedIn publishes no most for a title or a body.
|
|
90
|
+
- **LinkedIn has no API that publishes an article.** It is pasted into LinkedIn's editor: the article editor's Copy for LinkedIn copies the body, pasted into the empty body there, and the title is typed in its own field. Every block comes through as LinkedIn's own (measured on linkedin.com) but two: pictures are added there by hand, and an embed arrives as its link, made a player with LinkedIn's Embed.
|
|
91
|
+
|
|
92
|
+
## Check, measure and render
|
|
93
|
+
|
|
94
|
+
`allyhub check` reports what LinkedIn refuses under `allyhub.linkedin/…`, at its line. `allyhub inspect <post>` gives the commentary's characters beside 3,000, its lines, hashtags and links, and its media's bytes and alt text; `allyhub inspect <article>` its title, words, headings, pictures and embeds. `allyhub frames` draws a post as the feed shows it (`feed`, folded; `open`) and an article as its page does (`article`), in Inter in place of the system face LinkedIn draws in; an embed and a link's card are drawn by their address.
|
|
95
|
+
|
|
96
|
+
`allyhub render <post>` writes the Posts API's request (`post.json`: the commentary in LinkedIn's little text, each medium beside it with the API it goes up by and the placeholder its id fills), or what a person posts by hand (`--type txt`: `post.txt`, the commentary as written, each medium beside it and its alt text in `<name>.alt.txt`). `allyhub render <article>` writes `article.html` with its pictures beside it. The editor's Export offers `txt` and a picture of the post (`png`); the request waits for publishing. Publishing to LinkedIn is not built.
|
package/docs/reports.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Reports
|
|
2
|
+
|
|
3
|
+
A report is a page read on a screen and sent as a link: one HTML file you write freely, in HTML, CSS and JavaScript, listed in `allyhub.yaml` as `kind: report` ([project.md](project.md#items)), and whatever it loads beside it. AllyHub gives it no components, classes or layout: every part of the page is yours. It draws the page offline, the same on every computer, checks it for what is objectively wrong, draws pictures of it to look at, and makes it into files.
|
|
4
|
+
|
|
5
|
+
## A report item
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
research/channels/
|
|
9
|
+
channels.html the report
|
|
10
|
+
charts.js anything it loads, beside it or elsewhere in the project
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
work:
|
|
15
|
+
- file: research/channels/channels.html
|
|
16
|
+
kind: report
|
|
17
|
+
title: AI productivity channels
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- Its id is its file without its extension (`research/channels/channels`); commands take either.
|
|
21
|
+
- Its file ends in `.html`; one that does not, or is not there, is AK-M017.
|
|
22
|
+
|
|
23
|
+
## What it loads
|
|
24
|
+
|
|
25
|
+
The page is drawn from a server of the project's folder: it loads the project's files by their paths, relative to the report (`../../data/channels.csv`), and nothing else.
|
|
26
|
+
|
|
27
|
+
- **Data**: `fetch` a CSV or a JSON by its path and draw from it, so a figure, a table and a chart are one number. A sheet's table files hold the rows typed into it, not what its formulas compute: for those, render the sheet into the report's folder (`allyhub render <sheet> --type csv` or `json`, then copy the file beside the report) and load that.
|
|
28
|
+
- **Libraries** are files of the project: a package installed and loaded by its path (`../../node_modules/chart.js/dist/chart.umd.min.js`), or a file beside the report. A classic script or a module with no imports is carried by the self-contained HTML export; a module that imports others is not (bundle it into one file).
|
|
29
|
+
- **Faces** are files: `@font-face` rules naming font files in the project (a `@fontsource` package's CSS, or your own). The built-in faces of the stage (project.md, "Fonts") are not loaded for a report.
|
|
30
|
+
- **Nothing from the network**: an address outside the project (a CDN, Google Fonts) is refused when the page is drawn and is AK-N003. Put the file in the project instead.
|
|
31
|
+
- A report style (below) brings its faces and Chart.js as files.
|
|
32
|
+
|
|
33
|
+
## How it is drawn
|
|
34
|
+
|
|
35
|
+
`check`, `frames` and `render` draw the page the same way, in the pinned Chrome:
|
|
36
|
+
|
|
37
|
+
- At a window of 1440 × 900 CSS pixels (`100vh` is 900), at 1 device pixel per CSS pixel, unless asked otherwise.
|
|
38
|
+
- `prefers-reduced-motion: reduce` and `prefers-color-scheme: light`, unless asked otherwise. `Math.random` gives the same numbers each time; the clock is the real one.
|
|
39
|
+
- It is drawn once it has settled: loaded, its network quiet (up to 3 s after the load event), its fonts ready, its pictures decoded, `window.allyhubReady` kept when the page sets it to a promise, its CSS animations finished (an endless one paused at its start), then 1.2 s more for what scripts animate. A page that draws later than that (a chart animating for longer) sets `window.allyhubReady`, or turns its motion off under reduced motion.
|
|
40
|
+
- A page that has not loaded and settled within 30 s is AK-P004.
|
|
41
|
+
|
|
42
|
+
Each of these is a `--param` of `allyhub render` (`width`, `height`, `scale`, `timeout`, `network`, `quiet`, `dark`, `paper`): `allyhub help render`.
|
|
43
|
+
|
|
44
|
+
## Check
|
|
45
|
+
|
|
46
|
+
`allyhub check` draws each report and reports objective errors alone:
|
|
47
|
+
|
|
48
|
+
| Code | What |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| AK-M017 | Its file is not an HTML file, or is not there |
|
|
51
|
+
| AK-A001 | It asks for a file of the project that is not there |
|
|
52
|
+
| AK-N003 | It asks for an address outside the project, which is refused |
|
|
53
|
+
| AK-R001 | Its scripts threw and did not catch |
|
|
54
|
+
| AK-P004 | It did not load, or did not settle, within its timeout |
|
|
55
|
+
| AK-L006 | Text is drawn in a face of the computer rather than a file of the project (a warning: another computer draws it in its own) |
|
|
56
|
+
|
|
57
|
+
How it looks, what it says and how it is laid out are never problems.
|
|
58
|
+
|
|
59
|
+
## In Studio and allyhub dev
|
|
60
|
+
|
|
61
|
+
A report opens in its view: the page in a frame, served from the project's files with the same rule as the render (nothing from outside the project loads), at the window's width or a desktop's, a tablet's or a phone's, scaled down when wider than the window. It is drawn again when a file it is made from changes: its own, or one its page loaded (the CSV it fetched, a face its stylesheet named), wherever it is in the project. A person changes one thing in it by hand, its theme, where its report style writes themes: the view's theme menu sets `data-theme` on the page's `<html>`, every other byte of the file kept, and you see it in the file. A read-only view (a snapshot) and a share's viewer offer no theme to set, as they offer nothing that changes the item. Anything else they point at with Mark up and send to you.
|
|
62
|
+
|
|
63
|
+
## Look at it
|
|
64
|
+
|
|
65
|
+
`allyhub frames <report>` draws the page as the render does, from its top, and writes the picture under `.allyhub/work/frames/<place>/`:
|
|
66
|
+
|
|
67
|
+
- `--width 375` at a phone's width, `--dark` as a reader who asks for dark sees it (a page with no `prefers-color-scheme: dark` styles looks the same), `--print` laid out for paper (`@media print`) as one long picture;
|
|
68
|
+
- `--at <selector>` one element alone, at its size, its picture named by the selector;
|
|
69
|
+
- a page more than about 1.6 times as tall as it is wide is cut into bands laid side by side (at most six), so one picture shows all of it.
|
|
70
|
+
|
|
71
|
+
It says the page's height, and what it asked for that was missing or refused and what it threw.
|
|
72
|
+
|
|
73
|
+
## Render
|
|
74
|
+
|
|
75
|
+
`allyhub render <report>` writes under `.allyhub/out/`, by its id:
|
|
76
|
+
|
|
77
|
+
- `html` (the default): one self-contained HTML file, and the render says its size and how much of it is faces. Every file the page loaded is put inside it, its bytes as they are in the project: scripts and style sheets in their tags, pictures and faces as `data:` URLs, and what its scripts loaded (`fetch`, `XMLHttpRequest`, a picture or a script made by code) answered from a table in a first script. It runs offline on any computer, its interactivity kept. A module script that imports another file stops it, with why.
|
|
78
|
+
- `pdf`: Chrome's print of the page, its backgrounds printed, on Letter (`--param paper=a4`) unless its `@page` names a size; write `@media print` for paper.
|
|
79
|
+
- `png`: the whole page as one long picture at its width.
|
|
80
|
+
|
|
81
|
+
`--type html,pdf,png` makes them all.
|
|
82
|
+
|
|
83
|
+
## Report styles
|
|
84
|
+
|
|
85
|
+
A report style is a look written down for a report to start from when the person gives no style of their own: a reference, never a limit, and never a component.
|
|
86
|
+
|
|
87
|
+
- `allyhub report style list` names them, each with its themes.
|
|
88
|
+
- `allyhub report style show <name>` prints one: its themes, tokens, type, page, example parts and charts.
|
|
89
|
+
- `allyhub report style use <report> <name>` writes its `style.css` (the tokens as CSS variables, each theme as `[data-theme="…"]`, the faces' `@font-face` rules, reduced motion) and `tokens.js` (the same tokens for a canvas chart: `reportToken("hero-deco2")`) in the report's `style/` folder, and copies its faces and Chart.js once into the project's `assets/report-styles/<name>/`. It prints the lines to link them. The files are then the report's own: change them as it needs; `--force` writes style.css and tokens.js again.
|
package/docs/scenery.md
CHANGED
|
@@ -154,7 +154,7 @@ camera: shots([
|
|
|
154
154
|
|
|
155
155
|
### A phone
|
|
156
156
|
|
|
157
|
-
`PHONE_CAMERA` (`@allyhub/sdk/scenery`) names a phone's main camera as the options of each mechanism; `phoneCamera(over)` changes any value and keeps the rest. `lens` goes into a camera state, `sensor` into `scenery({ sensor })`, `hand` into `handheld()`, and the marks it leaves on its picture (grain, softness, sharpening
|
|
157
|
+
`PHONE_CAMERA` (`@allyhub/sdk/scenery`) names a phone's main camera as the options of each mechanism; `phoneCamera(over)` changes any value and keeps the rest. `lens` goes into a camera state, `sensor` into `scenery({ sensor })`, `hand` into `handheld()`, and the marks it leaves on its picture (grain, softness, sharpening) into `video()`'s `capture` ([video.md](video.md)). Its `motionBlur` is null: each sample draws a frame again (8 made a phone-filmed short take three times as long to render), and a hand's moves barely show it. The sensor's `grade` follows what fills the frame, as a phone's exposure does: on a room or a person its `room` grade (a gentle contrast, a little more colour); as a screen comes to fill the frame, its `screen` grade (the phone exposes for the lit screen: its white a neutral light grey, its middle tones and colours deep), eased in between `share[0]` and `share[1]` of the frame filled (default 50% and 80%), frame by frame. Each grade is a brightness curve (`curve`, hues kept), then `saturation` and `hue`; it grades the scenery layer alone, not captions laid over it; `grade: null` for none. The screen's grade and the capture's marks are measured against phone photos of a laptop's screen (fine grain kept in the whites, crisp sharpened text). Each is a starting point, not a look.
|
|
158
158
|
|
|
159
159
|
```ts file=phone/phone.ts
|
|
160
160
|
import { part, video } from "@allyhub/sdk";
|
|
@@ -182,7 +182,6 @@ const camera = handheld(
|
|
|
182
182
|
export default video({
|
|
183
183
|
format: "9x16",
|
|
184
184
|
capture: phone.capture,
|
|
185
|
-
motionBlur: phone.motionBlur,
|
|
186
185
|
parts: () => [
|
|
187
186
|
part({
|
|
188
187
|
key: "look",
|
|
@@ -238,7 +237,7 @@ export default video({
|
|
|
238
237
|
| `box` | the frame | `[x, y, w, h]` as fractions of the frame; the camera's aspect is the box's |
|
|
239
238
|
| `background` | the scenery's own | A colour, or `"transparent"`; without it what `build` set as the scene's background, else transparent |
|
|
240
239
|
| `time` | `{ from: 0 }` | The scenery's time from the film's: `{ from }` at the film's start, or `(filmT) => number`. It runs on across parts and cuts |
|
|
241
|
-
| `quality` | `{ scale:
|
|
240
|
+
| `quality` | `{ scale: 1, focusLevels: 8 }` | `scale`: the share of the layer's size each way it is drawn at (above 1 supersamples; 0.5 for a quicker draft, softer). `focusLevels`: Gaussian levels a screen's depth of field is mixed from. `SCENERY_LAYER_DEFAULTS` |
|
|
242
241
|
| `sensor` | none | A phone's sensor filming it: the moiré its Bayer grid makes of the screens' pixels. `{ photosites, lens, moire, chroma, distortion }`, `SENSOR_DEFAULTS` |
|
|
243
242
|
| `screens` | none | `{ <object name>: screen(…) }` (below) |
|
|
244
243
|
| `props` | none | `SceneryProp`s this layer brings in (below) |
|
|
@@ -264,7 +263,7 @@ export default video({
|
|
|
264
263
|
| `size` | `[1920, 1080]` | Layers only: the content's pixels (a video uses its format's) |
|
|
265
264
|
| `dur` | to the layer's end | Layers only |
|
|
266
265
|
| `background` | `"#000000"` | Behind the content, or `"transparent"` |
|
|
267
|
-
| `pixels` | `{ density: 2, rows: 0.15 }` | Its physical pixels, for a sensor's
|
|
266
|
+
| `pixels` | `{ density: 2, rows: 0.15, mesh: 0.09 }` | Its physical pixels, for a sensor's moiré, and `mesh` (0–1, 0 none): the fine grid of faint lines a phone close to a screen shows, every three of its pixels (`PANEL_DEFAULTS`) |
|
|
268
267
|
| `glass` | none | `{ reflectance?, roughness?, scale? }`: what its glass reflects of the scenery over its picture, by Fresnel; `{}` the defaults (`GLASS_DEFAULTS`) |
|
|
269
268
|
| `inScenery` | `true` | Drawn in the scenery: `{ brightness?, light? }` (below); `false`: laid over the scenery |
|
|
270
269
|
|
package/docs/sheets.md
CHANGED
|
@@ -71,8 +71,9 @@ Its JSON Schema is `https://allyhub.com/schemas/sheet.schema.json`.
|
|
|
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
|
+
| `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 |
|
|
74
75
|
|
|
75
|
-
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, …look }`: `name` is a defined name for that cell.
|
|
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
77
|
|
|
77
78
|
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.
|
|
78
79
|
|
|
@@ -127,6 +128,8 @@ sheets:
|
|
|
127
128
|
protect: true # Protect Sheet, with no password
|
|
128
129
|
```
|
|
129
130
|
|
|
131
|
+
`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
|
+
|
|
130
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`.
|
|
131
134
|
|
|
132
135
|
### Files in a cell
|
|
@@ -186,8 +189,9 @@ A **calculated column** has its `formula` in `columns` and no column in the CSV,
|
|
|
186
189
|
The language is Excel's: `A1` and `$` references, ranges, `Sheet!A1`, `'My Sheet'!A1`, `Jan:Dec!A1`, whole columns and rows, defined names, structured references (`orders[total]`, `[@price]`, `orders[@total]`, `orders[[#Headers],[a]:[c]]`, `orders` for its rows), operators with Excel's precedence (`-2^2` is 4), array constants, `LET`, `LAMBDA` (a name may hold one, and is then called: `=double(4)`), error values. `allyhub sheet capabilities` lists the functions under `formulas`.
|
|
187
190
|
|
|
188
191
|
- Results are computed in order, each once. `NOW`, `TODAY`, `RAND`, `RANDBETWEEN`, `OFFSET` and `INDIRECT` are volatile. `NOW` and `TODAY` read the clock when the sheet is built or exported; `RAND` in a build and an export is seeded by the sheet's files, so the same files give the same rows.
|
|
189
|
-
- A formula that reads itself is a problem, and its cells and what reads them show `#CYCLE!`: Excel says so in a dialog. A cycle through a branch `IF` does not take is none, as in Excel.
|
|
192
|
+
- A formula that reads itself is a problem, and its cells and what reads them show `#CYCLE!`: Excel says so in a dialog. A cycle through a branch `IF` does not take is none, as in Excel. With `iteration` on it is no problem: as Excel's iterative calculation does, its cells and what reads them are computed again, each reading the latest value of the others (a cell not computed yet reads its `start`, or 0), until no value moves by `max_change` or `max_iterations` rounds have run. `allyhub inspect sheet` says how many rounds ran and how far a value moved in the last.
|
|
190
193
|
- An array result spills, as in Excel: the formula's cell shows the first value and the cells beside it the rest. They hold nothing in any file, read like any others, and `A1#` is the range the spill covers now. `#SPILL!` says something stands in the way (a cell that holds anything, a merge, a table, the edge of the sheet), and what stands there going lets it spill. A calculated column cannot spill. `=@A1:A9` is the value in the formula's own row. `FILTER`, `SORT`, `SORTBY`, `UNIQUE`, `SEQUENCE`, `RANDARRAY` (seeded as `RAND` is), `TEXTSPLIT`, `TAKE`, `DROP`, `VSTACK`, `HSTACK`, `TOCOL`, `TOROW`, `CHOOSEROWS`, `CHOOSECOLS`, `EXPAND`, `WRAPROWS` and `WRAPCOLS` give arrays; `MAP`, `REDUCE`, `SCAN`, `BYROW`, `BYCOL` and `MAKEARRAY` take a `LAMBDA`.
|
|
194
|
+
- A **data table** is Excel's What-If Analysis table, `=TABLE(row input, column input)` over its cells as a range key (`B5:F9: =TABLE($B$1,$B$2)`), its references absolute: each cell is the table's formula with the inputs set to the value atop its column and the value left of its row. A two-way table's formula is the cell above its left column, `A4` here; with a column input alone (`=TABLE(,$B$2)`) the formulas are the row above it, one a column, and with a row input alone (`=TABLE($B$1,)`) the column left of it, one a row. It is worked out after what it reads, iterating where the model does, and again with every change; an `.xlsx` holds it as Excel's own.
|
|
191
195
|
- A formula cannot reach into another workbook.
|
|
192
196
|
|
|
193
197
|
## In a script
|
|
@@ -290,7 +294,20 @@ charts:
|
|
|
290
294
|
size: 9 # its text, points; title_size 14 and color #595959 unless it says
|
|
291
295
|
```
|
|
292
296
|
|
|
293
|
-
In a flow map (`{ … }`), quote a reference with `[`. A scatter's `x` names its places across, each series its own, the chart's `categories` unless it says.
|
|
297
|
+
In a flow map (`{ … }`), quote a reference with `[`. A scatter's `x` names its places across, each series its own, the chart's `categories` unless it says.
|
|
298
|
+
|
|
299
|
+
A **combination chart** is Excel's: a column, line or area chart whose series each may be drawn as another of those kinds, `type` (`column-clustered`, `column-stacked`, `column-stacked-100`, `line`, `line-markers`, `area`, `area-stacked`, `area-stacked-100`), and on a second value axis at the right, `secondary: true`, which `secondary_axis` sets as `value_axis` sets the first (`{ title, min, max, major, format, gridlines, visible }`). Areas are drawn first, then columns, then lines, the second axis's over the first's:
|
|
300
|
+
|
|
301
|
+
```yaml
|
|
302
|
+
- type: column-clustered
|
|
303
|
+
at: F3
|
|
304
|
+
categories: orders[month]
|
|
305
|
+
series:
|
|
306
|
+
- { values: "orders[total]" }
|
|
307
|
+
- { values: "orders[margin]", type: line-markers, secondary: true }
|
|
308
|
+
secondary_axis: { min: 0, max: 1, format: "0%" }
|
|
309
|
+
```
|
|
310
|
+
Rows and columns a person or a filter hides are left out, as Excel plots what shows; an empty cell or `#N/A` is a gap, text is 0. An inserted row, a renamed table or column and a cut reach a chart's references as they reach a formula, and `allyhub check` reports one that names nothing.
|
|
294
311
|
|
|
295
312
|
In a script they are openpyxl's classes. A `Reference` is a range; a table's column or a spill, which it cannot name, is a formula's text:
|
|
296
313
|
|
|
@@ -381,11 +398,11 @@ A name of openpyxl's that is not held throws where it is used, naming what the c
|
|
|
381
398
|
- `allyhub sheet calc <sheet> [what]` prints what a workbook computes, as an aligned table: a sheet (`Summary`, its used range), a range (`Summary!B3:M3`), a table, a name, or every sheet. `--scenario high` computes it with a scenario's inputs; `--scenarios` compares them.
|
|
382
399
|
- `allyhub sheet trace <sheet> <cell>` prints a cell's formula, where it is written, what it reads and what reads it.
|
|
383
400
|
- `allyhub sheet <sheet>` measures each table's columns: counts, empty cells, distinct values, errors, smallest and largest, sum and mean, lengths, the most frequent values.
|
|
384
|
-
- `allyhub inspect <sheet>`, and `allyhub inspect` for a whole project, says what a workbook's formulas and cells are like, as facts, never problems: `sheet-error`, each cell whose value is an error and whether it starts there; `sheet-number`, numbers written into a formula and what takes each, once for a formula a range holds; `sheet-unlike`, a cell between neighbours that read alike, unlike them; `sheet-exception`, a cell set apart from its calculated column's formula; `sheet-unused`, names and typed numbers nothing reads (no formula, chart, rule, check or name); `sheet-invalid`, a value under a validation that breaks it; `sheet-typed`, a number its code typed that neither its data nor its code holds; `sheet-ordinary`, a sheet its code makes and the workbook file holds too. `allyhub inspect sheet <sheet>` has their options: `--plain 0,1,-1` the numbers not said, `--around 1` how many neighbours each side must agree, `--kind`, `--all` for every finding, every number and a table's columns nothing reads.
|
|
401
|
+
- `allyhub inspect <sheet>`, and `allyhub inspect` for a whole project, says what a workbook's formulas and cells are like, as facts, never problems: `sheet-error`, each cell whose value is an error and whether it starts there; `sheet-number`, numbers written into a formula and what takes each, once for a formula a range holds; `sheet-unlike`, a cell between neighbours that read alike, unlike them; `sheet-exception`, a cell set apart from its calculated column's formula; `sheet-unused`, names and typed numbers nothing reads (no formula, chart, rule, check or name); `sheet-invalid`, a value under a validation that breaks it; `sheet-typed`, a number its code typed that neither its data nor its code holds; `sheet-ordinary`, a sheet its code makes and the workbook file holds too; `sheet-iteration`, with `iteration` on, the rounds iterative calculation ran over how many cells and how far a value moved in the last. `allyhub inspect sheet <sheet>` has their options: `--plain 0,1,-1` the numbers not said, `--around 1` how many neighbours each side must agree, `--kind`, `--all` for every finding, every number and a table's columns nothing reads.
|
|
385
402
|
- `allyhub sheet diff <was> <now>` compares two versions, two folders or a folder and an `.xlsx`: what changed value under a formula that did not, what changed formula with its value the same, both, what came and went, names, a table's rows lined up by its `key`, else by their place. `--tolerance`, `--all`, `--json`.
|
|
386
403
|
- `allyhub sheet capabilities` says what the SDK holds of openpyxl's.
|
|
387
404
|
- `allyhub sheet import <file> --to finance/forecast.yaml` makes a sheet of an Excel, CSV or TSV file, its tables' rows in `finance/data/`, never over a place that is taken (see [Excel](#excel)).
|
|
388
|
-
- `allyhub render` writes each sheet to `.allyhub/out/<id>/`: `--type xlsx` (the default), `pdf`, `png`, `csv` (a file a sheet
|
|
405
|
+
- `allyhub render` writes each sheet to `.allyhub/out/<id>/`: `--type xlsx` (the default), `pdf`, `png`, `csv` (a file a sheet, named after it). An agent reads a sheet's values with `allyhub sheet calc`, not a file. A sheet with a problem is not written.
|
|
389
406
|
- `allyhub frames <sheet>` draws a picture of a sheet as a person sees it, letters and numbers on its edges; `--range` names a sheet (`Summary`), a range (`Summary!B3:D9`), columns (`A:C`) or rows (`1:20`). Without a range it draws the first 200 rows and 60 columns of each sheet, and says what it left out.
|
|
390
407
|
|
|
391
408
|
`allyhub help sheet` and `allyhub help render` give every option.
|
|
@@ -397,7 +414,7 @@ A name of openpyxl's that is not held throws where it is used, naming what the c
|
|
|
397
414
|
**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:
|
|
398
415
|
|
|
399
416
|
- 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.
|
|
400
|
-
- `Not carried over:` VBA, pivot tables, a chart of a kind a sheet has none of (radar, stock, surface, bubble, 3-D,
|
|
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.
|
|
401
418
|
- 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.
|
|
402
419
|
- `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.
|
|
403
420
|
|
package/docs/slides.md
CHANGED
|
@@ -101,7 +101,7 @@ slides:
|
|
|
101
101
|
| `script` | none | Its script, from the module's folder, with `{locale}` once in its name for each language (`./deck.{locale}.yaml`) |
|
|
102
102
|
| `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; a carousel is an image, [image.md](image.md)) or `{ width, height }` in EMU |
|
|
103
103
|
| `title` | none | Its name for people, what lists show it by |
|
|
104
|
-
| `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. A font named with no file the stage has is AK-L006 |
|
|
104
|
+
| `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. These and Calibri, Times New Roman, Cambria and Courier New are drawn here by fonts of the same metrics (Arimo, Noto Sans SC, Carlito, Tinos, Caladea, Cousine), 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. A font named with no file the stage has is AK-L006 |
|
|
105
105
|
|
|
106
106
|
## Masters, layouts and placeholders
|
|
107
107
|
|
|
@@ -110,8 +110,12 @@ 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, a rectangle's 0 top, 1 left, 2 bottom, 3 right, and its ends then follow the shape; `begin_x`, `begin_y`, `end_x` and `end_y` read and move them), `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
|
|
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; 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.
|
|
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.
|
|
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
|
+
- `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 }, …]`.
|
|
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.
|
|
115
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.
|
|
116
120
|
|
|
117
121
|
## Components
|
|
@@ -122,6 +126,48 @@ python-pptx opens these from a template; here code makes them.
|
|
|
122
126
|
|
|
123
127
|
`prs.generators.add(name, (g) => { … })` makes slides from data: `g.data(path)` reads a data file (CSV rows, YAML, JSON) from the module'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. The slides file 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>: … }`.
|
|
124
128
|
|
|
129
|
+
A slide drawn whole by code, a diagram, is one generator's slide. The deck is then three files: its module, its slides file placing the generator's block, and its script, which still has its file (with `{locale}` in its name, one language or many), with no rows (`slides: []`):
|
|
130
|
+
|
|
131
|
+
```ts file=figure/figure.ts
|
|
132
|
+
import {
|
|
133
|
+
MSO_ARROWHEAD,
|
|
134
|
+
MSO_CONNECTOR,
|
|
135
|
+
MSO_SHAPE,
|
|
136
|
+
Pt,
|
|
137
|
+
presentation,
|
|
138
|
+
} from "@allyhub/sdk/slides";
|
|
139
|
+
|
|
140
|
+
export default presentation(
|
|
141
|
+
{ slides: "./figure.yaml", script: "./figure.{locale}.yaml" },
|
|
142
|
+
(prs) => {
|
|
143
|
+
prs.slide_masters.add("Blank").slide_layouts.add("Blank");
|
|
144
|
+
prs.generators.add("figure", (g) => {
|
|
145
|
+
const slide = g.slides.add_slide("Blank", "flow");
|
|
146
|
+
const a = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, Pt(60), Pt(120), Pt(160), Pt(60));
|
|
147
|
+
a.text_frame.text = "Encoder";
|
|
148
|
+
const b = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, Pt(360), Pt(120), Pt(160), Pt(60));
|
|
149
|
+
b.text_frame.text = "Decoder";
|
|
150
|
+
const c = slide.shapes.add_connector(MSO_CONNECTOR.STRAIGHT, 0, 0, Pt(1), 0);
|
|
151
|
+
c.begin_connect(a, 3);
|
|
152
|
+
c.end_connect(b, 1);
|
|
153
|
+
c.line.end_arrow = MSO_ARROWHEAD.TRIANGLE;
|
|
154
|
+
});
|
|
155
|
+
},
|
|
156
|
+
);
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
```yaml
|
|
160
|
+
# figure/figure.yaml
|
|
161
|
+
slides:
|
|
162
|
+
- id: figure
|
|
163
|
+
generate: figure
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
```yaml
|
|
167
|
+
# figure/figure.en.yaml
|
|
168
|
+
slides: []
|
|
169
|
+
```
|
|
170
|
+
|
|
125
171
|
## The slides file
|
|
126
172
|
|
|
127
173
|
| Field | What it is |
|
|
@@ -133,7 +179,7 @@ python-pptx opens these from a template; here code makes them.
|
|
|
133
179
|
| `slides[].shapes` | Its shapes by name: what it changes of its layout's placeholders, and its own |
|
|
134
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) |
|
|
135
181
|
|
|
136
|
-
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`), `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 to its text), `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, `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.
|
|
137
183
|
|
|
138
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:
|
|
139
185
|
|
package/docs/speech.md
CHANGED
|
@@ -104,7 +104,7 @@ export default video({
|
|
|
104
104
|
Text to speech. `allyhub voice` makes the missing files with the cloud voice tool, each in `assets/media/gen/say/<hash>` with its words and its record (each tool's description says what it costs). A `say` without its file is AK-T002; until it has one, the part lasts about as long as the line takes to say (`SPEECH_RATE_DEFAULTS`: 0.38 s a word, 0.22 s a Chinese, Japanese or Korean character; at least 1 s), and its anchors are placed in proportion along the line.
|
|
105
105
|
|
|
106
106
|
- `voice`: the voice tool's voice id (`allyhub ai-media find-voices` finds them); default the tool's own.
|
|
107
|
-
- `tool`: the voice tool; default `"speak"` (`"
|
|
107
|
+
- `tool`: the voice tool; default `"speak"` (`"clone-voice"` speaks in the voice of a recording you give in `params`; `allyhub help ai-media <tool>` lists its input).
|
|
108
108
|
- `params`: more input for the tool, plain JSON: fields its schema has besides the text and voice (`text` and `voiceId` throw).
|
|
109
109
|
- `speed`: 0.5 to 2, default 1: plays the file faster or slower, pitch kept, as `.speed()` does. Not sent to the tool, so the same file.
|
|
110
110
|
|
package/docs/x.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# X posts and articles
|
|
2
|
+
|
|
3
|
+
Two kinds in X's own model, each a file listed in `allyhub.yaml` ([project.md](project.md#items)): an `x-post` (a post, a thread or a long post) and an `x-article`.
|
|
4
|
+
|
|
5
|
+
## An X post
|
|
6
|
+
|
|
7
|
+
An `x-post` is a YAML file (`- { kind: x-post, file: launch/launch.yaml }`). Its fields are POST /2/tweets's own:
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
reply_settings: following # who may reply to each post: following, mentionedUsers, subscribers or verified
|
|
11
|
+
posts:
|
|
12
|
+
- text: |
|
|
13
|
+
We shipped dark mode.
|
|
14
|
+
media:
|
|
15
|
+
- file: ./shots.ts#hero # an image's board, a video item, or a picture or video file, from this file's folder
|
|
16
|
+
alt: The dashboard in dark mode.
|
|
17
|
+
- text: Which do you use?
|
|
18
|
+
poll: { options: [Light, Dark], duration_minutes: 1440 }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **A thread** is its posts in order; each after the first is published as a reply to the one before. A post alone is a thread of one. The first post may also `reply` (`in_reply_to_tweet_id`) or quote (`quote_tweet_id`) a post already on X; quoting through the API needs an Enterprise plan. A post may say `made_with_ai` and `paid_partnership`.
|
|
22
|
+
- **Length is X's weighted count**, not the characters shown: Latin letters, digits and common punctuation 1; Chinese, Japanese, Korean and most other scripts 2; every emoji 2, whatever it is made of; every link 23, however long. At most 280 a post.
|
|
23
|
+
- **A long post** is a post over 280, which an X Premium account publishes up to 25,000. `allyhub.config.ts`'s `x: { premium: true }` says the account is Premium; it also takes videos up to 4 hours and 16 GB. X's timeline folds a long post at "Show more": at most 280 characters, back to a word's end (measured on x.com; `allyhub frames` draws the fold).
|
|
24
|
+
- **Plain text.** The API publishes no bold or italics. A link is its address.
|
|
25
|
+
- **A post's text as a block (`|`) or in quotes** when it holds ` #` (YAML reads the rest of the line as a comment), starts with `@`, `#` or a quote, or holds `: `. The line break a block ends in is not posted.
|
|
26
|
+
- **Media**: up to 4 pictures (JPEG, PNG or WebP, 5 MB each), or 1 GIF (15 MB), or 1 video (MP4 or MOV), never mixed. Alt text up to 1,000 characters. X publishes no picture size, crop or safe area. A video is checked against the widest of what X publishes: 0.5 s to 20 minutes (4 hours with Premium), 8 GB (16 GB), sides 32 px to 1920 on the long side and 1200 on the short, 1:3 to 3:1. X's ways of posting take less: its web upload 1:2.39 to 2.39:1 at 40 frames a second and 25 Mbps, and without Premium 140 seconds and 512 MB; its API's media guide 1280×1024 and 60 frames a second. A 1280×720 or 720×1280 H.264 MP4 at 30 frames a second under 140 seconds suits every way.
|
|
27
|
+
- **Another item's made file**: `./shots.ts#hero` is the image `shots`'s board `hero`, made first when the post is rendered; a video item's file is its first version. Its bytes are checked when it is made.
|
|
28
|
+
|
|
29
|
+
## An X article
|
|
30
|
+
|
|
31
|
+
An `x-article` is a Markdown file (`- { kind: x-article, file: launch/story.md }`), its title and cover in its front matter, its body in X's blocks alone:
|
|
32
|
+
|
|
33
|
+
```markdown
|
|
34
|
+
---
|
|
35
|
+
title: How we built dark mode
|
|
36
|
+
cover: ./shots.ts#cover # a picture file or an image's board; or { file, alt }
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
Paragraphs with **bold**, _italic_, ~~strikethrough~~ and [links](https://example.com).
|
|
40
|
+
|
|
41
|
+
# A heading (X has two: # a Heading, ## a Subheading)
|
|
42
|
+
|
|
43
|
+
- a list, one level deep
|
|
44
|
+
|
|
45
|
+
1. or numbered
|
|
46
|
+
|
|
47
|
+
> A quote.
|
|
48
|
+
|
|
49
|
+
<br />
|
|
50
|
+
|
|
51
|
+

|
|
52
|
+
|
|
53
|
+
https://x.com/allyhub/status/1234567890
|
|
54
|
+
|
|
55
|
+
https://example.com/launch
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
$$
|
|
60
|
+
e^{i\pi} + 1 = 0
|
|
61
|
+
$$
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- **Each element is one of X's blocks**: a paragraph, a Heading (`#`) and a Subheading (`##`), lists a level deep, a quote, a picture, GIF or video on a line of its own (its alt text and its caption), a post's address on a line of its own (an embedded post), any other address on a line of its own (a link's card, as X's link preview), `---` (a divider), `$$ … $$` (an equation), a code block or a table (X's Markdown block: 10,000 together, weighted as X counts), and `<br />` alone on a line (an empty line, which X keeps). A third level of heading, a list inside a list, inline code, a picture or an equation inside a line and other HTML are not: each is a problem at its line.
|
|
65
|
+
- **A code block or a picture written inside a list item** stands after the list, and the list starts again after it, as X's editor places it.
|
|
66
|
+
- **Media** are pictures (JPEG, PNG or WebP, 5 MB each), GIFs (15 MB) and videos (MP4 or MOV); the cover is a picture at 5:2. An image's board (`./shots.ts#chart`) or a video item (`./teaser.ts`) may be one, made first when the article is rendered. X publishes no most for a title or a body.
|
|
67
|
+
- **X Premium** writes articles. Through the API an article is drafted and published, and nothing else: it cannot be changed or deleted once published.
|
|
68
|
+
|
|
69
|
+
## Check, measure and render
|
|
70
|
+
|
|
71
|
+
`allyhub check` reports what X refuses under `allyhub.x/…`, at its line. `allyhub inspect <post>` gives each post's weighted length beside 280 and 25,000, its links, mentions, hashtags and cashtags, and its media's bytes; `allyhub inspect <article>` its words, its weighted length, its headings, its media, its embedded posts and links' cards, and its code's weight against 10,000. `allyhub frames` draws a post or an article as X shows it once published (a thread as the timeline does, an article in X's column), in Inter in place of X's own face; an embedded post and a link's card are drawn by their address, as their content is X's to fetch.
|
|
72
|
+
|
|
73
|
+
`allyhub render <post>` writes POST /2/tweets's request for each post (`posts.json`, the media beside it), or what a person posts by hand (`--type txt`: each post's text as written, `1.txt`, `2.txt`…, each medium beside it as `<post>-<place>` and its alt text in `<post>-<place>.alt.txt`). `allyhub render <article>` writes POST /2/articles/draft's request (`article.json`, its media beside it with `media.json`). The editor's Export offers `txt` and a picture (`png`) of a post, and a picture of an article; the requests wait for publishing. Publishing to X is not built.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@allyhub/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.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",
|