@openpresentation/opf 0.12.2 → 0.14.0

package/dist/spec/catalogs/narratives/what-so-what-now-what.json

@@ -9,9 +9,9 @@
     "senior-managers",
     "board"
   ],
-  "durationRange": {
-    "minMinutes": 5,
-    "maxMinutes": 15
+  "duration": {
+    "min": 5,
+    "max": 15
   },
   "tags": [
     "executive",
@@ -25,24 +25,24 @@
       "name": "What",
       "description": "Present the facts, data, or findings objectively and clearly.",
       "instructions": "Present the facts, data, or findings objectively and clearly.",
-      "slideType": "chart",
-      "layoutHint": "chart-1x"
+      "type": "chart",
+      "layout": "chart-1x"
     },
     {
       "id": "so-what",
       "name": "So What",
       "description": "Explain the significance. Why should your audience care about this information?",
       "instructions": "Explain the significance. Why should your audience care about this information?",
-      "slideType": "metric",
-      "layoutHint": "number-2x"
+      "type": "metric",
+      "layout": "number-2x"
     },
     {
       "id": "now-what",
       "name": "Now What",
       "description": "Define the action required. What decisions or next steps follow from this?",
       "instructions": "Define the action required. What decisions or next steps follow from this?",
-      "slideType": "text",
-      "layoutHint": "title"
+      "type": "text",
+      "layout": "title"
     }
   ]
 }

package/dist/spec/openapi.yaml

@@ -506,11 +506,8 @@ components:
           additionalProperties: true
           description: Optional per-kind catalog overrides (inline records and/or a non-default source).
         narrative:
-          description: Structured storyline. A bare catalog id string, or an inline narrative object.
-          oneOf:
-            - type: string
-            - type: object
-              additionalProperties: true
+          description: Narrative plan by reference. A catalog id, an HTTPS URL or a `pkg:` reference; a custom narrative is a record in `catalogs.narratives.records`.
+          type: string
         audience:
           description: Intended audience(s). A string shorthand, or an array of strings/inline audience objects.
           oneOf:

package/dist/spec/reference/engine-defaults.json

@@ -27,8 +27,8 @@
   },
 
   "chartTypes": [
-    "stacked-column-3x",
-    "stacked-area-3x",
+    "stacked-column",
+    "stacked-area",
     "line-with-markers"
   ]
 }

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

