@tribe-nest/forge 1.13.0

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -0,0 +1,208 @@
+import { useEffect, useRef } from "react";
+import { useTrackEvent, newEventId } from "../../data/queries/useAnalytics";
+import { useSiteConfig } from "../../data/queries/useWebsite";
+import { initMetaPixelScoped, fireMetaEventSingle } from "../../utils/metaPixel";
+import { setCurrentPageEventId, isProfilePixelSuppressed } from "../../utils/analyticsBus";
+import { useCookieConsent } from "../headless/consent/useCookieConsent";
+
+export interface ForgeAnalyticsProps {
+  /**
+   * The tenant's Meta Pixel id. When set, the pixel is initialised once and a
+   * `PageView` is fired (with an event id for CAPI de-duping) on every route
+   * change. **Omit** to auto-resolve it from the tenant's runtime settings
+   * (`useSiteConfig().metaPixelId`) so changing the pixel needs no rebuild; pass
+   * `""` to explicitly disable it.
+   */
+  metaPixelId?: string;
+  /** Auto-track clicks on links/buttons (and any `[data-track]` element). Default `true`. */
+  trackClicks?: boolean;
+  /** Master switch — set `false` (e.g. in the editor/preview) to record nothing. Default `true`. */
+  enabled?: boolean;
+  /**
+   * Honour the visitor's cookie choice (from `<CookieConsent />`). Default
+   * `true`: first-party analytics wait for `performance` consent and the Meta
+   * Pixel waits for `marketing` consent, so nothing fires until the visitor
+   * opts in. Set `false` to track unconditionally (only where a banner isn't
+   * legally required).
+   */
+  requireConsent?: boolean;
+  /**
+   * How first-party (non-Meta) analytics behaves:
+   * - `"consent"` (default): gated on `performance` consent; stores a session id
+   *   in `sessionStorage` for accurate per-session visits.
+   * - `"cookieless"`: Plausible-style. Always runs; with no `performance`
+   *   consent it stores nothing (the backend derives a rotating per-day visitor
+   *   hash), and once the visitor turns Performance on it upgrades to a stored
+   *   `sessionStorage` session for more precise visits. Choose this so analytics
+   *   works out of the box without storage consent, but improves with it.
+   *
+   * The Meta Pixel is always gated on `marketing` consent regardless of this.
+   */
+  firstPartyMode?: "consent" | "cookieless";
+}
+
+/**
+ * The full resolved path the visitor is on (e.g. `/i/store/abc-123`) — never a
+ * route template like `store/:id`. This is the value the admin analytics "top
+ * pages" report groups on (`event_data->>'pathname'`), so a code site's real
+ * routes show up per-page instead of collapsed into a parameterised template.
+ */
+function currentPathname(): string {
+  if (typeof window === "undefined") return "";
+  return window.location.pathname;
+}
+
+/** Full route including query — kept alongside `pathname` for detail. */
+function currentPage(): string {
+  if (typeof window === "undefined") return "";
+  return window.location.pathname + window.location.search;
+}
+
+/**
+ * Drop-in website analytics. Render once, high in the tree (inside
+ * `ForgeProvider`), and it wires the site into the platform's analytics:
+ *
+ * - Auto page views on every navigation → `POST /public/websites/track-event`,
+ *   surfaced in the admin analytics dashboard (visits, pages, geo).
+ * - Auto click tracking on links/buttons (opt out with `trackClicks={false}`).
+ * - Optional Meta Pixel: pass `metaPixelId` to init the pixel and mirror each
+ *   page view as a Meta `PageView` (event-id matched for CAPI de-dup).
+ *
+ * Consent-aware: with `requireConsent` (default), it reads the shared cookie
+ * consent — first-party analytics wait for `performance`, the Meta Pixel waits
+ * for `marketing` — so pairing it with `<CookieConsent />` is GDPR-correct out
+ * of the box. Router-agnostic: SPA navigations are detected via the History API,
+ * so it works under any router (or none). It renders nothing.
+ *
+ *     <ForgeAnalytics metaPixelId={META_PIXEL_ID} />
+ */
+export function ForgeAnalytics({
+  metaPixelId,
+  trackClicks = true,
+  enabled = true,
+  requireConsent = true,
+  firstPartyMode = "consent",
+}: ForgeAnalyticsProps) {
+  const cookieless = firstPartyMode === "cookieless";
+  // Resolve the pixel from the tenant's runtime settings when not explicitly
+  // passed (so changing it needs no rebuild). An explicit prop — including `""`
+  // to disable — always wins.
+  const { data: siteConfig } = useSiteConfig();
+  const pixelId = metaPixelId ?? siteConfig?.metaPixelId ?? undefined;
+  const { performance: perfConsent, marketing: mktConsent } = useCookieConsent();
+  // Session storage follows performance consent. In `consent` mode first-party
+  // only runs with that consent, so it always stores; in `cookieless` mode it
+  // runs regardless but only stores a device session once the visitor turns
+  // Performance on — otherwise it stays cookieless (backend derives the id).
+  const storeSession = cookieless ? perfConsent : true;
+  const { track } = useTrackEvent({ storeSession });
+  const lastPage = useRef<string | null>(null);
+
+  // Consent gates. The Meta Pixel always needs `marketing`. First-party analytics
+  // needs `performance` — UNLESS it's cookieless (stores nothing without consent),
+  // in which case it's treated as essential and runs anyway. Flipping a gate to
+  // `true` (visitor accepts) re-runs the effects, recording the current page.
+  const firstPartyOn = enabled && (cookieless || !requireConsent || perfConsent);
+  const metaOn = enabled && !!pixelId && (!requireConsent || mktConsent);
+
+  // Init the Meta pixel once (scoped — no auto PageView; we fire it ourselves so
+  // it doesn't leak into a per-page campaign pixel).
+  useEffect(() => {
+    if (!metaOn || !pixelId) return;
+    initMetaPixelScoped(pixelId);
+  }, [metaOn, pixelId]);
+
+  // Page-view tracking on initial load + every SPA navigation. We detect
+  // navigation by patching pushState/replaceState and listening for popstate,
+  // which keeps this free of any router dependency.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    if (!firstPartyOn && !metaOn) return; // nothing consented yet — wait
+
+    const sendPageView = () => {
+      const page = currentPage();
+      if (page === lastPage.current) return; // de-dupe repeated fires for the same URL
+      lastPage.current = page;
+
+      const eventId = newEventId();
+      // Publish the id so a per-page <PageMetaPixel/> (and its server CAPI twin)
+      // can dedupe against the same page view.
+      setCurrentPageEventId(eventId);
+      if (firstPartyOn) {
+        track("page_view", {
+          // `pathname` (full resolved path) is what the admin "top pages" report
+          // groups on; `page` keeps the query string for detail.
+          pathname: currentPathname(),
+          page,
+          pageTitle: typeof document !== "undefined" ? document.title : undefined,
+          referrer: typeof document !== "undefined" ? document.referrer || undefined : undefined,
+          eventId,
+        });
+      }
+      // Fire the profile pixel to ITSELF (trackSingle), and skip it on routes a
+      // campaign pixel has taken over (PageMetaPixel override). Deferred a tick
+      // so a page pixel mounting on this route can register its suppression first.
+      if (metaOn && pixelId) {
+        const path = currentPathname();
+        const pixel = pixelId;
+        queueMicrotask(() => {
+          if (!isProfilePixelSuppressed(path)) fireMetaEventSingle(pixel, "PageView", {}, eventId);
+        });
+      }
+    };
+
+    // Wrap the history methods so programmatic navigations emit an event.
+    const origPush = window.history.pushState;
+    const origReplace = window.history.replaceState;
+    const emit = () => window.dispatchEvent(new Event("forge:locationchange"));
+    window.history.pushState = function (...args) {
+      const r = origPush.apply(this, args as Parameters<typeof origPush>);
+      emit();
+      return r;
+    };
+    window.history.replaceState = function (...args) {
+      const r = origReplace.apply(this, args as Parameters<typeof origReplace>);
+      emit();
+      return r;
+    };
+    window.addEventListener("popstate", sendPageView);
+    window.addEventListener("forge:locationchange", sendPageView);
+
+    sendPageView(); // initial page
+
+    return () => {
+      window.history.pushState = origPush;
+      window.history.replaceState = origReplace;
+      window.removeEventListener("popstate", sendPageView);
+      window.removeEventListener("forge:locationchange", sendPageView);
+    };
+  }, [firstPartyOn, metaOn, pixelId, track]);
+
+  // Click tracking — first-party only, one delegated listener for the document.
+  useEffect(() => {
+    if (!firstPartyOn || !trackClicks || typeof document === "undefined") return;
+
+    const onClick = (e: MouseEvent) => {
+      const start = e.target as Element | null;
+      if (!start) return;
+      const el = start.closest("a,button,[data-track]") as HTMLElement | null;
+      if (!el) return;
+
+      const anchor = el.closest("a") as HTMLAnchorElement | null;
+      const text = (el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 120) || undefined;
+      track("click", {
+        pathname: currentPathname(),
+        page: currentPage(),
+        elementType: el.tagName.toLowerCase(),
+        text,
+        href: anchor?.href || undefined,
+        id: el.id || el.getAttribute("data-track") || undefined,
+      });
+    };
+
+    document.addEventListener("click", onClick, { capture: true });
+    return () => document.removeEventListener("click", onClick, { capture: true });
+  }, [firstPartyOn, trackClicks, track]);
+
+  return null;
+}

