@numueg/theme-sdk 0.2.3 → 0.3.1

package/CHANGELOG.md

@@ -4,7 +4,35 @@ All notable changes to `@numueg/theme-sdk` are documented here. The format is ba
 
 ## [Unreleased]
 
-## [0.1.0] - 2026-05-11
+## [0.3.1] - 2026-06-17
+
+### Added
+
+- **Size charts** — `useProductSizeChart()` hook + `resolveSizeChart()` pure
+  resolver. Resolves the per-product chart (`product.attributes.size_chart`)
+  against the store-wide default (`store.settings.size_chart`) using the same
+  precedence as the merchant hub + backend validator (`mode`:
+  `custom` → `default` → `off`, with a legacy no-mode fallback). New types
+  `SizeChart` / `SizeChartMode`.
+- `Product.attributes` and `Store.settings` are now typed (optional
+  `Record<string, unknown>`) — the storefront already forwards these JSONB
+  blobs (also used by `useFieldTranslation`); they were previously untyped.
+
+## [0.3.0] - 2026-06-10
+
+### Added
+
+- **`defineThemeEntry`** — one-call theme entry that returns both `mount`
+  (client, hydration-aware via `hydrateRoot`) and `createApp` (server
+  `renderToString`), wiring `NuMuProvider` + page/product/collection context +
+  catalog forwarding + global style tokens + the customizer's live-preview
+  draft cycle. This is the SSR contract for federated themes.
+
+### Changed
+
+- `mount()` adopts host-server-rendered HTML instead of re-rendering when the
+  host passes `hydrate: true`; pure, browser-free global-style-token compute so
+  the server render is deterministic.
 
 First public release. Full surface documented at [numueg.app/docs/sdk/overview](https://numueg.app/docs/sdk/overview).
 

package/dist/{entities-C8B2U-V0.d.mts → entities-6MGANln7.d.mts}

@@ -11,6 +11,14 @@ interface Store {
     default_language: string;
     use_nextjs_storefront: boolean;
     social_links?: Record<string, string>;
+    /**
+     * Store-level JSONB settings blob. Holds merchant-wide configuration the
+     * storefront forwards to themes — e.g. the store-wide default
+     * `size_chart` (see {@link SizeChart}) used when a product opts into
+     * `mode: "default"`. Untyped here because the shape grows independently
+     * of the SDK; narrow it at the read site.
+     */
+    settings?: Record<string, unknown>;
 }
 /** Product entity */
 interface Product {
@@ -30,6 +38,42 @@ interface Product {
     in_stock: boolean;
     seo_title?: string;
     seo_description?: string;
+    /**
+     * Per-product JSONB attribute blob the storefront forwards verbatim.
+     * Holds translated fields (`name_ar`, … — see `useFieldTranslation`) and
+     * the per-product `size_chart` ({@link SizeChart}). Untyped because the
+     * shape is open-ended; `useProductSizeChart` narrows the size-chart slot.
+     */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Size-chart resolution mode (mirrors the merchant hub's editor).
+ *
+ *   "custom"  → use the product's own chart
+ *   "default" → fall back to the store-wide chart (`store.settings.size_chart`)
+ *   "off"     → never show, even if a store default exists
+ */
+type SizeChartMode = "default" | "custom" | "off";
+/**
+ * A size / measurement chart, stored per-product at
+ * `product.attributes.size_chart` and store-wide at
+ * `store.settings.size_chart`. Resolve the two with {@link useProductSizeChart}
+ * instead of reading the raw blobs.
+ */
+interface SizeChart {
+    /** Legacy boolean kept for charts written before `mode` existed. */
+    enabled?: boolean;
+    mode?: SizeChartMode;
+    /** Column labels, e.g. ["Chest", "Waist", "Hip"]. */
+    column_headers: string[];
+    /** One row per size; `values` aligns to `column_headers`. */
+    rows: Array<{
+        size: string;
+        values: string[];
+    }>;
+    unit?: "cm" | "in" | "kg";
+    notes?: string;
+    image_url?: string;
 }
 interface ProductImage {
     id: string;
@@ -181,4 +225,4 @@ interface Page {
     data?: Record<string, any>;
 }
 
-export type { Address as A, Cart as C, Order as O, Page as P, Store as S, CartItem as a, Collection as b, Customer as c, OrderItem as d, Product as e, ProductImage as f, ProductVariant as g, ProductOption as h };
+export type { Address as A, Cart as C, Order as O, Page as P, SizeChart as S, CartItem as a, Collection as b, Customer as c, OrderItem as d, Product as e, ProductImage as f, ProductVariant as g, SizeChartMode as h, Store as i, ProductOption as j };

package/dist/{entities-C8B2U-V0.d.ts → entities-6MGANln7.d.ts}

@@ -11,6 +11,14 @@ interface Store {
     default_language: string;
     use_nextjs_storefront: boolean;
     social_links?: Record<string, string>;
+    /**
+     * Store-level JSONB settings blob. Holds merchant-wide configuration the
+     * storefront forwards to themes — e.g. the store-wide default
+     * `size_chart` (see {@link SizeChart}) used when a product opts into
+     * `mode: "default"`. Untyped here because the shape grows independently
+     * of the SDK; narrow it at the read site.
+     */
+    settings?: Record<string, unknown>;
 }
 /** Product entity */
 interface Product {
@@ -30,6 +38,42 @@ interface Product {
     in_stock: boolean;
     seo_title?: string;
     seo_description?: string;
+    /**
+     * Per-product JSONB attribute blob the storefront forwards verbatim.
+     * Holds translated fields (`name_ar`, … — see `useFieldTranslation`) and
+     * the per-product `size_chart` ({@link SizeChart}). Untyped because the
+     * shape is open-ended; `useProductSizeChart` narrows the size-chart slot.
+     */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Size-chart resolution mode (mirrors the merchant hub's editor).
+ *
+ *   "custom"  → use the product's own chart
+ *   "default" → fall back to the store-wide chart (`store.settings.size_chart`)
+ *   "off"     → never show, even if a store default exists
+ */
+type SizeChartMode = "default" | "custom" | "off";
+/**
+ * A size / measurement chart, stored per-product at
+ * `product.attributes.size_chart` and store-wide at
+ * `store.settings.size_chart`. Resolve the two with {@link useProductSizeChart}
+ * instead of reading the raw blobs.
+ */
+interface SizeChart {
+    /** Legacy boolean kept for charts written before `mode` existed. */
+    enabled?: boolean;
+    mode?: SizeChartMode;
+    /** Column labels, e.g. ["Chest", "Waist", "Hip"]. */
+    column_headers: string[];
+    /** One row per size; `values` aligns to `column_headers`. */
+    rows: Array<{
+        size: string;
+        values: string[];
+    }>;
+    unit?: "cm" | "in" | "kg";
+    notes?: string;
+    image_url?: string;
 }
 interface ProductImage {
     id: string;
@@ -181,4 +225,4 @@ interface Page {
     data?: Record<string, any>;
 }
 
-export type { Address as A, Cart as C, Order as O, Page as P, Store as S, CartItem as a, Collection as b, Customer as c, OrderItem as d, Product as e, ProductImage as f, ProductVariant as g, ProductOption as h };
+export type { Address as A, Cart as C, Order as O, Page as P, SizeChart as S, CartItem as a, Collection as b, Customer as c, OrderItem as d, Product as e, ProductImage as f, ProductVariant as g, SizeChartMode as h, Store as i, ProductOption as j };

package/dist/index.cjs

@@ -942,6 +942,29 @@ function useRelatedProducts(productId, options = {}) {
   }, [productId, limit]);
   return { items, loading, error };
 }
+function useProductSizeChart(productOverride) {
+  const ctxProduct = useProductOptional();
+  const product = productOverride ?? ctxProduct;
+  const shop = useShop();
+  const storeSettings = shop?.settings;
+  return react.useMemo(
+    () => resolveSizeChart(product?.attributes, storeSettings),
+    [product?.attributes, storeSettings]
+  );
+}
+function hasRows(c) {
+  return !!c && typeof c === "object" && Array.isArray(c.rows) && c.rows.length > 0;
+}
+function resolveSizeChart(productAttributes, storeSettings) {
+  const product = productAttributes?.size_chart;
+  const storeDefault = storeSettings?.size_chart;
+  if (product?.mode === "off") return null;
+  if (product?.mode === "custom") return hasRows(product) ? product : null;
+  if (product?.mode === "default") return hasRows(storeDefault) ? storeDefault : null;
+  if (hasRows(product)) return product;
+  if (hasRows(storeDefault)) return storeDefault;
+  return null;
+}
 var COOKIE_NAME = "numu_currency";
 var COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
 function readCookie(name) {
@@ -1991,6 +2014,9 @@ function injectFontLink(href) {
   link.setAttribute("data-numu-font", "");
   document.head.appendChild(link);
 }
+function lookupFontStack(value) {
+  return FONT_REGISTRY[value]?.stack ?? value;
+}
 function resolveFontStack(value) {
   const entry = FONT_REGISTRY[value];
   if (entry) {
@@ -1999,39 +2025,69 @@ function resolveFontStack(value) {
   }
   return value;
 }
-function applyGlobalStyleTokens(globalSettings, el) {
-  if (!el || !globalSettings || typeof globalSettings !== "object") return;
-  const style = el.style;
+function computeGlobalStyleTokens(globalSettings) {
+  const cssVars = {};
+  const fontHrefs = [];
+  if (!globalSettings || typeof globalSettings !== "object") {
+    return { cssVars, fontHrefs };
+  }
+  const pushHref = (href) => {
+    if (href && !fontHrefs.includes(href)) fontHrefs.push(href);
+  };
   for (const [key, value] of Object.entries(globalSettings)) {
     if (!key || key.startsWith("__")) continue;
     if (value && typeof value === "object" && !Array.isArray(value)) {
       for (const [role, c] of Object.entries(value)) {
-        if (isColorValue(c)) style.setProperty(`--scheme-${key}-${role}`, c);
+        if (isColorValue(c)) cssVars[`--scheme-${key}-${role}`] = c;
       }
       continue;
     }
     if (isColorValue(value)) {
-      style.setProperty(`--theme-${key}`, value.trim());
+      cssVars[`--theme-${key}`] = value.trim();
       const role = COLOR_ROLE_ALIASES[key];
-      if (role) style.setProperty(`--theme-color-${role}`, value.trim());
+      if (role) cssVars[`--theme-color-${role}`] = value.trim();
       continue;
     }
     if (isFontToken(value)) {
-      const stack = resolveFontStack(value);
-      style.setProperty(`--theme-${key}`, stack);
+      const entry = FONT_REGISTRY[value];
+      cssVars[`--theme-${key}`] = entry.stack;
       const role = FONT_ROLE_ALIASES[key];
-      if (role) style.setProperty(`--theme-font-${role}`, stack);
+      if (role) cssVars[`--theme-font-${role}`] = entry.stack;
+      pushHref(entry.href);
       continue;
     }
     if (typeof value === "string" || typeof value === "number") {
       const v = String(value).trim();
-      if (v) style.setProperty(`--theme-${key}`, v);
+      if (v) cssVars[`--theme-${key}`] = v;
+    }
+  }
+  for (const id of ["heading_font", "body_font"]) {
+    const value = globalSettings[id];
+    if (typeof value === "string" && value.trim()) {
+      cssVars[`--theme-${id}`] = lookupFontStack(value);
+      pushHref(FONT_REGISTRY[value]?.href);
     }
   }
+  return { cssVars, fontHrefs };
+}
+function applyGlobalStyleTokens(globalSettings, el) {
+  if (!el || !globalSettings || typeof globalSettings !== "object") return;
+  const { cssVars, fontHrefs } = computeGlobalStyleTokens(globalSettings);
+  const style = el.style;
+  for (const [prop, value] of Object.entries(cssVars)) {
+    style.setProperty(prop, value);
+  }
+  for (const href of fontHrefs) injectFontLink(href);
 }
 function pickStore(ctx) {
   const s = ctx.storeData ?? ctx.store;
-  if (s) return s;
+  if (s) {
+    const raw = s;
+    if (!raw.currency && raw.default_currency) {
+      return { ...raw, currency: raw.default_currency };
+    }
+    return s;
+  }
   return {
     id: "unknown",
     name: "Store",
@@ -2066,19 +2122,9 @@ var ThemeMountBridge = react.forwardRef(function ThemeMountBridge2({ ctx, mountE
     []
   );
   react.useEffect(() => {
+    if (!mountEl) return;
     const gs = themeSettings.global_settings ?? {};
     applyGlobalStyleTokens(gs, mountEl);
-    const headingFont = gs.heading_font;
-    if (typeof headingFont === "string" && headingFont.trim()) {
-      mountEl.style.setProperty(
-        "--theme-heading_font",
-        resolveFontStack(headingFont)
-      );
-    }
-    const bodyFont = gs.body_font;
-    if (typeof bodyFont === "string" && bodyFont.trim()) {
-      mountEl.style.setProperty("--theme-body_font", resolveFontStack(bodyFont));
-    }
   }, [themeSettings, mountEl]);
   const store = pickStore(ctx);
   const template = pickTemplate(ctx);
@@ -2108,22 +2154,22 @@ var ThemeMountBridge = react.forwardRef(function ThemeMountBridge2({ ctx, mountE
     }
   );
 });
+function buildThemeElement(ctx, mountEl, renderApp, ref) {
+  return /* @__PURE__ */ jsxRuntime.jsx(react.StrictMode, { children: /* @__PURE__ */ jsxRuntime.jsx(ThemeMountBridge, { ctx, mountEl, renderApp, ref }) });
+}
 function mountTheme(el, ctx, renderApp) {
-  const root = client.createRoot(el);
   const handleRef = { current: null };
-  root.render(
-    /* @__PURE__ */ jsxRuntime.jsx(react.StrictMode, { children: /* @__PURE__ */ jsxRuntime.jsx(
-      ThemeMountBridge,
-      {
-        ctx,
-        mountEl: el,
-        renderApp,
-        ref: (h) => {
-          handleRef.current = h;
-        }
-      }
-    ) })
-  );
+  const element = buildThemeElement(ctx, el, renderApp, (h) => {
+    handleRef.current = h;
+  });
+  const shouldHydrate = ctx.hydrate === true && el.firstElementChild !== null;
+  let root;
+  if (shouldHydrate) {
+    root = client.hydrateRoot(el, element);
+  } else {
+    root = client.createRoot(el);
+    root.render(element);
+  }
   return {
     applyDraft: (next) => handleRef.current?.applyDraft(next),
     cleanup: () => {
@@ -2132,6 +2178,14 @@ function mountTheme(el, ctx, renderApp) {
     }
   };
 }
+
+// src/entry.tsx
+function defineThemeEntry(renderApp) {
+  return {
+    mount: (el, ctx) => mountTheme(el, ctx, renderApp),
+    createApp: (ctx) => buildThemeElement(ctx, null, renderApp)
+  };
+}
 function CollectionProvider({ collection, children }) {
   return /* @__PURE__ */ jsxRuntime.jsx(CollectionContext.Provider, { value: collection, children });
 }
@@ -2755,7 +2809,14 @@ function sanitizeHtmlServer(input) {
   return s;
 }
 function RichText({ html, className, as = "div" }) {
-  const safe = react.useMemo(() => sanitizeHtml(html || ""), [html]);
+  const [domReady, setDomReady] = react.useState(false);
+  react.useEffect(() => {
+    setDomReady(true);
+  }, []);
+  const safe = react.useMemo(
+    () => domReady ? sanitizeHtml(html || "") : sanitizeHtmlServer(html || ""),
+    [html, domReady]
+  );
   if (!safe) return null;
   const Tag = as;
   return /* @__PURE__ */ jsxRuntime.jsx(
@@ -3421,8 +3482,13 @@ function collectBlocks(modules) {
 
 // src/utils/assetUrl.ts
 function getRuntime() {
-  if (typeof window === "undefined") return {};
-  return window;
+  if (typeof window !== "undefined") {
+    return window;
+  }
+  if (typeof globalThis !== "undefined") {
+    return globalThis;
+  }
+  return {};
 }
 function assetUrl(name) {
   if (!name) return "";
@@ -3520,12 +3586,15 @@ exports.asImageTransform = asImageTransform;
 exports.assetUrl = assetUrl;
 exports.availableValues = availableValues;
 exports.buildLocaleBundle = buildLocaleBundle;
+exports.buildThemeElement = buildThemeElement;
 exports.clearSdkSingleton = clearSdkSingleton;
 exports.collectBlocks = collectBlocks;
 exports.collectSections = collectSections;
+exports.computeGlobalStyleTokens = computeGlobalStyleTokens;
 exports.defaultVariant = defaultVariant;
 exports.defineBlock = defineBlock;
 exports.defineSection = defineSection;
+exports.defineThemeEntry = defineThemeEntry;
 exports.dynamicSource = dynamicSource;
 exports.findVariantByOptions = findVariantByOptions;
 exports.flattenMessages = flattenMessages;
@@ -3543,6 +3612,7 @@ exports.registerSdkSingleton = registerSdkSingleton;
 exports.resolveDynamicValue = resolveDynamicValue;
 exports.resolveFontStack = resolveFontStack;
 exports.resolveSettingsMap = resolveSettingsMap;
+exports.resolveSizeChart = resolveSizeChart;
 exports.resolveSourcePath = resolveSourcePath;
 exports.resolveThemeSettings = resolveThemeSettings;
 exports.sanitizeHtml = sanitizeHtml;
@@ -3572,6 +3642,7 @@ exports.useOrders = useOrders;
 exports.usePage = usePage;
 exports.useProduct = useProduct;
 exports.useProductOptional = useProductOptional;
+exports.useProductSizeChart = useProductSizeChart;
 exports.useProducts = useProducts;
 exports.useRelatedProducts = useRelatedProducts;
 exports.useReorder = useReorder;