@numueg/theme-sdk 0.2.2 → 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/README.md

@@ -5,7 +5,7 @@
 [![npm](https://img.shields.io/npm/v/@numueg/theme-sdk.svg)](https://www.npmjs.com/package/@numueg/theme-sdk)
 [![license](https://img.shields.io/npm/l/@numueg/theme-sdk.svg)](./LICENSE)
 
-The SDK every NUMU theme consumes. 25+ hooks (`useCart`, `useProduct`, `useCheckout`, `useVariantSelection`, `useGiftCardBalance`, …), 15+ components (`AddToCartButton`, `ProductCard`, `Money`, `Section`, `NuMuProvider`, …), and helpers for variant resolution, asset URLs, and federation singletons.
+The SDK every NUMU theme consumes. The `mountTheme()` runtime helper, 27+ hooks (`useCart`, `useProduct`, `useCheckout`, `useVariantSelection`, `useCurrentTemplate`, `useResolvedSettings`, …), 15+ components (`AddToCartButton`, `ProductCard`, `Money`, `Section`, `EditableText`/`EditableImage`, `NuMuProvider`, …), and helpers for variant resolution, focal image crops (`focalSrc`), global style tokens, asset URLs, and federation singletons.
 
 Themes import via the bare specifier `@numueg/theme-sdk` — at runtime the storefront's import map resolves it to the host-loaded singleton so every theme on the platform shares one React identity.
 
@@ -31,23 +31,23 @@ The `@numueg/theme-plugin` Vite plugin does this for you automatically.
 
 ## Usage
 
+The host storefront calls your bundle's `mount(el, ctx)` where `ctx = { storeData, page, themeSettings, locale, … }`. Use `mountTheme()` — it wires catalog data, global style tokens, navigation, and live-edit updates for you and returns the `{ unmount, update }` contract the host expects:
+
 ```tsx
-import { createRoot } from "react-dom/client";
-import { NuMuProvider, useCart, AddToCartButton } from "@numueg/theme-sdk";
-import type { MountContext } from "@numueg/theme-sdk";
+import { mountTheme, useCart } from "@numueg/theme-sdk";
 
 function App() {
   const { cart } = useCart();
   return <p>Items in cart: {cart.item_count}</p>;
 }
 
-export function mount(ctx: MountContext) {
-  const root = createRoot(document.getElementById("numu-root")!);
-  root.render(<NuMuProvider {...ctx}><App /></NuMuProvider>);
-  return () => root.unmount();
+export function mount(el: HTMLElement, ctx: unknown) {
+  return mountTheme(el, ctx, () => <App />);
 }
 ```
 
+> The authoritative `ctx` shape is defined by the host's `ByotThemeBoundary` (numu-storefront), not by SDK types — accept it as opaque and let `mountTheme`/`NuMuProvider` normalize it.
+
 ## Docs
 
 - [SDK Overview](https://numueg.app/docs/sdk/overview)

package/dist/{entities-iiuRSPpk.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;
@@ -138,6 +182,25 @@ interface Order {
     items: OrderItem[];
     created_at: string;
     shipping_address?: Address;
+    /**
+     * Discount code the customer applied at checkout, if any. Sourced from
+     * the backend order-detail (`GET /storefront/me/orders/{id}`). Themes
+     * render this on the order-confirmation / order-detail page.
+     */
+    coupon_code?: string | null;
+    /**
+     * Automatic offers (offers-v2 promotions) applied to the order. Each
+     * entry carries the localized title and the discount it contributed.
+     * `amount` is in integer cents — divide by 100 (or pass through
+     * `<Money>`) before display, consistent with the rest of the order's
+     * money fields.
+     */
+    applied_promotions?: {
+        id: string;
+        title: string;
+        title_ar?: string;
+        amount: number;
+    }[];
 }
 interface OrderItem {
     product_id: string;
@@ -162,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-iiuRSPpk.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;
@@ -138,6 +182,25 @@ interface Order {
     items: OrderItem[];
     created_at: string;
     shipping_address?: Address;
+    /**
+     * Discount code the customer applied at checkout, if any. Sourced from
+     * the backend order-detail (`GET /storefront/me/orders/{id}`). Themes
+     * render this on the order-confirmation / order-detail page.
+     */
+    coupon_code?: string | null;
+    /**
+     * Automatic offers (offers-v2 promotions) applied to the order. Each
+     * entry carries the localized title and the discount it contributed.
+     * `amount` is in integer cents — divide by 100 (or pass through
+     * `<Money>`) before display, consistent with the rest of the order's
+     * money fields.
+     */
+    applied_promotions?: {
+        id: string;
+        title: string;
+        title_ar?: string;
+        amount: number;
+    }[];
 }
 interface OrderItem {
     product_id: string;
@@ -162,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 };