@numueg/theme-sdk 0.3.2 → 0.5.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.5.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);
@@ -1936,6 +2330,64 @@ function NuMuProvider({
 function ProductProvider({ product, children }) {
   return /* @__PURE__ */ jsxRuntime.jsx(ProductContext.Provider, { value: product, children });
 }
+function CollectionProvider({ collection, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(CollectionContext.Provider, { value: collection, children });
+}
+
+// src/utils/logoStyle.ts
+var LOGO_SHAPE_OPTIONS = [
+  { value: "none", label: "Original", label_ar: "\u0627\u0644\u0623\u0635\u0644\u064A" },
+  { value: "square", label: "Square", label_ar: "\u0645\u0631\u0628\u0639" },
+  { value: "rounded", label: "Rounded square", label_ar: "\u0645\u0631\u0628\u0639 \u0628\u0632\u0648\u0627\u064A\u0627 \u062F\u0627\u0626\u0631\u064A\u0629" },
+  { value: "circle", label: "Circle", label_ar: "\u062F\u0627\u0626\u0631\u0629" },
+  { value: "triangle", label: "Triangle", label_ar: "\u0645\u062B\u0644\u062B" }
+];
+var LOGO_SIZE_OPTIONS = [
+  { value: "small", label: "Small", label_ar: "\u0635\u063A\u064A\u0631" },
+  { value: "medium", label: "Medium", label_ar: "\u0645\u062A\u0648\u0633\u0637" },
+  { value: "large", label: "Large", label_ar: "\u0643\u0628\u064A\u0631" }
+];
+var SHAPED_PX = {
+  small: { plain: 32, rounded: 48 },
+  medium: { plain: 40, rounded: 64 },
+  large: { plain: 56, rounded: 80 }
+};
+function normalizeSize(size) {
+  return size === "large" || size === "medium" ? size : "small";
+}
+function logoImgStyle(shape, size) {
+  if (!shape || shape === "none") return void 0;
+  const s = normalizeSize(size);
+  const isRound = shape === "circle" || shape === "rounded";
+  const px = isRound ? SHAPED_PX[s].rounded : SHAPED_PX[s].plain;
+  const base = {
+    height: px,
+    width: px,
+    objectFit: "cover",
+    flex: "0 0 auto"
+  };
+  switch (shape) {
+    case "circle":
+      return { ...base, borderRadius: "9999px" };
+    case "rounded":
+      return { ...base, borderRadius: "0.5rem" };
+    case "triangle":
+      return { ...base, clipPath: "polygon(50% 0%, 100% 100%, 0% 100%)" };
+    case "square":
+    default:
+      return base;
+  }
+}
+function logoStyleTokens(shape, size) {
+  const style = logoImgStyle(shape, size);
+  if (!style) return {};
+  const box = `${style.height}px`;
+  return {
+    "--theme-logo-box": box,
+    "--theme-logo-radius": typeof style.borderRadius === "string" ? style.borderRadius : "0",
+    "--theme-logo-clip": typeof style.clipPath === "string" ? style.clipPath : "none"
+  };
+}
 
 // src/utils/styleTokens.ts
 var COLOR_ROLE_ALIASES = {
@@ -2076,6 +2528,12 @@ function computeGlobalStyleTokens(globalSettings) {
       pushHref(FONT_REGISTRY[value]?.href);
     }
   }
+  const gs = globalSettings;
+  const logoTokens = logoStyleTokens(
+    typeof gs.logo_shape === "string" ? gs.logo_shape : void 0,
+    typeof gs.logo_size === "string" ? gs.logo_size : void 0
+  );
+  for (const [k, v] of Object.entries(logoTokens)) cssVars[k] = v;
   return { cssVars, fontHrefs };
 }
 function applyGlobalStyleTokens(globalSettings, el) {
@@ -2118,6 +2576,16 @@ function pickDemo(ctx, themeSettings) {
   const t = themeSettings.templates;
   return !t || Object.keys(t).length === 0;
 }
+function wrapEntityProviders(app, pageData) {
+  let inner = app;
+  if (pageData.collection) {
+    inner = /* @__PURE__ */ jsxRuntime.jsx(CollectionProvider, { collection: pageData.collection, children: inner });
+  }
+  if (pageData.product) {
+    inner = /* @__PURE__ */ jsxRuntime.jsx(ProductProvider, { product: pageData.product, children: inner });
+  }
+  return inner;
+}
 var ThemeMountBridge = react.forwardRef(function ThemeMountBridge2({ ctx, mountEl, renderApp }, ref) {
   const [themeSettings, setThemeSettings] = react.useState(
     ctx.themeSettings
@@ -2158,7 +2626,7 @@ var ThemeMountBridge = react.forwardRef(function ThemeMountBridge2({ ctx, mountE
       initialProducts: pageData.products,
       initialCollections: pageData.collections,
       currentTemplate: template,
-      children: pageData.product ? /* @__PURE__ */ jsxRuntime.jsx(ProductProvider, { product: pageData.product, children: app }) : app
+      children: wrapEntityProviders(app, pageData)
     }
   );
 });
@@ -2194,9 +2662,6 @@ function defineThemeEntry(renderApp) {
     createApp: (ctx) => buildThemeElement(ctx, null, renderApp)
   };
 }
-function CollectionProvider({ collection, children }) {
-  return /* @__PURE__ */ jsxRuntime.jsx(CollectionContext.Provider, { value: collection, children });
-}
 function Money({
   amount,
   currency,
@@ -2347,6 +2812,43 @@ function Image({
     }
   );
 }
+var str = (v) => typeof v === "string" ? v : "";
+var NONE_HEIGHT = { small: 28, medium: 36, large: 48 };
+function Logo({
+  src,
+  alt,
+  shape,
+  size,
+  className,
+  style,
+  fallback
+}) {
+  const settings = useThemeSettings();
+  const shop = useShop();
+  const g = settings?.global_settings ?? {};
+  const url = str(src) || str(g.logo_url) || shop?.logo_url || "";
+  const resolvedShape = shape || str(g.logo_shape) || "none";
+  const resolvedSize = size || str(g.logo_size) || "small";
+  const altText = alt || str(g.brand_name) || shop?.name || "";
+  if (!url) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: fallback ?? null });
+  const shaped = resolvedShape !== "none";
+  const imgStyle = shaped ? { ...logoImgStyle(resolvedShape, resolvedSize), ...style } : {
+    height: NONE_HEIGHT[resolvedSize] ?? NONE_HEIGHT.small,
+    width: "auto",
+    objectFit: "contain",
+    ...style
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "img",
+    {
+      src: url,
+      alt: altText,
+      className,
+      style: imgStyle,
+      loading: "eager"
+    }
+  );
+}
 var ABSOLUTE_URL = /^[a-z]+:|^\/\//i;
 function Link({ to, children, ...rest }) {
   const shop = useShop();
@@ -3572,9 +4074,14 @@ 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.LOGO_SHAPE_OPTIONS = LOGO_SHAPE_OPTIONS;
+exports.LOGO_SIZE_OPTIONS = LOGO_SIZE_OPTIONS;
 exports.Link = Link;
 exports.LocaleSwitcher = LocaleSwitcher;
 exports.LocalizationContext = LocalizationContext;
+exports.Logo = Logo;
 exports.MAX_BLOCK_DEPTH = MAX_BLOCK_DEPTH;
 exports.Money = Money;
 exports.NavigationContext = NavigationContext;
@@ -3583,10 +4090,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 +4123,9 @@ exports.isDefinedBlock = isDefinedBlock;
 exports.isDefinedSection = isDefinedSection;
 exports.isDynamicSource = isDynamicSource;
 exports.isSdkAvailable = isSdkAvailable;
+exports.logoImgStyle = logoImgStyle;
+exports.logoStyleTokens = logoStyleTokens;
+exports.mergeResults = mergeResults;
 exports.mountTheme = mountTheme;
 exports.pickTranslations = pickTranslations;
 exports.registerReactSingleton = registerReactSingleton;
@@ -3664,5 +4177,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