package/src/ui/analytics/PageMetaPixel.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useLayoutEffect } from "react";
+import { initMetaPixelScoped, fireMetaEventSingle } from "../../utils/metaPixel";
+import {
+  getCurrentPageEventId,
+  suppressProfilePixel,
+  unsuppressProfilePixel,
+} from "../../utils/analyticsBus";
+import { useCookieConsent } from "../headless/consent/useCookieConsent";
+
+// useLayoutEffect warns during SSR; fall back to useEffect on the server.
+const useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+export interface PageMetaPixelProps {
+  /** The campaign pixel id for this page (a public Meta Pixel id). */
+  pixelId: string;
+  /** Fire a `PageView` to this pixel on mount. Default `true`. */
+  trackPageView?: boolean;
+  /** Gate on the visitor's `marketing` cookie consent. Default `true`. */
+  requireConsent?: boolean;
+  /**
+   * Suppress the global profile pixel's PageView on this route so only the
+   * campaign pixel fires here. Default `true`. Set `false` to fire both.
+   */
+  overrideProfilePixel?: boolean;
+}
+
+/**
+ * Per-page Meta Pixel for an AI-built landing / smart-link page. Drop it on the
+ * page with a campaign `pixelId`; it initialises that pixel and fires a
+ * `PageView` to it (reusing the current page view's event id so it dedupes with
+ * the server-side Custom Page CAPI event). By default it takes over from the
+ * site-wide profile pixel on this route. Fire conversion events (`Lead`,
+ * `ViewContent`, …) on CTAs via `usePageMetaPixel`.
+ *
+ *     <PageMetaPixel pixelId="123456789" />
+ *
+ * Renders nothing.
+ */
+export function PageMetaPixel({
+  pixelId,
+  trackPageView = true,
+  requireConsent = true,
+  overrideProfilePixel = true,
+}: PageMetaPixelProps) {
+  const { marketing } = useCookieConsent();
+  const allowed = !requireConsent || marketing;
+
+  // Register suppression before ForgeAnalytics' deferred profile-pixel fire runs.
+  useIsoLayoutEffect(() => {
+    if (!overrideProfilePixel || typeof window === "undefined") return;
+    const path = window.location.pathname;
+    suppressProfilePixel(path);
+    return () => unsuppressProfilePixel(path);
+  }, [overrideProfilePixel]);
+
+  useEffect(() => {
+    if (!allowed || !pixelId || typeof window === "undefined") return;
+    initMetaPixelScoped(pixelId);
+    if (trackPageView) {
+      fireMetaEventSingle(pixelId, "PageView", {}, getCurrentPageEventId() ?? undefined);
+    }
+  }, [allowed, pixelId, trackPageView]);
+
+  return null;
+}
+
+/**
+ * Imperative companion to `<PageMetaPixel/>` — returns `fire(event, data?)` to
+ * send conversion events (e.g. `Lead` on a CTA click) to the campaign pixel,
+ * gated on marketing consent and reusing the current page view's event id.
+ *
+ *     const { fire } = usePageMetaPixel("123456789");
+ *     <button onClick={() => fire("Lead", { content_name: "Pre-save" })}>…</button>
+ */
+export function usePageMetaPixel(pixelId: string, opts?: { requireConsent?: boolean }) {
+  const requireConsent = opts?.requireConsent ?? true;
+  const { marketing } = useCookieConsent();
+  const allowed = !requireConsent || marketing;
+
+  useEffect(() => {
+    if (!allowed || !pixelId) return;
+    initMetaPixelScoped(pixelId);
+  }, [allowed, pixelId]);
+
+  return {
+    allowed,
+    fire: (eventName: string, data: Record<string, unknown> = {}) => {
+      if (!allowed || !pixelId) return;
+      fireMetaEventSingle(pixelId, eventName, data, getCurrentPageEventId() ?? undefined);
+    },
+  };
+}

