@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/communities/index.ts

@@ -0,0 +1,96 @@
+// Communities: every page of a community has a headless version (decision 14).
+// A styled component is one of these hooks plus markup and nothing else, so a
+// creator can rebuild the list, the About page, the join sheet, the pending
+// screen, the upgrade sheet and the membership menu on their own routes.
+export {
+  CommunityProvider,
+  useCommunityContext,
+  useOptionalCommunityContext,
+  isCommunityId,
+  MissingCommunityProviderError,
+  CommunityUpgradeOpenerProvider,
+  useCommunityUpgradeOpener,
+  type CommunityContextValue,
+  type CommunityProviderProps,
+  type CommunityUpgradeOpener,
+} from "../../../contexts/CommunityContext";
+export {
+  useCommunities,
+  useCommunity,
+  communityJoinOffer,
+  viewerHasAccess,
+  COMMUNITY_ACCESS_STATES,
+  type CommunityJoinOffer,
+  type UseCommunityOptions,
+} from "./useCommunity";
+export {
+  useCommunityInvite,
+  describeCommunityInvite,
+  type CommunityInviteProblem,
+  type CommunityInviteSummary,
+} from "./useCommunityInvite";
+export {
+  useCommunityJoin,
+  communityJoinStep,
+  tierHasChoice,
+  type CommunityJoinStep,
+  type CommunityJoinStepInput,
+  type UseCommunityJoinOptions,
+} from "./useCommunityJoin";
+export {
+  useCommunityUpgrade,
+  type CommunityUpgradeStep,
+  type CommunityUpgradeOption,
+  type UseCommunityUpgradeOptions,
+} from "./useCommunityUpgrade";
+export { useCommunityMembership, communityDowngradeTiers } from "./useCommunityMembership";
+export {
+  useCommunityAbout,
+  type CommunityAboutAction,
+  type UseCommunityAboutOptions,
+} from "./useCommunityAbout";
+export { useCommunityHome, type UseCommunityHomeOptions } from "./useCommunityHome";
+export { useMyMemberships, toMyMembershipEntry, type MyMembershipEntry } from "./useMyMemberships";
+export { CommunityGate, communityGateAllows, type CommunityGateProps, type CommunityGateState } from "./CommunityGate";
+export { communitiesListPath, communityAboutPath, communityHomePath } from "./paths";
+export {
+  useCommunityWiki,
+  useCommunityWikiPage,
+  shapeWikiList,
+  defaultWikiPageSlug,
+  parseWikiContent,
+  extractWikiToc,
+  wikiHeadingSlug,
+  lexicalNodeText,
+  wikiImageSource,
+  wikiMediaImageStatus,
+  wikiUnlockParts,
+  useWikiMediaImage,
+  type WikiImageSource,
+  type WikiMediaImageStatus,
+  WIKI_TOC_MIN_HEADINGS,
+  type CommunityWikiTocEntry,
+  type UseCommunityWikiOptions,
+} from "./useCommunityWiki";
+export {
+  useCommunityClassroom,
+  classroomProgressPercent,
+  classroomCourseState,
+  classroomUnlockParts,
+  classroomCourseHref,
+  type ClassroomCourseState,
+} from "./useCommunityClassroom";
+export {
+  useCommunityCalendar,
+  calendarDayKey,
+  calendarMonthStart,
+  calendarMonthWindow,
+  calendarItemIsOver,
+  groupCalendarItems,
+  rsvpErrorCode,
+  nextRsvp,
+  callJoinable,
+  type CommunityCalendarDay,
+  type CommunityRsvpErrorCode,
+  type UseCommunityCalendarOptions,
+} from "./useCommunityCalendar";

package/src/ui/headless/communities/paths.ts

