@zohofinance/commerce 2.0.0 → 2.2.0

package/ts-dist/utils/schema-validation.js

@@ -0,0 +1,544 @@
+/**
+ * Schema checks aligned with storefront_template_engine SchemaValidator
+ * on patch_storefront_logging_and_error_handling. color_scheme is included
+ * because SchemaSettingsUtil resolves it. Findings the storefront still
+ * renders are warnings.
+ */
+export const MAX_BLOCK_NESTING_DEPTH = 5;
+export const EDITABLE_PAGE_KEYS = [
+    'index',
+    'cart',
+    'product',
+    'page',
+    'blog',
+    'blogs',
+    'collection',
+    'category',
+    'checkout',
+    'orders',
+    'search',
+    '404'
+];
+export const SECTION_GROUP_KEYS = ['header-group', 'footer-group'];
+const ALLOWED_AVAILABLE_IN = new Set([
+    ...EDITABLE_PAGE_KEYS,
+    ...SECTION_GROUP_KEYS
+]);
+/** Engine SchemaValidator.KNOWN_SETTING_TYPES plus color_scheme. */
+export const SUPPORTED_SETTING_TYPES = new Set([
+    'checkbox',
+    'radio',
+    'select',
+    'collection',
+    'blog',
+    'form',
+    'category',
+    'product',
+    'menu',
+    'color',
+    'color_scheme',
+    'range',
+    'image_picker',
+    'media_picker',
+    'url',
+    'text',
+    'image',
+    'richtext',
+    'inline_richtext',
+    'header'
+]);
+const OPTION_SETTING_TYPES = new Set(['select', 'radio']);
+const RESOURCE_SETTING_TYPES = new Set([
+    'collection',
+    'category',
+    'product',
+    'blog',
+    'menu'
+]);
+const META_VALUES = new Set(['desktop', 'mobile']);
+const THEME_BLOCK_PREFIX = 'zc_theme__';
+const APP_BLOCK_PREFIX = 'zc_app__';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+function push(issues, message, severity = 'error') {
+    issues.push({ message, severity });
+}
+export function validateSchemaDocument(schema, options = {}) {
+    const issues = [];
+    if (!isNonEmptyString(schema.name)) {
+        push(issues, 'name is required and must be a non-empty string');
+    }
+    if ('tag' in schema && typeof schema.tag !== 'string') {
+        push(issues, 'tag must be a string');
+    }
+    if ('class' in schema && typeof schema.class !== 'string') {
+        push(issues, 'class must be a string');
+    }
+    if ('max_blocks' in schema && !isPositiveInteger(schema.max_blocks)) {
+        push(issues, 'max_blocks must be a positive integer');
+    }
+    const requirementSeverity = options.requirementSeverity ?? 'warning';
+    validateAvailableIn(schema, issues, options.requireAvailableIn === true, requirementSeverity);
+    validateSettingsArray(schema.settings, 'settings', issues);
+    validateSchemaBlocks(schema.blocks, 'blocks', issues, 1);
+    validatePresets(schema, issues, options.requirePresets === true, options.themeBlockSchemas, requirementSeverity);
+    return issues;
+}
+function validateAvailableIn(schema, issues, required, requirementSeverity) {
+    if (!('available_in' in schema)) {
+        if (required) {
+            push(issues, 'available_in is required and must list at least one page in available_in.templates', requirementSeverity);
+        }
+        return;
+    }
+    if (!isRecord(schema.available_in)) {
+        push(issues, 'available_in must be an object', 'warning');
+        return;
+    }
+    const templates = schema.available_in.templates;
+    if (templates === undefined || templates === null) {
+        if (required) {
+            push(issues, 'available_in.templates must contain at least one page', requirementSeverity);
+        }
+        return;
+    }
+    if (!Array.isArray(templates)) {
+        push(issues, 'available_in.templates must be an array', 'warning');
+        return;
+    }
+    if (required && templates.length === 0) {
+        push(issues, 'available_in.templates must contain at least one page', requirementSeverity);
+    }
+    templates.forEach((value, index) => {
+        const path = `available_in.templates[${index}]`;
+        if (typeof value !== 'string') {
+            push(issues, `${path} must be a string`, 'warning');
+            return;
+        }
+        if (!ALLOWED_AVAILABLE_IN.has(value)) {
+            push(issues, `${path} '${value}' is not an editable page; allowed values: ${[
+                ...ALLOWED_AVAILABLE_IN
+            ].join(', ')}`, 'warning');
+        }
+    });
+}
+function validateSettingsArray(settings, path, issues) {
+    if (settings === undefined || settings === null) {
+        return;
+    }
+    if (!Array.isArray(settings)) {
+        push(issues, `${path} must be an array`);
+        return;
+    }
+    const seenIds = new Set();
+    settings.forEach((setting, index) => {
+        const settingPath = `${path}[${index}]`;
+        if (!isRecord(setting)) {
+            push(issues, `${settingPath} must be an object`);
+            return;
+        }
+        validateSetting(setting, settingPath, issues, seenIds);
+    });
+}
+function validateSetting(setting, path, issues, seenIds) {
+    const type = setting.type;
+    if (!isNonEmptyString(type)) {
+        push(issues, `${path}.type is required`);
+        return;
+    }
+    if (!SUPPORTED_SETTING_TYPES.has(type)) {
+        push(issues, `${path}.type '${type}' is not a recognised setting type`);
+        return;
+    }
+    if ('meta' in setting) {
+        if (typeof setting.meta !== 'string' || !META_VALUES.has(setting.meta)) {
+            push(issues, `${path}.meta must be one of desktop, mobile`);
+        }
+    }
+    if (type === 'header') {
+        if (!isNonEmptyString(setting.content)) {
+            push(issues, `${path} (header) must have a content`);
+        }
+        return;
+    }
+    const id = setting.id;
+    if (!isNonEmptyString(id)) {
+        push(issues, `${path}.id is required for type '${type}'`);
+    }
+    else if (seenIds.has(id)) {
+        push(issues, `${path}.id '${id}' is duplicated in ${path.split('[')[0]}`, 'warning');
+    }
+    else {
+        seenIds.add(id);
+    }
+    if (OPTION_SETTING_TYPES.has(type)) {
+        validateOptions(setting, path, issues);
+    }
+    if (type === 'range') {
+        validateRange(setting, path, issues);
+        return;
+    }
+    validateStructuredDefault(setting, type, path, issues);
+}
+function validateStructuredDefault(setting, type, path, issues) {
+    const needsOptionDefault = OPTION_SETTING_TYPES.has(type);
+    const needsResourceDefault = RESOURCE_SETTING_TYPES.has(type);
+    const needsUrlDefault = type === 'url';
+    const needsImageDefault = type === 'image_picker';
+    const needsMediaDefault = type === 'media_picker';
+    if (!needsOptionDefault &&
+        !needsResourceDefault &&
+        !needsUrlDefault &&
+        !needsImageDefault &&
+        !needsMediaDefault) {
+        if (type === 'checkbox' && 'default' in setting && typeof setting.default !== 'boolean') {
+            push(issues, `${path}.default must be a boolean for type 'checkbox'`, 'warning');
+        }
+        return;
+    }
+    const defaultPath = `${path}.default`;
+    if (!('default' in setting)) {
+        push(issues, `${defaultPath} is required for type '${type}'`);
+        return;
+    }
+    if (!isRecord(setting.default)) {
+        push(issues, `${defaultPath} must be an object`);
+        return;
+    }
+    const def = setting.default;
+    if (needsOptionDefault) {
+        requireString(def, 'display_name', defaultPath, issues);
+        requireString(def, 'value', defaultPath, issues);
+        if (typeof def.value === 'string' && Array.isArray(setting.options)) {
+            const values = setting.options
+                .filter(isRecord)
+                .map((option) => option.value)
+                .filter((value) => typeof value === 'string');
+            if (values.length > 0 && !values.includes(def.value)) {
+                push(issues, `${defaultPath}.value '${def.value}' is not one of options (${values.join(', ')})`, 'warning');
+            }
+        }
+        return;
+    }
+    if (needsUrlDefault) {
+        requireString(def, 'display_name', defaultPath, issues);
+        requireString(def, 'handle', defaultPath, issues);
+        return;
+    }
+    if (needsResourceDefault) {
+        if (type === 'menu') {
+            requireString(def, 'display_name', defaultPath, issues);
+        }
+        requireString(def, 'handle', defaultPath, issues);
+        return;
+    }
+    if (needsImageDefault || needsMediaDefault) {
+        requireString(def, 'url', defaultPath, issues);
+        optionalBoolean(def, 'enable_customisation', defaultPath, issues);
+        if (needsMediaDefault) {
+            optionalBoolean(def, 'is_video', defaultPath, issues);
+        }
+    }
+}
+function requireString(def, key, defaultPath, issues) {
+    if (typeof def[key] !== 'string') {
+        push(issues, `${defaultPath}.${key} is required and must be a string`);
+    }
+}
+function optionalBoolean(def, key, defaultPath, issues) {
+    if (key in def && typeof def[key] !== 'boolean') {
+        push(issues, `${defaultPath}.${key} must be a boolean`);
+    }
+}
+function validateOptions(setting, path, issues) {
+    if (!Array.isArray(setting.options)) {
+        push(issues, `${path}.options is required and must be an array`);
+        return;
+    }
+    if (setting.options.length === 0) {
+        push(issues, `${path}.options must not be empty`);
+        return;
+    }
+    setting.options.forEach((option, index) => {
+        const optionPath = `${path}.options[${index}]`;
+        if (!isRecord(option)) {
+            push(issues, `${optionPath} must be an object`);
+            return;
+        }
+        if (typeof option.value !== 'string') {
+            push(issues, `${optionPath}.value is required`);
+        }
+        if (typeof option.label !== 'string') {
+            push(issues, `${optionPath}.label is required`);
+        }
+    });
+}
+function validateRange(setting, path, issues) {
+    if ('unit' in setting && typeof setting.unit !== 'string') {
+        push(issues, `${path}.unit must be a string`);
+    }
+    const min = setting.min;
+    const max = setting.max;
+    if (typeof min !== 'number') {
+        push(issues, `${path}.min is required and must be a number for type 'range'`);
+    }
+    if (typeof max !== 'number') {
+        push(issues, `${path}.max is required and must be a number for type 'range'`);
+    }
+    if (typeof min === 'number' && typeof max === 'number') {
+        if (min >= max) {
+            push(issues, `${path}.min must be less than max`);
+        }
+        if ('step' in setting &&
+            (typeof setting.step !== 'number' || setting.step <= 0)) {
+            push(issues, `${path}.step must be a positive number`);
+        }
+        if (typeof setting.default === 'number') {
+            if (setting.default < min || setting.default > max) {
+                push(issues, `${path}.default must be within the min/max range`);
+            }
+        }
+    }
+}
+function validateSchemaBlocks(blocks, path, issues, depth) {
+    if (blocks === undefined || blocks === null) {
+        return;
+    }
+    if (!Array.isArray(blocks)) {
+        push(issues, `${path} must be an array`);
+        return;
+    }
+    if (depth > MAX_BLOCK_NESTING_DEPTH) {
+        push(issues, `${path} nesting exceeds the maximum depth of ${MAX_BLOCK_NESTING_DEPTH}`);
+        return;
+    }
+    blocks.forEach((block, index) => {
+        const blockPath = `${path}[${index}]`;
+        if (!isRecord(block)) {
+            push(issues, `${blockPath} must be an object`);
+            return;
+        }
+        const type = block.type;
+        if (!isNonEmptyString(type)) {
+            push(issues, `${blockPath}.type is required`);
+            return;
+        }
+        if (type === '@theme' ||
+            type === '@widget' ||
+            type === '@app' ||
+            type.startsWith(THEME_BLOCK_PREFIX) ||
+            type.startsWith(APP_BLOCK_PREFIX)) {
+            return;
+        }
+        if ('limit' in block && !isPositiveInteger(block.limit)) {
+            push(issues, `${blockPath}.limit must be a positive integer`);
+        }
+        if ('settings' in block) {
+            validateSettingsArray(block.settings, `${blockPath}.settings`, issues);
+        }
+        validateSchemaBlocks(block.blocks, `${blockPath}.blocks`, issues, depth + 1);
+    });
+}
+function validatePresets(schema, issues, required, themeBlockSchemas, requirementSeverity = 'warning') {
+    if (!('presets' in schema)) {
+        if (required) {
+            push(issues, 'presets must contain at least one preset with a name', requirementSeverity);
+        }
+        return;
+    }
+    if (!Array.isArray(schema.presets)) {
+        push(issues, 'presets must be an array');
+        return;
+    }
+    if (required && schema.presets.length === 0) {
+        push(issues, 'presets must contain at least one preset with a name', requirementSeverity);
+    }
+    schema.presets.forEach((preset, index) => {
+        const path = `presets[${index}]`;
+        if (!isRecord(preset)) {
+            push(issues, `${path} must be an object`);
+            return;
+        }
+        if (!isNonEmptyString(preset.name)) {
+            push(issues, `${path}.name is required`, required ? requirementSeverity : 'error');
+        }
+        if ('settings' in preset && !isRecord(preset.settings)) {
+            push(issues, `${path}.settings must be an object`);
+        }
+        validatePresetBlocks(preset, path, schema, issues, 1, themeBlockSchemas);
+    });
+}
+function validatePresetBlocks(preset, path, containerSchema, issues, depth, themeBlockSchemas) {
+    if (!('blocks' in preset)) {
+        return;
+    }
+    if (!isRecord(preset.blocks)) {
+        push(issues, `${path}.blocks must be an object keyed by block name, with block_order. An array is ignored by the engine, so those preset blocks are never created`, 'warning');
+        return;
+    }
+    const presetBlocks = preset.blocks;
+    if (depth > MAX_BLOCK_NESTING_DEPTH) {
+        push(issues, `${path}.blocks nesting exceeds the maximum depth of ${MAX_BLOCK_NESTING_DEPTH}`);
+        return;
+    }
+    for (const [blockName, block] of Object.entries(presetBlocks)) {
+        const blockType = isRecord(block) ? block.type : undefined;
+        if (!isNonEmptyString(blockType)) {
+            push(issues, `${path}.blocks.${blockName}.type is required`);
+        }
+        else if (containerSchema &&
+            !isBlockTypeAllowed(containerSchema, blockType)) {
+            push(issues, `${path}.blocks.${blockName} type '${blockType}' is not allowed by the container schema blocks`);
+        }
+        if (isRecord(block)) {
+            const childSchema = isNonEmptyString(blockType)
+                ? resolveChildContainerSchema(containerSchema, blockType, themeBlockSchemas)
+                : null;
+            validatePresetBlocks(block, `${path}.blocks.${blockName}`, childSchema, issues, depth + 1, themeBlockSchemas);
+        }
+    }
+    if (!('block_order' in preset)) {
+        return;
+    }
+    if (!Array.isArray(preset.block_order)) {
+        push(issues, `${path}.block_order must be an array`);
+        return;
+    }
+    preset.block_order.forEach((blockName, index) => {
+        if (typeof blockName !== 'string' || !(blockName in presetBlocks)) {
+            push(issues, `${path}.block_order[${index}] '${String(blockName)}' is not a key in blocks`);
+        }
+    });
+}
+export function isBlockTypeAllowed(containerSchema, blockType) {
+    if (!containerSchema || !blockType) {
+        return false;
+    }
+    const blocks = containerSchema.blocks;
+    if (!Array.isArray(blocks)) {
+        return false;
+    }
+    let allowsAllThemeBlocks = false;
+    let allowsAppBlocks = false;
+    for (const blockSchema of blocks) {
+        if (!isRecord(blockSchema) || typeof blockSchema.type !== 'string') {
+            continue;
+        }
+        if (blockSchema.type === '@theme') {
+            allowsAllThemeBlocks = true;
+        }
+        else if (blockSchema.type === '@widget' || blockSchema.type === '@app') {
+            allowsAppBlocks = true;
+        }
+        else if (blockSchema.type === blockType) {
+            return true;
+        }
+    }
+    if (blockType.startsWith(THEME_BLOCK_PREFIX)) {
+        return allowsAllThemeBlocks;
+    }
+    if (blockType.startsWith(APP_BLOCK_PREFIX)) {
+        return allowsAppBlocks;
+    }
+    return false;
+}
+/**
+ * Schema whose `blocks` allow a placed block's children.
+ * Theme-block files are resolved by the caller via `themeBlockSchemas`.
+ */
+export function resolveChildContainerSchema(containerSchema, blockType, themeBlockSchemas) {
+    if (!blockType) {
+        return null;
+    }
+    if (blockType.startsWith(THEME_BLOCK_PREFIX)) {
+        return themeBlockSchemas?.get(blockType.slice(THEME_BLOCK_PREFIX.length)) ?? null;
+    }
+    if (!containerSchema || !Array.isArray(containerSchema.blocks)) {
+        return null;
+    }
+    for (const blockSchema of containerSchema.blocks) {
+        if (isRecord(blockSchema) && blockSchema.type === blockType) {
+            return blockSchema;
+        }
+    }
+    return null;
+}
+export function declaredThemeBlockNames(schema) {
+    if (!Array.isArray(schema.blocks)) {
+        return [];
+    }
+    const names = [];
+    for (const block of schema.blocks) {
+        if (isRecord(block) &&
+            typeof block.type === 'string' &&
+            block.type.startsWith(THEME_BLOCK_PREFIX)) {
+            names.push(block.type.slice(THEME_BLOCK_PREFIX.length));
+        }
+    }
+    return names;
+}
+export function validateThemeSettingsGroups(groups) {
+    const issues = [];
+    if (!Array.isArray(groups)) {
+        return [
+            {
+                message: 'settings/schema.json must be an array of setting groups',
+                severity: 'error'
+            }
+        ];
+    }
+    groups.forEach((group, index) => {
+        const path = `groups[${index}]`;
+        if (!isRecord(group)) {
+            push(issues, `${path} must be an object`);
+            return;
+        }
+        if (!isNonEmptyString(group.name)) {
+            push(issues, `${path}.name is required and must be a non-empty string`);
+        }
+        validateSettingsArray(group.settings, `${path}.settings`, issues);
+    });
+    return issues;
+}
+export function validateThemeSettingsData(data) {
+    const issues = [];
+    if (!isRecord(data)) {
+        return [
+            {
+                message: 'settings/theme.json must be an object',
+                severity: 'error'
+            }
+        ];
+    }
+    if (!isRecord(data.presets)) {
+        return [
+            {
+                message: 'settings/theme.json presets must be an object',
+                severity: 'error'
+            }
+        ];
+    }
+    const presetNames = Object.keys(data.presets);
+    let selectedName;
+    if (typeof data.selected === 'string') {
+        selectedName = data.selected;
+    }
+    else if (isRecord(data.selected) && typeof data.selected.preset_name === 'string') {
+        selectedName = data.selected.preset_name;
+    }
+    else {
+        push(issues, 'settings/theme.json selected must be a preset name or { preset_name }');
+        return issues;
+    }
+    if (!presetNames.includes(selectedName)) {
+        push(issues, `settings/theme.json selected preset '${selectedName}' is not a key in presets`);
+    }
+    return issues;
+}

