@tribe-nest/forge 3.54.0 → 3.58.0

package/src/ui/styled/_tests/membershipTiersCuratedAccess.spec.tsx

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, waitFor, fireEvent, cleanup } from "@testing-library/react";
+import axios, { type AxiosAdapter, type InternalAxiosRequestConfig } from "axios";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import type { MembershipApplicationStatus, MembershipTier } from "../../../types/models";
+import { MembershipTiers } from "../MembershipTiers";
+
+/**
+ * The tier card under curated access, over the REAL query layer: what the card
+ * offers for each join mode and each state of the fan's own application, that
+ * the invite token on the url reaches the tier list request, and that Withdraw
+ * posts to the right application.
+ */
+
+const PROFILE_ID = "profile-1";
+let sent: { method: string; url: string; params: Record<string, unknown>; body: Record<string, unknown> | null }[] = [];
+let realAdapter: AxiosAdapter | undefined;
+
+const tier = (id: string, overrides: Partial<MembershipTier> = {}): MembershipTier => ({
+  id,
+  name: `Tier ${id}`,
+  description: "",
+  priceMonthly: 10,
+  payWhatYouWant: false,
+  benefits: [],
+  ...overrides,
+});
+
+const withApplication = (id: string, status: MembershipApplicationStatus) =>
+  tier(id, { joinMode: "application", myApplication: { id: `app-${id}`, status, paymentWindowExpiresAt: null } });
+
+function mount(tiers: MembershipTier[]) {
+  sent = [];
+  const adapter: AxiosAdapter = async (config: InternalAxiosRequestConfig) => {
+    const url = config.url ?? "";
+    const body = config.data ? (JSON.parse(config.data as string) as Record<string, unknown>) : null;
+    sent.push({ method: (config.method ?? "get").toLowerCase(), url, params: config.params ?? {}, body });
+    const reply = (data: unknown) =>
+      Promise.resolve({ data, status: 200, statusText: "OK", headers: {}, config } as never);
+    if (url.includes("/public/membership-tiers")) return reply(tiers);
+    if (url.includes("/withdraw")) return reply({ application: { id: "x", status: "withdrawn" } });
+    return reply({});
+  };
+  realAdapter = axios.defaults.adapter as AxiosAdapter | undefined;
+  axios.defaults.adapter = adapter;
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+        <PublicAuthContext.Provider value={{ user: null, isInitialized: true, isAuthenticated: false } as never}>
+          <ForgeThemeProvider theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}>
+            <MembershipTiers />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  if (realAdapter) axios.defaults.adapter = realAdapter;
+  window.history.replaceState(null, "", "/");
+});
+
+const cardOf = async (name: string) => {
+  const heading = await screen.findByRole("heading", { name });
+  return heading.parentElement as HTMLElement;
+};
+
+describe("MembershipTiers: the card per join mode and application state", () => {
+  it("reads Select, Accept invite and Apply to join by join mode", async () => {
+    mount([tier("open"), tier("inv", { joinMode: "invite" }), tier("app", { joinMode: "application" })]);
+
+    expect((await cardOf("Tier open")).textContent).toContain("Select");
+    expect((await cardOf("Tier inv")).textContent).toContain("Accept invite");
+    expect((await cardOf("Tier app")).textContent).toContain("Apply to join");
+  });
+
+  it("shows the application's state instead of the join button", async () => {
+    mount([
+      withApplication("p", "pending"),
+      withApplication("a", "approved"),
+      withApplication("f", "payment_failed"),
+      withApplication("d", "declined"),
+    ]);
+
+    const pending = await cardOf("Tier p");
+    expect(pending.textContent).toContain("Application pending");
+    expect(pending.textContent).toContain("Withdraw application");
+    expect(pending.textContent).not.toContain("Apply to join");
+
+    const approved = await cardOf("Tier a");
+    expect(approved.textContent).toContain("Approved, finishing up");
+    expect(approved.querySelector("button")).toBeNull();
+
+    const failed = await cardOf("Tier f");
+    expect(failed.textContent).toContain("Approved: complete your membership");
+    expect(failed.textContent).toContain("Complete your membership");
+
+    const declined = await cardOf("Tier d");
+    expect(declined.textContent).toContain("Not approved");
+    expect(declined.querySelector("button")).toBeNull();
+  });
+
+  it("withdraws the pending application it shows", async () => {
+    mount([withApplication("p", "pending")]);
+    const card = await cardOf("Tier p");
+    fireEvent.click(card.querySelector("button") as HTMLButtonElement);
+
+    await waitFor(() => expect(sent.some((r) => r.method === "post" && r.url.includes("/withdraw"))).toBe(true));
+    const post = sent.find((r) => r.url.includes("/withdraw"))!;
+    expect(post.url).toContain("/public/membership-applications/app-p/withdraw");
+    expect(post.body).toEqual({ profileId: PROFILE_ID });
+  });
+});
+
+describe("the invite token reaches the tier list", () => {
+  it("forwards `?invite=` as inviteToken", async () => {
+    window.history.replaceState(null, "", "/i/membership?invite=tok-123");
+    mount([tier("inv", { joinMode: "invite" })]);
+    await cardOf("Tier inv");
+
+    const get = sent.find((r) => r.url.includes("/public/membership-tiers"))!;
+    expect(get.params).toEqual({ profileId: PROFILE_ID, inviteToken: "tok-123" });
+  });
+
+  it("sends no inviteToken without one", async () => {
+    mount([tier("open")]);
+    await cardOf("Tier open");
+
+    const get = sent.find((r) => r.url.includes("/public/membership-tiers"))!;
+    expect(get.params).toEqual({ profileId: PROFILE_ID });
+  });
+});

