@numueg/theme-sdk 0.3.2 → 0.5.0

package/dist/mount-BN2mz_wx.d.ts

@@ -0,0 +1,225 @@
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { C as Cart, b as Collection, c as Customer, P as Page, e as Product, i as Store } from './entities-6MGANln7.js';
+import { T as ThemeSettingsV3, M as MountResult } from './theme-D0QybTQS.js';
+
+interface LocalizationState {
+    locale: string;
+    direction: "ltr" | "rtl";
+    translations: Record<string, string>;
+    formatMoney: (amount: number, currency?: string) => string;
+    formatDate: (date: string | Date) => string;
+    /**
+     * Phase 3.7 — locale-aware number formatter. Routes to either
+     * Western (1234) or Arab-Indic (١٢٣٤) digits depending on
+     * `store.settings.numerals`. Themes calling formatMoney get the
+     * same digit choice automatically; this is for raw counts ("12 items").
+     */
+    formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
+    /**
+     * Phase 3.6 — switch the active locale.
+     *
+     * Sets the `numu_locale` cookie and triggers a full page reload so
+     * the server-rendered layout picks up the new locale (the storefront
+     * resolves locale at SSR time from cookie/query). Returns once the
+     * cookie is written; the page navigation cancels any pending React
+     * work so callers don't need to await.
+     */
+    setLocale: (next: string) => void;
+    /**
+     * Phase 3.6 — list of locales the store advertises. Empty when the
+     * store hasn't configured a multi-locale catalog. Themes use this
+     * to decide whether to render the LocaleSwitcher at all.
+     */
+    availableLocales: string[];
+}
+declare const ShopContext: react.Context<Store | null>;
+declare const ProductContext: react.Context<Product | null>;
+declare const CollectionContext: react.Context<Collection | null>;
+declare const CartContext: react.Context<{
+    cart: Cart;
+    addItem: (productId: string, variantId?: string, quantity?: number) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    updateQuantity: (itemId: string, quantity: number) => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    updateNote: (note: string) => Promise<void>;
+    clearCart: () => Promise<void>;
+    loading: boolean;
+} | null>;
+declare const CustomerContext: react.Context<Customer | null>;
+declare const ThemeSettingsContext: react.Context<ThemeSettingsV3 | null>;
+declare const LocalizationContext: react.Context<LocalizationState | null>;
+declare const PageContext: react.Context<Page | null>;
+/**
+ * A merchant-managed navigation menu item, exactly as the storefront
+ * menus resolver returns it (`GET /storefront/store/{id}/menus`):
+ * bilingual `label`, a pre-resolved `url`, and nested `children`.
+ *
+ * This is the RAW shape the host injects via `NuMuProvider`'s
+ * `navigation` prop. `useNavigation(handle)` localizes it to the
+ * display-ready `NavigationItem` (a single `title` string for the
+ * active locale).
+ */
+interface MenuItemData {
+    id: string;
+    label: Record<string, string>;
+    url: string;
+    type?: string | null;
+    resource_id?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the item targets a CMS page
+     * (`/pages/<handle>`) that is currently unpublished or deleted. The backend
+     * menus resolver annotates it; absent/`true` means visible (back-compat).
+     */
+    target_visible?: boolean;
+    children?: MenuItemData[];
+}
+/**
+ * Phase 2.4 — navigation menus keyed by handle (`main-menu`, `footer`,
+ * plus custom), injected by the host from the storefront resolver so a
+ * theme's `useNavigation(handle)` resolves without a client round-trip.
+ *
+ * Defaults to `{}` — an empty map signals "host provided no menus", at
+ * which point `useNavigation` falls back to its own fetch / a theme's
+ * `DEFAULT_NAV`. A present-but-handle-absent map means the menu simply
+ * doesn't exist (render nothing / fallback), no fetch attempted.
+ */
+declare const NavigationContext: react.Context<Record<string, MenuItemData[]>>;
+
+/**
+ * `mountTheme(el, ctx, renderApp)` — the canonical V3 bundle entry helper.
+ *
+ * ## Why this exists
+ *
+ * Every theme bundle exports `mount(el, ctx): MountResult`. Historically each
+ * theme hand-wrote that function, and the wiring it needs is non-trivial and
+ * easy to get wrong:
+ *
+ *   1. **Forward the real catalog.** The host ships the page's products /
+ *      collections in `ctx.page.data` (home + listing routes) and the product
+ *      in `ctx.page.data.product` (PDP). A theme that doesn't pass these into
+ *      `NuMuProvider` (+ wrap the PDP in `<ProductProvider>`) sees
+ *      `useProducts()` / `useProductOptional()` return empty on a REAL store —
+ *      so product sections render "No products yet" or fall back to demo data
+ *      on a stocked merchant. This was the single most common BYOT bug:
+ *      only bon-younes wired it; the other 13 themes dropped the catalog.
+ *
+ *   2. **Apply global style tokens.** Merchant-chosen colors/fonts live in
+ *      `themeSettings.global_settings`; they only paint if the bundle calls
+ *      `applyGlobalStyleTokens` on its mount root (and resolves font tokens
+ *      to real stacks + injects the webfont link). Themes that skipped this
+ *      ignored every color/font picker.
+ *
+ *   3. **Forward navigation.** `useNavigation(handle)` only resolves the
+ *      header/footer menus the host pre-resolved if the bundle passes
+ *      `ctx.navigation` into `NuMuProvider`.
+ *
+ *   4. **Live-preview + lifecycle.** The customizer streams draft settings via
+ *      the host's `applyDraft`; the bundle must hold them in state and re-paint
+ *      the style tokens on every draft. And it must return a `MountResult`
+ *      (`cleanup` + `applyDraft`) the host's `ByotThemeBoundary` understands.
+ *
+ * `mountTheme` does all of that once, so a theme's `main.tsx` collapses to:
+ *
+ * ```tsx
+ * import { mountTheme } from "@numueg/theme-sdk";
+ * export function mount(el, ctx) {
+ *   return mountTheme(el, ctx, ({ currentTemplate }) =>
+ *     <ThemeApp currentTemplate={currentTemplate} />,
+ *   );
+ * }
+ * ```
+ *
+ * The theme owns only its section list (`ThemeApp`). Everything in the list
+ * above is handled here — fix it once, every theme benefits.
+ *
+ * ## Both ctx shapes
+ *
+ * The host (numu-storefront `ByotThemeBoundary`) passes
+ * `{ themeSettings, storeData, page, locale, demo, navigation }`. Older / dev
+ * contexts used `{ store, currentTemplate }`. We normalise both so a bundle
+ * built against this helper works regardless of which host calls it.
+ */
+
+/** Minimal page descriptor the host forwards in the mount context. */
+interface ThemeMountPage {
+    type?: string;
+    handle?: string;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * The mount context a host (or dev harness) passes to a bundle's `mount`.
+ * Accepts both the current storefront shape (`storeData`/`page`) and the
+ * legacy/dev shape (`store`/`currentTemplate`); `mountTheme` normalises them.
+ */
+interface ThemeMountContext {
+    storeData?: Store;
+    page?: ThemeMountPage;
+    store?: Store;
+    currentTemplate?: string;
+    themeSettings: ThemeSettingsV3;
+    initialCart?: Cart;
+    customer?: Customer | null;
+    locale?: string;
+    translations?: Record<string, string>;
+    /** AUTHORITATIVE marketplace-preview flag from the host (true only for the
+     *  catalog "Try theme" preview). Themes with demo-image fallbacks gate on
+     *  it so a real installed store never shows demo imagery. */
+    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. */
+interface ThemeRenderArgs {
+    /** Active template key — "home" | "product" | "collection" | "cart" | … */
+    currentTemplate: string;
+    /** Marketplace-preview flag (see ThemeMountContext.demo). */
+    demo: boolean;
+    /** The raw host page descriptor (type/handle/data), or null. */
+    page: ThemeMountPage | null;
+    /** Normalised store record (never undefined). */
+    store: Store;
+    /** 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;
+
+export { CartContext as C, type LocalizationState as L, type MenuItemData as M, NavigationContext as N, PageContext as P, ShopContext as S, type ThemeMountContext as T, type ThemeRenderArgs as a, CollectionContext as b, CustomerContext as c, LocalizationContext as d, ProductContext as e, type ThemeMountPage as f, ThemeSettingsContext as g, buildThemeElement as h, mountTheme as m };

package/dist/mount-DH9dz3dq.d.mts

@@ -0,0 +1,225 @@
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { C as Cart, b as Collection, c as Customer, P as Page, e as Product, i as Store } from './entities-6MGANln7.mjs';
+import { T as ThemeSettingsV3, M as MountResult } from './theme-D0QybTQS.mjs';
+
+interface LocalizationState {
+    locale: string;
+    direction: "ltr" | "rtl";
+    translations: Record<string, string>;
+    formatMoney: (amount: number, currency?: string) => string;
+    formatDate: (date: string | Date) => string;
+    /**
+     * Phase 3.7 — locale-aware number formatter. Routes to either
+     * Western (1234) or Arab-Indic (١٢٣٤) digits depending on
+     * `store.settings.numerals`. Themes calling formatMoney get the
+     * same digit choice automatically; this is for raw counts ("12 items").
+     */
+    formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
+    /**
+     * Phase 3.6 — switch the active locale.
+     *
+     * Sets the `numu_locale` cookie and triggers a full page reload so
+     * the server-rendered layout picks up the new locale (the storefront
+     * resolves locale at SSR time from cookie/query). Returns once the
+     * cookie is written; the page navigation cancels any pending React
+     * work so callers don't need to await.
+     */
+    setLocale: (next: string) => void;
+    /**
+     * Phase 3.6 — list of locales the store advertises. Empty when the
+     * store hasn't configured a multi-locale catalog. Themes use this
+     * to decide whether to render the LocaleSwitcher at all.
+     */
+    availableLocales: string[];
+}
+declare const ShopContext: react.Context<Store | null>;
+declare const ProductContext: react.Context<Product | null>;
+declare const CollectionContext: react.Context<Collection | null>;
+declare const CartContext: react.Context<{
+    cart: Cart;
+    addItem: (productId: string, variantId?: string, quantity?: number) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    updateQuantity: (itemId: string, quantity: number) => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    updateNote: (note: string) => Promise<void>;
+    clearCart: () => Promise<void>;
+    loading: boolean;
+} | null>;
+declare const CustomerContext: react.Context<Customer | null>;
+declare const ThemeSettingsContext: react.Context<ThemeSettingsV3 | null>;
+declare const LocalizationContext: react.Context<LocalizationState | null>;
+declare const PageContext: react.Context<Page | null>;
+/**
+ * A merchant-managed navigation menu item, exactly as the storefront
+ * menus resolver returns it (`GET /storefront/store/{id}/menus`):
+ * bilingual `label`, a pre-resolved `url`, and nested `children`.
+ *
+ * This is the RAW shape the host injects via `NuMuProvider`'s
+ * `navigation` prop. `useNavigation(handle)` localizes it to the
+ * display-ready `NavigationItem` (a single `title` string for the
+ * active locale).
+ */
+interface MenuItemData {
+    id: string;
+    label: Record<string, string>;
+    url: string;
+    type?: string | null;
+    resource_id?: string | null;
+    /**
+     * §5 hide-page → hide-nav-link. `false` when the item targets a CMS page
+     * (`/pages/<handle>`) that is currently unpublished or deleted. The backend
+     * menus resolver annotates it; absent/`true` means visible (back-compat).
+     */
+    target_visible?: boolean;
+    children?: MenuItemData[];
+}
+/**
+ * Phase 2.4 — navigation menus keyed by handle (`main-menu`, `footer`,
+ * plus custom), injected by the host from the storefront resolver so a
+ * theme's `useNavigation(handle)` resolves without a client round-trip.
+ *
+ * Defaults to `{}` — an empty map signals "host provided no menus", at
+ * which point `useNavigation` falls back to its own fetch / a theme's
+ * `DEFAULT_NAV`. A present-but-handle-absent map means the menu simply
+ * doesn't exist (render nothing / fallback), no fetch attempted.
+ */
+declare const NavigationContext: react.Context<Record<string, MenuItemData[]>>;
+
+/**
+ * `mountTheme(el, ctx, renderApp)` — the canonical V3 bundle entry helper.
+ *
+ * ## Why this exists
+ *
+ * Every theme bundle exports `mount(el, ctx): MountResult`. Historically each
+ * theme hand-wrote that function, and the wiring it needs is non-trivial and
+ * easy to get wrong:
+ *
+ *   1. **Forward the real catalog.** The host ships the page's products /
+ *      collections in `ctx.page.data` (home + listing routes) and the product
+ *      in `ctx.page.data.product` (PDP). A theme that doesn't pass these into
+ *      `NuMuProvider` (+ wrap the PDP in `<ProductProvider>`) sees
+ *      `useProducts()` / `useProductOptional()` return empty on a REAL store —
+ *      so product sections render "No products yet" or fall back to demo data
+ *      on a stocked merchant. This was the single most common BYOT bug:
+ *      only bon-younes wired it; the other 13 themes dropped the catalog.
+ *
+ *   2. **Apply global style tokens.** Merchant-chosen colors/fonts live in
+ *      `themeSettings.global_settings`; they only paint if the bundle calls
+ *      `applyGlobalStyleTokens` on its mount root (and resolves font tokens
+ *      to real stacks + injects the webfont link). Themes that skipped this
+ *      ignored every color/font picker.
+ *
+ *   3. **Forward navigation.** `useNavigation(handle)` only resolves the
+ *      header/footer menus the host pre-resolved if the bundle passes
+ *      `ctx.navigation` into `NuMuProvider`.
+ *
+ *   4. **Live-preview + lifecycle.** The customizer streams draft settings via
+ *      the host's `applyDraft`; the bundle must hold them in state and re-paint
+ *      the style tokens on every draft. And it must return a `MountResult`
+ *      (`cleanup` + `applyDraft`) the host's `ByotThemeBoundary` understands.
+ *
+ * `mountTheme` does all of that once, so a theme's `main.tsx` collapses to:
+ *
+ * ```tsx
+ * import { mountTheme } from "@numueg/theme-sdk";
+ * export function mount(el, ctx) {
+ *   return mountTheme(el, ctx, ({ currentTemplate }) =>
+ *     <ThemeApp currentTemplate={currentTemplate} />,
+ *   );
+ * }
+ * ```
+ *
+ * The theme owns only its section list (`ThemeApp`). Everything in the list
+ * above is handled here — fix it once, every theme benefits.
+ *
+ * ## Both ctx shapes
+ *
+ * The host (numu-storefront `ByotThemeBoundary`) passes
+ * `{ themeSettings, storeData, page, locale, demo, navigation }`. Older / dev
+ * contexts used `{ store, currentTemplate }`. We normalise both so a bundle
+ * built against this helper works regardless of which host calls it.
+ */
+
+/** Minimal page descriptor the host forwards in the mount context. */
+interface ThemeMountPage {
+    type?: string;
+    handle?: string;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * The mount context a host (or dev harness) passes to a bundle's `mount`.
+ * Accepts both the current storefront shape (`storeData`/`page`) and the
+ * legacy/dev shape (`store`/`currentTemplate`); `mountTheme` normalises them.
+ */
+interface ThemeMountContext {
+    storeData?: Store;
+    page?: ThemeMountPage;
+    store?: Store;
+    currentTemplate?: string;
+    themeSettings: ThemeSettingsV3;
+    initialCart?: Cart;
+    customer?: Customer | null;
+    locale?: string;
+    translations?: Record<string, string>;
+    /** AUTHORITATIVE marketplace-preview flag from the host (true only for the
+     *  catalog "Try theme" preview). Themes with demo-image fallbacks gate on
+     *  it so a real installed store never shows demo imagery. */
+    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. */
+interface ThemeRenderArgs {
+    /** Active template key — "home" | "product" | "collection" | "cart" | … */
+    currentTemplate: string;
+    /** Marketplace-preview flag (see ThemeMountContext.demo). */
+    demo: boolean;
+    /** The raw host page descriptor (type/handle/data), or null. */
+    page: ThemeMountPage | null;
+    /** Normalised store record (never undefined). */
+    store: Store;
+    /** 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;
+
+export { CartContext as C, type LocalizationState as L, type MenuItemData as M, NavigationContext as N, PageContext as P, ShopContext as S, type ThemeMountContext as T, type ThemeRenderArgs as a, CollectionContext as b, CustomerContext as c, LocalizationContext as d, ProductContext as e, type ThemeMountPage as f, ThemeSettingsContext as g, buildThemeElement as h, mountTheme as m };