@wocart/theme 1.6.0 → 2.1.0

package/dist/definitions.js

@@ -4,8 +4,11 @@
  * data — the validator exists so a theme's test suite fails loudly on catalog
  * bugs when the catalog is assembled.
  */
-import { instantiatePreset } from "./composition.js";
-import { checkStoredValue, onStepGrid } from "./instances.js";
+import { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, guaranteedRole, innerGuarantees, placementAllows, surfaceRules, } from "./blocks.js";
+import { instantiatePreset, surfaceCovers } from "./composition.js";
+import { conditionProblem } from "./conditions.js";
+import { COLOR_SCHEME_ID_PATTERN, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, colorSchemesProblem, styleSizeProblem, styleValueProblem, } from "./style.js";
+import { HANDLE_LIST_MAX, checkStoredValue, handleListProblem, onStepGrid } from "./instances.js";
 import { validatePageData } from "./page-data.js";
 import { RICH_TEXT_FORMATS, isRichTextDocumentShape, richTextProblem } from "./rich-text.js";
 import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
@@ -95,17 +98,27 @@ export function validateThemeDefinition(theme, options = {}) {
             addIssue(issues, "surfaces", "invalid-theme", "`surfaces` must be an array of surface declarations");
         }
         else {
-            inspectSurfaces(theme.surfaces, issues, locales);
+            inspectSurfaces(theme.surfaces, issues, locales, new Set(Object.keys(theme.components)));
         }
     }
+    if (theme.areas !== undefined)
+        inspectAreas(theme.areas, issues, locales, new Set(Object.keys(theme.components)));
     const rules = {
         contentKeys,
         catalogKeys: new Set(Object.keys(theme.components)),
         locales,
-        surfaceKeys: new Set((Array.isArray(theme.surfaces) ? theme.surfaces : [])
-            .map((surface) => (isRecord(surface) ? surface.key : undefined))
-            .filter((key) => typeof key === "string")),
+        surfaceKeys: new Set([
+            ...(Array.isArray(theme.surfaces) ? theme.surfaces : [])
+                .map((surface) => (isRecord(surface) ? surface.key : undefined))
+                .filter((key) => typeof key === "string"),
+            ...(Array.isArray(theme.areas) ? theme.areas : [])
+                .map((area) => (isRecord(area) && typeof area.key === "string" ? areaSurface(area.key) : undefined))
+                .filter((key) => key !== undefined),
+        ]),
+        style: isRecord(theme.style) ? theme.style : undefined,
     };
+    if (theme.style !== undefined)
+        inspectStyle(theme.style, issues);
     if (theme.settings !== undefined)
         inspectSettings(theme.settings, issues, rules);
     for (const [key, definition] of Object.entries(theme.components)) {
@@ -120,8 +133,12 @@ export function validateThemeDefinition(theme, options = {}) {
             addIssue(issues, `${path}.type`, "type-mismatch", `definition type "${definition.type}" must equal its catalog key "${key}"`);
         }
     }
-    // Documents and presets are read through the catalog, so they are checked
-    // once the catalog itself is sound.
+    // Block rules span components, and documents and presets are read through
+    // the catalog, so each is checked once everything before it is sound.
+    if (issues.length === 0)
+        inspectColorSchemes(theme, issues);
+    if (issues.length === 0)
+        inspectBlockRules(theme, issues);
     if (issues.length === 0)
         inspectComposition(theme, issues);
     return issues;
