@openpresentation/opf 0.2.1 → 0.3.0

package/dist/types.d.ts

@@ -1,6 +1,7 @@
-export { P as Presentation, V as ValidationIssue, a as ValidationResult } from './validator-D7WwzKyx.js';
+export { P as Presentation } from './presentation-C8BOK0-5.js';
 export { CatalogKind } from './catalogs.js';
 export { SchemaName } from './schemas.js';
+export { ValidationIssue, ValidationResult } from './validator.js';
 
 /**
  * Schema for audience records in the pptx.gallery library. Each record names an audience archetype (e.g. 'executives', 'engineering-team', 'investors') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) → catalogs.audiences.source → the default catalog at https://www.pptx.gallery/audiences. The audience field also accepts free-form strings; this catalog is for engine-aware audience archetypes that carry generation hints.

package/dist/validator.d.ts

@@ -1,3 +1,40 @@
-import './catalogs.js';
-export { O as OPFValidationError, S as SchemaOrKind, V as ValidationIssue, a as ValidationResult, b as assertValid, c as assertValidCatalogRecord, d as assertValidPresentation, v as validate, e as validateCatalogRecord, f as validatePresentation } from './validator-D7WwzKyx.js';
-import './schemas.js';
+import { CatalogKind } from './catalogs.js';
+import { SchemaName } from './schemas.js';
+import { P as Presentation } from './presentation-C8BOK0-5.js';
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+type JsonSchema = JsonObject;
+
+interface ValidationIssue {
+    path: string;
+    message: string;
+    keyword: string;
+    schemaPath: string;
+    params: Record<string, unknown>;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    /** Advisory issues such as unknown catalog ids. Warnings never affect `valid`. */
+    warnings: ValidationIssue[];
+    schemaName?: SchemaName;
+    catalogKind?: CatalogKind;
+}
+type SchemaOrKind = SchemaName | CatalogKind | JsonSchema;
+declare class OPFValidationError extends Error {
+    readonly issues: ValidationIssue[];
+    readonly result: ValidationResult;
+    constructor(result: ValidationResult);
+}
+declare function validate(value: unknown, schemaOrKind?: SchemaOrKind): ValidationResult;
+declare function assertValid<T = unknown>(value: T, schemaOrKind?: SchemaOrKind): T;
+declare function validatePresentation(value: unknown): ValidationResult;
+declare function assertValidPresentation(value: unknown): asserts value is Presentation;
+declare function validateCatalogRecord(kind: CatalogKind, value: unknown): ValidationResult;
+declare function assertValidCatalogRecord(kind: CatalogKind, value: unknown): void;
+
+export { OPFValidationError, type SchemaOrKind, type ValidationIssue, type ValidationResult, assertValid, assertValidCatalogRecord, assertValidPresentation, validate, validateCatalogRecord, validatePresentation };

package/dist/validator.js

@@ -16,6 +16,411 @@ var catalogSchemaNames = {
   fontSchemes: "fontScheme"
 };
 
