slotdeck 0.1.0 → 0.1.2

package/docs/languages.md

@@ -0,0 +1,83 @@
+# Languages and reading direction
+
+A template is designed for one reading direction (`direction` in the manifest: `ltr` or `rtl`). A deck states
+its own (`direction` in the deck, defaulting to the template's). When they differ, the text flips and the layout
+stays.
+
+This works both ways: a Hebrew or Arabic deck on a left-to-right template, and an English deck on a
+right-to-left template.
+
+## Setting language and direction
+
+In a deck:
+
+```json
+{ "version": 1, "language": "he", "direction": "rtl", "slides": [ ... ] }
+```
+
+In a brief for the planner, `language` is enough: the direction follows from it.
+
+```ts
+await generateDeck(template, { prompt: '...', language: 'he' }, options);
+```
+
+`directionOf('he')` returns `'rtl'`; `directionOf('en')` returns `'ltr'`.
+
+## What changes in a deck that reads the other way
+
+| Thing | What happens |
+| --- | --- |
+| Paragraph direction | Every paragraph gets the direction of its own text, from its first letter. A Hebrew deck may hold an English line, and that line is left to right. Text with no letters ("78%") keeps the template paragraph's direction. |
+| Alignment | Left and right alignment are swapped (`alignOnDirectionChange: "flip"`, the default). A paragraph that states no alignment counts as left-aligned. Centred text stays centred. |
+| Rows and grids of items | Filled mirror-wise within each line, so the deck's first item is where its readers start: at the right in a right-to-left deck. Shapes do not move; the values go to the mirrored positions. |
+| Tables | Run in the deck's direction, with text aligned to its start. |
+| Charts | Labels are set right to left. |
+| Run language | Right-to-left text is marked with a right-to-left language. |
+| Shapes | Do not move. A photo on the right stays on the right. Bullets and their indent follow the paragraph direction automatically. |
+
+## Keeping alignment
+
+Mirroring alignment suits templates whose text boxes are as wide as the area they belong to. It does not suit a
+template whose text boxes share one edge but not the other: flipped text would then start at uneven positions or
+run into a neighbouring shape.
+
+- For the whole template: `"alignOnDirectionChange": "keep"` in the manifest.
+- For one slot: `"alignOnDirectionChange": "keep"` (or `"flip"`) on that text slot.
+
+A common case for a per-slot `keep` is a line next to a logo: it should stay beside the logo in either
+direction.
+
+## Why runs are marked with a language
+
+PowerPoint decides where punctuation and spaces go by the language of the run they are in, not only by the
+paragraph's direction. In a run marked as English, the text
+
+```
+שאלות: name@example.org
+```
+
+is displayed with the colon on the far side of the address. slotdeck therefore marks right-to-left runs with a
+right-to-left language (`he-IL` for Hebrew, `ar-SA` for Arabic) unless the template already gave the run one.
+You do not need to do anything for this.
+
+## Fonts
+
+Text keeps the template's fonts. If the template's font has no glyphs for the deck's script, PowerPoint
+substitutes another font. For a template that will be used in two scripts, set a complex-script font on its text
+(in PowerPoint: the font for "complex scripts"), or choose fonts that cover both.
+
+## Mirrored item order in the deck JSON
+
+The deck always numbers items in its own reading order: `card1` is the first card for the reader. You do not
+reverse anything yourself. Validation messages name the slot as the deck wrote it.
+
+## Language of generated text
+
+The planner writes in `brief.language`. Slot names and pattern ids stay as the manifest defines them (they are
+identifiers, not content). Translating an existing deck is an edit:
+
+```ts
+await editDeck(template, deck, 'Translate the deck to English', { llm });
+```
+
+This rewrites every slide, sets the direction, and translates deck-level fields.

package/docs/layout-freedom.md

@@ -0,0 +1,136 @@
+# Layout freedom
+
+A deck can depart from the template slide in four bounded ways. In each, the choice is a small value in the deck
+JSON, the manifest says what is allowed, and the code moves the shapes. Nothing is ever positioned by a model.
+
+## 1. A different number of items
+
+A pattern with a `repeat` in the manifest has a row or grid of like items: cards, figures, steps. The deck says
+how many with `items`.
+
+Manifest:
+
+```json
+"repeat": {
+  "item": "card",
+  "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+  "shapes": [["6"], ["12"], ["18"], ["24"]],
+  "min": 2,
+  "max": 4
+}
+```
+
+Deck:
+
+```json
+{ "pattern": "icon-cards", "items": 3, "slots": { "title": "...", "card1Icon": {"asset": "clock"}, "card1Heading": "...", "card1Text": "...", "card2Icon": {"asset": "shield"}, "card2Heading": "...", "card2Text": "...", "card3Icon": {"asset": "people"}, "card3Heading": "...", "card3Text": "..." } }
+```
+
+What the renderer does:
+
+- **Fewer items than drawn:** the surplus items' shapes are removed.
+- **More items than drawn:** the last item is copied. A copy's slots have the next numbers (`card5Icon`,
+  `card5Heading`, ...) and take the last drawn item's limits.
+- **Spacing:** the items are laid out again around the centre of the area the row occupied. They keep the
+  template's spacing when there is room and move closer together when there is not. With a `span`, the row may
+  spread out to those limits.
+- Without `items`, the slide has the number of items drawn on the template slide.
+
+An `items` value outside `min` to `max` is an error:
+`pattern "icon-cards" takes 2 to 4 cards, not 5`.
+
+How many items fit is a property of the template: `changeManifest` refuses a `max` that does not fit side by
+side and says the most that do (see [template-studio.md](template-studio.md)).
+
+## 2. Grids
+
+With `columns` in the `repeat`, the items form a grid. `columns` is how many items one line holds on the
+template slide.
+
+- Items fill lines in reading order and use as few lines as the count needs.
+- They are spread evenly over those lines: in a three-column grid, four items make two lines of two (not three
+  and one), five make three and two, three make one line.
+- Each line is centred, and a single line moves to the middle of the grid's area.
+- A grid cannot hold more items than it draws.
+
+## 3. Larger text
+
+A deck can ask for larger body text:
+
+```json
+{ "version": 1, "textScale": 1.25, "slides": [ ... ] }
+```
+
+or, on a brief for the planner, `textSize: 'large'` (1.25) or `'x-large'` (1.5). The named sizes are in
+`TEXT_SIZES`: `{ normal: 1, large: 1.25, 'x-large': 1.5 }`.
+
+- It applies to **body text**: by default, text slots whose template size is 12 pt or under and that are not
+  deck fields. Titles and large figures keep their size. A slot can opt in or out with `scales` in the
+  manifest.
+- Boxes do not grow, so larger text fits less. The character budget of a scaled slot is divided by the square
+  of the scale (a 300-character slot holds 192 at 1.25), and the paragraph budget by the scale. The planner
+  shows the model the reduced budgets, so it writes less.
+- Through `editDeck`, "make the text larger" sets the scale and rewrites only the slides whose text no longer
+  fits.
+- Table text and chart labels follow the scale where the manifest states their size (`bodyText.size`,
+  `headerText.size`, `text.size`), and a table cell then holds less.
+
+### Larger text for a whole template
+
+The engine keeps the template's own font sizes. A template designed with small body text, such as 9 pt on a
+10-inch-wide slide, therefore gives decks with small body text. To change that once, for every deck, set
+`textScale` on the manifest:
+
+```json
+{ "version": 1, "name": "corporate", "direction": "rtl", "textScale": 1.3, "patterns": [ ... ] }
+```
+
+With `changeManifest`: `{ op: 'setManifest', textScale: 1.3 }`.
+
+- It works exactly like a deck's `textScale` and applies to the same slots (body text: 12 pt and under by
+  default), but for every deck made from the template.
+- Budgets shrink to match, in validation, in what the planner shows the model, and in `sampleDeck`: a slot
+  that held 240 characters holds 142 at 1.3. Render the sample deck after setting it to see that everything
+  still fits.
+- A deck's own text size goes on top. With a template at 1.3, a deck at `large` (1.25) shows body text at about
+  1.6 times the designed size.
+- A slot that should keep its size can opt out with `"scales": false`.
+
+## 4. Derived patterns
+
+Several patterns may point at the same template slide and use it differently. A derived pattern is made by
+copying a pattern and changing some of its slots:
+
+| Change | Manifest property | Example |
+| --- | --- | --- |
+| Remove a shape always | `"empty": "drop"` on a slot that points at it | A text-only slide from a slide with a photo |
+| Move or resize a text box | `box` on the text slot | Widen the text over the area the photo left free |
+| Set a font size | `fontSize` | Larger body text for a slide with little on it |
+| Space paragraphs | `paragraphGap` | Air between two or three short paragraphs |
+| Give a picture another area | `box` on the image slot | A wide diagram in place of a small sample chart |
+| A native chart in place of a picture | a `chart` slot on the picture's shape | The chart slide with editable data |
+
+Example: a text-only pattern derived from a photo pattern.
+
+```json
+{
+  "id": "text-only",
+  "sourceSlide": 2,
+  "description": "A title, an optional supporting line and two or three short paragraphs, with no picture.",
+  "slots": [
+    { "name": "photo", "kind": "image", "imageKind": "graphic", "shapeId": "2", "empty": "drop" },
+    { "name": "title", "kind": "text", "shapeId": "5", "size": 34, "maxChars": 83, "box": { "x": 0.0375, "y": 0.2, "w": 0.925, "h": 0.187 } },
+    { "name": "body", "kind": "text", "shapeId": "7", "size": 18, "maxChars": 331, "maxParagraphs": 3, "fontSize": 20, "paragraphGap": 12, "box": { "x": 0.0375, "y": 0.4933, "w": 0.72, "h": 0.3867 } }
+  ]
+}
+```
+
+With `changeManifest` this is three operations (`copyPattern`, `addSlot` with role `decoration`, `setSlot` with
+a `box`), and the budgets are worked out for you: see [template-studio.md](template-studio.md).
+
+## What is not possible
+
+- Moving a shape to an arbitrary place from a deck. Positions come only from the template and the manifest.
+- Swapping the side of a photo.
+- A grid with more items than the template slide draws.
+- New kinds of slides that the template has no sample for.

