@numueg/theme-sdk 0.2.2 → 0.3.1

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { S as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, g as ProductVariant } from './entities-iiuRSPpk.mjs';
-export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, h as ProductOption } from './entities-iiuRSPpk.mjs';
+import { i as Store, e as Product, b as Collection, C as Cart, c as Customer, P as Page, S as SizeChart, g as ProductVariant } from './entities-6MGANln7.mjs';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, j as ProductOption, h as SizeChartMode } from './entities-6MGANln7.mjs';
 import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-D0QybTQS.mjs';
 export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-D0QybTQS.mjs';
 import * as react from 'react';
-import { ReactNode, ElementType, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
+import { ReactNode, ReactElement, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.mjs';
 
 /**
@@ -744,6 +744,33 @@ declare function useRelatedProducts(productId: string | null | undefined, option
     limit?: number;
 }): RelatedProductsState;
 
+/**
+ * useProductSizeChart — resolve the size chart to show for a product.
+ *
+ * The merchant hub writes the per-product chart to
+ * `product.attributes.size_chart` and the store-wide default to
+ * `store.settings.size_chart`, with an explicit `mode`:
+ *
+ *   "off"     → never show, even if a store default exists
+ *   "custom"  → use the product's own chart
+ *   "default" → fall back to the store-wide chart
+ *   (legacy)  → no `mode`: a populated product chart wins, else the default
+ *
+ * This hook centralises that precedence so every theme resolves it identically
+ * (the backend `SizeChartSchema` validator and the hub editor share the same
+ * shape). Returns `null` when there is nothing to show — render the size-guide
+ * trigger only when this is non-null.
+ *
+ * @param productOverride - resolve against this product instead of the one in
+ *   context (e.g. when rendering a chart for a related/quick-view product).
+ */
+declare function useProductSizeChart(productOverride?: Product | null): SizeChart | null;
+/**
+ * Pure resolver (no React) — exported so non-hook code (SSR helpers, tests)
+ * can apply the same precedence.
+ */
+declare function resolveSizeChart(productAttributes: Record<string, unknown> | undefined, storeSettings: Record<string, unknown> | undefined): SizeChart | null;
+
 /**
  * Multi-currency presentment — Phase 6.
  *
@@ -1155,6 +1182,14 @@ interface ThemeMountContext {
     demo?: boolean;
     /** Store navigation menus keyed by handle, resolved server-side. */
     navigation?: Record<string, MenuItemData[]>;
+    /**
+     * Host signal that the container already holds server-rendered HTML for
+     * this exact ctx (produced via `createApp` from `defineThemeEntry`).
+     * `mountTheme` then adopts it with `hydrateRoot` instead of re-rendering
+     * from scratch. Ignored when the container is empty, so a host can pass
+     * it optimistically and still get a plain client mount on SSR failure.
+     */
+    hydrate?: boolean;
     [extra: string]: unknown;
 }
 /** Arguments handed to a theme's render callback on every (re)render. */
@@ -1170,17 +1205,81 @@ interface ThemeRenderArgs {
     /** Live theme settings (reflects customizer drafts via applyDraft). */
     themeSettings: ThemeSettingsV3;
 }
+interface DraftHandle {
+    applyDraft: (next: ThemeSettingsV3) => void;
+}
+/**
+ * Build the canonical theme element tree for a ctx. BOTH render paths go
+ * through here — `mountTheme` (client mount/hydrate) and `createApp`
+ * (host-side `renderToString`) — so the server markup and the hydration
+ * tree are the same React tree by construction. `mountEl` is a prop, not
+ * DOM output, so it differing between server (null) and client (the
+ * container) cannot cause a hydration mismatch.
+ */
+declare function buildThemeElement(ctx: ThemeMountContext, mountEl: HTMLElement | null, renderApp: (args: ThemeRenderArgs) => ReactNode, ref?: (h: DraftHandle | null) => void): ReactElement;
 /**
  * Mount a V3 theme. Owns the React root, the provider stack (catalog + nav +
  * style tokens), and the live-preview draft cycle. Returns the host-contract
  * `MountResult` (`cleanup` + `applyDraft`).
  *
+ * When the host passes `ctx.hydrate === true` and the container already
+ * holds server-rendered HTML (produced by this theme's `createApp` with the
+ * identical ctx), the tree is adopted via `hydrateRoot` — no re-render, no
+ * flash. An empty container downgrades to a plain client mount so hosts can
+ * pass the flag optimistically.
+ *
  * @param el        the host-supplied container element
  * @param ctx       the mount context (either host or legacy/dev shape)
  * @param renderApp returns the theme's section tree for the current args
  */
 declare function mountTheme(el: HTMLElement, ctx: ThemeMountContext, renderApp: (args: ThemeRenderArgs) => ReactNode): MountResult;
 
+/**
+ * `defineThemeEntry(renderApp)` — one-call theme entry that yields BOTH
+ * halves of the V3 contract from a single component:
+ *
+ *   - `mount(el, ctx)`   — the client entry every host already calls
+ *                          (now hydration-aware via `ctx.hydrate`).
+ *   - `createApp(ctx)`   — the same React tree as a plain element, so the
+ *                          host can `renderToString(createApp(ctx))` on the
+ *                          server and ship real HTML before any JS runs.
+ *
+ * ```tsx
+ * // src/main.tsx
+ * import { defineThemeEntry } from "@numueg/theme-sdk";
+ *
+ * const entry = defineThemeEntry(({ currentTemplate }) => (
+ *   <ThemeApp currentTemplate={currentTemplate} />
+ * ));
+ *
+ * export const mount = entry.mount;
+ * export const createApp = entry.createApp;
+ * ```
+ *
+ * Why both MUST come from one definition: hydration only succeeds when the
+ * server markup and the client tree are identical. Routing both through
+ * `buildThemeElement` makes that true by construction — a theme cannot
+ * accidentally ship a `createApp` that disagrees with its `mount`.
+ *
+ * Themes that only export `mount` keep working exactly as before; they are
+ * simply never server-rendered (the host detects the missing `createApp`
+ * and falls back to today's client-only mount).
+ */
+
+/** The pair of entry points a V3 theme bundle exports. */
+interface ThemeEntry {
+    /** Client entry — host contract `mount(el, ctx): MountResult`. */
+    mount: (el: HTMLElement, ctx: ThemeMountContext) => MountResult;
+    /**
+     * Server entry — returns the exact element tree `mount` would render,
+     * for host-side `renderToString`. Must stay side-effect free: no DOM
+     * access happens until React effects run (which they don't on the
+     * server).
+     */
+    createApp: (ctx: ThemeMountContext) => ReactElement;
+}
+declare function defineThemeEntry(renderApp: (args: ThemeRenderArgs) => ReactNode): ThemeEntry;
+
 interface NuMuProviderProps {
     store: Store;
     themeSettings: ThemeSettingsV3;
@@ -1263,6 +1362,78 @@ interface MoneyProps {
  */
 declare function Money({ amount, currency, compareAt, className, as, }: MoneyProps): react.ReactElement<any, string | react.JSXElementConstructor<any>>;
 
+/**
+ * Non-destructive image framing transform (focal / zoom / rotation).
+ *
+ * An image setting value may carry optional `transform` metadata
+ * (`{ url, alt, transform }`). The original asset is never modified — the
+ * storefront reproduces the framing purely from these numbers via CSS, so the
+ * SAME uploaded image can be framed differently per placement (hero vs card).
+ *
+ * Hoisted into the SDK (was duplicated in every theme's `_shared.ts` and in
+ * the merchant-hub editor's `imageTransform.ts`). The editor copy MUST stay
+ * equivalent so its preview matches the storefront render exactly.
+ */
+interface ImageTransform {
+    v: 1;
+    focal?: {
+        x: number;
+        y: number;
+    };
+    zoom?: number;
+    rotation?: number;
+    fit?: "cover" | "contain";
+}
+/** Read the transform off an image setting value (string | {url,alt,transform}). */
+declare function asImageTransform(v: unknown): ImageTransform | undefined;
+/**
+ * CSS reproducing the transform on an `<img>` that fills a fixed-aspect,
+ * overflow-hidden frame. Default fit is `cover` (Shopify-style: the image
+ * fills its frame, cropping to the focal point) — pass `"contain"` only for
+ * placements that must show the whole image (e.g. a logo). Empty object when
+ * there is no transform AND the caller wants the section's own className to
+ * decide; pass an explicit `fit` to force a default even without a transform.
+ */
+declare function applyImageTransform(t: ImageTransform | undefined | null, fit?: "cover" | "contain"): CSSProperties;
+/**
+ * focalSrc — build a URL for a server-side, focal-point-aware image transform.
+ *
+ * OPT-IN helper. A theme that wants a bandwidth-efficient SMART CROP for a big
+ * image (typically a hero) calls this to point the <img src> at the storefront's
+ * `/api/image-transform` endpoint with focal/aspect params. The endpoint honors
+ * them only when Cloudflare Image Resizing is enabled on the zone
+ * (NUMU_CF_IMAGE_RESIZING=1); otherwise it gracefully ignores them and serves a
+ * plain resized image — so the theme's CSS `applyImageTransform` framing remains
+ * the correctness baseline either way. This is purely a perf optimization.
+ *
+ * Returns a RELATIVE path (`/api/image-transform?...`) — the SDK runs
+ * same-origin inside the storefront, matching how <Form>/useShop build URLs.
+ *
+ * @example
+ *   <img
+ *     src={focalSrc(hero.url, { width: 1600, focal: t?.focal, aspect: "16/9" })}
+ *     style={applyImageTransform(t, "cover")}   // CSS still frames as fallback
+ *   />
+ */
+interface FocalSrcOptions {
+    /** Target width in px (e.g. 1600 for a desktop hero). Required for a crop. */
+    width?: number;
+    /** Focal point, normalized 0..1 (0.5,0.5 = center). */
+    focal?: {
+        x?: number;
+        y?: number;
+    };
+    /** Target aspect ratio "W/H" (e.g. "16/9"); drives the crop box height. */
+    aspect?: string;
+    /** Crop mode. Default "cover". */
+    fit?: "cover" | "contain";
+    /** Quality 1..100. */
+    quality?: number;
+    /** Output format. */
+    format?: "webp" | "avif" | "jpeg" | "jpg" | "png";
+}
+declare function focalSrc(url: string | null | undefined, options?: FocalSrcOptions): string;
+
 interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet"> {
     src: string | undefined | null;
     alt: string;
@@ -1283,6 +1454,29 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
      * "eager" for above-the-fold imagery.
      */
     loading?: "eager" | "lazy";
+    /**
+     * Shopify-style frame. When set (e.g. "3/4", "16/9", "1/1") the image is
+     * wrapped in a fixed-aspect, overflow-hidden box and the `<img>` fills it.
+     * Combined with `objectFit="cover"` (the default) this guarantees the image
+     * ALWAYS fits its frame — no letterboxing, no overflow — cropping to the
+     * focal point. Omit to render a bare `<img>` (legacy behavior).
+     */
+    aspectRatio?: string;
+    /**
+     * How the image fills its box. Default "cover" (fill + crop) — the merchant
+     * never sees a letterboxed/squashed image. Use "contain" for logos/badges
+     * that must show in full.
+     */
+    objectFit?: "cover" | "contain" | "fill" | "scale-down" | "none";
+    /** CSS object-position (e.g. "50% 50%"). Ignored if `transform` is set. */
+    objectPosition?: string;
+    /**
+     * Non-destructive focal/zoom/rotation metadata from the image setting value
+     * (`asImageTransform(setting)`). When present it drives object-fit +
+     * object-position + scale/rotate so the editor preview and the live render
+     * match exactly. Overrides `objectFit`/`objectPosition`.
+     */
+    transform?: ImageTransform | null;
 }
 /**
  * <Image> — drop-in replacement for `<img>` with srcSet + lazy loading
@@ -1293,7 +1487,7 @@ interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "
  * If `src` is empty/null, renders a placeholder div so the layout
  * doesn't shift while a merchant configures images in the customizer.
  */
-declare function Image({ src, alt, sizes, responsive, loading, className, style, ...rest }: ImageProps): react.JSX.Element;
+declare function Image({ src, alt, sizes, responsive, loading, aspectRatio, objectFit, objectPosition, transform, className, style, ...rest }: ImageProps): react.JSX.Element;
 
 interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
     /**
@@ -1993,45 +2187,6 @@ declare function collectBlocks<T extends Record<string, unknown>>(modules: T): R
  */
 declare function assetUrl(name: string): string;
 
-/**
- * focalSrc — build a URL for a server-side, focal-point-aware image transform.
- *
- * OPT-IN helper. A theme that wants a bandwidth-efficient SMART CROP for a big
- * image (typically a hero) calls this to point the <img src> at the storefront's
- * `/api/image-transform` endpoint with focal/aspect params. The endpoint honors
- * them only when Cloudflare Image Resizing is enabled on the zone
- * (NUMU_CF_IMAGE_RESIZING=1); otherwise it gracefully ignores them and serves a
- * plain resized image — so the theme's CSS `applyImageTransform` framing remains
- * the correctness baseline either way. This is purely a perf optimization.
- *
- * Returns a RELATIVE path (`/api/image-transform?...`) — the SDK runs
- * same-origin inside the storefront, matching how <Form>/useShop build URLs.
- *
- * @example
- *   <img
- *     src={focalSrc(hero.url, { width: 1600, focal: t?.focal, aspect: "16/9" })}
- *     style={applyImageTransform(t, "cover")}   // CSS still frames as fallback
- *   />
- */
-interface FocalSrcOptions {
-    /** Target width in px (e.g. 1600 for a desktop hero). Required for a crop. */
-    width?: number;
-    /** Focal point, normalized 0..1 (0.5,0.5 = center). */
-    focal?: {
-        x?: number;
-        y?: number;
-    };
-    /** Target aspect ratio "W/H" (e.g. "16/9"); drives the crop box height. */
-    aspect?: string;
-    /** Crop mode. Default "cover". */
-    fit?: "cover" | "contain";
-    /** Quality 1..100. */
-    quality?: number;
-    /** Output format. */
-    format?: "webp" | "avif" | "jpeg" | "jpg" | "png";
-}
-declare function focalSrc(url: string | null | undefined, options?: FocalSrcOptions): string;
-
 /**
  * `applyGlobalStyleTokens(globalSettings, el)` — Phase 3.5.
  *
@@ -2070,11 +2225,32 @@ type GlobalSettings = Record<string, unknown> | null | undefined;
  * family/stack the theme author supplied.
  */
 declare function resolveFontStack(value: string): string;
+/** Result of `computeGlobalStyleTokens` — everything a host needs to paint
+ *  global settings without a DOM. */
+interface ComputedStyleTokens {
+    /** CSS custom properties to set on the theme's mount root. */
+    cssVars: Record<string, string>;
+    /** Google-Fonts stylesheet hrefs for any registry fonts in use. */
+    fontHrefs: string[];
+}
+/**
+ * Pure half of `applyGlobalStyleTokens`: compute the exact CSS custom
+ * properties (and webfont hrefs) a settings object maps to, without touching
+ * any DOM. This is what lets a host SERVER-render a theme with the same vars
+ * the bundle applies on mount — both sides call this one function, so the
+ * values cannot drift (drift = unstyled flash or hydration noise).
+ *
+ * Includes the explicit `heading_font` / `body_font` resolution that
+ * `mountTheme` historically layered on top: any string value for those two
+ * ids resolves through the registry (or passes verbatim) so a picked font
+ * gets a real stack even when it isn't a known token.
+ */
+declare function computeGlobalStyleTokens(globalSettings: GlobalSettings): ComputedStyleTokens;
 /**
  * Map a store's global settings onto CSS custom properties on `el`. Call on
  * mount and on every `applyDraft` (live preview). No-op when `el` or the
  * settings are missing. Reserved `__`-prefixed keys (e.g. `__translations`)
- * are skipped.
+ * are skipped. Thin DOM shell over `computeGlobalStyleTokens`.
  */
 declare function applyGlobalStyleTokens(globalSettings: GlobalSettings, el: HTMLElement | null | undefined): void;
 
@@ -2136,4 +2312,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, CartContext, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionContext, CollectionProvider, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, CustomerContext, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, LocalizationContext, type MenuItemData, Money, MountResult, NavigationContext, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, PageContext, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductContext, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, ShopContext, type ShopWithHelpers, Store, type ThemeMountContext, type ThemeMountPage, type ThemeRenderArgs, ThemeSettingsContext, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, assetUrl, availableValues, buildLocaleBundle, clearSdkSingleton, collectBlocks, collectSections, defaultVariant, defineBlock, defineSection, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, Cart, CartContext, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionContext, CollectionProvider, type ComputedStyleTokens, type CurrencyConfig, type CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, CustomerContext, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type GiftCardBalance, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, Link, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, LocalizationContext, type MenuItemData, Money, MountResult, NavigationContext, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, PageContext, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductContext, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, ShopContext, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, type ThemeMountContext, type ThemeMountPage, type ThemeRenderArgs, ThemeSettingsContext, ThemeSettingsV3, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, buildThemeElement, clearSdkSingleton, collectBlocks, collectSections, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, mountTheme, pickTranslations, registerReactSingleton, registerSdkSingleton, resolveDynamicValue, resolveFontStack, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, useAnalytics, useApp, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useLocale, useLocalization, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };