@tribe-nest/forge 3.54.0 → 3.58.0

package/src/ui/headless/event/useEventSeating.ts

@@ -0,0 +1,233 @@
+import { useMemo } from "react";
+import { flattenSeats, type SeatMapDocument } from "@tribe-nest/seating-core";
+import { useEventSeatingQuery, type PublicEventSeat, type PublicEventSeating } from "../../../data/queries/useEvents";
+
+/**
+ * Reserved seating on the buyer surface (seating wave 2, docs §11.6).
+ *
+ * This hook is the ONE join between the two halves of the seating read: the
+ * frozen layout (where a seat is drawn, what it is called) and the live seat
+ * list (which event seat it is, which tier prices it, whether it is free). The
+ * picker draws off the layout and toggles off the seat list, and every label a
+ * buyer reads ("Stalls · Row A · Seat 12") is built here, once, so the alert
+ * that names a seat somebody else took and the chip under the tier row can
+ * never disagree about what a seat is called.
+ */
+
+/** A public event seat joined to its place in the layout. */
+export interface EventSeat extends PublicEventSeat {
+  /** The section or table the seat belongs to, in the layout. */
+  objectId: string;
+  objectType: "section" | "table";
+  /** Position of the parent in the document's z-order: the "section order" of best-available. */
+  objectOrder: number;
+  sectionName: string;
+  /** Empty for a table seat. */
+  rowLabel: string;
+  seatLabel: string;
+  rowOrder: number;
+  seatOrder: number;
+  /** "Stalls · Row A · Seat 12", or "Table 4 · Seat 2". What every surface prints. */
+  label: string;
+}
+
+export interface EventSeatingState {
+  /** `undefined` while loading, `null` when the event has no seat map. */
+  seating: PublicEventSeating | null | undefined;
+  isLoading: boolean;
+  /** True once a read has completed, whatever it said. Selection rules wait for this. */
+  isFetched: boolean;
+  refetch: () => Promise<unknown>;
+  /** By EVENT seat id (what an order names). */
+  byId: Map<string, EventSeat>;
+  /** By the seat's id inside the layout (what a `<circle>` carries). */
+  bySource: Map<string, EventSeat>;
+  /** Seats that read `available`, per ticket tier. Tiers with no seat are absent. */
+  availableByTier: Record<string, number>;
+  /** Tiers that sell reserved seats on this event: the ones an order must carry `seats` for. */
+  seatedTierIds: Set<string>;
+  /** Every seat, in layout order (section, row, seat). */
+  seats: EventSeat[];
+}
+
+export interface UseEventSeatingOptions {
+  /** Fetch at all. Default true. */
+  enabled?: boolean;
+  /** Poll interval while enabled. Default 5000; `0`/`false` polls nothing. */
+  pollMs?: number | false;
+}
+
+const EMPTY_SEATS: EventSeat[] = [];
+
+/** The buyer-facing name of a seat. Table seats have no row. */
+export const seatLabel = (parts: { sectionName: string; rowLabel: string; seatLabel: string }): string =>
+  parts.rowLabel
+    ? `${parts.sectionName} · Row ${parts.rowLabel} · Seat ${parts.seatLabel}`
+    : `${parts.sectionName} · Seat ${parts.seatLabel}`;
+
+/**
+ * Join the seat list to the layout. Pure, so the picker's tests and the
+ * checkout's tests can build the same index off a fixture.
+ *
+ * A seat the layout does not know (it cannot happen on a bound map, but the
+ * two halves are separate rows) still gets an entry, labelled by its id, so an
+ * order can name it and an alert can still say something.
+ */
+export function indexEventSeats(seating: PublicEventSeating | null | undefined): {
+  seats: EventSeat[];
+  byId: Map<string, EventSeat>;
+  bySource: Map<string, EventSeat>;
+} {
+  const byId = new Map<string, EventSeat>();
+  const bySource = new Map<string, EventSeat>();
+  if (!seating) return { seats: EMPTY_SEATS, byId, bySource };
+
+  const flat = new Map(flattenSeats(seating.layout as SeatMapDocument).map((seat) => [seat.seatId, seat]));
+  const objectOrder = new Map<string, number>();
+  seating.layout.objects.forEach((object, index) => objectOrder.set(object.id, index));
+
+  const seats: EventSeat[] = seating.seats.map((seat) => {
+    const place = flat.get(seat.sourceSeatId);
+    if (!place) {
+      return {
+        ...seat,
+        objectId: "",
+        objectType: "section",
+        objectOrder: Number.MAX_SAFE_INTEGER,
+        sectionName: "",
+        rowLabel: "",
+        seatLabel: seat.sourceSeatId,
+        rowOrder: Number.MAX_SAFE_INTEGER,
+        seatOrder: Number.MAX_SAFE_INTEGER,
+        label: `Seat ${seat.sourceSeatId}`,
+      };
+    }
+    return {
+      ...seat,
+      objectId: place.objectId,
+      objectType: place.objectType,
+      objectOrder: objectOrder.get(place.objectId) ?? Number.MAX_SAFE_INTEGER,
+      sectionName: place.sectionName,
+      rowLabel: place.rowLabel,
+      seatLabel: place.seatLabel,
+      rowOrder: place.rowOrder,
+      seatOrder: place.seatOrder,
+      label: seatLabel(place),
+    };
+  });
+  seats.sort(compareSeats);
+  for (const seat of seats) {
+    byId.set(seat.id, seat);
+    bySource.set(seat.sourceSeatId, seat);
+  }
+  return { seats, byId, bySource };
+}
+
+/** Section (z-order), then row, then seat: the "lowest" a best-available pick means. */
+export const compareSeats = (a: EventSeat, b: EventSeat): number =>
+  a.objectOrder - b.objectOrder || a.rowOrder - b.rowOrder || a.seatOrder - b.seatOrder;
+
+/**
+ * The best `count` available seats of a tier.
+ *
+ * The lowest contiguous run in the lowest row first: a party of three wants
+ * three seats side by side more than it wants the three lowest numbers in the
+ * room. A run means consecutive `seatOrder` inside ONE row, and an unavailable
+ * seat breaks it, so "A1, A2, A4" is never offered as a run. When no row has a
+ * free run that long, the lowest `count` seats are returned instead. Fewer
+ * than `count` available: whatever is left, and the caller decides what that
+ * means.
+ *
+ * `exclude` is the buyer's current selection, so "+" adds seats rather than
+ * re-offering the ones already chosen. `near` prefers, for a single seat, one
+ * adjacent to a seat already held in the same row, which is what makes the
+ * stepper build a party rather than scatter it.
+ */
+export function bestAvailableSeats(
+  seats: readonly EventSeat[],
+  ticketId: string,
+  count: number,
+  exclude: ReadonlySet<string> = new Set(),
+  near: readonly EventSeat[] = [],
+): EventSeat[] {
+  if (count <= 0) return [];
+  const candidates = seats
+    .filter((seat) => seat.eventTicketId === ticketId && seat.status === "available" && !exclude.has(seat.id))
+    .sort(compareSeats);
+  if (candidates.length === 0) return [];
+
+  if (count === 1 && near.length > 0) {
+    for (const held of [...near].sort(compareSeats)) {
+      const neighbour = candidates.find(
+        (seat) =>
+          seat.objectId === held.objectId &&
+          seat.rowOrder === held.rowOrder &&
+          Math.abs(seat.seatOrder - held.seatOrder) === 1,
+      );
+      if (neighbour) return [neighbour];
+    }
+  }
+
+  // Rows in order; the first row holding a run of `count` wins.
+  const rows = new Map<string, EventSeat[]>();
+  for (const seat of candidates) {
+    const key = `${seat.objectId}\u0000${seat.rowOrder}`;
+    const row = rows.get(key);
+    if (row) row.push(seat);
+    else rows.set(key, [seat]);
+  }
+  for (const row of rows.values()) {
+    for (let i = 0; i + count <= row.length; i += 1) {
+      const first = row[i]!;
+      const last = row[i + count - 1]!;
+      if (last.seatOrder - first.seatOrder === count - 1) return row.slice(i, i + count);
+    }
+  }
+  return candidates.slice(0, count);
+}
+
+/**
+ * The seat map and live availability for one event, joined and indexed.
+ *
+ * Polls every `pollMs` while `enabled`: the picker passes `enabled` only while
+ * it is on screen, so a fan reading the event page costs the API nothing, and
+ * a fan choosing seats sees a seat somebody else took within five seconds.
+ */
+export function useEventSeating(eventId?: string, opts: UseEventSeatingOptions = {}): EventSeatingState {
+  const { enabled = true, pollMs = 5000 } = opts;
+  const query = useEventSeatingQuery(eventId, { enabled, pollMs });
+  const seating = query.data;
+
+  const index = useMemo(() => indexEventSeats(seating), [seating]);
+
+  const availableByTier = useMemo(() => {
+    const out: Record<string, number> = {};
+    for (const seat of index.seats) {
+      if (!(seat.eventTicketId in out)) out[seat.eventTicketId] = 0;
+      if (seat.status === "available") out[seat.eventTicketId] += 1;
+    }
+    return out;
+  }, [index.seats]);
+
+  // A tier is seated when it HAS seats on this event, which is the server's
+  // own definition (§11.2). `tierMapping` is deliberately not consulted: a
+  // category mapped to a tier through a general admission AREA puts no seat
+  // on the map, and that tier keeps its plain quantity.
+  const seatedTierIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const seat of index.seats) ids.add(seat.eventTicketId);
+    return ids;
+  }, [index.seats]);
+
+  return {
+    seating,
+    isLoading: enabled && query.isLoading,
+    isFetched: query.isFetched,
+    refetch: query.refetch,
+    byId: index.byId,
+    bySource: index.bySource,
+    availableByTier,
+    seatedTierIds,
+    seats: index.seats,
+  };
+}

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

@@ -0,0 +1,187 @@
+// @vitest-environment jsdom
+// Hooks with effects need a DOM; the runner defaults to node and opts in per
+// file, per the note in vitest.config.ts.
+import { describe, it, expect } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { usePhoneInput } from "../usePhoneInput";
+
+/**
+ * The contract these pin is narrow and load-bearing: whatever a visitor types,
+ * what leaves this hook is either strict E.164 or null.
+ *
+ * `services/admin/consent/phone.ts` keys suppression by number and deliberately
+ * refuses to guess a country for a bare national string, so a number stored
+ * without its country never matches the E.164 one a carrier sends on a STOP.
+ * These are the cases where that used to happen.
+ *
+ * On the fixtures: UK numbers here are from ASSIGNABLE ranges. Ofcom reserves
+ * 07700 900xxx and 020 7946 0xxx for drama, and libphonenumber correctly calls
+ * those invalid, so a spec written with them fails for a reason that has
+ * nothing to do with this hook.
+ */
+const ready = async (hook: { result: { current: { isReady: boolean } } }) =>
+  waitFor(() => expect(hook.result.current.isReady).toBe(true));
+
+describe("usePhoneInput", () => {
+  it("turns a national number under a chosen country into E.164", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("07400123456"));
+
+    expect(hook.result.current.e164).toBe("+447400123456");
+    expect(hook.result.current.isValid).toBe(true);
+  });
+
+  it("drops the trunk prefix, which is the whole reason a bare national number never matched", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("07400 123456"));
+
+    // The leading 0 is a national dialling convention, not part of the number.
+    // Stored verbatim it would never equal the +44… a carrier reports on STOP.
+    expect(hook.result.current.e164).toBe("+447400123456");
+    expect(hook.result.current.e164).not.toContain("+4407");
+  });
+
+  it("keeps a pasted international number intact and moves the flag to match", async () => {
+    // The field says "without the country code" and a large share of people
+    // paste the full number anyway. Formatted as a GB national string that
+    // would come out mangled.
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("+12015550123"));
+
+    expect(hook.result.current.e164).toBe("+12015550123");
+    expect(hook.result.current.country).toBe("US");
+  });
+
+  it("re-reads the same digits under a corrected country instead of clearing them", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("2015550123"));
+    act(() => hook.result.current.setCountry("US"));
+
+    // Someone who typed first and fixed the flag afterwards should not have to
+    // retype, and the answer must follow the new country rather than the old.
+    expect(hook.result.current.e164).toBe("+12015550123");
+  });
+
+  it("emits null rather than a half-number while the input is incomplete", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("0740"));
+
+    expect(hook.result.current.e164).toBeNull();
+    expect(hook.result.current.isValid).toBe(false);
+  });
+
+  it("rejects a number that is not valid for the country selected", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("1111111"));
+    act(() => hook.result.current.markTouched());
+
+    expect(hook.result.current.e164).toBeNull();
+    expect(hook.result.current.error).toBe("invalid");
+  });
+
+  it("asks for a country before it will judge a bare national number", async () => {
+    const hook = renderHook(() => usePhoneInput({}));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("7700900123"));
+    act(() => hook.result.current.markTouched());
+
+    // Guessing a country here is exactly the mistake the consent normaliser
+    // refuses to make, so the hook asks instead.
+    expect(hook.result.current.error).toBe("no_country");
+    expect(hook.result.current.e164).toBeNull();
+  });
+
+  it("stays quiet until the field has been blurred", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("07"));
+
+    // Shouting "invalid" at someone two characters into typing is noise.
+    expect(hook.result.current.error).toBeNull();
+  });
+
+  it("flags a landline for messaging but still yields the number", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB", mode: "messaging" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("02072193000"));
+
+    // A warning, never a block: line type comes from a numbering plan that many
+    // countries do not partition cleanly, so refusing on it would reject real
+    // numbers.
+    expect(hook.result.current.isValid).toBe(true);
+    expect(hook.result.current.e164).toBe("+442072193000");
+    expect(hook.result.current.warning).toBe("landline");
+  });
+
+  it("says nothing about line type when the number is for a courier", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB", mode: "shipping" }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("02072193000"));
+
+    expect(hook.result.current.isValid).toBe(true);
+    expect(hook.result.current.warning).toBeNull();
+  });
+
+  it("adopts a default country that only resolves after the first render", async () => {
+    // Checkout learns the shipping country after the address is filled.
+    const hook = renderHook(({ c }) => usePhoneInput({ defaultCountry: c }), {
+      initialProps: { c: undefined as "GB" | undefined },
+    });
+    await ready(hook);
+    expect(hook.result.current.country).toBeUndefined();
+
+    hook.rerender({ c: "GB" });
+
+    expect(hook.result.current.country).toBe("GB");
+  });
+
+  it("does not overrule a country the visitor chose themselves", async () => {
+    const hook = renderHook(({ c }) => usePhoneInput({ defaultCountry: c }), {
+      initialProps: { c: undefined as "GB" | undefined },
+    });
+    await ready(hook);
+
+    act(() => hook.result.current.setCountry("NG"));
+    hook.rerender({ c: "GB" });
+
+    expect(hook.result.current.country).toBe("NG");
+  });
+
+  it("offers a national example for the chosen country as the placeholder", async () => {
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB" }));
+    await ready(hook);
+
+    // Teaching the shape beats a sentence under the field, and it has to be the
+    // national form because that is what we are asking for.
+    expect(hook.result.current.placeholder).toBeTruthy();
+    expect(hook.result.current.placeholder).not.toContain("+44");
+  });
+
+  it("reports the caller's changes as E.164 or null, never as raw text", async () => {
+    const seen: (string | null)[] = [];
+    const hook = renderHook(() => usePhoneInput({ defaultCountry: "GB", onChange: (v) => seen.push(v) }));
+    await ready(hook);
+
+    act(() => hook.result.current.setValue("0740"));
+    act(() => hook.result.current.setValue("07400123456"));
+
+    expect(seen).toContain("+447400123456");
+    expect(seen.every((v) => v === null || v.startsWith("+"))).toBe(true);
+  });
+});

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