package/src/ui/styled/_tests/membershipTiersTrial.spec.tsx

@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import axios, { type AxiosAdapter, type InternalAxiosRequestConfig } from "axios";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import type { MembershipTier } from "../../../types/models";
+import { MembershipTiers } from "../MembershipTiers";
+
+/**
+ * The tier card with a free trial: the badge and the "Start free trial" button
+ * appear only when this fan would get the trial, an application tier keeps
+ * "Apply to join", and a member with a live subscription (changing tier) is
+ * offered no trial.
+ */
+
+let realAdapter: AxiosAdapter | undefined;
+
+const tier = (id: string, overrides: Partial<MembershipTier> = {}): MembershipTier => ({
+  id,
+  name: `Tier ${id}`,
+  description: "",
+  priceMonthly: 10,
+  payWhatYouWant: false,
+  benefits: [],
+  ...overrides,
+});
+
+function mount(tiers: MembershipTier[], user: unknown = null) {
+  const adapter: AxiosAdapter = async (config: InternalAxiosRequestConfig) =>
+    ({ data: (config.url ?? "").includes("/public/membership-tiers") ? tiers : {}, status: 200, statusText: "OK", headers: {}, config }) as never;
+  realAdapter = axios.defaults.adapter as AxiosAdapter | undefined;
+  axios.defaults.adapter = adapter;
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId="profile-1">
+        <PublicAuthContext.Provider value={{ user, isInitialized: true, isAuthenticated: !!user } as never}>
+          <ForgeThemeProvider theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}>
+            <MembershipTiers />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  if (realAdapter) axios.defaults.adapter = realAdapter;
+});
+
+const cardOf = async (name: string) => (await screen.findByRole("heading", { name })).parentElement as HTMLElement;
+const badge = (card: HTMLElement) => card.querySelector('[data-testid="membership-tier-trial-badge"]');
+
+describe("MembershipTiers: free trial badge and button", () => {
+  it("shows the badge and Start free trial when eligible, including for a signed-out visitor", async () => {
+    mount([tier("eligible", { trialDays: 14, trialEligible: true }), tier("anon", { trialDays: 7 })]);
+
+    const eligible = await cardOf("Tier eligible");
+    expect(badge(eligible)?.textContent).toBe("14-day free trial");
+    expect(eligible.querySelector("button")?.textContent).toBe("Start free trial");
+
+    const anon = await cardOf("Tier anon");
+    expect(badge(anon)?.textContent).toBe("7-day free trial");
+    expect(anon.querySelector("button")?.textContent).toBe("Start free trial");
+  });
+
+  it("shows no badge and the plain button to a fan who already had a trial, or on a tier without one", async () => {
+    mount([tier("used", { trialDays: 14, trialEligible: false }), tier("none", { trialDays: null })]);
+
+    for (const name of ["Tier used", "Tier none"]) {
+      const card = await cardOf(name);
+      expect(badge(card), name).toBeNull();
+      expect(card.querySelector("button")?.textContent, name).toBe("Select");
+    }
+  });
+
+  it("keeps Apply to join on an application tier, with the trial badge", async () => {
+    mount([tier("app", { joinMode: "application", trialDays: 30 })]);
+    const card = await cardOf("Tier app");
+    expect(badge(card)?.textContent).toBe("30-day free trial");
+    expect(card.querySelector("button")?.textContent).toBe("Apply to join");
+  });
+
+  it("offers no trial to a member with a live paid subscription (a tier change)", async () => {
+    mount([tier("t", { trialDays: 14, trialEligible: true })], {
+      id: "account-1",
+      membership: { paymentProviderSubscriptionId: "sub_1", status: "active", membershipTierId: "other" },
+    });
+    const card = await cardOf("Tier t");
+    expect(badge(card)).toBeNull();
+    expect(card.querySelector("button")?.textContent).toBe("Select");
+  });
+});