@@ -0,0 +1,36 @@
+import { internalPath } from "../../../runtime/pages";
+
+/**
+ * The hosted community pages, as plain paths. Built through `internalPath` so a
+ * page rename is a type error here rather than a dead link on a published site.
+ *
+ * Every flow that ends (a join, a paid join's Stripe return, an upgrade, an
+ * application) lands on the community HOME, never on `/i/account`.
+ */
+
+type Query = Record<string, string | number | null | undefined>;
+
+function withQuery(path: string, query?: Query): string {
+  if (!query) return path;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null && value !== "") params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `${path}?${qs}` : path;
+}
+
+/** Every community on the profile: `/i/communities`. */
+export function communitiesListPath(): string {
+  return internalPath("communities");
+}
+
+/** A community's About page, e.g. `communityAboutPath("fan-club", { tier })`. */
+export function communityAboutPath(slug: string, query?: { invite?: string; join?: string; tier?: string }): string {
+  return withQuery(internalPath("communities/$slug", { slug }), query);
+}
+
+/** The inside of a community. `welcome=1` after a join, `confirmSubscription=1` after a Stripe return. */
+export function communityHomePath(slug: string, query?: { welcome?: 1 | "1"; confirmSubscription?: 1 | "1" }): string {
+  return withQuery(internalPath("communities/$slug/home", { slug }), query);
+}

package/src/ui/headless/communities/useCommunity.ts