@@ -1,5 +1,7 @@
 import { useState } from "react";
+import type { CountryCode } from "libphonenumber-js";
 import { useJoinEmailList } from "../../../data/queries/useLeadMagnet";
+import { usePhoneInput } from "./usePhoneInput";
 
 export type FormStatus = "idle" | "submitting" | "success" | "error";
 
@@ -8,10 +10,16 @@ export interface UseEmailListFormOptions {
   leadMagnetId?: string;
   includeName?: boolean;
   includePhoneNumber?: boolean;
+  /**
+   * Seeds the country select. Pass the most confident source the site has (the
+   * visitor's geo, the creator's own country). Left undefined the visitor picks
+   * for themselves, which is better than a guess: an unasked-for default is how
+   * a number ends up stored under the wrong country.
+   */
+  defaultCountry?: CountryCode;
 }
 
 const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-const phoneRe = /^\+?[0-9\s\-()]{7,20}$/;
 
 /**
  * Headless email-list-join behavior: form state + validation + the join
@@ -21,7 +29,20 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
   const join = useJoinEmailList();
   const [email, setEmail] = useState("");
   const [name, setName] = useState("");
-  const [phoneNumber, setPhoneNumber] = useState("");
+  /**
+   * The phone field submits E.164, never what was typed.
+   *
+   * The regex this replaced accepted `0000000` and any bracket soup, and a
+   * national number stored verbatim can never match the E.164 a carrier sends
+   * on a STOP, so the suppression list misses and we keep texting someone who
+   * asked us not to. `usePhoneInput` asks for the country instead of guessing
+   * it, which is the only point in the flow where it can be known.
+   */
+  const phone = usePhoneInput({
+    enabled: !!opts.includePhoneNumber,
+    defaultCountry: opts.defaultCountry,
+    mode: "messaging",
+  });
   const [status, setStatus] = useState<FormStatus>("idle");
   const [error, setError] = useState<string | null>(null);
   const [requiresConfirmation, setRequiresConfirmation] = useState(false);
