@numueg/theme-sdk 0.3.2 → 0.4.0

package/dist/index.cjs

@@ -6,6 +6,400 @@ var jsxRuntime = require('react/jsx-runtime');
 
 // src/types/theme.ts
 var MAX_BLOCK_DEPTH = 5;
+
+// src/validation/index.ts
+var THEME_CONTRACT_VERSION = 1;
+var SDK_VERSION = "0.4.0" ;
+var REQUIRED_TEMPLATES = [
+  "home",
+  "product",
+  "collection",
+  "cart",
+  "page",
+  "search",
+  "404"
+];
+var KNOWN_TEMPLATES = /* @__PURE__ */ new Set([
+  ...REQUIRED_TEMPLATES,
+  "blog",
+  "article",
+  "policies",
+  "password",
+  "account",
+  "checkout"
+]);
+var KNOWN_SETTING_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "textarea",
+  "richtext",
+  "number",
+  "range",
+  "color",
+  "checkbox",
+  "select",
+  "radio",
+  "font",
+  "image_picker",
+  "url",
+  "product",
+  "product_list",
+  "collection",
+  "collection_list",
+  "header",
+  "paragraph",
+  "html",
+  "date",
+  "time",
+  "video_picker",
+  "color_scheme",
+  "page_picker",
+  "blog_picker",
+  "link_list_picker",
+  "variant_picker",
+  "file_upload",
+  "icon_picker",
+  "icon"
+]);
+var PRESENTATIONAL_SETTING_TYPES = /* @__PURE__ */ new Set([
+  "header",
+  "paragraph",
+  "html"
+]);
+var SECTION_TYPE_RE = /^[a-z][a-z0-9_-]*$/;
+var THEME_ID_RE = /^[a-z0-9][a-z0-9_-]*[a-z0-9]$/;
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+var IssueBag = class {
+  constructor() {
+    this.issues = [];
+  }
+  err(code, message, path) {
+    this.issues.push({ level: "error", code, message, path });
+  }
+  warn(code, message, path) {
+    this.issues.push({ level: "warning", code, message, path });
+  }
+  result() {
+    return {
+      valid: !this.issues.some((i) => i.level === "error"),
+      issues: this.issues
+    };
+  }
+};
+function collectPresetSectionTypes(manifest) {
+  const types = /* @__PURE__ */ new Set();
+  const presets = manifest.presets;
+  if (!isObject(presets)) return types;
+  const buckets = [presets.templates, presets.section_groups];
+  for (const bucket of buckets) {
+    if (!isObject(bucket)) continue;
+    for (const entry of Object.values(bucket)) {
+      if (!isObject(entry)) continue;
+      const sections = entry.sections;
+      const instances = Array.isArray(sections) ? sections : isObject(sections) ? Object.values(sections) : [];
+      for (const inst of instances) {
+        if (isObject(inst) && isNonEmptyString(inst.type)) types.add(inst.type);
+      }
+    }
+  }
+  return types;
+}
+function validateSettingInto(bag, setting, pathPrefix, seenIds) {
+  if (!isObject(setting)) {
+    bag.err("schema.setting.invalid", "Setting must be an object.", pathPrefix);
+    return;
+  }
+  const type = setting.type;
+  if (!isNonEmptyString(type)) {
+    bag.err("schema.setting.type.missing", "Setting is missing a `type`.", pathPrefix);
+  } else if (!KNOWN_SETTING_TYPES.has(type)) {
+    bag.warn(
+      "schema.setting.type.unknown",
+      `Unknown setting type "${type}" \u2014 the customizer will fall back to a text input.`,
+      pathPrefix
+    );
+  }
+  const presentational = isNonEmptyString(type) && PRESENTATIONAL_SETTING_TYPES.has(type);
+  if (!presentational) {
+    if (!isNonEmptyString(setting.id)) {
+      bag.err("schema.setting.id.missing", "Setting is missing an `id`.", pathPrefix);
+    } else {
+      if (seenIds.has(setting.id)) {
+        bag.err(
+          "schema.setting.id.duplicate",
+          `Duplicate setting id "${setting.id}".`,
+          pathPrefix
+        );
+      }
+      seenIds.add(setting.id);
+    }
+    if (!isNonEmptyString(setting.label)) {
+      bag.warn("schema.setting.label.missing", "Setting has no `label`.", pathPrefix);
+    }
+  }
+  if (type === "select" || type === "radio") {
+    const options = setting.options;
+    if (!Array.isArray(options) || options.length === 0) {
+      bag.err(
+        "schema.setting.options.missing",
+        `"${type}" setting "${String(setting.id)}" must declare a non-empty \`options\` array.`,
+        pathPrefix
+      );
+    }
+  }
+  if (type === "range") {
+    if (typeof setting.min !== "number" || typeof setting.max !== "number") {
+      bag.err(
+        "schema.setting.range.bounds",
+        `"range" setting "${String(setting.id)}" must declare numeric \`min\` and \`max\`.`,
+        pathPrefix
+      );
+    } else if (setting.min >= setting.max) {
+      bag.err(
+        "schema.setting.range.order",
+        `"range" setting "${String(setting.id)}" has min >= max.`,
+        pathPrefix
+      );
+    }
+  }
+}
+function validateSectionSchema(schema, opts = {}) {
+  const bag = new IssueBag();
+  const where = opts.filenameType ? `${opts.filenameType}.json` : "section schema";
+  if (!isObject(schema)) {
+    bag.err("schema.invalid", "Section schema must be a JSON object.", where);
+    return bag.result();
+  }
+  const type = schema.type;
+  if (!isNonEmptyString(type)) {
+    bag.err("schema.type.missing", "Section schema is missing a `type`.", where);
+  } else {
+    if (!SECTION_TYPE_RE.test(type)) {
+      bag.err(
+        "schema.type.format",
+        `Section type "${type}" must match ${SECTION_TYPE_RE} (lowercase, start with a letter).`,
+        where
+      );
+    }
+    if (opts.filenameType && type !== opts.filenameType) {
+      bag.err(
+        "schema.type.filename_mismatch",
+        `Schema type "${type}" must equal its filename "${opts.filenameType}" (component-filename = schema-type convention).`,
+        where
+      );
+    }
+  }
+  if (!isNonEmptyString(schema.name)) {
+    bag.err("schema.name.missing", "Section schema is missing a `name`.", where);
+  }
+  if (schema.settings === void 0) {
+    bag.warn("schema.settings.missing", "Section schema has no `settings`.", where);
+  } else if (!Array.isArray(schema.settings)) {
+    bag.err("schema.settings.invalid", "`settings` must be an array.", where);
+  } else {
+    const seen = /* @__PURE__ */ new Set();
+    schema.settings.forEach(
+      (s, i) => validateSettingInto(bag, s, `${where}.settings[${i}]`, seen)
+    );
+  }
+  if (schema.blocks !== void 0) {
+    if (!Array.isArray(schema.blocks)) {
+      bag.err("schema.blocks.invalid", "`blocks` must be an array.", where);
+    } else {
+      schema.blocks.forEach((b, i) => {
+        if (!isObject(b) || !isNonEmptyString(b.type)) {
+          bag.err("schema.block.type.missing", `Block[${i}] is missing a \`type\`.`, where);
+          return;
+        }
+        if (!SECTION_TYPE_RE.test(b.type)) {
+          bag.err(
+            "schema.block.type.format",
+            `Block type "${b.type}" must match ${SECTION_TYPE_RE}.`,
+            where
+          );
+        }
+        if (Array.isArray(b.settings)) {
+          const seen = /* @__PURE__ */ new Set();
+          b.settings.forEach(
+            (s, j) => validateSettingInto(bag, s, `${where}.blocks[${i}].settings[${j}]`, seen)
+          );
+        }
+      });
+    }
+  }
+  return bag.result();
+}
+function validateSettingsAgainstSchema(settings, schema, pathPrefix = "settings") {
+  const bag = new IssueBag();
+  if (!isObject(settings)) {
+    bag.err("instance.settings.invalid", "Section settings must be an object.", pathPrefix);
+    return bag.result();
+  }
+  const defs = Array.isArray(schema.settings) ? schema.settings : [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const d of defs) if (isNonEmptyString(d?.id)) byId.set(d.id, d);
+  for (const [key, value] of Object.entries(settings)) {
+    const def = byId.get(key);
+    if (!def) {
+      bag.warn(
+        "instance.setting.unknown",
+        `Setting "${key}" is not declared in the "${String(schema.type)}" schema.`,
+        `${pathPrefix}.${key}`
+      );
+      continue;
+    }
+    if (value === null || value === void 0) continue;
+    const p = `${pathPrefix}.${key}`;
+    if ((def.type === "select" || def.type === "radio") && Array.isArray(def.options)) {
+      const allowed = def.options.map((o) => o.value);
+      if (typeof value === "string" && !allowed.includes(value)) {
+        bag.err(
+          "instance.setting.option.invalid",
+          `"${key}" = "${value}" is not one of: ${allowed.join(", ")}.`,
+          p
+        );
+      }
+    }
+    if (def.type === "range" && typeof value === "number") {
+      if (typeof def.min === "number" && value < def.min) {
+        bag.err("instance.setting.range.under", `"${key}" = ${value} is below min ${def.min}.`, p);
+      }
+      if (typeof def.max === "number" && value > def.max) {
+        bag.err("instance.setting.range.over", `"${key}" = ${value} is above max ${def.max}.`, p);
+      }
+    }
+    if (def.type === "checkbox" && typeof value !== "boolean") {
+      bag.warn("instance.setting.type.mismatch", `"${key}" should be a boolean.`, p);
+    }
+    if ((def.type === "number" || def.type === "range") && typeof value !== "number") {
+      bag.warn("instance.setting.type.mismatch", `"${key}" should be a number.`, p);
+    }
+  }
+  return bag.result();
+}
+function validateManifestCore(bag, m) {
+  if (!isNonEmptyString(m.id)) {
+    bag.err("manifest.id.missing", "theme.json is missing `id`.", "id");
+  } else if (!THEME_ID_RE.test(m.id)) {
+    bag.err(
+      "manifest.id.format",
+      `Theme id "${m.id}" must be lowercase alphanumeric with dashes/underscores (no leading/trailing separator).`,
+      "id"
+    );
+  }
+  const name = m.name;
+  const nameOk = isNonEmptyString(name) || isObject(name) && Object.values(name).some((v) => isNonEmptyString(v));
+  if (!nameOk) {
+    bag.err("manifest.name.missing", "theme.json is missing a non-empty `name`.", "name");
+  }
+  if (!isNonEmptyString(m.version)) {
+    bag.err("manifest.version.missing", "theme.json is missing `version`.", "version");
+  } else if (!SEMVER_RE.test(m.version)) {
+    bag.err("manifest.version.invalid", `Version "${m.version}" is not valid semver.`, "version");
+  }
+  if (!isNonEmptyString(m.author)) {
+    bag.err("manifest.author.missing", "theme.json is missing `author`.", "author");
+  }
+  if (m.min_sdk_version !== void 0 && !SEMVER_RE.test(String(m.min_sdk_version))) {
+    bag.warn("manifest.min_sdk_version.invalid", "`min_sdk_version` is not valid semver.", "min_sdk_version");
+  }
+}
+function validateManifest(manifest, ctx = {}) {
+  const bag = new IssueBag();
+  if (!isObject(manifest)) {
+    bag.err("manifest.invalid", "theme.json must be a JSON object.", "theme.json");
+    return bag.result();
+  }
+  validateManifestCore(bag, manifest);
+  const presets = manifest.presets;
+  if (!isObject(presets) || Object.keys(presets).length === 0) {
+    bag.warn("manifest.presets.empty", "theme.json has no presets \u2014 merchants start with an empty page.", "presets");
+  } else {
+    if (ctx.sectionTypes) {
+      for (const type of collectPresetSectionTypes(manifest)) {
+        if (!ctx.sectionTypes.has(type)) {
+          bag.err(
+            "manifest.preset.unknown_section",
+            `Preset references section type "${type}" with no schemas/sections/${type}.json.`,
+            "presets"
+          );
+        }
+      }
+    }
+    const templates = isObject(presets.templates) ? presets.templates : {};
+    for (const t of REQUIRED_TEMPLATES) {
+      if (!(t in templates)) {
+        bag.warn(
+          "manifest.template.missing",
+          `No preset for required template "${t}" \u2014 the storefront will fall back to its built-in.`,
+          `presets.templates.${t}`
+        );
+      }
+    }
+  }
+  return bag.result();
+}
+function validateBuiltManifest(builtManifest, importMap, opts = {}) {
+  const bag = new IssueBag();
+  if (!isObject(builtManifest)) {
+    bag.err("built.invalid", "manifest.json must be a JSON object.", "manifest.json");
+    return bag.result();
+  }
+  validateManifestCore(bag, builtManifest);
+  const schemas = builtManifest.section_schemas;
+  const shipped = new Set(isObject(schemas) ? Object.keys(schemas) : []);
+  if (!isObject(schemas)) {
+    bag.warn("built.section_schemas.missing", "manifest.json has no `section_schemas`.", "section_schemas");
+  }
+  for (const type of collectPresetSectionTypes(builtManifest)) {
+    if (!shipped.has(type)) {
+      bag.err(
+        "built.preset.unknown_section",
+        `Preset references section type "${type}" not present in section_schemas.`,
+        "presets"
+      );
+    }
+  }
+  if (isObject(schemas)) {
+    for (const [type, schema] of Object.entries(schemas)) {
+      const r = validateSectionSchema(schema, { filenameType: type });
+      for (const issue of r.issues) bag.issues.push(issue);
+    }
+  }
+  if (!isNonEmptyString(builtManifest.plugin_version)) {
+    bag.warn("built.plugin_version.missing", "manifest.json has no `plugin_version`.", "plugin_version");
+  }
+  if (importMap !== void 0) {
+    if (!isObject(importMap)) {
+      bag.err("importmap.invalid", "import-map.json must be a JSON object.", "import-map.json");
+    } else {
+      const cv = importMap.contract_version;
+      if (typeof cv !== "number") {
+        bag.warn(
+          "importmap.contract_version.missing",
+          "import-map.json has no numeric `contract_version` \u2014 built by an older plugin.",
+          "contract_version"
+        );
+      } else if (typeof opts.hostContractVersion === "number" && cv > opts.hostContractVersion) {
+        bag.err(
+          "importmap.contract_version.incompatible",
+          `Theme built for contract v${cv}; this platform supports up to v${opts.hostContractVersion}.`,
+          "contract_version"
+        );
+      }
+    }
+  }
+  return bag.result();
+}
+function mergeResults(...results) {
+  const issues = results.flatMap((r) => r.issues);
+  return { valid: !issues.some((i) => i.level === "error"), issues };
+}
 var ShopContext = react.createContext(null);
 var ProductContext = react.createContext(null);
 var CollectionContext = react.createContext(null);