+// src/generated/catalog-ids.ts
+var catalogIds = {
+  audiences: [
+    "executives",
+    "board",
+    "engineering-team",
+    "investors",
+    "customers",
+    "sales-team",
+    "marketing-team",
+    "all-hands",
+    "candidates",
+    "regulators"
+  ],
+  purposes: [
+    "inform",
+    "decide",
+    "align",
+    "persuade",
+    "educate",
+    "report",
+    "pitch",
+    "sell",
+    "plan"
+  ],
+  tones: [
+    "formal",
+    "casual",
+    "inspirational",
+    "technical",
+    "persuasive",
+    "authoritative",
+    "conversational"
+  ],
+  themes: [
+    "bold",
+    "classic",
+    "dark",
+    "minimal"
+  ],
+  layouts: [
+    "blank",
+    "chart-1x",
+    "chart-2x",
+    "chart-3x",
+    "code-1x",
+    "image-1x",
+    "image-2x",
+    "image-3x",
+    "image-bleed",
+    "list-1x",
+    "list-2x",
+    "list-3x",
+    "list-4x",
+    "list-5x",
+    "list-6x",
+    "media-1x",
+    "number-1x",
+    "number-2x",
+    "number-3x",
+    "number-4x",
+    "number-5x",
+    "number-6x",
+    "table-1x",
+    "text-1x",
+    "text-2x",
+    "text-3x",
+    "title",
+    "title-subtitle"
+  ],
+  chartTypes: [
+    "100pct-bullet-bar",
+    "100pct-bullet-bar-2x",
+    "100pct-bullet-bar-3x",
+    "100pct-bullet-column",
+    "100pct-bullet-column-2x",
+    "100pct-bullet-column-3x",
+    "100pct-progress-bar",
+    "100pct-stacked-area-2x",
+    "100pct-stacked-area-3x",
+    "100pct-stacked-bar-2x",
+    "100pct-stacked-bar-3x",
+    "100pct-stacked-column-2x",
+    "100pct-stacked-column-3x",
+    "area",
+    "australia",
+    "bar",
+    "box-and-whisker",
+    "box-and-whisker-2x",
+    "box-and-whisker-3x",
+    "bullet-bar",
+    "bullet-bar-2x",
+    "bullet-bar-3x",
+    "bullet-column",
+    "bullet-column-2x",
+    "bullet-column-3x",
+    "canada",
+    "clustered-bar-2x",
+    "clustered-column",
+    "column",
+    "dot-plot",
+    "dot-plot-2x",
+    "dot-plot-3x",
+    "dot-plot-4x",
+    "dot-plot-5x",
+    "dot-plot-6x",
+    "doughnut",
+    "dumbbell",
+    "filled-radar",
+    "funnel",
+    "histogram",
+    "line",
+    "line-2x",
+    "line-3x",
+    "line-with-high-low",
+    "line-with-high-low-and-markers",
+    "line-with-markers",
+    "line-with-markers-2x",
+    "line-with-markers-3x",
+    "pareto",
+    "pie",
+    "radar",
+    "radar-with-markers",
+    "scatter",
+    "sparkline",
+    "sparkline-2x",
+    "sparkline-3x",
+    "sparkline-4x",
+    "sparkline-5x",
+    "sparkline-6x",
+    "stacked-area-2x",
+    "stacked-area-3x",
+    "stacked-bar-2x",
+    "stacked-bar-3x",
+    "stacked-column-2x",
+    "stacked-column-3x",
+    "stacked-line-2x",
+    "stacked-line-3x",
+    "stacked-line-with-markers-2x",
+    "stacked-line-with-markers-3x",
+    "treemap",
+    "treemap-2x",
+    "treemap-3x",
+    "united-kingdom",
+    "united-states",
+    "waterfall",
+    "world"
+  ],
+  narratives: [
+    "problem-solution",
+    "scqa",
+    "strategic-narrative",
+    "golden-circle",
+    "conference-talk",
+    "transformation-arc",
+    "pitch-deck",
+    "early-startup-pitch",
+    "venture-pitch",
+    "persuasive-sales",
+    "company-intro",
+    "marketing-strategy",
+    "product-launch",
+    "strategic-advisory",
+    "challenge-resolution",
+    "project-proposal",
+    "failure-analysis",
+    "classic-story",
+    "business-narrative",
+    "rags-to-riches",
+    "underdog-victory",
+    "survival-story",
+    "educate",
+    "persuade",
+    "reveal",
+    "justice",
+    "innovation",
+    "focus",
+    "qbr",
+    "business-review",
+    "board-meeting",
+    "weekly-progress",
+    "status-update",
+    "performance-review",
+    "survey-analysis",
+    "trend-analysis",
+    "employee-review",
+    "performance-improvement-plan",
+    "capacity-planning"
+  ],
+  socialPlatforms: [
+    "linkedin",
+    "x",
+    "github",
+    "youtube",
+    "instagram",
+    "facebook",
+    "tiktok",
+    "threads",
+    "mastodon",
+    "bluesky"
+  ],
+  languages: [
+    "afrikaans",
+    "albanian",
+    "amharic",
+    "arabic",
+    "armenian",
+    "aymara",
+    "azerbaijani",
+    "bengali",
+    "berber-latin",
+    "bosnian-latin",
+    "bulgarian",
+    "catalan",
+    "cebuano",
+    "chinese-simplified",
+    "chinese-traditional",
+    "chittagonian",
+    "croatian",
+    "czech",
+    "danish",
+    "dutch",
+    "english",
+    "english-au",
+    "english-ca",
+    "english-gb",
+    "english-in",
+    "english-us",
+    "estonian",
+    "filipino",
+    "finnish",
+    "french",
+    "fulfulde",
+    "galician",
+    "georgian",
+    "german",
+    "greek",
+    "gujarati",
+    "hausa",
+    "hebrew",
+    "hindi",
+    "hungarian",
+    "igbo",
+    "indonesian",
+    "italian",
+    "japanese",
+    "kannada",
+    "kazakh",
+    "khmer",
+    "kinyarwanda",
+    "korean",
+    "kurmanji",
+    "latvian",
+    "lithuanian",
+    "macedonian",
+    "malagasy",
+    "malay",
+    "malayalam",
+    "maori",
+    "marathi",
+    "mongolian",
+    "nepali",
+    "norwegian",
+    "odia",
+    "oromo",
+    "pashto",
+    "persian",
+    "polish",
+    "portuguese",
+    "punjabi-gurmukhi",
+    "punjabi-shahmukhi",
+    "romanian",
+    "russian",
+    "serbian-cyrillic",
+    "serbian-latin",
+    "shona",
+    "slovak",
+    "slovenian",
+    "somali",
+    "spanish",
+    "swahili",
+    "swedish",
+    "tagalog",
+    "tajik",
+    "tamil",
+    "telugu",
+    "thai",
+    "turkish",
+    "ukrainian",
+    "urdu",
+    "uzbek-latin",
+    "vietnamese-quoc-ngu",
+    "xhosa",
+    "yoruba",
+    "zulu"
+  ],
+  colorSchemes: [
+    "black-and-white",
+    "bold-red",
+    "boost",
+    "burnt-orange",
+    "cool-horizon",
+    "corporate-blue",
+    "deep-purple",
+    "forest-green",
+    "golden-yellow",
+    "luxury",
+    "pastel-red",
+    "slate-gray",
+    "steel-blue",
+    "vibes"
+  ],
+  fontSchemes: [
+    "angsana-new",
+    "aparajita",
+    "aptos",
+    "arabic-typesetting",
+    "arial",
+    "batang",
+    "bookman",
+    "calibri",
+    "century-schoolbook",
+    "consolas",
+    "constantia",
+    "courier-new",
+    "daunpenh",
+    "david",
+    "dilleniaupc",
+    "fangsong",
+    "garamond",
+    "gautami",
+    "georgia",
+    "gisha",
+    "grandview",
+    "gungsuh",
+    "impact",
+    "kalinga",
+    "kartika",
+    "khmer-ui",
+    "latha",
+    "lucida-sans",
+    "malgun-gothic",
+    "mangal",
+    "meiryo",
+    "microsoft-jhenghei",
+    "microsoft-yahei",
+    "mingliu",
+    "miriam",
+    "montserrat",
+    "ms-mincho",
+    "nirmala-ui",
+    "noto-naksh-arabic",
+    "noto-nastaliq-urdu",
+    "noto-sans",
+    "noto-sans-arabic",
+    "noto-sans-armenian",
+    "noto-sans-bengali",
+    "noto-sans-devangari",
+    "noto-sans-ethiopic",
+    "noto-sans-georgian",
+    "noto-sans-gujarati",
+    "noto-sans-gurmukhi",
+    "noto-sans-hebrew",
+    "noto-sans-jp",
+    "noto-sans-kannada",
+    "noto-sans-khmer",
+    "noto-sans-kr",
+    "noto-sans-malayalam",
+    "noto-sans-mongolian",
+    "noto-sans-oriya",
+    "noto-sans-sc",
+    "noto-sans-tamil",
+    "noto-sans-tc",
+    "noto-sans-telugu",
+    "noto-sans-thai",
+    "nyala",
+    "open-sans",
+    "pmingliu",
+    "poppins",
+    "pt-serif",
+    "raavi",
+    "raleway",
+    "roboto",
+    "rockwell",
+    "sakkal-majalla",
+    "seaford",
+    "segoe-ui",
+    "segoe-ui-light",
+    "shonar-bangla",
+    "shruti",
+    "simsun",
+    "skeena",
+    "sylfaen",
+    "tahoma",
+    "tenorite",
+    "times-new-roman",
+    "traditional-arabic",
+    "trebuchet-ms",
+    "tunga",
+    "verdana",
+    "vrinda",
+    "yu-gothic"
+  ]
+};
+
 // src/generated/schemas.ts
 var presentation = {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -110,20 +515,29 @@ var presentation = {
       ]
     },
     "audience": {
-      "type": "array",
-      "items": {
-        "oneOf": [
-          {
-            "type": "string"
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "$ref": "#/$defs/Audience"
+              }
+            ]
           },
-          {
-            "$ref": "#/$defs/Audience"
-          }
-        ]
-      },
-      "minItems": 1,
-      "description": "Intended audiences for the presentation. Each item accepts either:\n- A string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executives'), an HTTPS URL, or a 'pkg:' reference.\n- An inline Audience object for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.audiences.records[] \u2192 catalogs.audiences.source \u2192 default catalog at https://www.pptx.gallery/audiences.",
+          "minItems": 1
+        }
+      ],
+      "description": "Intended audiences for the presentation. Accepts either:\n- A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executives'), an HTTPS URL, or a 'pkg:' reference.\n- An array of string shorthands and/or inline Audience objects for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.audiences.records[] \u2192 catalogs.audiences.source \u2192 default catalog at https://www.pptx.gallery/audiences.",
       "examples": [
+        "executives",
+        "Biology Students and Wildlife Enthusiasts",
         [
           "executives"
         ],
@@ -2478,7 +2892,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "items": {
             "$ref": "#/$defs/ListItem"
           },
-          "description": "Full-slide generic list payload. Presence of this field infers type 'list'."
+          "description": "Full-slide generic list payload. Presence of this field infers type 'list'. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for layout-agnostic blocks."
         },
         "bullets": {
           "type": "array",
@@ -2548,7 +2962,7 @@ Resolution order: inline catalogs.fontSchemes.records[] -> catalogs.fontSchemes.
           "items": {
             "$ref": "#/$defs/ContentPayload"
           },
-          "description": "Layout-agnostic content blocks rendered together as a composed payload when exact placement is unspecified."
+          "description": "Layout-agnostic content blocks rendered together as a composed payload when exact placement is unspecified. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for equivalent blocks."
         },
         "design": {
           "$ref": "#/$defs/Design",
@@ -6484,6 +6898,12 @@ function inferredKinds(value) {
   if (hasOwn(value, "timeline")) kinds.push("timeline");
   return kinds;
 }
+function isImplicitBlocksComposition(value, inferred, options) {
+  if (options.allowBlocks !== true || hasOwn(value, "blocks")) {
+    return false;
+  }
+  return inferred.length > 1;
+}
 function validateContentPayload(value, path, options = {}) {
   const issues = [];
   const explicitType = value.type;
@@ -6510,6 +6930,9 @@ function validateContentPayload(value, path, options = {}) {
     return issues;
   }
   if (!kind && inferred.length > 1) {
+    if (isImplicitBlocksComposition(value, inferred, options)) {
+      return issues;
+    }
     issues.push(semanticIssue(path, "content payload mixes fields from incompatible content types", {
       inferredTypes: inferred
     }));
@@ -6642,6 +7065,126 @@ function validatePresentationSemantics(value) {
   });
   return issues;
 }
+var bareIdPattern = /^[a-z0-9][a-z0-9-]*$/;
+function inlineCatalogEntry(context, kind) {
+  const catalogsField = context.document.catalogs;
+  if (!isRecord(catalogsField)) {
+    return void 0;
+  }
+  const entry = catalogsField[kind];
+  return isRecord(entry) ? entry : void 0;
+}
+function unknownIdWarning(kind, value, path, context) {
+  if (typeof value !== "string" || !bareIdPattern.test(value)) {
+    return void 0;
+  }
+  if (context) {
+    const entry = inlineCatalogEntry(context, kind);
+    if (entry) {
+      if (Array.isArray(entry.records) && entry.records.some((record) => isRecord(record) && record.id === value)) {
+        return void 0;
+      }
+      if (typeof entry.source === "string") {
+        return void 0;
+      }
+    }
+  }
+  if (catalogIds[kind].includes(value)) {
+    return void 0;
+  }
+  return semanticIssue(path, `unknown ${kind} catalog id '${value}'`, { kind, id: value });
+}
+function referenceObjectWarning(kind, value, path, context) {
+  if (typeof value === "string") {
+    return unknownIdWarning(kind, value, path, context);
+  }
+  if (isRecord(value)) {
+    return unknownIdWarning(kind, value.id, pathFor(path, "id"), context);
+  }
+  return void 0;
+}
+function pushIfDefined(issues, issue) {
+  if (issue) {
+    issues.push(issue);
+  }
+}
+function designReferenceWarnings(design, path, context) {
+  if (!isRecord(design)) {
+    return [];
+  }
+  const issues = [];
+  pushIfDefined(issues, referenceObjectWarning("themes", design.theme, pathFor(path, "theme"), context));
+  pushIfDefined(issues, referenceObjectWarning("colorSchemes", design.colorScheme, pathFor(path, "colorScheme"), context));
+  pushIfDefined(issues, referenceObjectWarning("fontSchemes", design.fontScheme, pathFor(path, "fontScheme"), context));
+  if (isRecord(design.theme)) {
+    const themePath = pathFor(path, "theme");
+    pushIfDefined(issues, referenceObjectWarning("colorSchemes", design.theme.colorScheme, pathFor(themePath, "colorScheme"), context));
+    pushIfDefined(issues, referenceObjectWarning("fontSchemes", design.theme.fontScheme, pathFor(themePath, "fontScheme"), context));
+  }
+  return issues;
+}
+function chartTypeWarnings(payload, path, context) {
+  if (!isRecord(payload)) {
+    return [];
+  }
+  const issues = [];
+  if (isRecord(payload.chart)) {
+    pushIfDefined(issues, unknownIdWarning("chartTypes", payload.chart.type, `${pathFor(path, "chart")}/type`, context));
+  }
+  if (Array.isArray(payload.blocks)) {
+    payload.blocks.forEach((block, index) => {
+      issues.push(...chartTypeWarnings(block, `${pathFor(path, "blocks")}/${index}`, context));
+    });
+  }
+  return issues;
+}
+function presentationReferenceWarnings(value) {
+  if (!isRecord(value) || !Array.isArray(value.slides)) {
+    return [];
+  }
+  const context = { document: value };
+  const issues = [];
+  if (typeof value.narrative === "string") {
+    pushIfDefined(issues, unknownIdWarning("narratives", value.narrative, "/narrative", context));
+  }
+  issues.push(...designReferenceWarnings(value.design, "/design", context));
+  value.slides.forEach((slide, index) => {
+    if (!isRecord(slide)) {
+      return;
+    }
+    const slidePath = `/slides/${index}`;
+    issues.push(...designReferenceWarnings(slide.design, pathFor(slidePath, "design"), context));
+    issues.push(...chartTypeWarnings(slide, slidePath, context));
+    for (const key of Object.keys(slide)) {
+      if (promotedRegionKeySet.has(key)) {
+        issues.push(...chartTypeWarnings(slide[key], pathFor(slidePath, key), context));
+      }
+    }
+  });
+  return issues;
+}
+var catalogCrossLinkFields = {
+  audience: { recommendedNarratives: "narratives", recommendedTones: "tones" },
+  purpose: { recommendedNarratives: "narratives", recommendedTones: "tones" },
+  tone: { recommendedNarratives: "narratives" }
+};
+function catalogCrossLinkWarnings(schemaName, value) {
+  const fields = catalogCrossLinkFields[schemaName];
+  if (!fields || !isRecord(value)) {
+    return [];
+  }
+  const issues = [];
+  for (const [field, kind] of Object.entries(fields)) {
+    const links = value[field];
+    if (!Array.isArray(links)) {
+      continue;
+    }
+    links.forEach((link, index) => {
+      pushIfDefined(issues, unknownIdWarning(kind, link, `${pathFor("/", field)}/${index}`));
+    });
+  }
+  return issues;
+}
 function validateLanguageSemantics(value) {
   if (!isRecord(value)) {
     return [];
@@ -6657,14 +7200,20 @@ function validate(value, schemaOrKind = "presentation") {
   const resolved = resolveValidator(schemaOrKind);
   const valid = resolved.validate(value) === true;
   const errors = valid ? [] : (resolved.validate.errors ?? []).map(toIssue);
+  const warnings = [];
   if (resolved.schemaName === "presentation") {
     errors.push(...validatePresentationSemantics(value));
+    warnings.push(...presentationReferenceWarnings(value));
   } else if (resolved.schemaName === "language") {
     errors.push(...validateLanguageSemantics(value));
   }
+  if (resolved.schemaName) {
+    warnings.push(...catalogCrossLinkWarnings(resolved.schemaName, value));
+  }
   return {
     valid: errors.length === 0,
     errors,
+    warnings,
     schemaName: resolved.schemaName,
     catalogKind: resolved.catalogKind
   };