@@ -118,7 +118,7 @@
     "attentionBudgetMinutes": {
       "type": "number",
       "exclusiveMinimum": 0,
-      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's durationRange."
+      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's duration range."
     },
     "recommendedNarratives": {
       "type": "array",

package/dist/spec/schemas/catalog-index.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "title": "Catalog Index",
-  "description": "Generic shape shared by every `spec/catalogs/<kind>/index.json` file in the OPF repo and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (spec/catalogs is a pinned snapshot of that catalog; see docs/default-catalog.md). An index is a lightweight, ordered summary of the full-record JSON files that live alongside it: each entry names the record's stable id, a human-readable name, and the record's filename, plus whatever extra summary fields are useful for picker UIs (e.g. `summary`, `tags`, `bcp47`, `durationRange`). This schema describes catalog index files themselves, not OPF documents or individual catalog records — it is not part of the OPF document contract and is intentionally excluded from the package's published/typed schema surface.",
+  "description": "Generic shape shared by every `spec/catalogs/<kind>/index.json` file in the OPF repo and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (spec/catalogs is a pinned snapshot of that catalog; see docs/default-catalog.md). An index is a lightweight, ordered summary of the full-record JSON files that live alongside it: each entry names the record's stable id, a human-readable name, and the record's filename, plus whatever extra summary fields are useful for picker UIs (e.g. `summary`, `tags`, `bcp47`, `duration`). This schema describes catalog index files themselves, not OPF documents or individual catalog records — it is not part of the OPF document contract and is intentionally excluded from the package's published/typed schema surface.",
   "type": "object",
   "required": ["$schema", "version", "description", "records"],
   "additionalProperties": false,
@@ -56,7 +56,7 @@
   "$defs": {
     "IndexRecord": {
       "type": "object",
-      "description": "Lightweight summary of one catalog record. Additional per-kind fields (e.g. `summary`, `tags`, `bcp47`, `durationRange`, `group`, `label`) are allowed and vary by catalog kind.",
+      "description": "Lightweight summary of one catalog record. Additional per-kind fields (e.g. `summary`, `tags`, `bcp47`, `duration`, `group`, `label`) are allowed and vary by catalog kind.",
       "required": ["id", "name", "file"],
       "additionalProperties": true,
       "properties": {

package/dist/spec/schemas/chart-type.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
   "title": "Chart Type",
-  "description": "Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType). Each record describes a named chart variant, its Open XML mapping, its series/category cardinality, the column structure of the underlying workbook, and a small sample dataset suitable for previews. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.",
+  "description": "Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType), plus the column-and-line combination 'combo' (mappings.openxml.composition \"mixed\"). Each record names a chart variant, its Open XML mapping, how many data series it expects and how pickers group it. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.",
   "type": "object",
   "additionalProperties": false,
   "patternProperties": {
@@ -25,29 +25,19 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this chart type. Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.",
+      "description": "Stable slug used by OPF documents to reference this chart type (`chart.type`). Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.",
       "examples": [
         "column",
         "bar",
-        "stacked-column-3x",
+        "stacked-column",
         "doughnut",
         "treemap",
-        "100pct-stacked-column-3x"
+        "100pct-stacked-column"
       ]
     },
     "name": {
       "type": "string",
-      "description": "Stable display/programmatic name for this chart type.",
-      "examples": [
-        "COLUMN",
-        "STACKED_COLUMN_3X",
-        "DOUGHNUT",
-        "TREEMAP"
-      ]
-    },
-    "label": {
-      "type": "string",
-      "description": "Human-readable label shown in chart pickers.",
+      "description": "Human-readable name of the chart type, as a chart picker shows it.",
       "examples": [
         "Column",
         "Stacked Column",
@@ -60,14 +50,14 @@
       "description": "One-sentence positioning: when to reach for this chart variant.",
       "examples": [
         "Single-series vertical column chart for comparing values across categories.",
-        "Bullet chart that benchmarks one value against ranked threshold bands."
+        "Stacked column chart that shows how the parts of each category add up to its total."
       ]
     },
     "description": {
       "type": "string",
       "description": "Longer prose describing the chart and ideal use cases.",
       "examples": [
-        "Use a clustered column when you want to compare a small number of series across the same categories — e.g., revenue by quarter for two product lines. Best with 2–4 series and ≤12 categories."
+        "Use a stacked column when you want to compare totals across categories and also show how each series contributes — e.g., revenue by quarter split by product line. Best with 2–4 series and ≤12 categories."
       ]
     },
     "mappings": {
@@ -76,11 +66,11 @@
     },
     "deprecation": {
       "$ref": "#/$defs/ChartTypeDeprecation",
-      "description": "Present when this chart type is deprecated. Deprecated records stay resolvable so existing documents keep validating, but pickers and default listings exclude them, validators warn when a document references them, and they are removed in the release named by `removal`."
+      "description": "Present when this chart type is deprecated. A deprecated record stays resolvable so existing documents keep validating, validators warn when a document references it, and pickers and generators should not offer it. The bundled default catalog holds no deprecated records; a publisher or an inline `catalogs.chartTypes.records` entry can still use the field."
     },
     "group": {
       "type": "string",
-      "description": "Top-level grouping in the chart picker (column, bar, line, area, pie, radar, etc.).",
+      "description": "Top-level grouping in the chart picker.",
       "examples": [
         "Column",
         "Bar",
@@ -91,9 +81,8 @@
         "Histogram",
         "XY (Scatter)",
         "Treemap",
-        "Bullet",
-        "Sparkline",
         "Map",
+        "Combo",
         "Other"
       ]
     },
@@ -115,155 +104,18 @@
         "hierarchical",
         "normalized"
       ],
-      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized')."
+      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data."
     },
     "series": {
       "type": "integer",
       "minimum": 0,
-      "description": "Number of data series this chart type expects.",
-      "examples": [
-        1,
-        2,
-        3,
-        4
-      ]
-    },
-    "categories": {
-      "type": "integer",
-      "minimum": 0,
-      "description": "Number of category labels this chart type expects on the primary axis.",
-      "examples": [
-        4,
-        6,
-        8,
-        12
-      ]
-    },
-    "seriesGroups": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Number of series groups (axis bands) this chart type uses; >1 for combo or banded charts.",
+      "description": "Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.",
       "examples": [
         1,
         2,
         3
       ]
     },
-    "useSecondaryCategories": {
-      "type": "boolean",
-      "description": "Whether the chart type uses a secondary category axis.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "workbookRange": {
-      "type": "string",
-      "description": "A1 reference to the source range in the embedded workbook.",
-      "examples": [
-        "Sheet1!$A$1:$I$2",
-        "Sheet1!$A$1:$G$3"
-      ]
-    },
-    "columns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Column header names of the embedded workbook, in left-to-right order.",
-      "examples": [
-        [
-          "Series 1",
-          "Value"
-        ],
-        [
-          "Series 1",
-          "Value 1",
-          "Value 2"
-        ]
-      ]
-    },
-    "dataColumns": {
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/ChartDataColumn"
-      },
-      "description": "Per-column metadata describing the role and position of each column in the workbook source.",
-      "examples": [
-        [
-          {
-            "name": "Series 1",
-            "role": "categoryLabel",
-            "type": "string",
-            "position": "row0_col0"
-          },
-          {
-            "name": "Value 1",
-            "role": "series",
-            "type": "number",
-            "position": "row1_col0"
-          },
-          {
-            "name": "Value 2",
-            "role": "series",
-            "type": "number",
-            "position": "row2_col0"
-          }
-        ]
-      ]
-    },
-    "helperColumns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Optional auxiliary column names used by calculated or banded charts (e.g., 'Excellent', 'Good', 'Fair', 'Poor' for a bullet chart).",
-      "examples": [
-        [
-          "Excellent",
-          "Good",
-          "Fair",
-          "Poor"
-        ],
-        [
-          "Band"
-        ]
-      ]
-    },
-    "sampleData": {
-      "$ref": "#/$defs/ChartSampleData",
-      "description": "Inline sample dataset for previews and pickers.",
-      "examples": [
-        {
-          "headers": [
-            "Series 1",
-            "Q1 2024",
-            "Q2 2024",
-            "Q3 2024",
-            "Q4 2024"
-          ],
-          "rows": [
-            [
-              "Value",
-              93810,
-              24592,
-              13278,
-              46048
-            ]
-          ]
-        }
-      ]
-    },
-    "slideNumber": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Source slide number in the original chart-gallery deck. Carried for traceability.",
-      "examples": [
-        1,
-        2,
-        48
-      ]
-    },
     "tags": {
       "type": "array",
       "items": {
@@ -276,9 +128,8 @@
           "comparison"
         ],
         [
-          "bullet",
-          "kpi",
-          "benchmark"
+          "stacked",
+          "composition"
         ]
       ]
     },
