@numueg/theme-sdk 0.2.2 → 0.2.3

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-C8B2U-V0.d.mts}

@@ -138,6 +138,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;

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

@@ -138,6 +138,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;

package/dist/index.cjs

@@ -1457,6 +1457,12 @@ function normalizeCartFromServer(cart) {
     items: Array.isArray(cart.items) ? cart.items.map((it) => ({ ...it, price: toMajor(it.price) })) : []
   };
 }
+function unwrapCart(json) {
+  if (json && typeof json === "object" && "data" in json && json.data && typeof json.data === "object") {
+    return json.data;
+  }
+  return json;
+}
 function readCsrfCookie() {
   if (typeof document === "undefined") return null;
   const match = document.cookie.match(/(?:^|;\s*)numu_csrf=([^;]+)/);
@@ -1476,8 +1482,8 @@ async function postCartMutation(endpoint, body, applyCart, reserveToken) {
     body: body === void 0 ? void 0 : JSON.stringify(body)
   });
   if (!res.ok) return;
-  const data = await res.json();
-  applyCart(data);
+  const json = await res.json();
+  applyCart(unwrapCart(json));
 }
 function NuMuProvider({
   store,
@@ -1657,7 +1663,8 @@ function NuMuProvider({
           cache: "no-store"
         });
         if (!res.ok || cancelled) return;
-        const data = await res.json();
+        const json = await res.json();
+        const data = unwrapCart(json);
         if (data && typeof data === "object") {
           setCart(normalizeCartFromServer(data));
         }
@@ -1704,11 +1711,32 @@ function NuMuProvider({
   );
   const addItem = react.useCallback(
     async (productId, variantId, quantity) => {
+      const eventId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}`;
+      const qty = quantity || 1;
       await mutate("/api/cart/add", {
         product_id: productId,
         variant_id: variantId,
-        quantity: quantity || 1
+        quantity: qty,
+        _event_id: eventId
       });
+      try {
+        if (typeof window !== "undefined") {
+          window.dispatchEvent(
+            new CustomEvent("numu:analytics:event", {
+              detail: {
+                event: "add_to_cart",
+                payload: {
+                  content_ids: [productId],
+                  content_type: "product",
+                  num_items: qty
+                },
+                event_id: eventId
+              }
+            })
+          );
+        }
+      } catch {
+      }
     },
     [mutate]
   );
@@ -2133,6 +2161,46 @@ function Money({
     children
   );
 }
+
+// src/utils/imageTransform.ts
+var _clampT = (n, lo, hi) => Math.min(hi, Math.max(lo, Number.isFinite(n) ? n : lo));
+function asImageTransform(v) {
+  if (v && typeof v === "object" && "transform" in v) {
+    const t = v.transform;
+    if (t && typeof t === "object") return t;
+  }
+  return void 0;
+}
+function applyImageTransform(t, fit = "cover") {
+  if (!t) return { objectFit: fit };
+  const fx = Math.round(_clampT(t.focal?.x ?? 0.5, 0, 1) * 1e4) / 100;
+  const fy = Math.round(_clampT(t.focal?.y ?? 0.5, 0, 1) * 1e4) / 100;
+  const zoom = _clampT(t.zoom ?? 1, 1, 4);
+  const rot = ((t.rotation ?? 0) % 360 + 360) % 360;
+  const effFit = t.fit ?? fit;
+  const style = {
+    transform: `scale(${zoom}) rotate(${rot}deg)`,
+    transformOrigin: `${fx}% ${fy}%`,
+    objectFit: effFit
+  };
+  if (effFit === "cover") style.objectPosition = `${fx}% ${fy}%`;
+  return style;
+}
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+function focalSrc(url, options = {}) {
+  if (!url) return "";
+  if (url.startsWith("data:") || /[?&](fp-x|fp-y)=/.test(url)) return url;
+  const p = new URLSearchParams();
+  p.set("url", url);
+  if (options.width) p.set("w", String(Math.round(options.width)));
+  if (options.focal?.x != null) p.set("fp-x", String(clamp01(options.focal.x)));
+  if (options.focal?.y != null) p.set("fp-y", String(clamp01(options.focal.y)));
+  if (options.aspect) p.set("ar", options.aspect);
+  if (options.fit) p.set("fit", options.fit);
+  if (options.quality) p.set("q", String(Math.min(100, Math.max(1, Math.round(options.quality)))));
+  if (options.format) p.set("f", options.format.toLowerCase());
+  return `/api/image-transform?${p.toString()}`;
+}
 var DEFAULT_WIDTHS2 = [320, 480, 640, 768, 1024, 1280, 1600, 1920];
 function buildSrcSet(src, widths = DEFAULT_WIDTHS2) {
   if (/[?&]w=\d+/.test(src)) return "";
@@ -2145,27 +2213,48 @@ function Image({
   sizes = "(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw",
   responsive = true,
   loading = "lazy",
+  aspectRatio,
+  objectFit,
+  objectPosition,
+  transform,
   className,
   style,
   ...rest
 }) {
+  const framed = Boolean(aspectRatio);
   if (!src) {
-    return /* @__PURE__ */ jsxRuntime.jsx(
+    const placeholder = /* @__PURE__ */ jsxRuntime.jsx(
       "div",
       {
-        className,
+        className: framed ? void 0 : className,
         role: "img",
         "aria-label": alt,
         style: {
           backgroundColor: "rgba(0,0,0,0.05)",
           display: "block",
-          ...style
+          width: "100%",
+          height: framed ? "100%" : void 0,
+          ...framed ? {} : style
         }
       }
     );
+    if (!framed) return placeholder;
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "span",
+      {
+        className,
+        style: { display: "block", aspectRatio, overflow: "hidden", ...style },
+        children: placeholder
+      }
+    );
   }
   const srcSet = responsive ? buildSrcSet(src) : void 0;
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const effFit = objectFit ?? (framed ? "cover" : void 0);
+  const fitStyle = transform ? applyImageTransform(transform, effFit === "contain" ? "contain" : "cover") : {
+    ...effFit ? { objectFit: effFit } : {},
+    ...objectPosition ? { objectPosition } : {}
+  };
+  const img = /* @__PURE__ */ jsxRuntime.jsx(
     "img",
     {
       src,
@@ -2174,11 +2263,27 @@ function Image({
       sizes: srcSet ? sizes : void 0,
       loading,
       decoding: "async",
-      className,
-      style,
+      className: framed ? void 0 : className,
+      style: framed ? { width: "100%", height: "100%", display: "block", ...fitStyle } : { ...fitStyle, ...style },
       ...rest
     }
   );
+  if (!framed) return img;
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "span",
+    {
+      className,
+      style: {
+        display: "block",
+        position: "relative",
+        width: "100%",
+        aspectRatio,
+        overflow: "hidden",
+        ...style
+      },
+      children: img
+    }
+  );
 }
 var ABSOLUTE_URL = /^[a-z]+:|^\/\//i;
 function Link({ to, children, ...rest }) {
@@ -3334,23 +3439,6 @@ function assetUrl(name) {
   return `${cleanBase}${filename}`;
 }
 
-// src/utils/imageTransform.ts
-var clamp01 = (n) => Math.min(1, Math.max(0, n));
-function focalSrc(url, options = {}) {
-  if (!url) return "";
-  if (url.startsWith("data:") || /[?&](fp-x|fp-y)=/.test(url)) return url;
-  const p = new URLSearchParams();
-  p.set("url", url);
-  if (options.width) p.set("w", String(Math.round(options.width)));
-  if (options.focal?.x != null) p.set("fp-x", String(clamp01(options.focal.x)));
-  if (options.focal?.y != null) p.set("fp-y", String(clamp01(options.focal.y)));
-  if (options.aspect) p.set("ar", options.aspect);
-  if (options.fit) p.set("fit", options.fit);
-  if (options.quality) p.set("q", String(Math.min(100, Math.max(1, Math.round(options.quality)))));
-  if (options.format) p.set("f", options.format.toLowerCase());
-  return `/api/image-transform?${p.toString()}`;
-}
-
 // src/utils/locales.ts
 function flattenMessages(source, prefix = "") {
   const out = {};
@@ -3427,6 +3515,8 @@ exports.SectionContext = SectionContext;
 exports.ShopContext = ShopContext;
 exports.ThemeSettingsContext = ThemeSettingsContext;
 exports.applyGlobalStyleTokens = applyGlobalStyleTokens;
+exports.applyImageTransform = applyImageTransform;
+exports.asImageTransform = asImageTransform;
 exports.assetUrl = assetUrl;
 exports.availableValues = availableValues;
 exports.buildLocaleBundle = buildLocaleBundle;