@@ -36,7 +57,8 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
       setError("Please enter your name");
       return;
     }
-    if (opts.includePhoneNumber && (!phoneNumber.trim() || !phoneRe.test(phoneNumber.trim()))) {
+    if (opts.includePhoneNumber && !phone.e164) {
+      phone.markTouched();
       setError("Please enter a valid phone number");
       return;
     }
@@ -47,7 +69,7 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
         emailListId: opts.emailListId,
         leadMagnetId: opts.leadMagnetId,
         firstName: opts.includeName ? name.trim() : undefined,
-        phoneNumber: opts.includePhoneNumber ? phoneNumber.trim() : undefined,
+        phoneNumber: opts.includePhoneNumber ? (phone.e164 ?? undefined) : undefined,
       });
       setRequiresConfirmation(!!data?.requiresConfirmation);
       setStatus("success");
@@ -63,8 +85,17 @@ export function useEmailListForm(opts: UseEmailListFormOptions = {}) {
     setEmail,
     name,
     setName,
-    phoneNumber,
-    setPhoneNumber,
+    /** The phone field's controller. Hand it to <PhoneInput controller={...} />. */
+    phone,
+    /** E.164 or empty. Kept for callers that only want the value. */
+    phoneNumber: phone.e164 ?? "",
+    /**
+     * @deprecated Use `phone.setValue`, or hand `phone` to <PhoneInput>.
+     * Kept so this release stays a minor: it forwards into the same formatter,
+     * so a caller still on it gets the country handling for free rather than
+     * writing an unvalidated string.
+     */
+    setPhoneNumber: phone.setValue,
     status,
     error,
     requiresConfirmation,