@openpresentation/opf 0.18.4 → 0.19.0

package/dist/spec/schemas/layout.schema.json

@@ -1,47 +1,50 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://openpresentation.org/schema/opf-layout/v1",
+  "$id": "https://openpresentation.org/schema/opf-layout/v2",
   "title": "Slide Layout",
-  "description": "Schema for slide-layout records. Each record describes a semantic slide layout: what regions it exposes, what content kinds those regions are intended to hold, how they are arranged (composition) and its design hints. Documents reference a layout from Slide.layout; a slide without a layout, or whose layout resolves nowhere, composes automatically.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
+  "description": "Schema for slide-layout records (OPF 0.19). A layout is a grid template: 'areas' names the cells of a grid in the notation of CSS grid-template-areas, 'columns' and 'rows' size its tracks, and 'regions' says, for every body area, which content kinds it takes and how several blocks share it. Slide content stays flat: engines bind a slide's blocks to the regions by reading order, role and kind (bindRegions in @openpresentation/opf), a block may pin itself to a region with 'region', and an empty region collapses into a neighbour. Built-in and custom layouts are records of this one schema; a custom layout is embedded under catalogs.custom.layouts or shipped in a catalog. Documents reference a layout from Slide.layout; a slide without a layout, with layout 'auto', or whose layout resolves nowhere composes automatically.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
   "required": [
     "$schema",
     "id",
-    "name"
+    "name",
+    "areas"
   ],
   "properties": {
     "$schema": {
       "type": "string",
-      "const": "https://openpresentation.org/schema/opf-layout/v1",
-      "description": "Identifies a published record file as a layout record. Required in a published file; an embedded copy omits it."
+      "const": "https://openpresentation.org/schema/opf-layout/v2",
+      "description": "Identifies a published record file as a layout template. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "The layout's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
+      "description": "The layout's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field. 'auto' is reserved: Slide.layout 'auto' is automatic composition, so no catalog may define a layout of that id.",
       "examples": [
-        "title",
-        "title-subtitle",
-        "chart-1x",
-        "image-focus"
-      ]
+        "cover",
+        "pillars",
+        "chart-beside",
+        "roadmap-split"
+      ],
+      "not": {
+        "const": "auto"
+      }
     },
     "name": {
       "type": "string",
-      "description": "Human-readable layout name shown in layout pickers.",
+      "description": "Human-readable layout name, shown in layout pickers and as the PowerPoint layout name.",
       "examples": [
-        "Title",
-        "Title Subtitle",
-        "Chart 1x",
-        "Image Bleed"
+        "Cover",
+        "Pillars",
+        "Chart beside"
       ]
     },
     "summary": {
       "type": "string",
-      "description": "One-sentence positioning of the layout — when to reach for it.",
+      "description": "One-sentence positioning of the layout \u2014 when to reach for it.",
       "examples": [
-        "Slide title aligned left over a single content area — flexible workhorse layout.",
-        "Title plus a single chart on the left and supporting copy on the right."
+        "Two to six ideas of equal weight, as cards.",
+        "A chart with the takeaway beside it."
       ]
     },
     "description": {
@@ -53,12 +56,92 @@
     },
     "design": {
       "$ref": "#/$defs/DesignHints",
-      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection). Composition, the renderer and the PPTX exporter all read the one result."
+      "description": "The layout's design defaults, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Per key the slide's design wins, then the deck's design, then the resolved theme's design, then this record's design, then the engine default. Composition, the renderer and the PPTX exporter all read the one result."
     },