package/src/ui/styled/forge-utilities.css

@@ -65,6 +65,9 @@
   .fg\:inset-0 {
     inset: calc(var(--fg-spacing) * 0);
   }
+  .fg\:top-2 {
+    top: calc(var(--fg-spacing) * 2);
+  }
   .fg\:top-4 {
     top: calc(var(--fg-spacing) * 4);
   }
@@ -74,18 +77,30 @@
   .fg\:right-0 {
     right: calc(var(--fg-spacing) * 0);
   }
+  .fg\:right-2 {
+    right: calc(var(--fg-spacing) * 2);
+  }
+  .fg\:right-14 {
+    right: calc(var(--fg-spacing) * 14);
+  }
   .fg\:bottom-0 {
     bottom: calc(var(--fg-spacing) * 0);
   }
   .fg\:left-0 {
     left: calc(var(--fg-spacing) * 0);
   }
+  .fg\:left-2 {
+    left: calc(var(--fg-spacing) * 2);
+  }
   .fg\:z-40 {
     z-index: 40;
   }
   .fg\:z-50 {
     z-index: 50;
   }
+  .fg\:m-0 {
+    margin: calc(var(--fg-spacing) * 0);
+  }
   .fg\:mx-auto {
     margin-inline: auto;
   }
@@ -158,33 +173,54 @@
   .fg\:hidden {
     display: none;
   }
+  .fg\:inline-block {
+    display: inline-block;
+  }
   .fg\:inline-flex {
     display: inline-flex;
   }
   .fg\:h-0\.5 {
     height: calc(var(--fg-spacing) * 0.5);
   }
+  .fg\:h-3 {
+    height: calc(var(--fg-spacing) * 3);
+  }
   .fg\:h-4 {
     height: calc(var(--fg-spacing) * 4);
   }
   .fg\:h-8 {
     height: calc(var(--fg-spacing) * 8);
   }
+  .fg\:h-9 {
+    height: calc(var(--fg-spacing) * 9);
+  }
   .fg\:h-12 {
     height: calc(var(--fg-spacing) * 12);
   }
   .fg\:h-\[70vh\] {
     height: 70vh;
   }
+  .fg\:h-\[320px\] {
+    height: 320px;
+  }
   .fg\:h-full {
     height: 100%;
   }
+  .fg\:min-h-\[320px\] {
+    min-height: 320px;
+  }
+  .fg\:w-3 {
+    width: calc(var(--fg-spacing) * 3);
+  }
   .fg\:w-4 {
     width: calc(var(--fg-spacing) * 4);
   }
   .fg\:w-8 {
     width: calc(var(--fg-spacing) * 8);
   }
+  .fg\:w-9 {
+    width: calc(var(--fg-spacing) * 9);
+  }
   .fg\:w-10 {
     width: calc(var(--fg-spacing) * 10);
   }
@@ -224,9 +260,15 @@
   .fg\:cursor-pointer {
     cursor: pointer;
   }
+  .fg\:touch-none {
+    touch-action: none;
+  }
   .fg\:resize-y {
     resize: vertical;
   }
+  .fg\:list-none {
+    list-style-type: none;
+  }
   .fg\:grid-cols-1 {
     grid-template-columns: repeat(1, minmax(0, 1fr));
   }
@@ -236,6 +278,9 @@
   .fg\:flex-col {
     flex-direction: column;
   }
+  .fg\:flex-row {
+    flex-direction: row;
+  }
   .fg\:flex-wrap {
     flex-wrap: wrap;
   }
@@ -308,6 +353,9 @@
       margin-block-end: calc(calc(var(--fg-spacing) * 6) * calc(1 - var(--tw-space-y-reverse)));
     }
   }