@@ -291,7 +142,7 @@
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.png"
+            "https://www.pptx.gallery/chart-types/column.png"
           ]
         },
         "thumbnailSrc": {
@@ -299,7 +150,7 @@
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.thumbnail.png"
+            "https://www.pptx.gallery/chart-types/column.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -307,7 +158,7 @@
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.svg"
+            "https://www.pptx.gallery/chart-types/column.svg"
           ]
         }
       }
@@ -327,7 +178,7 @@
           "description": "Id of the non-deprecated chart type that documents should reference instead.",
           "examples": [
             "column",
-            "stacked-column-3x"
+            "stacked-column"
           ]
         },
         "reason": {
@@ -356,7 +207,7 @@
         },
         "renderers": {
           "type": "object",
-          "description": "Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the \"aspose-slides\" key, e.g. {\"aspose-slides\": {\"chartType\": \"StackedColumn\"}}.",
+          "description": "Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the \"aspose-slides\" key, e.g. {\"aspose-slides\": {\"chartType\": \"StackedColumn\"}}; a mixed composition names the ChartType it starts from and the series type it switches series to, e.g. {\"chartType\": \"ClusteredColumn\", \"lineSeriesType\": \"LineWithMarkers\"}.",
           "additionalProperties": {
             "type": "object",
             "additionalProperties": true
@@ -455,128 +306,6 @@
           "description": "Short implementation note for mappings that need renderer interpretation."
         }
       }
