@tribe-nest/forge 3.26.0 → 3.29.0

package/src/i18n/index.ts

@@ -0,0 +1,125 @@
+// Forge i18n. Bundled strings only: the en/de JSON in this folder ships inside
+// the package and is read synchronously, so there is no network call, no
+// loading state and no way for a site to render an untranslated first paint.
+// See docs/proposals/i18n-initiative.md, "Why bundle-only is safe".
+//
+// Key naming is fixed by ./CONVENTION.md. Every key starts with "forge." so a
+// tenant's own copy can never collide with the package's.
+
+import { createContext, createElement, useContext, useMemo, type ReactNode } from "react";
+import enMessages from "./en.json";
+import deMessages from "./de.json";
+
+/** The locales Forge ships copy for. en + de is the whole proof of concept. */
+export const FORGE_LOCALES = ["en", "de"] as const;
+
+export type ForgeLocale = (typeof FORGE_LOCALES)[number];
+
+/** The locale every fallback ends at. English is the source language. */
+export const FORGE_DEFAULT_LOCALE: ForgeLocale = "en";
+
+/** A flat map of dotted key to copy. Not nested: see ./CONVENTION.md. */
+export type ForgeMessages = Record<string, string>;
+
+/** Values substituted into `{placeholders}`. */
+export type ForgeTVars = Record<string, string | number>;
+
+/** The translate function `useForgeT()` hands back. */
+export type ForgeT = (key: string, vars?: ForgeTVars) => string;
+
+const BUNDLES: Record<ForgeLocale, ForgeMessages> = {
+  en: enMessages as ForgeMessages,
+  de: deMessages as ForgeMessages,
+};
+
+/**
+ * Narrow anything a site might pass ("de", "de-DE", "DE", undefined) to a
+ * locale Forge actually has copy for. Anything unrecognised becomes English
+ * rather than an error, because a wrong language is a defect and a crashed
+ * page is an outage.
+ */
+export function resolveForgeLocale(locale?: string | null): ForgeLocale {
+  if (!locale) return FORGE_DEFAULT_LOCALE;
+  const base = locale.toLowerCase().split(/[-_]/)[0];
+  return (FORGE_LOCALES as readonly string[]).includes(base) ? (base as ForgeLocale) : FORGE_DEFAULT_LOCALE;
+}
+
+/**
+ * Substitute `{name}` placeholders. A placeholder with no matching var is left
+ * standing rather than blanked, so a missing value shows up as `{name}` in
+ * review instead of disappearing silently into a half-finished sentence.
+ */
+function interpolate(template: string, vars?: ForgeTVars): string {
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    Object.prototype.hasOwnProperty.call(vars, name) ? String(vars[name]) : match,
+  );
+}
+
+/**
+ * Look a key up with the full fallback chain: requested locale, then English,
+ * then the key itself. The last step is what guarantees a component never
+ * renders blank, and it makes an untranslated string visible in the UI rather
+ * than invisible.
+ */
+export function translateForge(locale: ForgeLocale, key: string, vars?: ForgeTVars): string {
+  const template = BUNDLES[locale]?.[key] ?? BUNDLES[FORGE_DEFAULT_LOCALE][key] ?? key;
+  return interpolate(template, vars);
+}
+
+/** Read-only access to a bundle, for parity specs and tooling. */
+export function getForgeMessages(locale: ForgeLocale): ForgeMessages {
+  return BUNDLES[locale] ?? BUNDLES[FORGE_DEFAULT_LOCALE];
+}
+
+// `null` means "no provider above me", which is a supported state, not a bug.
+const ForgeI18nContext = createContext<ForgeLocale | null>(null);
+
+export interface ForgeI18nProviderProps {
+  /**
+   * The site's language. Accepts any BCP-47-ish string and narrows it; absent
+   * or unsupported means English.
+   */
+  locale?: string | null;
+  children: ReactNode;
+}
+
+/**
+ * Puts the site's language in context. Mounted by `<TribeNestApp>`, so a site
+ * gains i18n from a Forge upgrade without editing its `__root.tsx`. Mount it
+ * yourself only if you hand-compose the provider tree instead of using
+ * `TribeNestApp`.
+ */
+export function ForgeI18nProvider({ locale, children }: ForgeI18nProviderProps) {
+  const resolved = resolveForgeLocale(locale);
+  return createElement(ForgeI18nContext.Provider, { value: resolved }, children);
+}
+
+/**
+ * The locale in effect. Returns the default ("en") outside a provider, so this
+ * is safe to call anywhere.
+ */
+export function useForgeLocale(): ForgeLocale {
+  return useContext(ForgeI18nContext) ?? FORGE_DEFAULT_LOCALE;
+}
+
+/**
+ * The translate function.
+ *
+ *     const t = useForgeT();
+ *     return <button>{t("forge.cart.checkout")}</button>;
+ *     return <p>{t("forge.cart.item_count", { count: items.length })}</p>;
+ *
+ * Fallback chain: the active locale, then bundled English, then the key itself.
+ * It never returns an empty string, so a missing key degrades to something a
+ * reviewer can see rather than to a blank space in the page.
+ *
+ * Outside a `<ForgeI18nProvider>` it returns a working English translator
+ * rather than throwing, so a component still renders standalone. This mirrors
+ * `useFunnelStep`, which returns a working no-op outside a `<Funnel>` for the
+ * same reason.
+ */
+export function useForgeT(): ForgeT {
+  const locale = useForgeLocale();
+  return useMemo<ForgeT>(() => (key, vars) => translateForge(locale, key, vars), [locale]);
+}