+  .fg\:gap-x-4 {
+    column-gap: calc(var(--fg-spacing) * 4);
+  }
   .fg\:space-x-4 {
     :where(& > :not(:last-child)) {
       --tw-space-x-reverse: 0;
@@ -315,6 +363,9 @@
       margin-inline-end: calc(calc(var(--fg-spacing) * 4) * calc(1 - var(--tw-space-x-reverse)));
     }
   }
+  .fg\:gap-y-2 {
+    row-gap: calc(var(--fg-spacing) * 2);
+  }
   .fg\:overflow-hidden {
     overflow: hidden;
   }
@@ -340,6 +391,10 @@
     border-style: var(--tw-border-style);
     border-width: 1px;
   }
+  .fg\:border-0 {
+    border-style: var(--tw-border-style);
+    border-width: 0px;
+  }
   .fg\:border-2 {
     border-style: var(--tw-border-style);
     border-width: 2px;
@@ -387,6 +442,9 @@
   .fg\:bg-transparent {
     background-color: transparent;
   }
+  .fg\:p-0 {
+    padding: calc(var(--fg-spacing) * 0);
+  }
   .fg\:p-0\.5 {
     padding: calc(var(--fg-spacing) * 0.5);
   }
@@ -583,6 +641,10 @@
     --tw-outline-style: none;
     outline-style: none;
   }
+  .fg\:select-none {
+    -webkit-user-select: none;
+    user-select: none;
+  }
   .fg\:focus\:border-primary {
     &:focus {
       border-color: var(--fg-color-primary);
@@ -678,6 +740,11 @@
       height: calc(var(--fg-spacing) * 64);
     }
   }