package/src/ui/content/Editable.tsx

@@ -0,0 +1,90 @@
+import type { CSSProperties, ElementType, ReactNode } from "react";
+import { useField } from "../../content/useField";
+import type { ImageValue } from "../../content/types";
+
+// Editable wrappers — the convenient way to bind content fields. Each registers
+// a field via `useField` and renders its resolved value, spreading `fieldProps`
+// so the visual overlay can locate it in edit mode (empty in published builds).
+
+export type EditableTextProps = {
+  /** The bound field path, e.g. "home.hero.title". */
+  field: string;
+  /** Rendered until the creator edits this field. */
+  default?: string;
+  /** The element to render (default: span). */
+  as?: ElementType;
+  /** Human label for the field panel; falls back to the path. */
+  label?: string;
+  localized?: boolean;
+  style?: CSSProperties;
+  className?: string;
+};
+
+export function EditableText({
+  field,
+  default: def = "",
+  as: Tag = "span",
+  label,
+  localized,
+  ...rest
+}: EditableTextProps) {
+  const { value, fieldProps } = useField<string>(field, { type: "text", default: def, label, localized });
+  return (
+    <Tag {...rest} {...fieldProps}>
+      {value}
+    </Tag>
+  );
+}
+
+export type EditableRichTextProps = Omit<EditableTextProps, "localized"> & { localized?: boolean };
+
+export function EditableRichText({
+  field,
+  default: def = "",
+  as: Tag = "div",
+  label,
+  localized,
+  ...rest
+}: EditableRichTextProps) {
+  const { value, fieldProps } = useField<string>(field, { type: "richtext", default: def, label, localized });
+  // Rich text is stored as HTML. The editor sanitizes on write.
+  return <Tag {...rest} {...fieldProps} dangerouslySetInnerHTML={{ __html: value }} />;
+}
+
+export type EditableImageProps = {
+  field: string;
+  /** Default image when the field is unedited. */
+  default?: ImageValue;
+  /** Fallback alt text. */
+  alt?: string;
+  label?: string;
+  style?: CSSProperties;
+  className?: string;
+};
+
+export function EditableImage({ field, default: def, alt, label, ...rest }: EditableImageProps) {
+  const { value, fieldProps } = useField<ImageValue | undefined>(field, {
+    type: "image",
+    default: def,
+    label,
+    localized: false,
+  });
+  const img = value ?? def;
+  const altText = typeof img?.alt === "string" ? img.alt : (alt ?? "");
+  if (!img?.url) return null;
+  return <img src={img.url} alt={altText} {...rest} {...fieldProps} />;
+}
+
+/** Render arbitrary children with a field marker (for composite editable regions). */
+export function EditableRegion({
+  field,
+  children,
+  ...rest
+}: { field: string; children: ReactNode } & { style?: CSSProperties; className?: string }) {
+  const { fieldProps } = useField(field, { type: "text", default: "" });
+  return (
+    <div {...rest} {...fieldProps}>
+      {children}
+    </div>
+  );
+}