package/src/index.ts

@@ -19,6 +19,27 @@ export {
 } from "./provider/ForgeProvider";
 export { SiteConfigProvider, useInitialSiteConfig } from "./provider/SiteConfigProvider";
 
+// i18n. Strings are bundled in the package (en + de), never fetched, so there
+// is no loading state and no untranslated first paint. `TribeNestApp` mounts
+// the provider, so a site gets this from a Forge upgrade alone. Outside a
+// provider `useForgeT()` still returns a working English translator.
+// Key naming is fixed by src/i18n/CONVENTION.md.
+export {
+  useForgeT,
+  useForgeLocale,
+  ForgeI18nProvider,
+  resolveForgeLocale,
+  translateForge,
+  getForgeMessages,
+  FORGE_LOCALES,
+  FORGE_DEFAULT_LOCALE,
+  type ForgeT,
+  type ForgeTVars,
+  type ForgeLocale,
+  type ForgeMessages,
+  type ForgeI18nProviderProps,
+} from "./i18n";
+
 // All domain types + enums/consts (models) and WebPage.
 export * from "./types";
 

package/src/provider/ForgeAppProvider.tsx

@@ -73,7 +73,8 @@ export interface ForgeProviderProps {
   initialToken?: string | null;
   /** Editing affordances (the in-place content editor). Off for a live site. */
   editable?: boolean;
-  /** Content locale. */
+  /** Content locale. Also the language `useForgeT()` renders Forge's own copy
+   * in when the tree is wrapped by `TribeNestApp`. Absent means "en". */
   locale?: string;
   /** SSR content document (from `fetchContentDocument`). Defaults to empty. */
   initialContentDoc?: ContentDocument;

package/src/provider/SiteConfigProvider.tsx

@@ -1,5 +1,6 @@
 import { createContext, useContext, type ReactNode } from "react";
 import type { SiteConfig } from "../data/queries/useWebsite";
+import { setSiteLocale } from "../client/activeLocale";
 
 /**
  * Holds an SSR-fetched site config so `useSiteConfig()` can seed React Query
@@ -18,6 +19,16 @@ export function SiteConfigProvider({
   initialConfig?: SiteConfig | null;
   children: ReactNode;
 }) {
+  // Publish the tenant's language to the axios client, which sends it as
+  // `x-locale` on every request so API messages come back in the language the
+  // page is written in. Done here rather than in each site's `__root.tsx` so an
+  // existing site gets it from a Forge upgrade alone.
+  //
+  // During render, not in an effect: an effect runs after the first paint, by
+  // which time the queries on the first screen have already gone out without the
+  // header. The write is an idempotent assignment of a value that is constant for
+  // the deploy, so repeating it (StrictMode, every SSR request) changes nothing.
+  setSiteLocale(initialConfig?.locale);
   return <SiteConfigContext.Provider value={initialConfig ?? undefined}>{children}</SiteConfigContext.Provider>;
 }
 

package/src/ui/headless/checkout/_tests/cartResume.spec.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  partitionResumeLines,
+  resumeLineToCartItem,
+  resumeLinesToTicketItems,
+  effectiveUnitCents,
+  type ResumeLine,
+} from "../useCartResume";
+import { rememberResumedCoupon, takeResumedCoupon } from "../resumedCoupon";
+import { ProductDeliveryType } from "../../../../types/models";
+
+/**
+ * The translation from a resumed line to a cart line, which is where a recovery
+ * link either restores the basket the buyer left or a subtly different one.
+ *
+ * Pure functions, so these run in the package's existing node environment with
+ * no jsdom and no network.
+ *
+ * The hook AROUND them lives in `useCartResume.spec.tsx`, in jsdom, where the
+ * exchange and the cart are both stubbed: which lines reach `restoreCart`, and
+ * when, is a question effects answer and a pure function cannot. What the two
+ * storefronts then DRAW is `ResumeCart.spec.tsx` here and `resume.spec.tsx` in
+ * `apps/client`. (This docblock previously claimed the hook was covered "end to
+ * end by the backend spec plus the two storefront pages", and none of those
+ * three existed.)
+ */
+
+const productLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "product",
+  quantity: 2,
+  title: "Tour Tee",
+  coverImage: "https://cdn.test/tee.jpg",
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2000,
+  priceChanged: true,
+  available: true,
+  unavailableReason: null,
+  productId: "prod-1",
+  productVariantId: "var-1",
+  deliveryType: ProductDeliveryType.Physical,
+  payWhatYouWant: false,
+  options: [{ axis: "Size", value: "L", swatchHex: null }],
+  isGift: false,
+  ...overrides,
+});
+
+const ticketLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "event_ticket",
+  quantity: 3,
+  title: "General Admission",
+  coverImage: null,
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2500,
+  priceChanged: false,
+  available: true,
+  unavailableReason: null,
+  eventId: "event-1",
+  ticketId: "tier-1",
+  eventSlug: "spring-tour",
+  eventTitle: "Spring Tour",
+  pwywAmount: null,
+  bookingFee: null,
+  ...overrides,
+});
+
+describe("resumeLineToCartItem", () => {
+  it("should carry the delivery type through rather than defaulting it", () => {
+    // The whole reason the payload has the field: a physical line restored as
+    // non-physical means checkout never asks where to send the record, and a
+    // missing address is not recoverable after payment.
+    const item = resumeLineToCartItem(productLine());
+    expect(item?.deliveryType).toBe(ProductDeliveryType.Physical);
+  });
+
+  it("should restore the quantity the buyer chose, not one", () => {
+    expect(resumeLineToCartItem(productLine({ quantity: 4 }))?.quantity).toBe(4);
+  });
+
+  it("should quote today's price, never the one the buyer was shown", () => {
+    const item = resumeLineToCartItem(productLine({ price: 25, quotedUnitPriceCents: 2000 }));
+    expect(item?.price).toBe(25);
+  });
+
+  it("should keep a gift a gift, with its recipient", () => {
+    const item = resumeLineToCartItem(
+      productLine({
+        isGift: true,
+        recipientName: "Ada",
+        recipientEmail: "ada@test.com",
+        recipientMessage: "Happy birthday",
+      }),
+    );
+    expect(item).toMatchObject({
+      isGift: true,
+      recipientName: "Ada",
+      recipientEmail: "ada@test.com",
+      recipientMessage: "Happy birthday",
+    });
+  });
+
+  it("should keep an add-on bound to the event it hangs off", () => {
+    // Without this the rebuilt bundle has an add-on with no base and the server
+    // refuses the whole checkout, with nothing on screen explaining why.
+    const item = resumeLineToCartItem(
+      productLine({ attachedTo: { type: "event", entityId: "event-1" } }),
+    );
+    expect(item?.attachedTo).toEqual({ type: "event", entityId: "event-1" });
+  });
+
+  it("should carry the chosen variant's options so the cart can name it", () => {
+    expect(resumeLineToCartItem(productLine())?.options).toEqual([
+      { axis: "Size", value: "L", swatchHex: null },
+    ]);
+  });
+
+  it("should refuse a line with no variant rather than invent one", () => {
+    expect(resumeLineToCartItem(productLine({ productVariantId: undefined }))).toBeNull();
+    expect(resumeLineToCartItem(productLine({ productId: undefined }))).toBeNull();
+  });
+});
+
+describe("resumeLinesToTicketItems", () => {
+  it("should group tiers of one event into a single selection", () => {
+    const items = resumeLinesToTicketItems([
+      ticketLine({ ticketId: "tier-1", quantity: 2, title: "GA" }),
+      ticketLine({ ticketId: "tier-2", quantity: 1, title: "VIP", price: 80, unitPriceCents: 8000 }),
+    ]);
+
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      eventId: "event-1",
+      eventSlug: "spring-tour",
+      eventTitle: "Spring Tour",
+      tickets: { "tier-1": 2, "tier-2": 1 },
+    });
+    expect(items[0].ticketMeta["tier-2"]).toMatchObject({ title: "VIP", price: 80 });
+  });
+
+  it("should keep two events apart", () => {
+    const items = resumeLinesToTicketItems([
+      ticketLine({ eventId: "event-1" }),
+      ticketLine({ eventId: "event-2", eventSlug: "autumn", eventTitle: "Autumn" }),
+    ]);
+    expect(items.map((item) => item.eventId)).toEqual(["event-1", "event-2"]);
+  });
+
+  it("should show a pay-what-you-want tier the buyer's own amount, and send it", () => {
+    // The bundle endpoint treats `price` as display-only and charges
+    // `pwywAmount`. Dropping the second field would silently undercharge to the
+    // tier's floor and still answer 200.
+    const items = resumeLinesToTicketItems([ticketLine({ price: 10, pwywAmount: 42 })]);
+    expect(items[0].ticketMeta["tier-1"]).toMatchObject({ price: 42, pwywAmount: 42 });
+  });
+
+  it("should carry the event's booking fee so the estimate matches the charge", () => {
+    const fee = { feeAmount: 1.5, feeBps: 250, currency: "USD", minorUnitFactor: 100 };
+    expect(resumeLinesToTicketItems([ticketLine({ bookingFee: fee })])[0].bookingFee).toEqual(fee);
+  });
+
+  it("should skip a line with no tier id", () => {
+    expect(resumeLinesToTicketItems([ticketLine({ ticketId: undefined })])).toEqual([]);
+  });
+});
+
+describe("partitionResumeLines", () => {
+  const courseLine = (): ResumeLine => ({
+    ...productLine(),
+    type: "course",
+    title: "Songwriting",
+    courseSlug: "songwriting",
+  });
+
+  it("sends a course onward rather than into the basket", () => {
+    const parts = partitionResumeLines([productLine(), courseLine()]);
+    expect(parts.restoredLines.map((line) => line.title)).toEqual(["Tour Tee"]);
+    expect(parts.continueLines.map((line) => line.title)).toEqual(["Songwriting"]);
+  });
+
+  it("keeps every line the server refused, with its reason intact", () => {
+    const gone = productLine({ available: false, unavailableReason: "removed", title: "Vinyl" });
+    const parts = partitionResumeLines([productLine(), gone]);
+    expect(parts.unavailableLines).toEqual([gone]);
+    expect(parts.restoredLines.map((line) => line.title)).toEqual(["Tour Tee"]);
+  });
+
+  it("REGRESSION: drops an add-on whose base ticket is not being restored", () => {
+    // The server refuses a bundle whose add-on has no base, so restoring it
+    // alone builds a basket that can only fail at the payment screen.
+    const poster = productLine({
+      title: "Tour poster",
+      attachedTo: { type: "event", entityId: "event-1" },
+    });
+    const parts = partitionResumeLines([
+      ticketLine({ available: false, unavailableReason: "sold_out" }),
+      poster,
+    ]);
+
+    expect(parts.restoredLines).toEqual([]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("keeps the add-on when its base ticket is restored", () => {
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-1" } });
+    const parts = partitionResumeLines([ticketLine(), poster]);
+    expect(parts.droppedLines).toEqual([]);
+    expect(parts.restoredLines).toContain(poster);
+  });
+
+  it("counts only the event the add-on names as its base", () => {
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-2" } });
+    const parts = partitionResumeLines([ticketLine({ eventId: "event-1" }), poster]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("does not accept a ticket line the cart would skip as a base", () => {
+    // `resumeLinesToTicketItems` needs both ids and silently skips a line
+    // missing either, so such a line is not a base that will exist.
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-1" } });
+    const parts = partitionResumeLines([ticketLine({ ticketId: undefined }), poster]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("leaves a product attached to nothing alone", () => {
+    // Attachment describes how a line was ADDED, not what the product is: the
+    // same poster bought from the shop sells on its own as always.
+    const parts = partitionResumeLines([productLine({ attachedTo: null })]);
+    expect(parts.droppedLines).toEqual([]);
+    expect(parts.restoredLines).toHaveLength(1);
+  });
+});
+
+describe("effectiveUnitCents", () => {
+  it("should use the catalogue price when nothing was chosen", () => {
+    expect(effectiveUnitCents(ticketLine())).toBe(2500);
+  });
+
+  it("should use the chosen amount on a pay-what-you-want tier", () => {
+    expect(effectiveUnitCents(ticketLine({ pwywAmount: 42 }))).toBe(4200);
+  });
+
+  it("should treat a chosen zero as a choice, not as absent", () => {
+    expect(effectiveUnitCents(ticketLine({ pwywAmount: 0 }))).toBe(0);
+  });
+});
+
+describe("the resumed coupon stash", () => {
+  const store = new Map<string, string>();
+
+  beforeEach(() => {
+    store.clear();
+    (globalThis as { window?: unknown }).window = {
+      sessionStorage: {
+        getItem: (key: string) => store.get(key) ?? null,
+        setItem: (key: string, value: string) => void store.set(key, value),
+        removeItem: (key: string) => void store.delete(key),
+      },
+    };
+    rememberResumedCoupon(null);
+  });
+
+  afterEach(() => {
+    delete (globalThis as { window?: unknown }).window;
+  });
+
+  it("should hand the code to the checkout page once", () => {
+    rememberResumedCoupon("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+    expect(store.has("tribenest-resumed-coupon")).toBe(false);
+  });
+
+  it("should survive a second read in the same page load", () => {
+    // React StrictMode invokes a lazy `useState` initialiser twice in
+    // development. Without the memo the field would come up blank on exactly
+    // the builds a developer tests against.
+    rememberResumedCoupon("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+  });
+
+  it("should answer empty when no link was followed", () => {
+    expect(takeResumedCoupon()).toBe("");
+  });
+
+  it("should forget a code when the next resume carries none", () => {
+    rememberResumedCoupon("SUMMER10");
+    rememberResumedCoupon(null);
+    expect(takeResumedCoupon()).toBe("");
+  });
+});