-    "placeholders": {
+    "areas": {
       "type": "array",
-      "items": { "$ref": "#/$defs/PlaceholderEntry" },
-      "description": "Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf, which counts the leaves of placeholder groups), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. An entry may instead be a placeholder group ({ \"type\": \"group\", \"composition\", \"placeholders\" }) that arranges its own regions inside one cell of this record's composition, so a record can say 'two stacked panels beside a chart' once; groups nest at most three levels. Slide content stays flat: its body payloads fill the leaf regions in reading order (depth first, in array order). Slide content itself lives either in root payload fields, blocks or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer."
+      "minItems": 1,
+      "maxItems": 12,
+      "items": {
+        "type": "string"
+      },
+      "description": "The grid, in the notation of CSS grid-template-areas: each string is a row, each word a cell, and a name repeated over adjacent cells spans them; '.' is an empty cell. Words are lowercase names ([a-z][a-z0-9-]*) or '.', separated by spaces, and every row has the same number of words (at most 12 rows and 12 columns). A name's cells must form one filled rectangle. 'title' and 'subtitle' are heading areas: 'title' holds the slide's heading group (tag, title and subtitle, stacked) and a 'subtitle' area takes the subtitle out of it; they have no regions entry, and a 'subtitle' area needs a 'title' area. A layout with no 'title' area gets an implicit auto row on top for a slide that has headings. Every other name is a body region and needs an entry in 'regions'. The grid rules a schema cannot express are the validate finding opf/layout-template.",
+      "examples": [
+        [
+          "title",
+          "body"
+        ],
+        [
+          "title title",
+          "timeline notes",
+          "timeline metrics"
+        ]
+      ]
+    },
+    "columns": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "items": {
+        "type": "number",
+        "exclusiveMinimum": 0,
+        "maximum": 100
+      },
+      "description": "Relative column widths, one per cell of a row; the columns share the content width in proportion, separated by the gap. Omitted: all 1. Columns are numbers only.",
+      "examples": [
+        [
+          1,
+          1
+        ],
+        [
+          3,
+          2
+        ]
+      ]
+    },
+    "rows": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "items": {
+        "oneOf": [
+          {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 100
+          },
+          {
+            "const": "auto"
+          }
+        ]
+      },
+      "description": "Relative row heights, one per string of 'areas'. 'auto' is the height the row's content needs at the starting text size (at most half the content box; areas that span several rows do not size it); the numeric rows share the rest in proportion. An auto row whose areas are all empty has no height. Omitted: all 1.",
+      "examples": [
+        [
+          "auto",
+          1
+        ],
+        [
+          "auto",
+          1,
+          "auto"
+        ]
+      ]
+    },
+    "regions": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/Region"
+      },
+      "description": "One entry per body area, keyed by the area's name. Region names may not be 'title', 'subtitle', 'tag', 'auto' or one of the promoted-region words ('left', 'center', 'right', 'top', 'middle', 'bottom'), so a Markdown block's region= option stays unambiguous. Region rules the schema cannot express (an area without a region, a region without an area, a reserved name) are the validate finding opf/layout-region."
+    },
+    "overflowRegion": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The region where content that no region accepts goes, whatever its 'accepts', while it has room; content beyond every region's room is drawn there too, with the warning opf/layout-unplaced. Omitted: the first primary region (in reading order) whose flow is not 'none'."
     },
     "tags": {
       "type": "array",
@@ -90,7 +173,7 @@
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://example.com/layouts/title-subtitle.png"
+            "https://example.com/layouts/cover.png"
           ]
         },
         "thumbnailSrc": {
@@ -98,7 +181,7 @@
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://example.com/layouts/title-subtitle.thumbnail.png"
+            "https://example.com/layouts/cover.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -106,254 +189,115 @@
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/layout-previews/title-subtitle.svg"
+            "https://www.pptx.gallery/layout-previews/cover.svg"
           ]
         }
       }
     },
     "composition": {
+      "type": "object",
+      "description": "Only 'gap', 'padding', 'minFontSize' and 'overflow', with their 0.18 meaning. A template's regions replace composition.mode, columns and weights.",
       "$ref": "#/$defs/Composition"
     }
   },
   "$defs": {
-    "PlaceholderEntry": {
-      "description": "One entry of a layout's placeholders: a region (Placeholder) or, when its type is 'group', a placeholder group (PlaceholderGroup).",
-      "if": {
-        "type": "object",
-        "required": [
-          "type"
-        ],
-        "properties": {
-          "type": {
-            "const": "group"
-          }
-        }
-      },
-      "then": {
-        "$ref": "#/$defs/PlaceholderGroup"
-      },
-      "else": {
-        "$ref": "#/$defs/Placeholder"
-      }
-    },
-    "PlaceholderGroup": {
+    "Region": {
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "type",
-        "placeholders"
+        "accepts"
       ],
-      "description": "A placeholder group: regions arranged by their own composition inside one cell of the record's composition, the way a content group (a block with blocks) arranges its children. Slide content fills the group's leaf regions in reading order, as part of one flat sequence for the whole record. A group holds body regions and groups only (no title, subtitle or tag, and no placement), and groups nest at most three levels inside a record: this is the first. Groups draw nothing of their own and have no slide path; design.chartPrimary is shorthand for a record whose root holds the chart and one group of the other content.",
+      "description": "One body region of a layout: which content it takes and how several blocks share it.",
       "properties": {
-        "type": {
-          "const": "group",
-          "description": "Marks the entry as a placeholder group."
-        },
-        "composition": {
-          "$ref": "#/$defs/Composition",
-          "description": "How the group arranges its regions, with the semantics of a content group's composition: only minFontSize and overflow inherit from the enclosing composition; padding defaults to 0 and gap is a fraction of the group's short edge. Omitted, the group arranges its regions automatically."
-        },
-        "placeholders": {
+        "accepts": {
           "type": "array",
           "minItems": 1,
+          "uniqueItems": true,
           "items": {
-            "$ref": "#/$defs/PlaceholderGroupEntry2"
+            "type": "string",
+            "enum": [
+              "text",
+              "list",
+              "image",
+              "video",
+              "chart",
+              "table",
+              "code",
+              "metric",
+              "quote",
+              "timeline",
+              "group"
+            ]
           },
-          "description": "The group's regions and nested groups, in reading order."
-        }
-      }
-    },
-    "PlaceholderGroupEntry2": {
-      "description": "An entry of a first-level group: a region (GroupedPlaceholder) or a second-level group (PlaceholderGroup2).",
-      "if": {
-        "type": "object",
-        "required": [
-          "type"
-        ],
-        "properties": {
-          "type": {
-            "const": "group"
-          }
-        }
-      },
-      "then": {
-        "$ref": "#/$defs/PlaceholderGroup2"
-      },
-      "else": {
-        "$ref": "#/$defs/GroupedPlaceholder"
-      }
-    },
-    "PlaceholderGroup2": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "type",
-        "placeholders"
-      ],
-      "description": "A placeholder group nested in another (the second level). Same fields as PlaceholderGroup.",
-      "properties": {
-        "type": {
-          "const": "group",
-          "description": "Marks the entry as a placeholder group."
-        },
-        "composition": {
-          "$ref": "#/$defs/Composition",
-          "description": "How the group arranges its regions; see PlaceholderGroup.composition."
-        },
-        "placeholders": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/PlaceholderGroupEntry3"
-          },
-          "description": "The group's regions and nested groups, in reading order."
-        }
-      }
-    },
-    "PlaceholderGroupEntry3": {
-      "description": "An entry of a second-level group: a region (GroupedPlaceholder) or a third-level group (PlaceholderGroup3).",
-      "if": {
-        "type": "object",
-        "required": [
-          "type"
-        ],
-        "properties": {
-          "type": {
-            "const": "group"
-          }
-        }
-      },
-      "then": {
-        "$ref": "#/$defs/PlaceholderGroup3"
-      },
-      "else": {
-        "$ref": "#/$defs/GroupedPlaceholder"
-      }
-    },
-    "PlaceholderGroup3": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "type",
-        "placeholders"
-      ],
-      "description": "The innermost placeholder group (the third level): it holds regions only, never another group.",
-      "properties": {
-        "type": {
-          "const": "group",
-          "description": "Marks the entry as a placeholder group."
-        },
-        "composition": {
-          "$ref": "#/$defs/Composition",
-          "description": "How the group arranges its regions; see PlaceholderGroup.composition."
+          "description": "Content kinds the region takes: the body content kinds, and 'group' for a content group of any content. A group is also accepted where every one of its leaf kinds is.",
+          "examples": [
+            [
+              "text",
+              "list"
+            ],
+            [
+              "image",
+              "video"
+            ]
+          ]
         },
-        "placeholders": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/GroupedPlaceholder"
-          },
-          "description": "The group's regions, in reading order."
-        }
-      }
-    },
-    "GroupedPlaceholder": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "type"
-      ],
-      "description": "A region inside a placeholder group: a body content kind only. Headings ('title', 'subtitle', 'tag') stay at the record's top level, and only a top-level image placeholder may carry a placement.",
-      "properties": {
-        "type": {
+        "role": {
           "type": "string",
           "enum": [
-            "text",
-            "list",
-            "image",
-            "video",
-            "chart",
-            "table",
-            "code",
-            "metric",
-            "quote",
-            "timeline"
+            "primary",
+            "secondary",
+            "media",
+            "supporting"
           ],
-          "description": "The content kind of the region, from the one OPF content-kind vocabulary (see Placeholder.type)."
-        }
-      }
-    },
-    "Placeholder": {
-      "type": "object",
-      "required": [
-        "type"
-      ],
-      "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; every other placeholder describes the content kind that region holds. The array order in the surrounding 'placeholders' field preserves layout region order.",
-      "if": {
-        "required": [
-          "placement"
-        ]
-      },
-      "then": {
-        "properties": {
-          "type": {
-            "const": "image"
-          }
-        }
-      },
-      "properties": {
-        "type": {
+          "description": "Which content the region wants first. Binding gives a picture (image, video) to a media region first, then primary, secondary, supporting; every other kind to a primary region first, then secondary, supporting, media; of two equal regions the first in reading order fills first. A supporting region receives content only when no primary or secondary region that accepts it has room, or by a pin. Default 'primary'."
+        },
+        "flow": {
           "type": "string",
           "enum": [
-            "title",
-            "subtitle",
-            "tag",
-            "text",
-            "list",
-            "image",
-            "video",
-            "chart",
-            "table",
-            "code",
-            "metric",
-            "quote",
-            "timeline"
+            "none",
+            "grid",
+            "column",
+            "auto"
           ],
-          "description": "The content kind of the region. This is the one OPF content-kind vocabulary: the same words name a slide's payload fields (text, items, image, video, chart, table, code, metric, quote, timeline). 'title', 'subtitle' and 'tag' are the heading kinds and bind to Slide.title, Slide.subtitle and Slide.tag. 'text' holds text and bullets; 'list' holds items. 'image' is filled by an image payload and 'video' by a video payload. 'metric', 'quote', 'timeline', 'chart', 'table' and 'code' are filled by the payload of the same name; a metric region shows the metric payload with its optional label, description, unit, delta, trend and sentiment."
+          "description": "How several blocks share the region: 'none' one block fills it; 'grid' by count (1 fills, 2 side by side, 3 in a row, 4 as 2 x 2, 5 as 3 + 2, 6 as 3 x 2, 7 to 12 in four columns; rows and columns swap in a portrait region; a short last row is centred); 'column' stacked with equal heights; 'auto' a grid when every block is short and a column when any block is long (more than 6 estimated lines in its grid cell at the starting size). design.contentDirection turns every flowing region into one row or one column. Default 'auto'."
         },
-        "placement": {
-          "$ref": "#/$defs/ImagePlacement",
-          "description": "Image placeholders only. Bleeds the slide's image for this region to one slide edge, as an image block's placement does: the n-th image placeholder (counting the image regions of placeholder groups too, in reading order) places the slide's n-th top-level image (Slide.image or an image block in blocks) unless that block sets its own placement. Only a top-level image placeholder may carry a placement; a region inside a placeholder group cannot bleed to a slide edge. The headings and the other content compose in the rest of the slide."
-        }
-      }
-    },
-    "ImagePlacement": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "edge"
-      ],
-      "description": "The same object as ImagePlacement in opf.schema.json: a band along one slide edge for the image, edge to edge, with the rest of the slide left to the headings and the other content.",
-      "properties": {
-        "edge": {
+        "max": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 12,
+          "description": "Blocks the region holds on one slide. Default 1 for flow 'none' (which requires 1), else 6. Content beyond every region's room is drawn in the overflow region with the warning opf/layout-unplaced, and paginate moves it to a continuation slide."
+        },
+        "bleed": {
+          "type": "boolean",
+          "description": "The region's outer edges that lie on the content box's edge extend to the slide edge, as a placed image does. A bled region is never drawn as a card. Default false."
+        },
+        "listColumns": {
+          "oneOf": [
+            {
+              "const": "auto"
+            },
+            {
+              "const": 1
+            }
+          ],
+          "description": "'auto': a list in the region that does not fit its cell at the starting size (a lone list, or one of several blocks) flows into up to three columns before it shrinks, as a list payload's columns: 'auto'. Default 1."
+        },
+        "anchor": {
           "type": "string",
           "enum": [
-            "left",
-            "right",
             "top",
+            "middle",
             "bottom"
           ],
-          "description": "The slide edge the image bleeds to. In a right-to-left deck 'left' is the start side, drawn at the right."
+          "description": "Vertical position of the region's content when it is shorter than the region. Default 'top'."
         },
-        "size": {
-          "type": "number",
-          "minimum": 0.1,
-          "maximum": 0.9,
-          "description": "Share of the slide width (left, right) or height (top, bottom) given to the band. Default 0.5."
-        },
-        "inset": {
-          "type": "boolean",
-          "description": "Draw the frame inside the slide padding on every side of the band instead of edge to edge. Default false."
+        "empty": {
+          "type": "string",
+          "enum": [
+            "collapse",
+            "keep"
+          ],
+          "description": "What the region does on a slide that gives it no content: 'collapse' (default) joins its cells to a neighbouring area that shares the full length of one of its edges and is not itself empty; 'keep' leaves the space."
         }
       }
     },