package/src/ui/format/PriceDisplay.tsx

@@ -0,0 +1,142 @@
+import React from "react";
+import { formatCurrency } from "./useFormatCurrency";
+import type { PublicTaxQuote } from "../../types/models";
+
+/**
+ * <PriceDisplay/> — the one tax-aware price renderer (financial back-office).
+ *
+ * Two display modes, driven by the store's `pricesIncludeTax` setting:
+ *
+ * - **Exclusive** (US default, `pricesIncludeTax` falsy): renders the bare
+ *   price. Tax appears only as a separate "Tax" line in cart/checkout
+ *   summaries once the authoritative checkout `taxQuote` is known — that line
+ *   is rendered by the summary itself, not by this component.
+ * - **Inclusive** (EU/UK style, `pricesIncludeTax` true): the price already
+ *   contains tax, so it renders everywhere (listing + detail + checkout) with
+ *   a subtle muted caption — `incl. tax` generically, or
+ *   `incl. £10.00 VAT` once the contained tax amount is known.
+ *
+ * Deliberately **hook-free** so it works in every surface: Forge styled blocks
+ * (inside `ForgeThemeProvider`), frontend-shared Craft.js blocks (editor
+ * `themeSettings`), and plain client components. Formatting and the muted
+ * caption color are passed in by the caller; the caption falls back to
+ * inheriting the current color at reduced opacity, so it is always
+ * "muted foreground" relative to wherever it's dropped.
+ *
+ * DISPLAY ONLY — never computes or alters charge math. The authoritative
+ * numbers are the checkout `taxQuote` from every start-payment response.
+ */
+export interface PriceDisplayProps {
+  /** Price in MAJOR units, in the store's display currency. */
+  amount: number;
+  /** Store display mode (`sales_tax_settings.prices_include_tax`). */
+  pricesIncludeTax?: boolean | null;
+  /** Contained tax in MAJOR units — pass only when known (checkout quote).
+   * Only rendered in inclusive mode ("incl. X tax"). */
+  taxAmount?: number | null;
+  /** Currency code of `amount` — used by the fallback formatter only. */
+  currency?: string;
+  /** Formatter for amounts (a block's `fmt`). Falls back to a static
+   * symbol+thousands format of `currency`. */
+  formatAmount?: (amount: number, currencyCode?: string) => string;
+  /** Word used in the inclusive caption, e.g. "VAT". Default "tax". */
+  taxLabel?: string;
+  /** Muted caption color (e.g. the theme's muted foreground). When omitted the
+   * caption inherits the current color at 0.65 opacity. */
+  mutedColor?: string;
+  /** Rendered right after the price, inside the price element (e.g. "/mo"). */
+  suffix?: React.ReactNode;
+  /** Render the caption inline after the price instead of on its own line. */
+  inlineCaption?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  captionClassName?: string;
+  captionStyle?: React.CSSProperties;
+}
+
+/** The inclusive-mode caption text ("incl. tax" / "incl. £10.00 VAT"), or null
+ * when no caption should render (exclusive mode). Exported for callers that
+ * need the text without the markup. */
+export function priceTaxCaption(opts: {
+  pricesIncludeTax?: boolean | null;
+  taxAmount?: number | null;
+  taxLabel?: string;
+  formatAmount?: (amount: number, currencyCode?: string) => string;
+  currency?: string;
+}): string | null {
+  const { pricesIncludeTax, taxAmount, taxLabel = "tax", formatAmount, currency } = opts;
+  if (!pricesIncludeTax) return null;
+  if (taxAmount != null && taxAmount > 0) {
+    const fmt = formatAmount ?? ((n: number, c?: string) => formatCurrency(n, c ?? currency));
+    return `incl. ${fmt(taxAmount, currency)} ${taxLabel}`;
+  }
+  return `incl. ${taxLabel}`;
+}
+
+export function PriceDisplay({
+  amount,
+  pricesIncludeTax,
+  taxAmount,
+  currency,
+  formatAmount,
+  taxLabel = "tax",
+  mutedColor,
+  suffix,
+  inlineCaption = false,
+  className,
+  style,
+  captionClassName,
+  captionStyle,
+}: PriceDisplayProps) {
+  const fmt = formatAmount ?? ((n: number, c?: string) => formatCurrency(n, c ?? currency));
+  const caption = priceTaxCaption({ pricesIncludeTax, taxAmount, taxLabel, formatAmount, currency });
+
+  const captionEl = caption ? (
+    <span
+      className={captionClassName}
+      style={{
+        display: inlineCaption ? "inline" : "block",
+        fontSize: "0.72em",
+        fontWeight: 400,
+        lineHeight: 1.3,
+        whiteSpace: "nowrap",
+        ...(mutedColor ? { color: mutedColor } : { opacity: 0.65 }),
+        ...(inlineCaption ? { marginLeft: "0.35em" } : {}),
+        ...captionStyle,
+      }}
+    >
+      {caption}
+    </span>
+  ) : null;
+
+  return (
+    <span className={className} style={{ display: inlineCaption ? "inline" : "inline-block", ...style }}>
+      <span>
+        {fmt(amount, currency)}
+        {suffix}
+      </span>
+      {captionEl}
+    </span>
+  );
+}
+
+/**
+ * The tax portion of a checkout summary, derived from the authoritative
+ * `taxQuote`. Normalizes the two modes for summary UIs:
+ * - exclusive → a "Tax" row to render between Subtotal/Shipping and Total;
+ * - inclusive → a muted "Includes X tax" note under the Total (the total
+ *   does not grow).
+ * Returns null when there is no quote or no tax.
+ */
+export function summarizeTaxQuote(
+  quote: PublicTaxQuote | null | undefined,
+  formatAmount?: (amount: number, currencyCode?: string) => string,
+  taxLabel = "tax",
+): { mode: "exclusive" | "inclusive"; label: string; formattedTax: string } | null {
+  if (!quote || !(quote.tax > 0)) return null;
+  const fmt = formatAmount ?? ((n: number, c?: string) => formatCurrency(n, c));
+  const formattedTax = fmt(quote.tax, quote.currency);
+  return quote.pricesIncludeTax
+    ? { mode: "inclusive", label: `Includes ${formattedTax} ${taxLabel}`, formattedTax }
+    : { mode: "exclusive", label: "Tax", formattedTax };
+}