package/docs/manifest-format.md

@@ -0,0 +1,208 @@
+# Manifest format
+
+A manifest is a JSON object of type `TemplateManifest`. It describes one template: which of its slides are
+reusable patterns and which shapes on them are slots.
+
+```ts
+import type { TemplateManifest, PatternDef, SlotDef, TextSlotDef, ImageSlotDef, TableSlotDef, ChartSlotDef, RepeatDef } from 'slotdeck';
+```
+
+A manifest is written once per template. You can have a model draft it (`draftManifest`), change it with
+operations (`changeManifest`) or by instruction (`editManifest`), and verify it (`checkManifest`): see
+[template-studio.md](template-studio.md). This page is the reference for what the JSON means.
+
+## Example
+
+```json
+{
+  "version": 1,
+  "name": "demo",
+  "language": "en",
+  "direction": "ltr",
+  "alignOnDirectionChange": "flip",
+  "patterns": [
+    {
+      "id": "cover",
+      "sourceSlide": 1,
+      "description": "Opening slide with the presentation's title and a subtitle.",
+      "slots": [
+        { "name": "title", "kind": "text", "shapeId": "5", "size": 50, "maxChars": 36 },
+        { "name": "subtitle", "kind": "text", "shapeId": "6", "size": 20, "maxChars": 86, "empty": "remove" },
+        { "name": "organizationDepartment", "kind": "text", "shapeId": "7", "size": 13, "maxChars": 61, "deckField": "organizationDepartment", "alignOnDirectionChange": "keep" }
+      ]
+    },
+    {
+      "id": "icon-cards",
+      "sourceSlide": 5,
+      "description": "A row of cards, each with an icon, a heading and a short text.",
+      "slots": [
+        { "name": "title", "kind": "text", "shapeId": "5", "size": 34, "maxChars": 41 },
+        { "name": "card1Icon", "kind": "image", "imageKind": "icon", "shapeId": "9" },
+        { "name": "card1Heading", "kind": "text", "shapeId": "10", "size": 19, "maxChars": 15 },
+        { "name": "card1Text", "kind": "text", "shapeId": "11", "size": 15, "maxChars": 117 },
+        { "name": "card2Icon", "kind": "image", "imageKind": "icon", "shapeId": "15" },
+        { "name": "card2Heading", "kind": "text", "shapeId": "16", "size": 19, "maxChars": 15 },
+        { "name": "card2Text", "kind": "text", "shapeId": "17", "size": 15, "maxChars": 117 }
+      ],
+      "repeat": {
+        "item": "card",
+        "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+        "shapes": [["6"], ["12"]],
+        "min": 2,
+        "max": 4
+      }
+    }
+  ]
+}
+```
+
+## `TemplateManifest`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `version` | `1` | yes | Always 1. |
+| `name` | string | yes | A name for the template. Used in messages. |
+| `direction` | `"ltr"` or `"rtl"` | yes | The reading direction the template was designed for. |
+| `patterns` | `PatternDef[]` | yes | The reusable layouts. |
+| `language` | string | no | BCP 47 tag of the template's sample text. Decks default to it. |
+| `alignOnDirectionChange` | `"flip"` or `"keep"` | no | What happens to left and right paragraph alignment in a deck that reads the other way. `flip` (default) mirrors it. `keep` leaves it as designed. A text slot can override this. |
+| `textScale` | number | no | Enlarges the body text of every deck made from this template, as a factor on the designed size: `1.3` turns 9 pt into about 12 pt. For a template whose body text is too small to read comfortably. Budgets shrink to match. See "Larger text" in [layout-freedom.md](layout-freedom.md). |
+
+## `PatternDef`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `id` | string | yes | What decks call the pattern. Unique in the manifest. Lower-case words joined by hyphens is the convention. |
+| `sourceSlide` | integer | yes | Number of the template slide the pattern is cloned from, counted from 1. |
+| `description` | string | yes | What the pattern is for. The planning model reads it to choose patterns, so write it for an author: what the slide holds and when to use it. |
+| `slots` | `SlotDef[]` | yes | The shapes a deck fills. |
+| `figures` | boolean | no | The pattern is built around numbers. The planner offers it only when the brief contains figures, so a model is not led to invent statistics. |
+| `repeat` | `RepeatDef` | no | A row or grid of like items whose number a deck may choose. See below. |
+| `sequences` | string[][][] | no | Rows of items with a fixed count, for mirroring in decks that read the other way. Each row lists its items first to last in the template's direction, and each item lists its slot names. Not needed for slots covered by `repeat`. |
+
+## Slots: properties every kind has
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `name` | string | yes | What decks call the slot. Unique within the pattern. Letters and digits, starting with a lower-case letter. |
+| `kind` | `"text"`, `"image"`, `"table"` or `"chart"` | yes | What the slot holds. |
+| `shapeId` | string | yes | The id of the shape on the source slide (the `id` attribute of the shape's `p:cNvPr` element, as a string). `inspectTemplate` and `studioView` list them. |
+| `description` | string | no | Guidance for the planning model about this slot, such as "One line". |
+| `empty` | `"error"`, `"remove"`, `"keep"` or `"drop"` | no | What happens without a value. Default `error` (required). See [concepts.md](concepts.md). |
+
+Slots with `empty` of `keep` or `drop` are never offered to the planning model.
+
+## Text slot (`kind: "text"`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `maxChars` | integer | Soft limit on the total characters of the slot. Exceeding it gives a warning. |
+| `maxParagraphs` | integer | Soft limit on the number of paragraphs. When it is more than 1, the planner asks the model for a list of paragraphs. |
+| `deckField` | string | Take the value from `deck.fields[deckField]` when the slide does not set it. |
+| `size` | number | Font size of the slot's text on the template slide, in points. Informational: it decides whether a deck's `textScale` applies (see `scales`). |
+| `scales` | boolean | Whether a deck's `textScale` applies to this slot. Default: yes for text of 12 pt and under that is not a deck field. |
+| `fontSize` | number | Sets the font size outright, in points. For a derived pattern that uses the shape differently. |
+| `box` | `{ x, y, w, h }` | Moves and resizes the text box, as fractions of the slide (0 to 1). Only for a shape that is not inside a group. |
+| `paragraphGap` | number | Space after each paragraph, in points. |
+| `alignOnDirectionChange` | `"flip"` or `"keep"` | Overrides the manifest's setting for this slot. |
+| `styleRun` | `"first"` or `"last"` | Which run of the template paragraph supplies the formatting, when the template paragraph mixes styles (a bold label followed by plain text). Default `first`. |
+
+## Image slot (`kind: "image"`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `imageKind` | `"photo"`, `"icon"` or `"graphic"` | Required. `photo`: a generated or supplied photo. `icon`: one of the app's icon set. `graphic`: a picture the app supplies, such as a diagram. |
+| `fit` | `"cover"` or `"contain"` | `cover` crops the picture to fill the frame. `contain` shows the whole picture inside the frame's area. Default: `cover` for photos, `contain` for icons and graphics. |
+| `box` | `{ x, y, w, h }` | The area the picture may use, when other than the sample picture's frame. Fractions of the slide. Only for a picture that is not inside a group. |
+
+## Table slot (`kind: "table"`)
+
+The shape must be a table.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `maxColumns` | integer | Soft limit on columns. |
+| `maxRows` | integer | Soft limit on body rows (the header row is not counted). |
+| `maxCellChars` | integer | Soft limit on the characters in one cell. |
+| `headerText` | `{ size?, bold?, color?, font? }` | Formatting for header cells, where the sample table defines none or it should differ. `color` is hex without `#`. |
+| `bodyText` | `{ size?, bold?, color?, font? }` | The same for body cells. |
+
+## Chart slot (`kind: "chart"`)
+
+The shape is the sample picture of a chart. At render time it is replaced by a native chart in the same place.
+The shape must not be inside a group.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `box` | `{ x, y, w, h }` | The area the chart may use, when other than the sample picture's frame. |
+| `maxCategories` | integer | Soft limit on categories. |
+| `maxSeries` | integer | Soft limit on series. |
+| `colors` | string[] | Series colours in order, hex without `#`. They repeat when there are more series. |
+| `text` | `{ size?, bold?, color?, font? }` | Formatting of axis labels, data labels and the legend. |
+| `lineColor` | string | Colour of gridlines and axis lines, hex without `#`. |
+
+## `RepeatDef`: a row or grid of items
+
+```json
+"repeat": {
+  "item": "card",
+  "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+  "shapes": [["6"], ["12"], ["18"], ["24"]],
+  "min": 2,
+  "max": 4,
+  "span": { "left": 0.04, "right": 0.96 },
+  "columns": 3
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `item` | string | yes | What one item is called in prompts, such as `card` or `figure`. |
+| `slots` | string[] | yes | Slot name templates of one item. `{n}` stands for the item number, from 1. For every item drawn on the slide the pattern must have a slot with each of these names (`card1Icon`, `card2Icon`, ...). |
+| `shapes` | string[][] | yes | For each item drawn on the template slide, first in reading order first: the ids of the shapes that move together as that item. Usually the group around a card. A background shape that sits outside the group belongs in the list too. |
+| `min`, `max` | integer | no | Fewest and most items a deck may ask for. Both default to the number drawn. |
+| `span` | `{ left, right }` | no | Left and right limits of the row, as fractions of the slide width. Defaults to the row as drawn. Needed when `max` is more than the drawn items can fit in the drawn width. Only applies to shapes placed directly on the slide. |
+| `columns` | integer | no | For a grid: how many items one line holds on the template slide. Leave it out for a single row. A grid cannot hold more items than it draws. |
+
+How the items are laid out for a given count is described in [layout-freedom.md](layout-freedom.md).
+
+Slots of copied items do not appear in the manifest. They are derived: item 5 of a row that draws 4 gets copies
+of item 4's slots, named with the next number.
+
+## Rules a manifest must satisfy
+
+`checkManifest(template)` reports violations of these:
+
+- Every `sourceSlide` exists in the pptx.
+- Every `shapeId` is a shape on that slide, and is the right kind of shape for the slot (a text slot points at
+  a shape with text, an image slot at a picture, a table slot at a table). A slot with `"empty": "drop"` may
+  point at any shape, because the shape is only ever removed.
+- Pattern ids are unique. Slot names are unique within a pattern.
+- A `box` is not set on a shape inside a group. A chart slot's shape is not inside a group.
+- For a `repeat`: a slot exists for every name template and every drawn item; every shape id exists; all items
+  sit directly on the slide or all in the same group; `min` is at least 1 and not more than `max`.
+
+It also warns about text slots without `maxChars` and about two slots that point at the same shape.
+
+## Finding shape ids
+
+```ts
+import { inspectTemplate, PptxPackage } from 'slotdeck';
+
+const info = inspectTemplate(PptxPackage.load(pptxBytes));
+for (const shape of info.slides[4].shapes) {
+  // slide 5: index 4
+  console.log(shape.id, shape.kind, shape.box, shape.groupId ?? '', shape.paragraphs?.join(' / ') ?? '');
+}
+```
+
+`shape.box` is `{ x, y, w, h }` as fractions of the slide, already worked out through any groups. `shape.kind`
+is `text`, `picture`, `shape` (a drawn shape without text), `line`, `group`, `table` or `other`.
+
+## Writing good descriptions
+
+The planning model chooses a pattern by its `description` and its slots' names and limits. A description should
+say what the slide holds and when to use it, in one or two sentences, without numbers that the deck may change:
+
+- Good: "A row of cards, each with an icon, a heading and a short text: features, steps or categories."
+- Poor: "Four cards." (the count can vary, and it does not say what the cards are for)