@@ -3572,6 +3966,8 @@ exports.ICON_NAMES = ICON_NAMES;
 exports.Icon = Icon;
 exports.IconMap = IconMap;
 exports.Image = Image;
+exports.KNOWN_SETTING_TYPES = KNOWN_SETTING_TYPES;
+exports.KNOWN_TEMPLATES = KNOWN_TEMPLATES;
 exports.Link = Link;
 exports.LocaleSwitcher = LocaleSwitcher;
 exports.LocalizationContext = LocalizationContext;
@@ -3583,10 +3979,13 @@ exports.PageContext = PageContext;
 exports.ProductCard = ProductCard;
 exports.ProductContext = ProductContext;
 exports.ProductProvider = ProductProvider;
+exports.REQUIRED_TEMPLATES = REQUIRED_TEMPLATES;
 exports.RichText = RichText;
+exports.SDK_VERSION = SDK_VERSION;
 exports.Section = Section;
 exports.SectionContext = SectionContext;
 exports.ShopContext = ShopContext;
+exports.THEME_CONTRACT_VERSION = THEME_CONTRACT_VERSION;
 exports.ThemeSettingsContext = ThemeSettingsContext;
 exports.applyGlobalStyleTokens = applyGlobalStyleTokens;
 exports.applyImageTransform = applyImageTransform;
@@ -3613,6 +4012,7 @@ exports.isDefinedBlock = isDefinedBlock;
 exports.isDefinedSection = isDefinedSection;
 exports.isDynamicSource = isDynamicSource;
 exports.isSdkAvailable = isSdkAvailable;
+exports.mergeResults = mergeResults;
 exports.mountTheme = mountTheme;
 exports.pickTranslations = pickTranslations;
 exports.registerReactSingleton = registerReactSingleton;
@@ -3664,5 +4064,9 @@ exports.useThemeSettings = useThemeSettings;
 exports.useTranslation = useTranslation;
 exports.useVariantSelection = useVariantSelection;
 exports.useWishlist = useWishlist;
+exports.validateBuiltManifest = validateBuiltManifest;
+exports.validateManifest = validateManifest;
+exports.validateSectionSchema = validateSectionSchema;
+exports.validateSettingsAgainstSchema = validateSettingsAgainstSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map