@tribe-nest/forge 3.54.0 → 3.58.0

package/src/ui/headless/forms/usePhoneInput.ts

@@ -0,0 +1,294 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { CountryCode, Examples } from "libphonenumber-js";
+
+/**
+ * Phone entry that produces E.164, because the input is the only place the
+ * country is knowable.
+ *
+ * ## Why this exists at all
+ *
+ * `services/admin/consent/phone.ts` refuses to infer a country code from a bare
+ * national number, and it is right to: guessing `+1` for a ten-digit string is
+ * wrong for most of the world, and a wrong guess writes a phantom suppression
+ * against a number that never opted out. The consequence it accepts is that a
+ * bare national number simply never matches an E.164 one.
+ *
+ * That consequence is a live compliance hole on the way IN. Someone types
+ * `07700 900123` into a signup form, it is stored verbatim, they later text
+ * STOP from `+447700900123`, and the suppression lookup misses. We keep texting
+ * someone who said stop, which is the single most expensive failure in SMS.
+ *
+ * Nothing downstream can fix that, because by then the country is gone. So the
+ * fix belongs here: ask for the country, and emit E.164 from the start.
+ *
+ * ## Metadata cost, measured
+ *
+ * `libphonenumber-js/max` is 55.5 KB gzip / 48.1 KB brotli once bundled, and the
+ * metadata is effectively the whole of it: a build importing only `AsYouType`
+ * and `parsePhoneNumberFromString` measured 35.5 KB gzip against 35.7 KB for the
+ * full `min` import, so there is nothing to win by trimming the API surface.
+ *
+ * `max` rather than the smaller tiers, and the reason is not the line-type
+ * warning. `mobile` is a mobile-ONLY dataset: under it a landline is not typed
+ * as a landline, it is INVALID. That would refuse a perfectly good courier
+ * number at checkout, and would refuse real customers in the many countries
+ * whose numbers are typed FIXED_LINE_OR_MOBILE. `min` accepts everything but
+ * reports the type inconsistently (a GB landline resolves, a DE one does not),
+ * so a warning built on it would appear or vanish by country for no reason the
+ * visitor could see. `max` is the only tier where both modes below are correct.
+ *
+ * It is loaded with a dynamic `import()` so none of it sits in the first paint.
+ * A phone field is never the thing a visitor sees first, and until the metadata
+ * lands the input still accepts typing: `isReady` is false, validation holds
+ * off, and nothing is blocked.
+ */
+
+export type PhoneNumberType = "mobile" | "fixedLine" | "other" | "unknown";
+
+export interface UsePhoneInputOptions {
+  /**
+   * Where to start the country select. Pass the most confident source you have:
+   * checkout knows the shipping country, a storefront knows the visitor's geo.
+   * Never derive this from the digits someone is typing.
+   */
+  defaultCountry?: CountryCode;
+  /**
+   * `messaging` is for a number we will text: it demands a valid number and
+   * warns on a line type that cannot receive SMS. `shipping` is for a number a
+   * courier will ring, where a landline is perfectly good and the bar is only
+   * that the number is real.
+   */
+  mode?: "messaging" | "shipping";
+  /** Seed value, E.164 or national. An E.164 seed also sets the country. */
+  initialValue?: string;
+  /** Called with E.164 (or null while incomplete) on every change. */
+  onChange?: (e164: string | null) => void;
+  /**
+   * Set false when the field is not being shown. Hooks cannot be called
+   * conditionally, so a form with an optional phone field has to call this
+   * every render; this is what stops it fetching ~48 KB of metadata for a field
+   * nobody is going to see.
+   */
+  enabled?: boolean;
+}
+
+interface Metadata {
+  AsYouType: typeof import("libphonenumber-js/max").AsYouType;
+  parsePhoneNumberFromString: typeof import("libphonenumber-js/max").parsePhoneNumberFromString;
+  getCountries: typeof import("libphonenumber-js/max").getCountries;
+  getCountryCallingCode: typeof import("libphonenumber-js/max").getCountryCallingCode;
+  getExampleNumber: typeof import("libphonenumber-js/max").getExampleNumber;
+  examples: Examples;
+}
+
+let metadataPromise: Promise<Metadata> | null = null;
+
+/**
+ * One shared load for the whole page. Two phone fields on one checkout must not
+ * fetch the metadata twice, and the promise is cached rather than the result so
+ * concurrent callers await the same request.
+ */
+function loadMetadata(): Promise<Metadata> {
+  if (!metadataPromise) {
+    metadataPromise = Promise.all([
+      import("libphonenumber-js/max"),
+      import("libphonenumber-js/examples.mobile.json"),
+    ]).then(([lib, ex]) => ({
+      AsYouType: lib.AsYouType,
+      parsePhoneNumberFromString: lib.parsePhoneNumberFromString,
+      getCountries: lib.getCountries,
+      getCountryCallingCode: lib.getCountryCallingCode,
+      getExampleNumber: lib.getExampleNumber,
+      examples: ((ex as { default?: Examples }).default ?? ex) as Examples,
+    }));
+  }
+  return metadataPromise;
+}
+
+/** Let a host warm the metadata before the field is reached (on route enter, say). */
+export const preloadPhoneMetadata = loadMetadata;
+
+export interface CountryOption {
+  country: CountryCode;
+  callingCode: string;
+  flag: string;
+}
+
+/** Regional-indicator pair. "GB" becomes the flag, with no icon set to ship. */
+function flagOf(country: string): string {
+  if (country.length !== 2) return "";
+  return String.fromCodePoint(
+    ...[...country.toUpperCase()].map((c) => 0x1f1a5 + c.charCodeAt(0)),
+  );
+}
+
+export function usePhoneInput(opts: UsePhoneInputOptions = {}) {
+  const { defaultCountry, mode = "messaging", initialValue, onChange, enabled = true } = opts;
+
+  const [meta, setMeta] = useState<Metadata | null>(null);
+  const [country, setCountryState] = useState<CountryCode | undefined>(defaultCountry);
+  const [nationalValue, setNationalValue] = useState(initialValue ?? "");
+  const [touched, setTouched] = useState(false);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  useEffect(() => {
+    if (!enabled) return;
+    let alive = true;
+    loadMetadata().then((m) => {
+      if (alive) setMeta(m);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [enabled]);
+
+  /**
+   * A `defaultCountry` that resolves late still has to land. Checkout learns the
+   * shipping country after the address is filled, so a prop that arrives second
+   * must move the select, but only while the visitor has not chosen for
+   * themselves. Overriding a deliberate choice would be worse than being wrong.
+   */
+  useEffect(() => {
+    if (defaultCountry && !touched && !country) setCountryState(defaultCountry);
+  }, [defaultCountry, touched, country]);
+
+  const parsed = useMemo(() => {
+    if (!meta || !nationalValue.trim()) return null;
+    return meta.parsePhoneNumberFromString(nationalValue, country);
+  }, [meta, nationalValue, country]);
+
+  const e164 = parsed?.isValid() ? (parsed.number as string) : null;
+
+  const numberType: PhoneNumberType = useMemo(() => {
+    if (!parsed?.isValid()) return "unknown";
+    const t = parsed.getType();
+    if (t === "MOBILE") return "mobile";
+    if (t === "FIXED_LINE") return "fixedLine";
+    if (t === "FIXED_LINE_OR_MOBILE" || t === undefined) return "unknown";
+    return "other";
+  }, [parsed]);
+
+  /**
+   * A landline is a warning, never an error. The line type is a best guess from
+   * a numbering plan that many countries do not partition cleanly, and blocking
+   * a real number on a guess is worse than spending one credit finding out.
+   */
+  const warning = useMemo(() => {
+    if (mode !== "messaging" || !e164) return null;
+    return numberType === "fixedLine" ? ("landline" as const) : null;
+  }, [mode, e164, numberType]);
+
+  const error = useMemo(() => {
+    if (!touched || !meta) return null;
+    const raw = nationalValue.trim();
+    if (!raw) return "required" as const;
+    if (!country && !raw.startsWith("+")) return "no_country" as const;
+    if (!parsed) return "invalid" as const;
+    if (!parsed.isValid()) return "invalid" as const;
+    return null;
+  }, [touched, meta, nationalValue, country, parsed]);
+
+  /**
+   * Format as they type, in the national style of the selected country, so the
+   * value on screen matches the shape the placeholder promised.
+   *
+   * The exception is a pasted international number. The field says "without the
+   * country code" and a good share of people will paste `+44…` regardless. Left
+   * alone under a `GB` formatter that would read as a national string and come
+   * out mangled, so a leading `+` switches to international formatting and
+   * re-syncs the flag to whatever was pasted.
+   */
+  const setValue = useCallback(
+    (raw: string) => {
+      if (!meta) {
+        setNationalValue(raw);
+        return;
+      }
+      const isInternational = raw.trim().startsWith("+");
+      if (isInternational) {
+        const formatter = new meta.AsYouType();
+        const formatted = formatter.input(raw);
+        const detected = formatter.getCountry();
+        if (detected && detected !== country) {
+          setCountryState(detected);
+          setTouched(true);
+        }
+        setNationalValue(formatted);
+        return;
+      }
+      const formatter = new meta.AsYouType(country);
+      setNationalValue(formatter.input(raw));
+    },
+    [meta, country],
+  );
+
+  const setCountry = useCallback(
+    (next: CountryCode) => {
+      setCountryState(next);
+      setTouched(true);
+      // Re-format what is already typed under the new country rather than
+      // clearing it: someone correcting the flag after typing should not lose
+      // their number.
+      setNationalValue((current) => {
+        if (!meta || !current.trim() || current.trim().startsWith("+")) return current;
+        const digits = current.replace(/\D/g, "");
+        return new meta.AsYouType(next).input(digits);
+      });
+    },
+    [meta],
+  );
+
+  useEffect(() => {
+    onChangeRef.current?.(e164);
+  }, [e164]);
+
+  const countries: CountryOption[] = useMemo(() => {
+    if (!meta) return [];
+    return meta
+      .getCountries()
+      .map((c) => ({ country: c, callingCode: `+${meta.getCountryCallingCode(c)}`, flag: flagOf(c) }))
+      .sort((a, b) => a.country.localeCompare(b.country));
+  }, [meta]);
+
+  /**
+   * The placeholder is the real national format for the chosen country, which
+   * teaches the shape better than any sentence under the field: GB shows
+   * `07700 900123`, US shows `(201) 555-0123`.
+   */
+  const placeholder = useMemo(() => {
+    if (!meta || !country) return "";
+    const example = meta.getExampleNumber(country, meta.examples);
+    return example ? example.formatNational() : "";
+  }, [meta, country]);
+
+  return {
+    /** Loaded-metadata flag. Until true, validation holds off and typing still works. */
+    isReady: !!meta,
+    country,
+    setCountry,
+    countries,
+    callingCode: meta && country ? `+${meta.getCountryCallingCode(country)}` : "",
+    /** What the visitor sees: national format, no country code. */
+    value: nationalValue,
+    setValue,
+    placeholder,
+    /** What to submit. Null until the number is valid. */
+    e164,
+    isValid: !!e164,
+    numberType,
+    /** "landline" when messaging a number that cannot receive SMS. Never blocks. */
+    warning,
+    /** "required" | "no_country" | "invalid", or null. Only after blur. */
+    error,
+    touched,
+    markTouched: useCallback(() => setTouched(true), []),
+    reset: useCallback(() => {
+      setNationalValue("");
+      setTouched(false);
+      setCountryState(defaultCountry);
+    }, [defaultCountry]),
+  };
+}
+
+export type UsePhoneInputReturn = ReturnType<typeof usePhoneInput>;

package/src/ui/headless/forms/useSectionedForm.ts

@@ -111,7 +111,7 @@ function buildModel(form?: FormData) {
 
 /**
  * Headless multi-section form flow: a paginated wizard over `usePublicForm` that
- * mirrors the server walk (docs/forms-sections.md). Handles current-section
+ * mirrors the server walk (docs/archive/shipped/forms-sections.md). Handles current-section
  * state, in-page field visibility (show/hide), per-section required validation,
  * section→section branching (incl. submit), Back navigation, and submit. Bring
  * your own markup (or use the styled `<SectionedFormRenderer>`).
@@ -135,7 +135,7 @@ export function useSectionedForm(formId?: string) {
   const [error, setError] = useState("");
   const [isCompleted, setIsCompleted] = useState(false);
   // Graded quiz result (null until submit + only for quiz-mode forms). Shaped by
-  // the server's reveal policy — see docs/quizzes-certification-initiative.md.
+  // the server's reveal policy — see docs/archive/shipped/quizzes-certification-initiative.md.
   const [quizResult, setQuizResult] = useState<Record<string, unknown> | null>(null);
 
   // Start at the first section once the form loads.

package/src/ui/headless/index.ts

@@ -7,6 +7,14 @@ export { MembershipGate, type MembershipGateProps, type MembershipGateState } fr
 // S.4 members-only gates: the notice a storefront draws BEFORE the buyer pays.
 export { useMembershipGateNotice, type UseMembershipGateNoticeInput } from "./membership/useMembershipGateNotice";
 export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
+export {
+  usePhoneInput,
+  preloadPhoneMetadata,
+  type UsePhoneInputOptions,
+  type UsePhoneInputReturn,
+  type PhoneNumberType,
+  type CountryOption,
+} from "./forms/usePhoneInput";
 export { useContactForm } from "./forms/useContactForm";
 export { useSectionedForm } from "./forms/useSectionedForm";
 export { usePostEngagement, type UsePostEngagementOptions } from "./engagement/usePostEngagement";
@@ -52,7 +60,23 @@ export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 
 // Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
-export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export {
+  useEventCheckout,
+  type UseEventCheckoutOptions,
+  type EventCheckoutStep,
+  type ToggleSeatResult,
+} from "./event/useEventCheckout";
+// Reserved seating (wave 2): the joined seating read and the pure pieces a
+// host needs to drive a picker of its own.
+export {
+  useEventSeating,
+  bestAvailableSeats,
+  indexEventSeats,
+  seatLabel,
+  type EventSeat,
+  type EventSeatingState,
+  type UseEventSeatingOptions,
+} from "./event/useEventSeating";
 // Ticket requests (curated access): the pure decisions behind the picker and
 // the post-order routing, for a host that drives the hook from its own UI.
 export {
@@ -100,6 +124,29 @@ export {
   type MembershipCheckoutStep,
   type BillingCycle,
 } from "./membership/useMembershipCheckout";
+// Curated access (invite-only and apply-to-join tiers): the pure decisions the
+// tier card, the checkout and the account page share.
+export {
+  canWithdrawMembershipApplication,
+  MEMBERSHIP_APPLICATION_MESSAGE_MAX,
+  membershipApplicationOutcome,
+  tierCardAction,
+  tierUsesApplication,
+  type MembershipApplicationOutcome,
+  type MembershipTierCardAction,
+} from "./membership/membershipApplication";
+export {
+  formatTrialDate,
+  isMembershipInTrial,
+  tierTrialDays,
+  trialEndDate,
+} from "./membership/membershipTrial";
+// Tier questionnaires: which questions a checkout asks and what it sends.
+export {
+  buildQuestionnaireAnswers,
+  firstMissingAnswer,
+  tierQuestionnaire,
+} from "./membership/membershipQuestionnaire";
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";

package/src/ui/headless/membership/_tests/membershipApplication.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import {
+  canWithdrawMembershipApplication,
+  membershipApplicationOutcome,
+  tierCardAction,
+  tierUsesApplication,
+} from "../membershipApplication";
+import type { MembershipApplicationStatus, MembershipTier } from "../../../../types/models";
+
+const app = (status: MembershipApplicationStatus) => ({ id: "app-1", status, paymentWindowExpiresAt: null });
+
+describe("tierCardAction", () => {
+  it("offers the tier in its own words when the fan has no application", () => {
+    expect(tierCardAction({})).toBe("join");
+    expect(tierCardAction({ joinMode: "open" })).toBe("join");
+    expect(tierCardAction({ joinMode: "invite" })).toBe("accept_invite");
+    expect(tierCardAction({ joinMode: "application" })).toBe("apply");
+    expect(tierCardAction({ joinMode: "application", myApplication: null })).toBe("apply");
+  });
+
+  it("shows where the fan's application stands instead of the button", () => {
+    expect(tierCardAction({ joinMode: "application", myApplication: app("pending") })).toBe("pending");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("approved") })).toBe("approved");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("payment_failed") })).toBe("complete");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("declined") })).toBe("declined");
+  });
+
+  it("lets a fan pick an unfinished card step back up", () => {
+    expect(tierCardAction({ joinMode: "application", myApplication: app("card_pending") })).toBe("apply");
+  });
+});
+
+describe("tierUsesApplication", () => {
+  it("is true on an application tier", () => {
+    expect(tierUsesApplication({ joinMode: "application" })).toBe(true);
+    expect(tierUsesApplication({ joinMode: "application", myApplication: app("pending") })).toBe(true);
+  });
+
+  it("EXCEPTION: a payment_failed application completes through the ordinary paid checkout", () => {
+    expect(tierUsesApplication({ joinMode: "application", myApplication: app("payment_failed") })).toBe(false);
+  });
+
+  it("is false on open and invite tiers, and with no tier", () => {
+    expect(tierUsesApplication({ joinMode: "open" } as Pick<MembershipTier, "joinMode">)).toBe(false);
+    expect(tierUsesApplication({ joinMode: "invite" })).toBe(false);
+    expect(tierUsesApplication({})).toBe(false);
+    expect(tierUsesApplication(undefined)).toBe(false);
+  });
+});
+
+describe("canWithdrawMembershipApplication", () => {
+  it("allows withdrawing only before a decision", () => {
+    expect(canWithdrawMembershipApplication("card_pending")).toBe(true);
+    expect(canWithdrawMembershipApplication("pending")).toBe(true);
+    for (const status of ["approved", "payment_failed", "joined", "declined", "withdrawn", "expired"] as const) {
+      expect(canWithdrawMembershipApplication(status)).toBe(false);
+    }
+    expect(canWithdrawMembershipApplication(undefined)).toBe(false);
+  });
+});
+
+describe("membershipApplicationOutcome", () => {
+  const outcome = (status: MembershipApplicationStatus, closedReason: string | null = null, confirmed = false) =>
+    membershipApplicationOutcome({ status, closedReason }, confirmed);
+
+  it("is null before anything was submitted, and while the card step is still ahead", () => {
+    expect(membershipApplicationOutcome(null)).toBeNull();
+    expect(outcome("card_pending")).toBeNull();
+  });
+
+  it("reads a confirmed card the server has not caught up with as received", () => {
+    expect(outcome("card_pending", null, true)).toBe("received");
+  });
+
+  it("maps every other status", () => {
+    expect(outcome("pending")).toBe("received");
+    expect(outcome("approved")).toBe("approved");
+    expect(outcome("joined")).toBe("approved");
+    expect(outcome("payment_failed")).toBe("approved");
+    expect(outcome("declined")).toBe("declined");
+    expect(outcome("withdrawn", "tier_full")).toBe("tier_full");
+    expect(outcome("withdrawn")).toBe("closed");
+    expect(outcome("expired", "expired")).toBe("closed");
+  });
+});

package/src/ui/headless/membership/_tests/membershipCheckoutRefetch.spec.tsx

@@ -39,6 +39,8 @@ vi.mock("../../../../contexts/PublicAuthContext", async (importOriginal) => ({
 vi.mock("../../../../data/queries/useMembership", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../../../../data/queries/useMembership")>()),
   useGetMembershipTiers: () => ({ data: tiers, isLoading: false }),
+  useApplyForMembership: () => ({ mutateAsync: vi.fn(), isPending: false }),
+  useConfirmMembershipApplication: () => ({ mutateAsync: vi.fn(), isPending: false }),
 }));
 
 vi.mock("../../../../data/queries/useSubscriptions", async (importOriginal) => ({

package/src/ui/headless/membership/_tests/membershipTrial.spec.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { formatTrialDate, isMembershipInTrial, tierTrialDays, trialEndDate } from "../membershipTrial";
+
+/**
+ * Free trials on paid membership tiers: who gets one, when it ends, and whether
+ * a membership is still inside it. Every surface reads these, so they are pinned
+ * as pure functions.
+ */
+describe("tierTrialDays", () => {
+  it("gives the tier's trial to an eligible fan, and to a signed-out visitor (no trialEligible)", () => {
+    expect(tierTrialDays({ trialDays: 14, trialEligible: true })).toBe(14);
+    expect(tierTrialDays({ trialDays: 7 })).toBe(7);
+  });
+
+  it("gives none to a fan who already had a trial with this business", () => {
+    expect(tierTrialDays({ trialDays: 14, trialEligible: false })).toBe(0);
+  });
+
+  it("gives none when the tier has no trial", () => {
+    expect(tierTrialDays({ trialDays: null })).toBe(0);
+    expect(tierTrialDays({ trialDays: 0 })).toBe(0);
+    expect(tierTrialDays({ trialDays: -3 })).toBe(0);
+    expect(tierTrialDays({})).toBe(0);
+    expect(tierTrialDays(undefined)).toBe(0);
+  });
+
+  it("gives none to a member with a live paid subscription (that is a tier change)", () => {
+    expect(
+      tierTrialDays({ trialDays: 14 }, { paymentProviderSubscriptionId: "sub_1", status: "active" }),
+    ).toBe(0);
+    // A lapsed or free membership does not block the trial.
+    expect(tierTrialDays({ trialDays: 14 }, { paymentProviderSubscriptionId: "sub_1", status: "cancelled" })).toBe(14);
+    expect(tierTrialDays({ trialDays: 14 }, { status: "active" })).toBe(14);
+  });
+});
+
+describe("trialEndDate", () => {
+  it("is today plus the trial days", () => {
+    const now = new Date("2026-09-17T10:00:00.000Z");
+    expect(trialEndDate(14, now).toISOString()).toBe("2026-10-01T10:00:00.000Z");
+  });
+});
+
+describe("isMembershipInTrial", () => {
+  const now = new Date("2026-09-17T10:00:00.000Z");
+  it("is true only while trialEndsAt is in the future", () => {
+    expect(isMembershipInTrial({ trialEndsAt: "2026-09-30T00:00:00.000Z" }, now)).toBe(true);
+    expect(isMembershipInTrial({ trialEndsAt: "2026-09-01T00:00:00.000Z" }, now)).toBe(false);
+    expect(isMembershipInTrial({ trialEndsAt: null }, now)).toBe(false);
+    expect(isMembershipInTrial({}, now)).toBe(false);
+    expect(isMembershipInTrial(undefined, now)).toBe(false);
+    expect(isMembershipInTrial({ trialEndsAt: "not a date" }, now)).toBe(false);
+  });
+});
+
+describe("formatTrialDate", () => {
+  it("formats per locale", () => {
+    expect(formatTrialDate("2026-10-01T12:00:00.000Z", "en")).toBe("Oct 1, 2026");
+    expect(formatTrialDate("2026-10-01T12:00:00.000Z", "de")).toContain("2026");
+  });
+});