@@ -0,0 +1,140 @@
+import { useContext, useMemo } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { useOptionalCommunityContext, MissingCommunityProviderError } from "../../../contexts/CommunityContext";
+import {
+  isNotFound,
+  usePublicCommunities,
+  usePublicCommunity,
+  useCommunityViewerState,
+  type CommunityTokens,
+  type CommunityViewerState,
+  type PublicCommunity,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+import { cycleFloor, cycleIsFree, defaultCycle, offeredCycles, type BillingCycle } from "../../format/membershipPwyw";
+
+/**
+ * Every community on the profile, for a list page.
+ *
+ * `only` is the one community when there is exactly one, so a list page can go
+ * straight to it rather than asking the fan to choose between one option.
+ */
+export function useCommunities() {
+  const query = usePublicCommunities();
+  const communities = query.data ?? [];
+  return {
+    communities,
+    only: communities.length === 1 ? communities[0]! : null,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    refetch: query.refetch,
+  };
+}
+
+/** What the About page's single Join button offers, decided from the creator's tiers. */
+export type CommunityJoinOffer =
+  | { kind: "free"; tier: PublicTier }
+  | { kind: "paid"; tier: PublicTier; amount: number; cycle: BillingCycle }
+  | { kind: "apply"; tier: PublicTier }
+  | null;
+
+/**
+ * The Join button reflects the creator's tiers (decision 8): "Join free" when a
+ * free tier exists, otherwise "Join" with the lowest price, and "Apply" when
+ * every tier is apply-to-join. Pure, so a custom About page words it the same.
+ */
+export function communityJoinOffer(tiers: PublicTier[]): CommunityJoinOffer {
+  if (!tiers.length) return null;
+  const joinable = tiers.filter((tier) => tier.joinMode !== "application");
+  const free = joinable.find((tier) => cycleIsFree(tier, defaultCycle(tier)));
+  if (free) return { kind: "free", tier: free };
+  let cheapest: { tier: PublicTier; amount: number; cycle: BillingCycle } | null = null;
+  for (const tier of joinable) {
+    const cycles = offeredCycles(tier);
+    // A pay-what-you-want tier with no floor sells no cycle at a price, and is
+    // still a paid join from nothing.
+    const candidates = (["month", "year"] as const).filter((cycle) => cycles[cycle]);
+    for (const cycle of candidates.length ? candidates : (["month"] as const)) {
+      const amount = cycleFloor(tier, cycle);
+      // Compare on a monthly footing so a yearly price is not mistaken for the dearer one.
+      const monthly = cycle === "year" ? amount / 12 : amount;
+      const best = cheapest ? (cheapest.cycle === "year" ? cheapest.amount / 12 : cheapest.amount) : Infinity;
+      if (monthly < best) cheapest = { tier, amount, cycle };
+    }
+  }
+  if (cheapest) return { kind: "paid", ...cheapest };
+  return { kind: "apply", tier: tiers[0]! };
+}
+
+/** The viewer states that hold access to member content. `past_due` keeps it through the grace window. */
+export const COMMUNITY_ACCESS_STATES: ReadonlyArray<CommunityViewerState["state"]> = ["member", "past_due"];
+
+/** Does this viewer state grant access to the community's member content. */
+export function viewerHasAccess(viewer: Pick<CommunityViewerState, "state"> | null | undefined): boolean {
+  return !!viewer && COMMUNITY_ACCESS_STATES.includes(viewer.state);
+}
+
+const NO_TIERS: PublicTier[] = [];
+
+export interface UseCommunityOptions extends CommunityTokens {
+  enabled?: boolean;
+}
+
+/**
+ * One community: what it is, the tiers this viewer may join, and where the
+ * viewer stands IN IT (`none`, `pending`, `member`, `past_due`, `cancelled`, or
+ * `anonymous`), plus the upgrade and pending details a custom page needs.
+ *
+ * `slug` is a slug or an id. Omitted, the surrounding `<CommunityProvider>` is
+ * read, and outside one this throws rather than guess a community.
+ *
+ * The viewer comes from `/me` once signed in, so it follows a sign-in that
+ * happened on this page (the join sheet) without a reload.
+ */
+export function useCommunity(slug?: string, opts: UseCommunityOptions = {}) {
+  const context = useOptionalCommunityContext();
+  const ref = slug ?? context?.ref;
+  if (!ref) throw new MissingCommunityProviderError("useCommunity()");
+  const tokens: CommunityTokens = { invite: opts.invite ?? null, join: opts.join ?? null };
+  const signedIn = !!useContext(PublicAuthContext)?.user;
+
+  const detail = usePublicCommunity(ref, tokens, { enabled: opts.enabled });
+  const me = useCommunityViewerState(ref, { enabled: signedIn && opts.enabled !== false });
+
+  const community: PublicCommunity | undefined = detail.data?.community ?? context?.community;
+  const tiers: PublicTier[] = detail.data?.tiers ?? NO_TIERS;
+  const viewer: CommunityViewerState | undefined = (signedIn ? me.data : undefined) ?? detail.data?.viewer;
+
+  return useMemo(() => {
+    const membership = viewer?.membership ?? null;
+    const currentTier = membership ? (tiers.find((tier) => tier.id === membership.tierId) ?? null) : null;
+    return {
+      community,
+      communityId: community?.id,
+      slug: community?.slug,
+      tiers,
+      viewer,
+      /** The invite the URL carried, as the community read resolved it. */
+      invite: detail.data?.invite ?? null,
+      isLoading: detail.isLoading || (signedIn && me.isLoading),
+      /** True while the viewer is being re-read, e.g. straight after signing in. */
+      viewerLoading: signedIn && (me.isLoading || me.isFetching),
+      isError: detail.isError,
+      notFound: isNotFound(detail.error),
+      /** An active member (including `past_due`, which keeps access through the grace window). */
+      isMember: viewerHasAccess(viewer),
+      /** Applied and waiting for the creator's decision: inside, but no member content. */
+      isPending: viewer?.state === "pending",
+      /** When the pending application was made, for a waiting screen. */
+      pendingSince: viewer?.state === "pending" ? (viewer.application?.createdAt ?? null) : null,
+      membership,
+      currentTier,
+      upgradeTiers: viewer?.upgradeTiers ?? [],
+      hasUpgrade: (viewer?.upgradeTiers?.length ?? 0) > 0,
+      canInteract: viewer?.canInteract ?? false,
+      joinOffer: communityJoinOffer(tiers),
+      refetch: () => Promise.all([detail.refetch(), signedIn ? me.refetch() : Promise.resolve()]),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [community, tiers, viewer, detail.data?.invite, detail.isLoading, detail.isError, detail.error, me.isLoading, me.isFetching, signedIn]);
+}

package/src/ui/headless/communities/useCommunityAbout.ts

@@ -0,0 +1,71 @@
+import { useEffect, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { useCommunity } from "./useCommunity";
+import { communityHomePath } from "./paths";
+
+/** What the About page's main button does for THIS viewer. */
+export type CommunityAboutAction = "join" | "enter" | "pending";
+
+export interface UseCommunityAboutOptions {
+  /** A per-email invite token (`?invite=`). Opens the join sheet straight away. */
+  invite?: string | null;
+  /** A shareable invite link token (`?join=`). Opens the join sheet straight away. */
+  join?: string | null;
+  /** A tier to preselect (`?tier=`). */
+  tierId?: string | null;
+  /** The host's router, for "go inside". Default a full-page visit. */
+  navigate?: (href: string) => void;
+}
+
+/**
+ * The About page: the community, what each tier gives, and ONE main action.
+ *
+ * - `join` opens the join sheet in place (it never leaves the page).
+ * - `enter` for a member, who skips Join and goes straight inside.
+ * - `pending` for a fan whose application is being reviewed; they go inside to
+ *   the pending screen.
+ *
+ * The sheet opens by itself when the URL carries an invite or a shareable
+ * link, already set to the invited tier. A signed-in member arriving on an
+ * invite link is still shown the sheet: accepting it may be a tier change.
+ */
+export function useCommunityAbout(opts: UseCommunityAboutOptions = {}) {
+  if (!useOptionalCommunityContext()) throw new MissingCommunityProviderError("useCommunityAbout()");
+  const community = useCommunity();
+  const hasToken = !!(opts.invite || opts.join);
+  const [sheetOpen, setSheetOpen] = useState(hasToken);
+  const [sheetTierId, setSheetTierId] = useState<string | null>(opts.tierId ?? null);
+
+  // A token that arrives after the first render (client-side navigation) still opens the sheet.
+  useEffect(() => {
+    if (hasToken) setSheetOpen(true);
+  }, [hasToken]);
+
+  const action: CommunityAboutAction = community.isMember ? "enter" : community.isPending ? "pending" : "join";
+  const homePath = community.slug ? communityHomePath(community.slug) : "";
+
+  const goInside = () => {
+    if (!homePath) return;
+    if (opts.navigate) opts.navigate(homePath);
+    else if (typeof window !== "undefined") window.location.assign(homePath);
+  };
+
+  return {
+    ...community,
+    action,
+    homePath,
+    /** Run the main action: open the sheet, or go inside. */
+    primary: () => (action === "join" ? (setSheetTierId(opts.tierId ?? null), setSheetOpen(true)) : goInside()),
+    goInside,
+    sheetOpen,
+    /** The tier the sheet opens on: a tier card's own Join, or `?tier=`. */
+    sheetTierId,
+    openJoin: (tierId?: string | null) => {
+      setSheetTierId(tierId ?? opts.tierId ?? null);
+      setSheetOpen(true);
+    },
+    setSheetOpen,
+    invite: opts.invite ?? null,
+    join: opts.join ?? null,
+  };
+}

package/src/ui/headless/communities/useCommunityCalendar.ts

@@ -0,0 +1,156 @@
+import { useMemo, useState } from "react";
+import { communityRequestStatus } from "../../../data/queries/useCommunityClassroom";
+import {
+  useCommunityCalendarItems,
+  useCommunityCallRsvp,
+  type CommunityCalendarCall,
+  type CommunityCalendarItem,
+  type CommunityRsvpResponse,
+} from "../../../data/queries/useCommunityCalendar";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** One day of the agenda, in the viewer's own time zone. */
+export interface CommunityCalendarDay {
+  /** `YYYY-MM-DD`, local. */
+  key: string;
+  /** Local midnight of the day. */
+  date: Date;
+  items: CommunityCalendarItem[];
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** The local day an instant falls on, as `YYYY-MM-DD`. */
+export function calendarDayKey(value: Date | string): string {
+  const date = typeof value === "string" ? new Date(value) : value;
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** Local midnight on the first of the month `offset` months from `now`. */
+export function calendarMonthStart(now: Date, offset = 0): Date {
+  return new Date(now.getFullYear(), now.getMonth() + offset, 1);
+}
+
+/** The window one month reads: its first local midnight up to the next month's. */
+export function calendarMonthWindow(monthStart: Date): { from: Date; to: Date } {
+  return {
+    from: new Date(monthStart.getFullYear(), monthStart.getMonth(), 1),
+    to: new Date(monthStart.getFullYear(), monthStart.getMonth() + 1, 1),
+  };
+}
+
+/** When an item is over: its end, or its start when it has no end. */
+export function calendarItemIsOver(item: Pick<CommunityCalendarItem, "startsAt" | "endsAt">, now: Date): boolean {
+  return new Date(item.endsAt ?? item.startsAt).getTime() < now.getTime();
+}
+
+/**
+ * The agenda, grouped by the local day each item starts on and split in two:
+ * `upcoming` (anything not yet over, soonest first) and `past` (most recent
+ * day first), so what a member can still act on is always at the top. Items
+ * keep their time order inside a day.
+ */
+export function groupCalendarItems(
+  items: CommunityCalendarItem[] | undefined,
+  now: Date,
+): { upcoming: CommunityCalendarDay[]; past: CommunityCalendarDay[] } {
+  const sorted = [...(Array.isArray(items) ? items : [])].sort((a, b) => a.startsAt.localeCompare(b.startsAt));
+  const group = (list: CommunityCalendarItem[]) => {
+    const days = new Map<string, CommunityCalendarDay>();
+    for (const item of list) {
+      const key = calendarDayKey(item.startsAt);
+      let day = days.get(key);
+      if (!day) {
+        const start = new Date(item.startsAt);
+        day = { key, date: new Date(start.getFullYear(), start.getMonth(), start.getDate()), items: [] };
+        days.set(key, day);
+      }
+      day.items.push(item);
+    }
+    return [...days.values()];
+  };
+  const upcoming = group(sorted.filter((item) => !calendarItemIsOver(item, now)));
+  const past = group(sorted.filter((item) => calendarItemIsOver(item, now))).reverse();
+  return { upcoming, past };
+}
+
+/** What a failed going or not going means for the member. */
+export type CommunityRsvpErrorCode = "closed" | "not_found" | "failed";
+
+export function rsvpErrorCode(error: unknown): CommunityRsvpErrorCode {
+  const status = communityRequestStatus(error);
+  if (status === 409) return "closed";
+  if (status === 404) return "not_found";
+  return "failed";
+}
+
+/** Pressing the answer a member already gave clears it; any other answer replaces it. */
+export function nextRsvp(
+  current: CommunityRsvpResponse | null,
+  pressed: CommunityRsvpResponse,
+): CommunityRsvpResponse | null {
+  return current === pressed ? null : pressed;
+}
+
+/** Join is offered only while the server says the room is open and there is a room to join. */
+export function callJoinable(call: Pick<CommunityCalendarCall, "isOpen" | "callPublicId">): boolean {
+  return call.isOpen && !!call.callPublicId;
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+export interface UseCommunityCalendarOptions {
+  /** The clock, for tests. Defaults to the time of the first render. */
+  now?: Date;
+}
+
+/**
+ * Headless community calendar: one month at a time (this month first, arrows
+ * either way), grouped by day with what is still ahead on top, and going or
+ * not going on a call. Answering the answer already given clears it. A refused
+ * answer (the call is over or was cancelled, 409) is kept per call for the
+ * row to show.
+ */
+export function useCommunityCalendar(opts: UseCommunityCalendarOptions = {}) {
+  const [initialNow] = useState(() => opts.now ?? new Date());
+  const now = opts.now ?? initialNow;
+  const [offset, setOffset] = useState(0);
+  const monthStart = useMemo(() => calendarMonthStart(now, offset), [now, offset]);
+  const range = useMemo(() => calendarMonthWindow(monthStart), [monthStart]);
+  const query = useCommunityCalendarItems(range);
+  const groups = useMemo(() => groupCalendarItems(query.data, now), [query.data, now]);
+  const rsvpMutation = useCommunityCallRsvp();
+  const [rsvpError, setRsvpError] = useState<{ callId: string; code: CommunityRsvpErrorCode } | null>(null);
+  const status = communityRequestStatus(query.error);
+
+  const answer = (call: CommunityCalendarCall, pressed: CommunityRsvpResponse) => {
+    setRsvpError(null);
+    rsvpMutation.mutate(
+      { callId: call.id, response: nextRsvp(call.rsvp.mine, pressed) },
+      { onError: (error) => setRsvpError({ callId: call.id, code: rsvpErrorCode(error) }) },
+    );
+  };
+
+  return {
+    monthStart,
+    isCurrentMonth: offset === 0,
+    goToPreviousMonth: () => setOffset((o) => o - 1),
+    goToNextMonth: () => setOffset((o) => o + 1),
+    goToToday: () => setOffset(0),
+    items: Array.isArray(query.data) ? query.data : [],
+    upcoming: groups.upcoming,
+    past: groups.past,
+    now,
+    isLoading: query.isLoading,
+    /** Signed out, or not a member of this community. */
+    forbidden: status === 401 || status === 403,
+    isError: query.isError && status !== 401 && status !== 403,
+    /** Answer going or not going; pressing the current answer clears it. */
+    answer,
+    /** The call whose answer is being saved. */
+    pendingCallId: rsvpMutation.isPending ? (rsvpMutation.variables?.callId ?? null) : null,
+    /** Why a call's last answer was refused. */
+    rsvpErrorFor: (callId: string) => (rsvpError?.callId === callId ? rsvpError.code : null),
+  };
+}

package/src/ui/headless/communities/useCommunityClassroom.ts

@@ -0,0 +1,84 @@
+import { useCommunityUpgradeOpener, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  communityRequestStatus,
+  useCommunityClassroomCourses,
+  type CommunityClassroomCourse,
+  type CommunityClassroomProgress,
+} from "../../../data/queries/useCommunityClassroom";
+import { internalPath } from "../../../runtime/pages";
+import { communityAboutPath } from "./paths";
+import { wikiUnlockParts } from "./useCommunityWiki";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** Where a member stands with one course card. */
+export type ClassroomCourseState = "locked" | "not_started" | "in_progress" | "completed";
+
+/** How far through a course the member is, 0 to 100. */
+export function classroomProgressPercent(progress: CommunityClassroomProgress | null | undefined): number {
+  if (!progress) return 0;
+  if (progress.completedAt) return 100;
+  const total = Number(progress.total) || 0;
+  if (total <= 0) return 0;
+  return Math.max(0, Math.min(100, Math.round(((Number(progress.completed) || 0) / total) * 100)));
+}
+
+export function classroomCourseState(course: Pick<CommunityClassroomCourse, "open" | "progress">): ClassroomCourseState {
+  if (!course.open) return "locked";
+  const progress = course.progress;
+  if (!progress) return "not_started";
+  if (progress.completedAt || (progress.total > 0 && progress.completed >= progress.total)) return "completed";
+  return progress.completed > 0 ? "in_progress" : "not_started";
+}
+
+/**
+ * What opens a locked course: the level the member has not reached (null when
+ * the level is not what is missing) and the names of the tiers that include
+ * it (empty when none are named). The same reading as a locked wiki page.
+ */
+export function classroomUnlockParts(course: Pick<CommunityClassroomCourse, "unlockLevel" | "unlockTiers">) {
+  return wikiUnlockParts(course);
+}
+
+/**
+ * Where an open card leads: the course player, addressed by the member's
+ * access id. Null without one. The course's own page is the sales page, a dead
+ * end for someone who already holds the course, so it is never the fallback.
+ */
+export function classroomCourseHref(course: Pick<CommunityClassroomCourse, "open" | "accessId">): string | null {
+  return course.open && course.accessId ? internalPath("course-access/$accessId", { accessId: course.accessId }) : null;
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless classroom for the surrounding community: the course cards, open
+ * ones first as the server orders them, whether the viewer may see the tab at
+ * all (`forbidden` for a non-member), and how to unlock a locked card. `unlock`
+ * opens the community's upgrade sheet on the first tier that includes the
+ * course when a community home provides one; otherwise `unlockHref` is the
+ * About page with that tier chosen. A card only a level holds back has nothing
+ * to buy, so it offers no upgrade.
+ */
+export function useCommunityClassroom(opts: { enabled?: boolean } = {}) {
+  const community = useOptionalCommunityContext();
+  const opener = useCommunityUpgradeOpener();
+  const query = useCommunityClassroomCourses(opts);
+  const status = communityRequestStatus(query.error);
+  const courses = Array.isArray(query.data) ? query.data : [];
+
+  return {
+    courses,
+    isLoading: query.isLoading,
+    /** Signed out, or not a member of this community. */
+    forbidden: status === 401 || status === 403,
+    notFound: status === 404,
+    isError: query.isError && status !== 401 && status !== 403 && status !== 404,
+    refetch: query.refetch,
+    /** A locked card offers an upgrade only when a tier includes it. */
+    canUpgrade: (course: CommunityClassroomCourse) => !course.open && course.unlockTiers.length > 0,
+    unlock: opener ? (course: CommunityClassroomCourse) => opener.openUpgrade(course.unlockTiers[0]?.id ?? null) : null,
+    unlockHref: (course: CommunityClassroomCourse) =>
+      community?.slug ? communityAboutPath(community.slug, { tier: course.unlockTiers[0]?.id }) : null,
+  };
+}

package/src/ui/headless/communities/useCommunityHome.ts

@@ -0,0 +1,91 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { useConfirmLatestSubscription } from "../../../data/queries/useSubscriptions";
+import { requestAppInstall } from "../siteApp/appPrompts";
+import { useInvalidateCommunities } from "../../../data/queries/useCommunities";
+import { useCommunity } from "./useCommunity";
+import { communityAboutPath } from "./paths";
+
+export interface UseCommunityHomeOptions {
+  /** `?welcome=1`: the fan just joined. */
+  welcome?: boolean;
+  /** `?confirmSubscription=1`: back from Stripe. The subscription is reconciled here, inside the community. */
+  confirmSubscription?: boolean;
+}
+
+/**
+ * The state of a community's home shell: the header (name, tier badge,
+ * Upgrade), the one upgrade sheet every locked item opens, the Membership
+ * menu, a welcome after joining, and reconciling a paid join or upgrade on the
+ * way back from Stripe, which used to happen on the account page.
+ */
+export function useCommunityHome(opts: UseCommunityHomeOptions = {}) {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityHome()");
+  const community = useCommunity();
+  const confirmLatest = useConfirmLatestSubscription();
+  const invalidate = useInvalidateCommunities();
+
+  const [welcomeVisible, setWelcomeVisible] = useState(!!opts.welcome);
+  const [upgradeOpen, setUpgradeOpen] = useState(false);
+  const [upgradeTierId, setUpgradeTierId] = useState<string | null>(null);
+  const [membershipOpen, setMembershipOpen] = useState(false);
+
+  // Reconcile once per arrival, as soon as the community id is known.
+  //
+  // `confirming` is this component's own state, NOT `confirmLatest.isPending`.
+  // A mutation started from an effect loses its observer when React StrictMode
+  // unmounts and remounts the component in development, so `isPending` stayed
+  // true for ever and the home was stuck on "Confirming" although the request
+  // had answered. The promise itself always settles, so state set from it does.
+  const confirmed = useRef(false);
+  const [confirming, setConfirming] = useState(false);
+  const communityId = community.communityId ?? context.communityId;
+  useEffect(() => {
+    if (!opts.confirmSubscription || confirmed.current || !communityId) return;
+    confirmed.current = true;
+    setConfirming(true);
+    confirmLatest
+      .mutateAsync({ communityId })
+      // Back from paying to join: the same moment as a free join to offer the app.
+      .then(() => requestAppInstall("joined_community"))
+      .catch(() => undefined)
+      .finally(() => {
+        setConfirming(false);
+        void invalidate();
+      });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [opts.confirmSubscription, communityId]);
+
+  const opener = useMemo(
+    () => ({
+      openUpgrade: (tierId?: string | null) => {
+        setUpgradeTierId(tierId ?? null);
+        setUpgradeOpen(true);
+      },
+    }),
+    [],
+  );
+
+  return {
+    ...community,
+    /** Show the one-time welcome after a join. */
+    welcomeVisible: welcomeVisible && community.isMember,
+    dismissWelcome: () => setWelcomeVisible(false),
+    /** True while a Stripe return is being reconciled. */
+    confirming,
+    /** The header's Upgrade button shows only when a higher tier exists. */
+    showUpgrade: community.isMember && community.hasUpgrade,
+    /** The header's Join link, for a visitor who is not a member. */
+    showJoin: !community.isLoading && !community.isMember && !community.isPending,
+    joinPath: community.slug ? communityAboutPath(community.slug) : "",
+    upgradeOpen,
+    upgradeTierId,
+    /** Hand to `CommunityUpgradeOpenerProvider` so every locked item opens the same sheet. */
+    opener,
+    openUpgrade: opener.openUpgrade,
+    setUpgradeOpen,
+    membershipOpen,
+    setMembershipOpen,
+  };
+}