@@ -369,7 +313,7 @@
             "center",
             "right"
           ],
-          "description": "Horizontal alignment of the title placeholder."
+          "description": "Horizontal alignment of the title heading area."
         },
         "contentAlignment": {
           "type": "string",
@@ -390,7 +334,7 @@
             "horizontal",
             "vertical"
           ],
-          "description": "Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. Composition applies it when neither the slide nor this layout's composition sets a mode, below the slide's and the deck's design.contentDirection and above automatic selection."
+          "description": "Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. On a layout slide it turns every flowing region into one row or one column; the slide's own composition.mode, columns and weights rank above it."
         },
         "chartPrimary": {
           "type": "string",
@@ -401,7 +345,7 @@
             "left",
             "right"
           ],
-          "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there. It is shorthand for a placeholder group: a record can state the same structure explicitly as a root row or column of the chart and one PlaceholderGroup of the other regions, weighted 3:2."
+          "description": "Where the primary chart sits relative to supporting content on automatic slides. Template layouts express this arrangement with their regions; chartPrimary does not override a template."
         },
         "imageFit": {
           "type": "string",
@@ -419,30 +363,18 @@
             "image"
           ],
           "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
+        },
+        "mirror": {
+          "type": "boolean",
+          "description": "Draw the layout mirrored: each row's cells and the column sizes reversed, so a 'beside' layout puts its picture, chart or table at the end. Logical: a right-to-left deck mirrors on top. Binding and reading order do not change."
         }
       }
     },
     "Composition": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Portable dynamic composition. Slide fields override the resolved layout. Nested groups (placeholder groups here, content groups in a slide) arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.",
+      "description": "A template's composition: only gap, padding, minFontSize and overflow, with their 0.18 meaning. A slide's composition overrides them; a slide's composition.mode, columns and weights arrange its first primary flowing region.",
       "properties": {
-        "mode": {
-          "type": "string",
-          "enum": [
-            "auto",
-            "grid",
-            "row",
-            "column"
-          ],
-          "description": "auto chooses a grid from available space and content; grid uses columns; row and column use one horizontal or vertical track."
-        },
-        "columns": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 12,
-          "description": "Column count for grid. In auto mode this caps the number of columns."
-        },
         "gap": {
           "type": "number",
           "minimum": 0,
@@ -455,17 +387,6 @@
           "maximum": 0.2,
           "description": "Inset as a fraction of the container short edge. Default 0.08 on a slide, 0 inside a group."
         },
-        "weights": {
-          "type": "array",
-          "minItems": 1,
-          "maxItems": 12,
-          "items": {
-            "type": "number",
-            "exclusiveMinimum": 0,
-            "maximum": 100
-          },
-          "description": "Relative track sizes: columns for row/grid/auto, rows for column. Omitted tracks have weight 1; extra weights are ignored."
-        },
         "minFontSize": {
           "type": "number",
           "minimum": 8,