package/src/ui/format/useFormatCurrency.ts

@@ -0,0 +1,92 @@
+import { Currency, currencySymbol } from "../../types/models";
+import { usePublicAuth } from "../../contexts/PublicAuthContext";
+import { useSiteConfig } from "../../data/queries/useWebsite";
+
+/** Thousands-separated, e.g. 1234.5 -> "1,234.5". */
+const toLocaleString = (n: number): string => Number(n).toLocaleString("en-US");
+
+/** Symbol for a currency code, falling back to USD. */
+export const getCurrencySymbol = (currencyCode?: string): string => {
+  if (!currencyCode) return currencySymbol[Currency.USD];
+  return currencySymbol[currencyCode as Currency] || currencySymbol[Currency.USD];
+};
+
+/** Static format (no conversion) — `formatCurrency(19.99, "USD") -> "$19.99"`. */
+export const formatCurrency = (amount: number | string, currencyCode?: string): string => {
+  const symbol = getCurrencySymbol(currencyCode);
+  const numAmount = typeof amount === "string" ? parseFloat(amount) : amount;
+  return `${symbol}${toLocaleString(Number(numAmount.toFixed(2)))}`;
+};
+
+/**
+ * Currency formatter that honors the visitor's selected currency and the
+ * tenant's exchange rates (both sourced from `usePublicAuth()`), converting the
+ * amount when a rate is available and falling back to the raw amount otherwise.
+ *
+ * The SOURCE currency (the currency an amount is in) defaults to the tenant's
+ * settlement currency from `useSiteConfig()` — the single source of truth — so
+ * callers just write `formatCurrency(amount)` with no baked currency constant.
+ * Pass an explicit code only when the amount is in a different, known currency
+ * (e.g. a payment's charged currency).
+ *
+ * This is the primitive every price/total in a Forge site should format through.
+ * Port of the client app's `useFormatCurrency`.
+ */
+export const useFormatCurrency = () => {
+  const { currencies, userSelectedCurrency } = usePublicAuth();
+  const { data: siteConfig } = useSiteConfig();
+  const settlementCurrency = siteConfig?.currency;
+
+  const formatCurrencyValue = (amount: number | string, currencyCode?: string): string => {
+    const source = currencyCode ?? settlementCurrency;
+    if (!source) return "N/A";
+
+    const numAmount = typeof amount === "string" ? parseFloat(amount) : amount;
+    const noConversion = () => `${getCurrencySymbol(source)}${toLocaleString(Number(numAmount.toFixed(2)))}`;
+
+    if (!currencies || !currencies.exchangeRates || Object.keys(currencies.exchangeRates).length === 0) {
+      return noConversion();
+    }
+    if (userSelectedCurrency && userSelectedCurrency === source) {
+      return noConversion();
+    }
+
+    const exchangeRate = currencies.exchangeRates[source as Currency]?.[userSelectedCurrency as Currency];
+    if (!exchangeRate) return noConversion();
+
+    const convertedAmount = Number(numAmount) * exchangeRate;
+    const symbol = getCurrencySymbol(userSelectedCurrency as string);
+    return `${symbol}${toLocaleString(Number(convertedAmount.toFixed(2)))}`;
+  };
+
+  /**
+   * Convert a numeric amount from `fromCode` (defaults to the tenant settlement
+   * currency) into `toCode` (defaults to the visitor's selected currency) using
+   * the tenant exchange rates. Returns the amount unchanged when no rate is
+   * available or the currencies match. Used to total mixed-currency values
+   * (e.g. shipping rates) before formatting.
+   */
+  const convertCurrency = (amount: number, fromCode?: string, toCode?: string): number => {
+    const from = (fromCode ?? settlementCurrency) as Currency | undefined;
+    const target = (toCode ?? userSelectedCurrency) as Currency | undefined;
+    if (!from || !target || from === target) return amount;
+    const rate = currencies?.exchangeRates?.[from]?.[target];
+    return rate ? amount * rate : amount;
+  };
+
+  return { formatCurrency: formatCurrencyValue, convertCurrency };
+};
+
+/**
+ * The amount formatter a styled block should use: the caller's `formatAmount`
+ * override if given, otherwise the runtime `useFormatCurrency` formatter (whose
+ * source currency is the tenant's settlement currency from `useSiteConfig`).
+ * This keeps currency a single source of truth — a block formats money
+ * correctly with no `formatAmount` prop and no baked currency constant.
+ */
+export const useAmountFormatter = (
+  override?: (amount: number, currencyCode?: string) => string,
+): ((amount: number, currencyCode?: string) => string) => {
+  const { formatCurrency } = useFormatCurrency();
+  return override ?? formatCurrency;
+};