package/ts-dist/utils/serve-theme-utils.d.ts

@@ -1,4 +1,4 @@
 import { LiveReloadServer } from 'livereload';
 export declare function findAvailablePort(): Promise<number>;
-export declare function watchFolders(liveReloadServer: LiveReloadServer, onChange?: () => void | Promise<void>): void;
+export declare function watchFolders(liveReloadServer?: LiveReloadServer, onChange?: () => void | Promise<void>): void;
 //# sourceMappingURL=serve-theme-utils.d.ts.map

package/ts-dist/utils/serve-theme-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve-theme-utils.d.ts","sourceRoot":"","sources":["../../src/utils/serve-theme-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAY9C,wBAAsB,iBAAiB,oBAWtC;AAID,wBAAgB,YAAY,CAC1B,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QA2CtC"}
+{"version":3,"file":"serve-theme-utils.d.ts","sourceRoot":"","sources":["../../src/utils/serve-theme-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAY9C,wBAAsB,iBAAiB,oBAWtC;AAID,wBAAgB,YAAY,CAC1B,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QA2CtC"}

package/ts-dist/utils/serve-theme-utils.js

@@ -57,7 +57,7 @@ export function watchFolders(liveReloadServer, onChange) {
                     console.error(chalk.red('Failed to revalidate theme:'), err);
                 }
             }
-            liveReloadServer.refresh('/');
+            liveReloadServer?.refresh('/');
         });
     }
     catch (err) {

package/ts-dist/utils/template-reference-validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Page JSON, section-group JSON, and Liquid reference checks.
+ * Mirrors PageJsonValidator / RenderUtil.validateBlocksAllowed so a theme
+ * fails in the CLI before the engine rejects it at render or save.
+ */
+import type { ValidationIssue } from './theme-validation.js';
+export declare function validateLiquidSchemas(cwd: string, mode?: 'dev' | 'build'): ValidationIssue[];
+export declare function validateThemeSettingsFiles(cwd: string): ValidationIssue[];
+export declare function validateTemplateJson(cwd: string): ValidationIssue[];
+export declare function validateLiquidReferences(cwd: string): ValidationIssue[];
+//# sourceMappingURL=template-reference-validation.d.ts.map

package/ts-dist/utils/template-reference-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-reference-validation.d.ts","sourceRoot":"","sources":["../../src/utils/template-reference-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA8J7D,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,KAAK,GAAG,OAAiB,GAC9B,eAAe,EAAE,CA6GnB;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAsCzE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAsKnE;AAkOD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAkFvE"}