-    },
-    "ChartDataColumn": {
-      "type": "object",
-      "description": "One column of the embedded chart workbook, annotated with its role and grid position.",
-      "required": [
-        "name",
-        "role",
-        "type"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "Column header name (e.g. 'Series 1', 'Value', 'Level1', 'Level2').",
-          "examples": [
-            "Series 1",
-            "Value",
-            "Level1",
-            "Level2"
-          ]
-        },
-        "role": {
-          "type": "string",
-          "enum": [
-            "categoryLabel",
-            "series",
-            "helper"
-          ],
-          "description": "Role this column plays: a category label (axis tick), a series (plotted values), or a helper (calculated/auxiliary)."
-        },
-        "type": {
-          "type": "string",
-          "enum": [
-            "string",
-            "number"
-          ],
-          "description": "Cell value type for the column."
-        },
-        "position": {
-          "type": "string",
-          "pattern": "^row[0-9]+_col[0-9]+$",
-          "description": "Grid position of the column header in the source workbook, as 'row<N>_col<M>' (zero-indexed).",
-          "examples": [
-            "row0_col0",
-            "row1_col0",
-            "row2_col0"
-          ]
-        }
-      }
-    },
-    "ChartSampleData": {
-      "type": "object",
-      "description": "Inline sample dataset for previews. Mirrors a small workbook with header row plus data rows.",
-      "required": [
-        "headers",
-        "rows"
-      ],
-      "properties": {
-        "headers": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Header row labels. The first cell typically labels the series column; the rest are category labels.",
-          "examples": [
-            [
-              "Series 1",
-              "Q1 2024",
-              "Q2 2024",
-              "Q3 2024",
-              "Q4 2024",
-              "Q1 2025",
-              "Q2 2025",
-              "Q3 2025",
-              "Q4 2025"
-            ]
-          ]
-        },
-        "rows": {
-          "type": "array",
-          "items": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ]
-            }
-          },
-          "description": "Two-dimensional sample data. Each row aligns by index with the headers — first cell is the row label, remaining cells are values.",
-          "examples": [
-            [
-              [
-                "Value",
-                93810,
-                24592,
-                13278,
-                46048,
-                42098,
-                39256,
-                28289,
-                23434
-              ]
-            ],
-            [
-              [
-                "Value 1",
-                98696,
-                81482,
-                21395,
-                87397
-              ],
-              [
-                "Value 2",
-                38657,
-                40495,
-                76237,
-                88907
-              ]
-            ]
-          ]
-        }
-      }
     }
   }
 }

package/dist/spec/schemas/color-scheme.schema.json

@@ -9,6 +9,14 @@
     "id",
     "name"
   ],
+  "$defs": {
+    "HexColor": {
+      "type": "string",
+      "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+      "description": "Hex color: '#RGB', '#RRGGBB' or '#RRGGBBAA'. The same definition as HexColor in opf.schema.json.",
+      "examples": ["#fff", "#2874A6", "#0F172AFF"]
+    }
+  },
   "properties": {
     "$schema": {
       "type": "string",
@@ -73,7 +81,7 @@
       ]
     },
     "accent1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 1 color (hex). Mirrors the OOXML accent1 slot.",
       "examples": [
         "#2874A6",
@@ -82,7 +90,7 @@
       ]
     },
     "accent2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 2 color (hex). Mirrors the OOXML accent2 slot.",
       "examples": [
         "#1B4F72",
@@ -91,7 +99,7 @@
       ]
     },
     "accent3": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 3 color (hex). Mirrors the OOXML accent3 slot.",
       "examples": [
         "#5499C7",
@@ -100,7 +108,7 @@
       ]
     },
     "accent4": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 4 color (hex). Mirrors the OOXML accent4 slot.",
       "examples": [
         "#7BDBB2",
@@ -109,7 +117,7 @@
       ]
     },
     "accent5": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 5 color (hex). Mirrors the OOXML accent5 slot.",
       "examples": [
         "#3AC67A",
@@ -118,7 +126,7 @@
       ]
     },
     "accent6": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Accent 6 color (hex). Mirrors the OOXML accent6 slot.",
       "examples": [
         "#24A89E",
@@ -127,42 +135,42 @@
       ]
     },
     "dark1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 1 color (hex). Typically the deepest neutral; OOXML dark1.",
       "examples": [
         "#000000"
       ]
     },
     "dark2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Dark 2 color (hex). Secondary dark; OOXML dark2.",
       "examples": [
         "#011842"
       ]
     },
     "light1": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 1 color (hex). Typically the slide canvas; OOXML lt1.",
       "examples": [
         "#FFFFFF"
       ]
     },
     "light2": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Light 2 color (hex). Secondary light surface; OOXML lt2.",
       "examples": [
         "#F0F0F0"
       ]
     },
     "hyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Hyperlink color (hex). OOXML hlink.",
       "examples": [
         "#0563C1"
       ]
     },
     "followedHyperlink": {
-      "type": "string",
+      "$ref": "#/$defs/HexColor",
       "description": "Followed-hyperlink color (hex). OOXML folHlink.",
       "examples": [
         "#954F72"