+  .fg\:md\:h-\[440px\] {
+    @media (width >= 48rem) {
+      height: 440px;
+    }
+  }
   .fg\:md\:w-64 {
     @media (width >= 48rem) {
       width: calc(var(--fg-spacing) * 64);

package/src/ui/styled/seating/EventSeatPicker.tsx

@@ -0,0 +1,190 @@
+import { useCallback, useEffect, useMemo, useState, type CSSProperties } from "react";
+import { AlertCircle, X } from "lucide-react";
+import type { IEvent } from "../../../types/models";
+import type { EventSeat, EventSeatingState } from "../../headless/event/useEventSeating";
+import type { ToggleSeatResult } from "../../headless/event/useEventCheckout";
+import { useForgeT } from "../../../i18n";
+import { useForgeTheme, type ForgeTheme } from "../../theme/ForgeThemeProvider";
+import { CallHelpHint } from "../../media/CallHelpHint";
+import { Loading } from "../Loading";
+import { SeatMapCanvas } from "./SeatMapCanvas";
+import { SeatLegend, type SeatLegendTier } from "./SeatLegend";
+import { tierColorMap } from "./paint";
+
+export interface EventSeatPickerProps {
+  /** The event whose tiers price the seats. Tier order fixes the palette. */
+  event: IEvent;
+  /** The joined seating read, from `useEventCheckout().seating` or `useEventSeating`. */
+  seating: EventSeatingState;
+  /** ticketId -> the EVENT seat ids the buyer holds. */
+  selectedSeats: Record<string, string[]>;
+  /**
+   * A tap on a seat. `useEventCheckout().toggleSeat` fits directly; a host
+   * driving its own state may return nothing, in which case no notice is shown.
+   */
+  onToggleSeat: (ticketId: string, seatId: string) => ToggleSeatResult | void;
+  /** Seats that left the selection because somebody else got them. Rendered as an alert. */
+  seatsTaken?: { labels: string[] } | null;
+  onDismissSeatsTaken?: () => void;
+  /** Format a numeric amount for display. */
+  formatAmount: (amount: number) => string;
+  /** Host classes on the outer element, passed through untouched. */
+  className?: string;
+}
+
+/** Append an alpha to a 6-digit hex color. */
+const a = (hex: string, alpha: number) =>
+  hex +
+  Math.round(alpha * 255)
+    .toString(16)
+    .padStart(2, "0");
+
+const NOTICE_MS = 2500;
+
+/**
+ * The buyer's seat picker: the map, the legend, and the two notices a buyer
+ * must see without asking (seats taken from under them, a tier at its cap).
+ *
+ * Rendered inside `EventTickets`' ticket step when `event.hasSeatMap`, and
+ * exported on its own for a host that composes the checkout from the headless
+ * hook. Colours come from the site theme except the tier palette, which the
+ * map, the legend and the tier rows share through `tierColorMap`.
+ */
+export function EventSeatPicker({
+  event,
+  seating,
+  selectedSeats,
+  onToggleSeat,
+  seatsTaken,
+  onDismissSeatsTaken,
+  formatAmount,
+  className,
+}: EventSeatPickerProps) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  const [notice, setNotice] = useState<string | null>(null);
+
+  // A brief inline notice, cleared on its own: it answers "why did nothing
+  // happen?" for one tap and must not sit on the map for ever.
+  useEffect(() => {
+    if (!notice) return;
+    const id = setTimeout(() => setNotice(null), NOTICE_MS);
+    return () => clearTimeout(id);
+  }, [notice]);
+
+  const tierColors = useMemo(() => tierColorMap(event.tickets.map((ticket) => ticket.id)), [event.tickets]);
+
+  const selectedIds = useMemo(() => new Set(Object.values(selectedSeats).flat()), [selectedSeats]);
+
+  const legendTiers = useMemo<SeatLegendTier[]>(
+    () =>
+      event.tickets
+        .filter((ticket) => seating.seatedTierIds.has(ticket.id))
+        .map((ticket) => ({
+          id: ticket.id,
+          title: ticket.title,
+          price: Number(ticket.price),
+          color: tierColors[ticket.id]!,
+          left: seating.availableByTier[ticket.id] ?? 0,
+        })),
+    [event.tickets, seating.seatedTierIds, seating.availableByTier, tierColors],
+  );
+
+  const onSeatTap = useCallback(
+    (seat: EventSeat) => {
+      const result = onToggleSeat(seat.eventTicketId, seat.id);
+      if (!result || result.ok) return;
+      const tier = event.tickets.find((ticket) => ticket.id === seat.eventTicketId);
+      if (result.reason === "max") setNotice(t("forge.event_seat_picker.max_reached", { tier: tier?.title ?? "" }));
+      else if (result.reason === "unavailable") setNotice(t("forge.event_seat_picker.seat_unavailable"));
+      else if (result.reason === "mix") setNotice(t("forge.event_seat_picker.mix_blocked"));
+    },
+    [onToggleSeat, event.tickets, t],
+  );
+
+  const layout = seating.seating?.layout;
+
+  return (
+    <div data-testid="event-seat-picker" className={className ?? "fg:flex fg:flex-col fg:gap-3"}>
+      <div className="fg:flex fg:items-center fg:gap-2">
+        <h3 style={{ fontSize: 16, fontWeight: 700, margin: 0 }}>{t("forge.event_seat_picker.title")}</h3>
+        <CallHelpHint label={t("forge.event_seat_picker.help_label")}>{t("forge.event_seat_picker.help_body")}</CallHelpHint>
+      </div>
+
+      {/* State the buyer has to act on, so it is a visible alert and not a
+          `?`: their selection just shrank, and these are the seats that went. */}
+      {seatsTaken && seatsTaken.labels.length > 0 && (
+        <div role="alert" data-testid="seats-taken-alert" style={alertStyle("#dc2626", theme)}>
+          <AlertCircle size={16} style={{ flexShrink: 0, marginTop: 2 }} />
+          <div style={{ flex: 1 }}>
+            <div style={{ fontWeight: 700 }}>{t("forge.event_seat_picker.seats_taken_title")}</div>
+            <div style={{ fontWeight: 400, marginTop: 2 }}>
+              {t("forge.event_seat_picker.seats_taken_body", { seats: seatsTaken.labels.join(", ") })}
+            </div>
+          </div>
+          {onDismissSeatsTaken && (
+            <button
+              type="button"
+              aria-label={t("forge.event_seat_picker.dismiss")}
+              onClick={onDismissSeatsTaken}
+              className="fg:cursor-pointer fg:p-0 fg:bg-transparent fg:border-0"
+              style={{ color: "inherit" }}
+            >
+              <X size={16} />
+            </button>
+          )}
+        </div>
+      )}
+
+      {seating.isLoading && !layout && (
+        <div
+          data-testid="seat-picker-loading"
+          className="fg:flex fg:items-center fg:justify-center fg:min-h-[320px]"
+          style={{ border: `1px solid ${a(theme.colors.primary, 0.25)}`, borderRadius: theme.cornerRadius }}
+        >
+          <Loading label={t("forge.event_seat_picker.loading")} />
+        </div>
+      )}
+
+      {!seating.isLoading && !layout && (
+        <p data-testid="seat-picker-empty" style={{ opacity: 0.7, fontSize: 14, margin: 0 }}>
+          {t("forge.event_seat_picker.empty")}
+        </p>
+      )}
+
+      {layout && (
+        <>
+          <SeatMapCanvas
+            layout={layout}
+            bySource={seating.bySource}
+            tierColors={tierColors}
+            selectedIds={selectedIds}
+            onSeatTap={onSeatTap}
+            overlay={
+              notice ? (
+                <div role="status" data-testid="seat-picker-notice" style={{ ...alertStyle(theme.colors.primary, theme), marginTop: 0 }}>
+                  <AlertCircle size={14} />
+                  {notice}
+                </div>
+              ) : null
+            }
+          />
+          <SeatLegend tiers={legendTiers} formatAmount={formatAmount} />
+        </>
+      )}
+    </div>
+  );
+}
+
+const alertStyle = (color: string, t: ForgeTheme): CSSProperties => ({
+  padding: "8px 12px",
+  borderRadius: t.cornerRadius,
+  fontSize: 14,
+  fontWeight: 600,
+  background: a(color, 0.1),
+  color,
+  border: `1px solid ${a(color, 0.3)}`,
+  display: "flex",
+  alignItems: "flex-start",
+  gap: 8,
+});

package/src/ui/styled/seating/SeatLegend.tsx

@@ -0,0 +1,73 @@
+import { useForgeT } from "../../../i18n";
+import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { UNAVAILABLE_FILL } from "./paint";
+
+export interface SeatLegendTier {
+  id: string;
+  title: string;
+  /** Per-unit price, in the artist's currency. */
+  price: number;
+  /** The tier's colour on the map. */
+  color: string;
+  /** Seats still available on this tier. */
+  left: number;
+}
+
+export interface SeatLegendProps {
+  tiers: SeatLegendTier[];
+  formatAmount: (amount: number) => string;
+  /** Host classes on the outer element, passed through untouched. */
+  className?: string;
+}
+
+/**
+ * What the colours on the map mean: one chip per seated tier (colour, name,
+ * price, how many are left), plus the two states every seat can be in
+ * regardless of tier. The colours come from the same `tierColorMap` the
+ * canvas and the tier rows use, so this is the key to the map by construction.
+ */
+export function SeatLegend({ tiers, formatAmount, className }: SeatLegendProps) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  return (
+    <ul
+      data-testid="seat-legend"
+      aria-label={t("forge.seat_legend.aria_label")}
+      className={className ?? "fg:flex fg:flex-wrap fg:gap-x-4 fg:gap-y-2 fg:list-none fg:m-0 fg:p-0"}
+      style={{ fontSize: 13, color: theme.colors.text }}
+    >
+      {tiers.map((tier) => (
+        <li key={tier.id} data-testid="seat-legend-tier" className="fg:flex fg:items-center fg:gap-2">
+          <Swatch color={tier.color} />
+          <span style={{ fontWeight: 600 }}>{tier.title}</span>
+          <span style={{ opacity: 0.8 }}>{formatAmount(tier.price)}</span>
+          <span style={{ opacity: 0.65 }}>
+            {tier.left === 0
+              ? t("forge.seat_legend.sold_out")
+              : tier.left === 1
+                ? t("forge.seat_legend.left_one", { count: tier.left })
+                : t("forge.seat_legend.left_other", { count: tier.left })}
+          </span>
+        </li>
+      ))}
+      <li className="fg:flex fg:items-center fg:gap-2">
+        <Swatch color={theme.colors.primary} ring={theme.colors.primary} />
+        <span>{t("forge.seat_legend.selected")}</span>
+      </li>
+      <li className="fg:flex fg:items-center fg:gap-2">
+        <Swatch color={UNAVAILABLE_FILL} />
+        <span>{t("forge.seat_legend.unavailable")}</span>
+      </li>
+    </ul>
+  );
+}
+
+function Swatch({ color, ring }: { color: string; ring?: string }) {
+  return (
+    <span
+      aria-hidden
+      className="fg:inline-block fg:w-3 fg:h-3 fg:rounded-full fg:shrink-0"
+      style={{ background: color, boxShadow: ring ? `0 0 0 2px #ffffff, 0 0 0 3.5px ${ring}` : undefined }}
+    />
+  );
+}