@@ -169,17 +186,21 @@ function inspectContent(content, issues, locales, localesDeclared) {
 }
 /** Default documents and presets, read through the (sound) catalog as a writer would. */
 function inspectComposition(theme, issues) {
-    (theme.surfaces ?? []).forEach((surface, index) => {
-        if (surface.document === undefined)
+    const documents = [
+        ...(theme.surfaces ?? []).map((surface, index) => ({ key: surface.key, document: surface.document, path: `surfaces[${index}].document` })),
+        ...(theme.areas ?? []).map((area, index) => ({ key: areaSurface(area.key), document: area.document, path: `areas[${index}].document` })),
+    ];
+    documents.forEach(({ key, document, path }) => {
+        if (document === undefined)
+            return;
+        const checked = validatePageData(theme, document);
+        if (checked.page !== null && checked.page.surface !== key) {
+            addIssue(issues, `${path}.surface`, "invalid-document", `the default document is for "${checked.page.surface}", not "${key}"`);
             return;
-        const path = `surfaces[${index}].document`;
-        const checked = validatePageData(theme, surface.document);
-        if (checked.page !== null && checked.page.surface !== surface.key) {
-            addIssue(issues, `${path}.surface`, "invalid-document", `the default document is for "${checked.page.surface}", not "${surface.key}"`);
         }
         for (const issue of checked.issues) {
-            // Content-keyed text is filled from the store's pack at render.
-            if (issue.code === "missing-required-prop")
+            // Filled at render: content-keyed text from the store's pack, required blocks by completion.
+            if (issue.code === "missing-required-prop" || issue.code === "missing-required-block")
                 continue;
             addIssue(issues, issue.path === "" ? path : `${path}.${issue.path}`, "invalid-document", issue.message);
         }
@@ -217,6 +238,9 @@ function inspectSettings(settings, issues, rules) {
     }
     const groupKeys = new Set();
     const settingKeys = new Set();
+    const allSettingKeys = new Set(settings.flatMap((group) => isRecord(group) && Array.isArray(group.fields)
+        ? group.fields.map((field) => (isRecord(field) && typeof field.key === "string" ? field.key : "")).filter((key) => key !== "")
+        : []));
     settings.forEach((group, index) => {
         const path = `settings[${index}]`;
         if (!isRecord(group)) {
@@ -239,7 +263,7 @@ function inspectSettings(settings, issues, rules) {
             addIssue(issues, `${path}.fields`, "invalid-settings", "`fields` must be an array");
             return;
         }
-        inspectFields(group.fields, path, issues, rules);
+        inspectFields(group.fields, path, issues, rules, { settings: true, siblings: allSettingKeys });
         for (const [fieldIndex, field] of group.fields.entries()) {
             if (!isRecord(field) || typeof field.key !== "string")
                 continue;
@@ -250,7 +274,38 @@ function inspectSettings(settings, issues, rules) {
         }
     });
 }
-function inspectSurfaces(surfaces, issues, locales) {
+/** The parts every page shares: kebab-case keys, once each, labelled, bounded like a surface. */
+function inspectAreas(areas, issues, locales, catalogKeys) {
+    if (!Array.isArray(areas)) {
+        addIssue(issues, "areas", "invalid-theme", "`areas` must be an array of area declarations");
+        return;
+    }
+    const keys = new Set();
+    areas.forEach((area, index) => {
+        const path = `areas[${index}]`;
+        if (!isRecord(area)) {
+            addIssue(issues, path, "invalid-theme", "an area must be { key, label, document?, required?, max? }");
+            return;
+        }
+        if (typeof area.key !== "string" || !TYPE_KEY_PATTERN.test(area.key)) {
+            addIssue(issues, `${path}.key`, "invalid-theme", "`key` must be lowercase kebab-case");
+        }
+        else if (keys.has(area.key)) {
+            addIssue(issues, `${path}.key`, "invalid-theme", `duplicate area "${area.key}"`);
+        }
+        else {
+            keys.add(area.key);
+        }
+        const labelProblem = localizedTextProblem(area.label, locales, { allowEmpty: false });
+        if (labelProblem !== null)
+            addIssue(issues, `${path}.label`, "invalid-theme", `\`label\` ${labelProblem}`);
+        if (area.document !== undefined && !isRecord(area.document)) {
+            addIssue(issues, `${path}.document`, "invalid-document", "`document` must be a page document");
+        }
+        inspectBlockBounds(area, path, issues, catalogKeys, THEME_LIMITS.sections, "invalid-theme");
+    });
+}
+function inspectSurfaces(surfaces, issues, locales, catalogKeys) {
     const seenKeys = new Set();
     surfaces.forEach((surface, index) => {
         const surfacePath = `surfaces[${index}]`;
@@ -278,6 +333,7 @@ function inspectSurfaces(surfaces, issues, locales) {
         if (surface.document !== undefined && !isRecord(surface.document)) {
             addIssue(issues, `${surfacePath}.document`, "invalid-document", "`document` must be a page document");
         }
+        inspectBlockBounds(surface, surfacePath, issues, catalogKeys, THEME_LIMITS.sections, "invalid-theme");
         if (typeof surface.key === "string" && surface.key.includes(".")) {
             const baseKey = surface.key.slice(0, surface.key.indexOf("."));
             const base = surfaces.find((candidate) => isRecord(candidate) && candidate.key === baseKey);
@@ -358,7 +414,7 @@ function inspectDefinition(definition, path, issues, rules) {
             addIssue(issues, `${path}.fields`, "invalid-field", "`fields` must be an array");
         }
         else {
-            inspectFields(definition.fields, path, issues, rules);
+            inspectFields(definition.fields, path, issues, rules, { props: true });
         }
     }
     if (definition.slots !== undefined) {
@@ -369,10 +425,178 @@ function inspectDefinition(definition, path, issues, rules) {
             inspectSlots(definition.slots, path, issues, rules.catalogKeys);
         }
     }
+    if (definition.placement !== undefined && !COMPONENT_PLACEMENTS.includes(definition.placement)) {
+        addIssue(issues, `${path}.placement`, "invalid-placement", `\`placement\` must be one of ${COMPONENT_PLACEMENTS.join(", ")}`);
+    }
+    if (definition.role !== undefined && !COMPONENT_ROLES.includes(definition.role)) {
+        addIssue(issues, `${path}.role`, "invalid-role", `\`role\` must be one of ${COMPONENT_ROLES.join(", ")}`);
+    }
+    if (definition.fixed !== undefined)
+        inspectFixed(definition.fixed, path, issues, rules);
+}
+/** The blocks a component's code places: named once each, of a type in the catalog. */
+function inspectFixed(fixed, path, issues, rules) {
+    if (!Array.isArray(fixed) || fixed.length === 0) {
+        addIssue(issues, `${path}.fixed`, "invalid-fixed", "`fixed` must be a non-empty array of fixed blocks (omit it for none)");
+        return;
+    }
+    const names = new Set();
+    fixed.forEach((block, index) => {
+        const blockPath = `${path}.fixed[${index}]`;
+        if (!isRecord(block)) {
+            addIssue(issues, blockPath, "invalid-fixed", "a fixed block must be { name, type, label? }");
+            return;
+        }
+        if (typeof block.name !== "string" || !TYPE_KEY_PATTERN.test(block.name)) {
+            addIssue(issues, `${blockPath}.name`, "invalid-fixed", "`name` must be lowercase kebab-case");
+        }
+        else if (names.has(block.name)) {
+            addIssue(issues, `${blockPath}.name`, "invalid-fixed", `duplicate fixed block "${block.name}"`);
+        }
+        else {
+            names.add(block.name);
+        }
+        if (typeof block.type !== "string" || !rules.catalogKeys.has(block.type)) {
+            addIssue(issues, `${blockPath}.type`, "invalid-fixed", `${JSON.stringify(block.type)} is not a component type in this catalog`);
+        }
+        if (block.label !== undefined) {
+            const problem = localizedTextProblem(block.label, rules.locales, { allowEmpty: false });
+            if (problem !== null)
+                addIssue(issues, `${blockPath}.label`, "invalid-fixed", `\`label\` ${problem}`);
+        }
+    });
+}
+/**
+ * A slot's or surface's `max` and `required`: whole-number bounds within the
+ * platform's cap, each required type one the catalog has and the list takes,
+ * and the minimums fitting under the cap.
+ */
+function inspectBlockBounds(holder, path, issues, catalogKeys, platformCap, code) {
+    const { max, required } = holder;
+    if (max !== undefined && !(typeof max === "number" && Number.isInteger(max) && max >= 1 && max <= platformCap)) {
+        addIssue(issues, `${path}.max`, code, `\`max\` must be a whole number from 1 to ${platformCap}`);
+    }
+    if (required === undefined)
+        return;
+    if (!Array.isArray(required) || required.length === 0) {
+        addIssue(issues, `${path}.required`, code, "`required` must be a non-empty array of { type, min?, max? } (omit it for none)");
+        return;
+    }
+    const allow = Array.isArray(holder.allow) ? holder.allow : undefined;
+    const types = new Set();
+    let minimums = 0;
+    required.forEach((entry, index) => {
+        const entryPath = `${path}.required[${index}]`;
+        if (!isRecord(entry)) {
+            addIssue(issues, entryPath, code, "a required entry must be { type, min?, max? }");
+            return;
+        }
+        if (typeof entry.type !== "string" || !catalogKeys.has(entry.type)) {
+            addIssue(issues, `${entryPath}.type`, code, `${JSON.stringify(entry.type)} is not a component type in this catalog`);
+        }
+        else if (allow !== undefined && !allow.includes(entry.type)) {
+            addIssue(issues, `${entryPath}.type`, code, `"${entry.type}" is required but not in \`allow\``);
+        }
+        else if (types.has(entry.type)) {
+            addIssue(issues, `${entryPath}.type`, code, `"${entry.type}" is required twice`);
+        }
+        else {
+            types.add(entry.type);
+        }
+        const min = entry.min ?? 1;
+        if (!(typeof min === "number" && Number.isInteger(min) && min >= 1)) {
+            addIssue(issues, `${entryPath}.min`, code, "`min` must be a whole number of at least 1");
+            return;
+        }
+        if (entry.max !== undefined && !(typeof entry.max === "number" && Number.isInteger(entry.max) && entry.max >= min)) {
+            addIssue(issues, `${entryPath}.max`, code, `\`max\` must be a whole number of at least \`min\` (${min})`);
+        }
+        minimums += min;
+    });
+    const cap = typeof max === "number" ? Math.min(max, platformCap) : holder.multiple === false ? 1 : platformCap;
+    if (minimums > cap)
+        addIssue(issues, `${path}.required`, code, `the required minimums (${minimums}) exceed what the list holds (${cap})`);
 }
-function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
+/**
+ * Rules that span components, once each one is sound: fixed and required
+ * blocks are placeable where they go, never contain themselves, nest within
+ * the platform's depth, and every product surface guarantees an order form.
+ */
+function inspectBlockRules(theme, issues) {
+    const definitionOf = (type) => (Object.hasOwn(theme.components, type) ? theme.components[type] : undefined);
+    for (const [type, definition] of Object.entries(theme.components)) {
+        for (const [index, block] of (definition.fixed ?? []).entries()) {
+            if (!placementAllows(definitionOf(block.type)?.placement, "block")) {
+                addIssue(issues, `components.${type}.fixed[${index}].type`, "invalid-fixed", `"${block.type}" is placed only as a section, not as a block`);
+            }
+        }
+        for (const [slotIndex, slot] of (definition.slots ?? []).entries()) {
+            for (const [index, entry] of (slot.required ?? []).entries()) {
+                if (!placementAllows(definitionOf(entry.type)?.placement, "block")) {
+                    addIssue(issues, `components.${type}.slots[${slotIndex}].required[${index}].type`, "invalid-slot", `"${entry.type}" is placed only as a section, not as a block`);
+                }
+            }
+        }
+    }
+    const holders = [
+        ...(theme.surfaces ?? []).map((surface, index) => ({ key: surface.key, required: surface.required, path: `surfaces[${index}]` })),
+        ...(theme.areas ?? []).map((area, index) => ({ key: areaSurface(area.key), required: area.required, path: `areas[${index}]` })),
+    ];
+    for (const holder of holders) {
+        (holder.required ?? []).forEach((entry, index) => {
+            const definition = definitionOf(entry.type);
+            const path = `${holder.path}.required[${index}].type`;
+            if (!placementAllows(definition?.placement, "section")) {
+                addIssue(issues, path, "invalid-theme", `"${entry.type}" is placed only as a block, not as a section`);
+            }
+            else if (definition?.capabilities?.surfaces !== undefined && !definition.capabilities.surfaces.some((entry) => surfaceCovers(entry, holder.key))) {
+                addIssue(issues, path, "invalid-theme", `"${entry.type}" is not available on "${holder.key}"`);
+            }
+        });
+    }
+    const depths = new Map();
+    const reported = new Set();
+    const nesting = (type, trail) => {
+        const known = depths.get(type);
+        if (known !== undefined)
+            return known;
+        const loop = trail.indexOf(type);
+        if (loop >= 0) {
+            const cycle = [...trail.slice(loop), type];
+            if (!reported.has(cycle[0])) {
+                reported.add(cycle[0]);
+                addIssue(issues, `components.${cycle[0]}`, "invalid-fixed", `fixed and required blocks contain themselves: ${cycle.join(" → ")}`);
+            }
+            return 0;
+        }
+        const definition = definitionOf(type);
+        const inner = definition === undefined ? [] : innerGuarantees(definition);
+        const depth = inner.reduce((deepest, { type: child }) => Math.max(deepest, 1 + nesting(child, [...trail, type])), 0);
+        depths.set(type, depth);
+        return depth;
+    };
+    for (const type of Object.keys(theme.components)) {
+        const depth = nesting(type, []);
+        if (depth > THEME_LIMITS.depth) {
+            addIssue(issues, `components.${type}`, "invalid-fixed", `fixed and required blocks nest ${depth} levels inside "${type}"; at most ${THEME_LIMITS.depth}`);
+        }
+    }
+    if (issues.length > 0)
+        return;
+    (theme.surfaces ?? []).forEach((surface, index) => {
+        if (surface.pageType !== "product")
+            return;
+        const rules = surfaceRules(theme, surface.key);
+        const guaranteed = (rules.required ?? []).reduce((count, entry) => count + (entry.min ?? 1) * guaranteedRole(theme, entry.type, "order-form"), 0);
+        if (guaranteed === 0) {
+            addIssue(issues, `surfaces[${index}]`, "order-form-not-guaranteed", `product surface "${surface.key}" must always render an order form: require a section that places a component with role "order-form" through fixed or required blocks`);
+        }
+    });
+}
+function inspectFields(fields, path, issues, rules, { inList = false, props = false, settings = false, siblings, } = {}) {
     const { contentKeys, locales } = rules;
     const seenKeys = new Set();
+    const siblingKeys = new Set(fields.map((field) => (isRecord(field) && typeof field.key === "string" ? field.key : "")).filter((key) => key !== ""));
     fields.forEach((field, index) => {
         const fieldPath = `${path}.fields[${index}]`;
         if (!isRecord(field)) {
@@ -396,6 +620,9 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
         else if (field.key === "__proto__") {
             addIssue(issues, `${fieldPath}.key`, "invalid-field", "`__proto__` cannot be a field key: as a prop name it would set a prototype");
         }
+        else if (props && field.key === "blocks") {
+            addIssue(issues, `${fieldPath}.key`, "invalid-field", "`blocks` cannot be a field key: the renderer gives every component its blocks under that prop");
+        }
         else if (seenKeys.has(field.key)) {
             addIssue(issues, `${fieldPath}.key`, "duplicate-field-key", `duplicate field key "${field.key}"`);
         }
@@ -415,6 +642,11 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
         if (field.required !== undefined && typeof field.required !== "boolean") {
             addIssue(issues, `${fieldPath}.required`, "invalid-field", "`required` must be a boolean");
         }
+        if (field.visibleIf !== undefined) {
+            const problem = conditionProblem(field.visibleIf, siblings ?? siblingKeys, typeof field.key === "string" ? field.key : "");
+            if (problem !== null)
+                addIssue(issues, `${fieldPath}.visibleIf`, "invalid-field", `\`visibleIf\` ${problem}`);
+        }
         switch (field.kind) {
             case "text":
             case "textarea": {
@@ -456,6 +688,12 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
                 if (field.step !== undefined && !(typeof field.step === "number" && Number.isFinite(field.step) && field.step > 0)) {
                     addIssue(issues, `${fieldPath}.step`, "invalid-field", "`step` must be a finite number greater than 0");
                 }
+                if (field.display !== undefined && field.display !== "input" && field.display !== "slider") {
+                    addIssue(issues, `${fieldPath}.display`, "invalid-field", "`display` must be input or slider");
+                }
+                else if (field.display === "slider" && (field.min === undefined || field.max === undefined || field.step === undefined)) {
+                    addIssue(issues, `${fieldPath}.display`, "invalid-field", "a slider needs `min`, `max` and `step`");
+                }
                 // A default outside the declared bounds would sail through assembly
                 // and then behave incoherently at runtime (`resolveInstance` trusts
                 // authored defaults while rejecting the same out-of-range instance
@@ -492,6 +730,9 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
                     (typeof field.default !== "string" || !options.includes(field.default))) {
                     addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be one of `options`");
                 }
+                if (field.display !== undefined && !["dropdown", "radio", "segmented"].includes(field.display)) {
+                    addIssue(issues, `${fieldPath}.display`, "invalid-field", "`display` must be dropdown, radio or segmented");
+                }
                 if (field.optionLabels !== undefined) {
                     if (!isRecord(field.optionLabels)) {
                         addIssue(issues, `${fieldPath}.optionLabels`, "invalid-field", "`optionLabels` must map options to labels");
@@ -550,6 +791,56 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
                     inspectListField(field, fieldPath, issues, rules);
                 break;
             }
+            case "style": {
+                const panels = field.panels;
+                if (!Array.isArray(panels) || panels.length === 0 || !panels.every((panel) => STYLE_PANELS.includes(panel))) {
+                    addIssue(issues, `${fieldPath}.panels`, "invalid-field", `\`panels\` must be a non-empty array of ${STYLE_PANELS.join(", ")}`);
+                }
+                else if (new Set(panels).size !== panels.length) {
+                    addIssue(issues, `${fieldPath}.panels`, "invalid-field", "`panels` names a panel twice");
+                }
+                else if (field.default !== undefined) {
+                    const problem = styleValueProblem(panels, field.default) ?? styleSizeProblem(rules.style, field.default);
+                    if (problem !== null)
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${problem}`);
+                }
+                break;
+            }
+            case "productList":
+            case "collectionList": {
+                for (const bound of ["min", "max"]) {
+                    const value = field[bound];
+                    const least = bound === "max" ? 1 : 0;
+                    if (value !== undefined && !(typeof value === "number" && Number.isInteger(value) && value >= least && value <= HANDLE_LIST_MAX)) {
+                        addIssue(issues, `${fieldPath}.${bound}`, "invalid-field", `\`${bound}\` must be a whole number from ${least} to ${HANDLE_LIST_MAX}`);
+                    }
+                }
+                if (typeof field.min === "number" && typeof field.max === "number" && field.min > field.max) {
+                    addIssue(issues, fieldPath, "invalid-field", "`min` must be <= `max`");
+                }
+                if (field.default !== undefined) {
+                    const problem = handleListProblem(field.kind, field.min, field.max, field.default);
+                    if (problem !== null)
+                        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${problem}`);
+                }
+                break;
+            }
+            case "colorScheme": {
+                if (field.default !== undefined && (typeof field.default !== "string" || !COLOR_SCHEME_ID_PATTERN.test(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a color scheme id");
+                }
+                break;
+            }
+            case "colorSchemes": {
+                if (!settings) {
+                    addIssue(issues, `${fieldPath}.kind`, "invalid-field", "a `colorSchemes` field holds the store's schemes: it belongs in the theme's settings");
+                    break;
+                }
+                const problem = colorSchemesProblem(field.default);
+                if (problem !== null)
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` (the theme's schemes) ${problem}`);
+                break;
+            }
             case "url": {
                 if (field.default !== undefined &&
                     (typeof field.default !== "string" || !isSafeLinkTarget(field.default))) {
@@ -562,6 +853,71 @@ function inspectFields(fields, path, issues, rules, { inList = false } = {}) {
         }
     });
 }
+/** The sizes a theme gives the platform's style steps and widths: whole pixels, within reason. */
+function inspectStyle(style, issues) {
+    if (!isRecord(style)) {
+        addIssue(issues, "style", "invalid-theme", "`style` must be { spacing?, widths? }");
+        return;
+    }
+    const scales = [
+        ["spacing", STYLE_STEPS, 0, 1024],
+        ["widths", STYLE_WIDTHS, 160, 4096],
+    ];
+    for (const key of Object.keys(style)) {
+        if (!scales.some(([name]) => name === key))
+            addIssue(issues, `style.${key}`, "invalid-theme", `"${key}" is not a style scale (spacing, widths)`);
+    }
+    for (const [name, keys, min, max] of scales) {
+        const scale = style[name];
+        if (scale === undefined)
+            continue;
+        if (!isRecord(scale)) {
+            addIssue(issues, `style.${name}`, "invalid-theme", `\`${name}\` must map ${keys.join(", ")} to pixels`);
+            continue;
+        }
+        for (const [key, size] of Object.entries(scale)) {
+            if (!keys.includes(key)) {
+                addIssue(issues, `style.${name}.${key}`, "invalid-theme", `"${key}" is not one of ${keys.join(", ")}`);
+            }
+            else if (!(typeof size === "number" && Number.isInteger(size) && size >= min && size <= max)) {
+                addIssue(issues, `style.${name}.${key}`, "invalid-theme", `must be a whole number of pixels from ${min} to ${max}`);
+            }
+        }
+    }
+}
+/**
+ * The store's color schemes and what picks them: at most one `colorSchemes`
+ * setting, which every `colorScheme` field needs, and whose schemes include
+ * each picker's default.
+ */
+function inspectColorSchemes(theme, issues) {
+    const holders = [];
+    (theme.settings ?? []).forEach((group, groupIndex) => group.fields.forEach((field, index) => {
+        if (field.kind === "colorSchemes")
+            holders.push({ path: `settings[${groupIndex}].fields[${index}]`, ids: new Set(field.default.map((scheme) => scheme.id)) });
+    }));
+    for (const extra of holders.slice(1))
+        addIssue(issues, extra.path, "invalid-settings", "a theme has at most one `colorSchemes` setting");
+    const ids = holders[0]?.ids;
+    const pickers = [];
+    const collect = (fields, path) => fields.forEach((field, index) => {
+        if (field.kind === "colorScheme")
+            pickers.push({ path: `${path}.fields[${index}]`, default: field.default });
+        if (field.kind === "list")
+            collect(field.fields, `${path}.fields[${index}]`);
+    });
+    for (const [type, definition] of Object.entries(theme.components))
+        collect(definition.fields ?? [], `components.${type}`);
+    (theme.settings ?? []).forEach((group, index) => collect(group.fields, `settings[${index}]`));
+    for (const picker of pickers) {
+        if (ids === undefined) {
+            addIssue(issues, picker.path, "invalid-field", "a `colorScheme` field needs the theme's `colorSchemes` setting");
+        }
+        else if (picker.default !== undefined && !ids.has(picker.default)) {
+            addIssue(issues, `${picker.path}.default`, "invalid-field", `"${picker.default}" is not one of the theme's color schemes`);
+        }
+    }
+}
 /** Preset shapes; what they build is checked once the catalog is sound (`inspectComposition`). */
 function inspectPresets(presets, path, issues, rules) {
     if (!Array.isArray(presets)) {
@@ -621,27 +977,40 @@ function inspectRichTextField(field, fieldPath, issues, locales) {
             formats = declared.filter((format) => RICH_TEXT_FORMATS.includes(format));
         }
     }
+    if (field.inline !== undefined && typeof field.inline !== "boolean") {
+        addIssue(issues, `${fieldPath}.inline`, "invalid-field", "`inline` must be a boolean");
+    }
+    else if (field.inline === true && (formats ?? RICH_TEXT_FORMATS).some((format) => format === "heading" || format === "list")) {
+        addIssue(issues, `${fieldPath}.formats`, "invalid-field", "an inline field is one line: list `formats` without `heading` or `list`");
+    }
     if (field.default === undefined)
         return;
     const value = field.default;
+    const before = issues.length;
     if (isRichTextDocumentShape(value)) {
         const problem = richTextProblem(value, formats);
         if (problem !== null)
             addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${problem}`);
-        return;
     }
-    if (!isLocaleMapOf(value, isRecord)) {
+    else if (!isLocaleMapOf(value, isRecord)) {
         addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a rich-text document or a map from language tags to documents");
         return;
     }
-    for (const [locale, document] of Object.entries(value)) {
-        const problem = richTextProblem(document, formats);
-        if (problem !== null)
-            addIssue(issues, `${fieldPath}.default.${locale}`, "invalid-field", `\`default\` (${locale}) ${problem}`);
+    else {
+        for (const [locale, document] of Object.entries(value)) {
+            const problem = richTextProblem(document, formats);
+            if (problem !== null)
+                addIssue(issues, `${fieldPath}.default.${locale}`, "invalid-field", `\`default\` (${locale}) ${problem}`);
+        }
+        const missing = locales.filter((locale) => !Object.hasOwn(value, locale));
+        if (missing.length > 0) {
+            addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` is missing the theme's languages: ${missing.join(", ")}`);
+        }
     }
-    const missing = locales.filter((locale) => !Object.hasOwn(value, locale));
-    if (missing.length > 0) {
-        addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` is missing the theme's languages: ${missing.join(", ")}`);
+    if (field.inline === true && issues.length === before) {
+        const checked = checkStoredValue(field, value);
+        if (!checked.ok)
+            addIssue(issues, `${fieldPath}.default`, "invalid-field", `\`default\` ${checked.message}`);
     }
 }
 function inspectListField(field, fieldPath, issues, rules) {
@@ -703,6 +1072,7 @@ function inspectSlots(slots, path, issues, catalogKeys) {
         if (slot.allow !== undefined) {
             inspectAllow(slot.allow, `${slotPath}.allow`, issues, catalogKeys);
         }
+        inspectBlockBounds(slot, slotPath, issues, catalogKeys, THEME_LIMITS.slotInstances, "invalid-slot");
     });
 }
 function inspectAllow(allow, path, issues, catalogKeys) {

package/dist/index.d.ts

@@ -17,6 +17,11 @@ export { resolveInstance, createInstance, checkStoredValue as checkFieldValue }
 export type { CheckedValue as FieldValueCheck } from "./instances.js";
 export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
 export { instantiatePreset, isInsertableOn } from "./composition.js";
+export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
+export { completePage, resolveSurfaceDocument } from "./surface-document.js";
+export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
+export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
+export type { SurfaceDocument, SurfaceDocumentReason } from "./surface-document.js";
 export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export type { DocumentEdit, DocumentIssue, DocumentIssueCode, InstanceLocation, InstancePlacement, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
@@ -30,4 +35,4 @@ export { diffThemeManifests } from "./manifest-diff.js";
 export { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";
 export type { PreviewEditorMessage, PreviewInstance, PreviewMode, PreviewPageMessage, PreviewPatch, PreviewRect, } from "./preview-protocol.js";
 export type { ManifestChange, ManifestDiff } from "./manifest-diff.js";
-export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, ComponentCapabilities, ComponentPreset, PresetInstance, SurfacePageType, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, NumberFieldDefinition, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ProductFieldDefinition, CategoryFieldDefinition, ImageFieldDefinition, RichTextFieldDefinition, RichTextFormat, ListFieldDefinition, ListItemFieldDefinition, ListItem, MediaReference, ResolvedImage, RichTextValue, RichTextDocument, RichTextBlock, RichTextParagraph, RichTextHeading, RichTextList, RichTextListItem, RichTextInline, RichTextText, RichTextBreak, RichTextMark, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";
+export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, RequiredBlock, ComponentPlacement, ComponentRole, FixedBlockDefinition, Breakpoint, Responsive, StyleStep, StyleWidth, StylePanel, StyleValue, StyleFieldDefinition, ColorRole, ColorScheme, ColorSchemeFieldDefinition, ColorSchemesFieldDefinition, ThemeStyle, ProductListFieldDefinition, CollectionListFieldDefinition, FieldCondition, ConditionValue, ComponentCapabilities, ComponentPreset, PresetInstance, SurfacePageType, ComponentDefinition, ComponentSpec, SurfaceSpec, AreaSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, NumberFieldDefinition, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ProductFieldDefinition, CategoryFieldDefinition, ImageFieldDefinition, RichTextFieldDefinition, RichTextFormat, ListFieldDefinition, ListItemFieldDefinition, ListItem, MediaReference, ResolvedImage, RichTextValue, RichTextDocument, RichTextBlock, RichTextParagraph, RichTextHeading, RichTextList, RichTextListItem, RichTextInline, RichTextText, RichTextBreak, RichTextMark, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

package/dist/index.js

@@ -16,6 +16,10 @@ export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance, checkStoredValue as checkFieldValue } from "./instances.js";
 export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
 export { instantiatePreset, isInsertableOn } from "./composition.js";
+export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
+export { completePage, resolveSurfaceDocument } from "./surface-document.js";
+export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
+export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
 export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";

package/dist/instances.d.ts

@@ -30,6 +30,10 @@ export declare function resolveField(field: FieldDefinition, raw: unknown, conte
  * refused, never stripped.
  */
 export declare function checkStoredValue(field: FieldDefinition, value: unknown): CheckedValue;
+/** The most handles a `productList` or `collectionList` holds. */
+export declare const HANDLE_LIST_MAX = 50;
+/** Why `value` is not a list of distinct handles within `min` and `max`, or `null`. */
+export declare function handleListProblem(kind: "productList" | "collectionList", min: number | undefined, max: number | undefined, value: unknown): string | null;
 /** On a grid of `step` from `base`, allowing for binary floating point. */
 export declare function onStepGrid(value: number, base: number, step: number): boolean;
 /**