@tribe-nest/forge 3.59.0 → 3.61.0

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

@@ -0,0 +1,59 @@
+import { useMemo } from "react";
+import { useMyCommunityMemberships, type MyCommunityMembership } from "../../../data/queries/useCommunities";
+import { getMembershipAccess, type MembershipAccessSummary } from "../../../utils/membershipAccess";
+import { communityHomePath } from "./paths";
+import { isMembershipInTrial } from "../membership/membershipTrial";
+
+export interface MyMembershipEntry {
+  id: string;
+  community: { id: string; name: string; slug: string };
+  tierId: string | null;
+  tierName: string;
+  status: string;
+  access: MembershipAccessSummary;
+  /** When the paid period ends: a renewal, or the last day when cancelling. */
+  periodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
+  pendingDowngradeTierId: string | null;
+  trialEndsAt: string | null;
+  /** Inside a free trial right now: nothing charged yet, the first charge on `trialEndsAt`. */
+  inTrial: boolean;
+  amount: number | null;
+  currency: string | null;
+  billingCycle: string | null;
+  /** The community home, where the fan manages this membership. */
+  homePath: string;
+}
+
+/** Normalise one `/public/memberships/mine` row. Pure, for the spec and for a custom list. */
+export function toMyMembershipEntry(row: MyCommunityMembership): MyMembershipEntry {
+  const cancelAtPeriodEnd = !!row.cancelAtPeriodEnd;
+  return {
+    id: row.id,
+    community: row.community,
+    tierId: row.tierId ?? row.membershipTierId ?? row.membershipTier?.id ?? null,
+    tierName: row.tierName ?? row.membershipTier?.name ?? "",
+    status: row.status,
+    access: getMembershipAccess({ status: row.status, cancelAtPeriodEnd }),
+    periodEnd: row.currentPeriodEnd ?? row.endDate ?? null,
+    cancelAtPeriodEnd,
+    pendingDowngradeTierId: row.pendingDowngradeTierId ?? null,
+    trialEndsAt: row.trialEndsAt ?? null,
+    inTrial: isMembershipInTrial({ trialEndsAt: row.trialEndsAt ?? null }),
+    amount: row.subscriptionAmount ?? null,
+    currency: row.subscriptionCurrency ?? null,
+    billingCycle: row.billingCycle ?? null,
+    homePath: communityHomePath(row.community.slug),
+  };
+}
+
+/**
+ * Every membership the signed-in fan holds with this creator, one per
+ * community, for the account page's "My memberships". Nothing sends a fan
+ * here: managing a membership happens inside its community.
+ */
+export function useMyMemberships() {
+  const query = useMyCommunityMemberships();
+  const memberships = useMemo(() => (query.data ?? []).map(toMyMembershipEntry), [query.data]);
+  return { memberships, isLoading: query.isLoading, isError: query.isError, refetch: query.refetch };
+}

package/src/ui/headless/community/communityPoll.ts

@@ -0,0 +1,297 @@
+import { useEffect, useMemo, useState } from "react";
+import {
+  COMMUNITY_POLL_RESULTS_VISIBILITY,
+  useVoteCommunityPoll,
+  type CommunityPollInput,
+  type CommunityPollResultsVisibility,
+  type CommunityPollView,
+  type CommunityPost,
+} from "../../../data/queries/useCommunity";
+
+/**
+ * Polls on community posts (community parity §6.1). A poll rides on a post:
+ * the post title is its question, and the poll carries 2 to 10 options. The
+ * limits below mirror the server's create schema, so a draft that passes here
+ * is not refused there for its shape.
+ */
+export const COMMUNITY_POLL_LIMITS = {
+  minOptions: 2,
+  maxOptions: 10,
+  optionMaxLength: 120,
+  questionMaxLength: 200,
+} as const;
+
+// ── Draft (the composer) ─────────────────────────────────────────────────────
+
+export interface CommunityPollDraft {
+  /** The question. Sent as the post title. */
+  question: string;
+  options: string[];
+  multipleChoice: boolean;
+  /** A `datetime-local` value (local time, no zone), or "" for no close. */
+  closesAt: string;
+  resultsVisibility: CommunityPollResultsVisibility;
+}
+
+export const emptyPollDraft = (): CommunityPollDraft => ({
+  question: "",
+  options: ["", ""],
+  multipleChoice: false,
+  closesAt: "",
+  resultsVisibility: "after_vote",
+});
+
+export type CommunityPollQuestionError = "question_required" | "question_too_long";
+export type CommunityPollOptionError = "option_empty" | "option_too_long" | "option_duplicate";
+export type CommunityPollOptionsError = "options_too_few" | "options_too_many";
+export type CommunityPollClosesError = "closes_invalid" | "closes_in_past" | "closes_required";
+
+export interface CommunityPollDraftErrors {
+  question: CommunityPollQuestionError | null;
+  /** One entry per option input, in order. */
+  options: (CommunityPollOptionError | null)[];
+  /** About the list as a whole (how many options). */
+  optionsList: CommunityPollOptionsError | null;
+  closesAt: CommunityPollClosesError | null;
+  resultsVisibility: "visibility_invalid" | null;
+  valid: boolean;
+}
+
+/** A `datetime-local` value as a Date, or null when it does not parse. */
+export function parsePollCloseTime(value: string): Date | null {
+  if (!value.trim()) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Check a draft against the server's limits: a question, 2 to 10 options of
+ * 1 to 120 characters each, no two alike (compared trimmed and ignoring case,
+ * as the server de-duplicates), and a close time, when given, in the future.
+ * A poll whose results wait for it to close must have a close time.
+ */
+export function validatePollDraft(draft: CommunityPollDraft, now: number = Date.now()): CommunityPollDraftErrors {
+  const question = draft.question.trim();
+  const questionError: CommunityPollQuestionError | null = !question
+    ? "question_required"
+    : question.length > COMMUNITY_POLL_LIMITS.questionMaxLength
+      ? "question_too_long"
+      : null;
+
+  const seen = new Set<string>();
+  const options = draft.options.map((raw): CommunityPollOptionError | null => {
+    const label = raw.trim();
+    if (!label) return "option_empty";
+    if (label.length > COMMUNITY_POLL_LIMITS.optionMaxLength) return "option_too_long";
+    const key = label.toLowerCase();
+    if (seen.has(key)) return "option_duplicate";
+    seen.add(key);
+    return null;
+  });
+
+  const optionsList: CommunityPollOptionsError | null =
+    draft.options.length < COMMUNITY_POLL_LIMITS.minOptions
+      ? "options_too_few"
+      : draft.options.length > COMMUNITY_POLL_LIMITS.maxOptions
+        ? "options_too_many"
+        : null;
+
+  let closesAt: CommunityPollClosesError | null = null;
+  if (draft.closesAt.trim()) {
+    const date = parsePollCloseTime(draft.closesAt);
+    if (!date) closesAt = "closes_invalid";
+    else if (date.getTime() <= now) closesAt = "closes_in_past";
+  } else if (draft.resultsVisibility === "after_close") {
+    // Results shown "when the poll closes" on a poll that never closes would
+    // never be shown to a member at all.
+    closesAt = "closes_required";
+  }
+
+  const resultsVisibility = COMMUNITY_POLL_RESULTS_VISIBILITY.includes(draft.resultsVisibility)
+    ? null
+    : ("visibility_invalid" as const);
+
+  return {
+    question: questionError,
+    options,
+    optionsList,
+    closesAt,
+    resultsVisibility,
+    valid: !questionError && options.every((e) => !e) && !optionsList && !closesAt && !resultsVisibility,
+  };
+}
+
+/** The create-post fields a draft becomes: the question as `title`, and the `poll` body. */
+export function buildPollPayload(draft: CommunityPollDraft): { title: string; poll: CommunityPollInput } {
+  const close = parsePollCloseTime(draft.closesAt);
+  return {
+    title: draft.question.trim(),
+    poll: {
+      options: draft.options.map((o) => o.trim()),
+      multipleChoice: draft.multipleChoice,
+      closesAt: close ? close.toISOString() : null,
+      resultsVisibility: draft.resultsVisibility,
+    },
+  };
+}
+
+/**
+ * The composer's poll state: the draft, adding and removing options within
+ * 2 to 10, and the errors (shown once the member has tried to post, so an
+ * untouched form does not open in red).
+ */
+export function useCommunityPollDraft() {
+  const [draft, setDraft] = useState<CommunityPollDraft>(emptyPollDraft);
+  const [showErrors, setShowErrors] = useState(false);
+  const errors = useMemo(() => validatePollDraft(draft), [draft]);
+
+  return {
+    draft,
+    errors,
+    /** True once a submit was attempted: render `errors` from then on. */
+    showErrors,
+    canAddOption: draft.options.length < COMMUNITY_POLL_LIMITS.maxOptions,
+    canRemoveOption: draft.options.length > COMMUNITY_POLL_LIMITS.minOptions,
+    setQuestion: (question: string) => setDraft((d) => ({ ...d, question })),
+    setOption: (index: number, value: string) =>
+      setDraft((d) => ({ ...d, options: d.options.map((o, i) => (i === index ? value : o)) })),
+    addOption: () =>
+      setDraft((d) =>
+        d.options.length >= COMMUNITY_POLL_LIMITS.maxOptions ? d : { ...d, options: [...d.options, ""] },
+      ),
+    removeOption: (index: number) =>
+      setDraft((d) =>
+        d.options.length <= COMMUNITY_POLL_LIMITS.minOptions
+          ? d
+          : { ...d, options: d.options.filter((_, i) => i !== index) },
+      ),
+    setMultipleChoice: (multipleChoice: boolean) => setDraft((d) => ({ ...d, multipleChoice })),
+    setClosesAt: (closesAt: string) => setDraft((d) => ({ ...d, closesAt })),
+    setResultsVisibility: (resultsVisibility: CommunityPollResultsVisibility) =>
+      setDraft((d) => ({ ...d, resultsVisibility })),
+    /** Mark a submit attempt; returns whether the draft may be sent. */
+    attempt: () => {
+      setShowErrors(true);
+      return validatePollDraft(draft).valid;
+    },
+    reset: () => {
+      setDraft(emptyPollDraft());
+      setShowErrors(false);
+    },
+  };
+}
+
+// ── Reading and voting ───────────────────────────────────────────────────────
+
+/** A share of the voters, as a whole percentage. A multiple-choice poll's shares can sum past 100. */
+export function pollOptionPercent(votes: number | null, totalVoters: number | null): number | null {
+  if (votes === null || totalVoters === null) return null;
+  if (totalVoters <= 0) return 0;
+  return Math.round((votes / totalVoters) * 100);
+}
+
+/** Why the counts are hidden, when they are. */
+export type CommunityPollHiddenReason = "after_vote" | "after_close" | null;
+
+export function pollHiddenReason(poll: CommunityPollView): CommunityPollHiddenReason {
+  if (poll.resultsVisible) return null;
+  return poll.resultsVisibility === "after_close" ? "after_close" : "after_vote";
+}
+
+/** What a failed vote means for the member. */
+export type CommunityPollVoteError = "closed" | "invalid" | "forbidden" | "generic";
+
+export function pollVoteErrorCode(error: unknown): CommunityPollVoteError {
+  const status = (error as { response?: { status?: number } } | null)?.response?.status;
+  if (status === 409) return "closed";
+  if (status === 400) return "invalid";
+  if (status === 403 || status === 401) return "forbidden";
+  return "generic";
+}
+
+/** Two answers are the same answer when they hold the same options, in any order. */
+export function sameAnswer(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  const set = new Set(a);
+  return b.every((id) => set.has(id));
+}
+
+/**
+ * Headless poll on one post: the member's selection (starting from their
+ * current vote), picking options (one on a single-choice poll, several on a
+ * multiple-choice one), sending the answer, changing it and withdrawing it.
+ * `disabled` (a post still waiting for approval) keeps it read-only.
+ */
+export function useCommunityPoll(post: Pick<CommunityPost, "id" | "spaceId" | "poll">, opts: { disabled?: boolean } = {}) {
+  const poll = post.poll ?? null;
+  const vote = useVoteCommunityPoll();
+  const myVotes = poll?.myVotes ?? [];
+  const hasVoted = myVotes.length > 0;
+  const [selection, setSelection] = useState<string[]>(myVotes);
+  // Changing a vote reopens the options; a fresh answer from the server closes them.
+  const [changing, setChanging] = useState(false);
+  const [error, setError] = useState<CommunityPollVoteError | null>(null);
+  const myVotesKey = myVotes.join(",");
+
+  useEffect(() => {
+    setSelection(poll?.myVotes ?? []);
+    // Re-sync only when the server's answer changes, not on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [myVotesKey, poll?.id]);
+
+  const closed = !!poll?.closed;
+  const canVote = !!poll && !closed && !opts.disabled;
+  /** Options are pickable: before a first vote, or while changing one. */
+  const choosing = canVote && (!hasVoted || changing);
+
+  const send = async (optionIds: string[]) => {
+    if (!poll) return;
+    setError(null);
+    try {
+      await vote.mutateAsync({ postId: post.id, spaceId: post.spaceId, optionIds });
+      setChanging(false);
+    } catch (e) {
+      setError(pollVoteErrorCode(e));
+    }
+  };
+
+  return {
+    poll,
+    closed,
+    hasVoted,
+    canVote,
+    choosing,
+    changing,
+    selection,
+    isSelected: (optionId: string) => selection.includes(optionId),
+    toggle: (optionId: string) => {
+      if (!choosing || !poll) return;
+      setSelection((prev) =>
+        poll.multipleChoice
+          ? prev.includes(optionId)
+            ? prev.filter((id) => id !== optionId)
+            : [...prev, optionId]
+          : [optionId],
+      );
+    },
+    /** Something is picked, and it differs from the answer already on record. */
+    canSubmit: choosing && selection.length > 0 && !sameAnswer(selection, myVotes) && !vote.isPending,
+    submit: () => send(selection),
+    startChange: () => {
+      if (!canVote) return;
+      setSelection(myVotes);
+      setChanging(true);
+      setError(null);
+    },
+    cancelChange: () => {
+      setSelection(myVotes);
+      setChanging(false);
+      setError(null);
+    },
+    /** Take the vote back: an empty answer. */
+    withdraw: () => send([]),
+    pending: vote.isPending,
+    error,
+    hiddenReason: poll ? pollHiddenReason(poll) : null,
+  };
+}

package/src/ui/headless/community/countries.ts

@@ -0,0 +1,123 @@
+/**
+ * Countries for the member directory and map: every ISO 3166-1 alpha-2 code a
+ * member may pick, a name for it in the viewer's language (through
+ * `Intl.DisplayNames`, so no name list ships), and an approximate centre per
+ * country for placing a dot on the member globe.
+ *
+ * The centres began as the admin analytics globe's table
+ * (apps/admin/.../analytics/-components/country-centroids.ts), which Forge
+ * cannot import, extended to most countries. They place a country-level dot and
+ * nothing finer: members choose a country, never a location. A country missing
+ * a centre still lists in the directory, it just has no dot.
+ */
+
+/** Every ISO 3166-1 alpha-2 code, as a member can choose one. */
+// prettier-ignore
+export const COUNTRY_CODES: readonly string[] = [
+  "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ",
+  "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS",
+  "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN",
+  "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE",
+  "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF",
+  "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM",
+  "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM",
+  "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC",
+  "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK",
+  "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA",
+  "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG",
+  "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW",
+  "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS",
+  "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO",
+  "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI",
+  "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW",
+];
+
+/** Approximate centre of each country, alpha-2 to [latitude, longitude]. */
+// prettier-ignore
+export const COUNTRY_CENTROIDS: Readonly<Record<string, readonly [number, number]>> = {
+  AD: [42.5, 1.6], AE: [23.4, 53.8], AF: [33.9, 67.7], AG: [17.1, -61.8], AL: [41.2, 20.2],
+  AM: [40.1, 45.0], AO: [-11.2, 17.9], AR: [-38.4, -63.6], AT: [47.5, 14.6], AU: [-25.3, 133.8],
+  AZ: [40.1, 47.6], BA: [43.9, 17.7], BB: [13.2, -59.5], BD: [23.7, 90.4], BE: [50.5, 4.5],
+  BF: [12.2, -1.6], BG: [42.7, 25.5], BH: [26.0, 50.6], BI: [-3.4, 29.9], BJ: [9.3, 2.3],
+  BN: [4.5, 114.7], BO: [-16.3, -63.6], BR: [-14.2, -51.9], BS: [25.0, -77.4], BT: [27.5, 90.4],
+  BW: [-22.3, 24.7], BY: [53.7, 27.9], BZ: [17.2, -88.5], CA: [56.1, -106.3], CD: [-4.0, 21.8],
+  CF: [6.6, 20.9], CG: [-0.2, 15.8], CH: [46.8, 8.2], CI: [7.5, -5.5], CL: [-35.7, -71.5],
+  CM: [7.4, 12.4], CN: [35.9, 104.2], CO: [4.6, -74.3], CR: [9.7, -83.8], CU: [21.5, -77.8],
+  CV: [16.0, -24.0], CY: [35.1, 33.4], CZ: [49.8, 15.5], DE: [51.2, 10.5], DJ: [11.8, 42.6],
+  DK: [56.3, 9.5], DM: [15.4, -61.4], DO: [18.7, -70.2], DZ: [28.0, 1.7], EC: [-1.8, -78.2],
+  EE: [58.6, 25.0], EG: [26.8, 30.8], ER: [15.2, 39.8], ES: [40.5, -3.7], ET: [9.1, 40.5],
+  FI: [61.9, 25.7], FJ: [-17.7, 178.1], FR: [46.2, 2.2], GA: [-0.8, 11.6], GB: [55.4, -3.4],
+  GD: [12.1, -61.7], GE: [42.3, 43.4], GH: [7.9, -1.0], GL: [71.7, -42.6], GM: [13.4, -15.3],
+  GN: [9.9, -9.7], GQ: [1.7, 10.3], GR: [39.1, 21.8], GT: [15.8, -90.2], GW: [11.8, -15.2],
+  GY: [4.9, -58.9], HK: [22.3, 114.2], HN: [15.2, -86.2], HR: [45.1, 15.2], HT: [18.97, -72.3],
+  HU: [47.2, 19.5], ID: [-0.8, 113.9], IE: [53.4, -8.2], IL: [31.0, 34.9], IN: [20.6, 79.0],
+  IQ: [33.2, 43.7], IR: [32.4, 53.7], IS: [65.0, -19.0], IT: [41.9, 12.6], JM: [18.1, -77.3],
+  JO: [30.6, 36.2], JP: [36.2, 138.3], KE: [-0.02, 37.9], KG: [41.2, 74.8], KH: [12.6, 104.99],
+  KM: [-11.9, 43.9], KN: [17.4, -62.8], KP: [40.3, 127.5], KR: [35.9, 127.8], KW: [29.3, 47.5],
+  KZ: [48.0, 66.9], LA: [19.9, 102.5], LB: [33.9, 35.9], LC: [13.9, -60.98], LI: [47.2, 9.6],
+  LK: [7.9, 80.8], LR: [6.4, -9.4], LS: [-29.6, 28.2], LT: [55.2, 23.9], LU: [49.8, 6.1],
+  LV: [56.9, 24.6], LY: [26.3, 17.2], MA: [31.8, -7.1], MC: [43.7, 7.4], MD: [47.4, 28.4],
+  ME: [42.7, 19.4], MG: [-18.8, 46.9], MK: [41.6, 21.7], ML: [17.6, -4.0], MM: [21.9, 95.96],
+  MN: [46.9, 103.8], MO: [22.2, 113.5], MR: [21.0, -10.9], MT: [35.9, 14.4], MU: [-20.3, 57.6],
+  MV: [3.2, 73.2], MW: [-13.3, 34.3], MX: [23.6, -102.6], MY: [4.2, 101.9], MZ: [-18.7, 35.5],
+  NA: [-22.9, 18.5], NE: [17.6, 8.1], NG: [9.1, 8.7], NI: [12.9, -85.2], NL: [52.1, 5.3],
+  NO: [60.5, 8.5], NP: [28.4, 84.1], NZ: [-40.9, 174.9], OM: [21.5, 55.9], PA: [8.5, -80.8],
+  PE: [-9.2, -75.0], PG: [-6.3, 143.96], PH: [12.9, 121.8], PK: [30.4, 69.3], PL: [51.9, 19.1],
+  PR: [18.2, -66.6], PS: [31.95, 35.2], PT: [39.4, -8.2], PY: [-23.4, -58.4], QA: [25.4, 51.2],
+  RO: [45.9, 25.0], RS: [44.0, 21.0], RU: [61.5, 105.3], RW: [-1.9, 29.9], SA: [23.9, 45.1],
+  SB: [-9.6, 160.2], SC: [-4.7, 55.5], SD: [12.9, 30.2], SE: [60.1, 18.6], SG: [1.35, 103.8],
+  SI: [46.2, 15.0], SK: [48.7, 19.7], SL: [8.5, -11.8], SM: [43.9, 12.5], SN: [14.5, -14.5],
+  SO: [5.2, 46.2], SR: [3.9, -56.0], SS: [6.9, 31.3], SV: [13.8, -88.9], SY: [34.8, 39.0],
+  SZ: [-26.5, 31.5], TD: [15.5, 18.7], TG: [8.6, 0.8], TH: [15.9, 100.99], TJ: [38.9, 71.3],
+  TL: [-8.9, 125.7], TM: [38.97, 59.6], TN: [33.9, 9.5], TO: [-21.2, -175.2], TR: [38.96, 35.2],
+  TT: [10.7, -61.2], TW: [23.7, 121.0], TZ: [-6.4, 34.9], UA: [48.4, 31.2], UG: [1.4, 32.3],
+  US: [37.1, -95.7], UY: [-32.5, -55.8], UZ: [41.4, 64.6], VC: [13.3, -61.2], VE: [6.4, -66.6],
+  VN: [14.1, 108.3], VU: [-15.4, 166.96], WS: [-13.8, -172.1], YE: [15.6, 48.5], ZA: [-30.6, 22.9],
+  ZM: [-13.1, 27.8], ZW: [-19.0, 29.2],
+};
+
+/** True for a two-letter code this list knows. */
+export function isCountryCode(code: unknown): code is string {
+  return typeof code === "string" && COUNTRY_CODES.includes(code.toUpperCase());
+}
+
+const displayNamesCache = new Map<string, Intl.DisplayNames | null>();
+
+function displayNames(locale: string): Intl.DisplayNames | null {
+  if (!displayNamesCache.has(locale)) {
+    let names: Intl.DisplayNames | null = null;
+    try {
+      names =
+        typeof Intl !== "undefined" && "DisplayNames" in Intl
+          ? new Intl.DisplayNames([locale], { type: "region" })
+          : null;
+    } catch {
+      names = null;
+    }
+    displayNamesCache.set(locale, names);
+  }
+  return displayNamesCache.get(locale) ?? null;
+}
+
+/**
+ * A country's name in `locale` ("DE" is "Germany" in English, "Deutschland"
+ * in German). Falls back to the code where the runtime has no names, and to
+ * null for no code at all.
+ */
+export function countryName(code: string | null | undefined, locale = "en"): string | null {
+  if (!code) return null;
+  const upper = code.toUpperCase();
+  try {
+    return displayNames(locale)?.of(upper) ?? upper;
+  } catch {
+    return upper;
+  }
+}
+
+/** Every country as a select option, sorted by its name in `locale`. */
+export function countryOptions(locale = "en"): { code: string; name: string }[] {
+  const collator = new Intl.Collator(locale);
+  return COUNTRY_CODES.map((code) => ({ code, name: countryName(code, locale) ?? code })).sort((a, b) =>
+    collator.compare(a.name, b.name),
+  );
+}

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

@@ -1,4 +1,4 @@
-// Community headless primitives. NOTE: this is a lane-local aggregator — the
+// Community headless primitives. NOTE: this is a lane-local aggregator. The
 // integrator re-exports it from `ui/headless/index.ts` (`export * from "./community"`).
 export {
   buildLexicalState,
@@ -18,3 +18,83 @@ export { useRichMentionComposer, type RichCommand } from "./useRichMentionCompos
 export { serializeRichToLexical, collectMentions, isRichEmpty } from "./richLexical";
 export { useCommunitySpaceFeed } from "./useCommunitySpaceFeed";
 export { useCommunityThread } from "./useCommunityThread";
+export {
+  useCommunityAgentThinking,
+  useChatAgentThinking,
+  useCommunityAgentAnswerFeedback,
+  useCommunityCatchUp,
+  linkifyText,
+  useCommunityAgentAnswerRatings,
+  chatThinkingKey,
+  AGENT_THINKING_TIMEOUT_MS,
+  CATCH_ME_UP_MIN_REPLIES,
+  type LinkifiedSegment,
+} from "./useCommunityAgent";
+export {
+  COUNTRY_CODES,
+  COUNTRY_CENTROIDS,
+  countryName,
+  countryOptions,
+  isCountryCode,
+} from "./countries";
+export {
+  useCommunityMemberDirectory,
+  memberGlobePoints,
+  memberMapCountries,
+  memberGlobeMarkers,
+  memberLocationLabel,
+  globeAnglesFor,
+  DIRECTORY_SORTS,
+  DIRECTORY_LEVELS,
+  DIRECTORY_SEARCH_DEBOUNCE_MS,
+  type MemberGlobePoint,
+  type MemberGlobeMarker,
+  type CommunityMembersView,
+  type UseCommunityMemberDirectoryOptions,
+} from "./useCommunityMembers";
+export {
+  useCommunityModeration,
+  useCommunityModeratorActions,
+  describeHoldReason,
+  describeModerationNotification,
+  restorableLogEntries,
+  communityMuteUntil,
+  moderationErrorMessage,
+  COMMUNITY_MUTE_DAYS,
+  type CommunityHoldReason,
+  type CommunityMuteDays,
+  type CommunityModerationOutcome,
+  type CommunityLogRestoreTarget,
+  type CommunityReportResolution,
+  type UseCommunityModerationOptions,
+} from "./useCommunityModeration";
+export {
+  useCommunityPoll,
+  useCommunityPollDraft,
+  validatePollDraft,
+  buildPollPayload,
+  emptyPollDraft,
+  parsePollCloseTime,
+  pollOptionPercent,
+  pollHiddenReason,
+  pollVoteErrorCode,
+  sameAnswer,
+  COMMUNITY_POLL_LIMITS,
+  type CommunityPollDraft,
+  type CommunityPollDraftErrors,
+  type CommunityPollQuestionError,
+  type CommunityPollOptionError,
+  type CommunityPollOptionsError,
+  type CommunityPollClosesError,
+  type CommunityPollHiddenReason,
+  type CommunityPollVoteError,
+} from "./communityPoll";
+export {
+  COMMUNITY_EMBED_ORIGINS,
+  safeHttpUrl,
+  safeEmbedUrl,
+  linkPreviewHost,
+  linkPreviewDisplay,
+  autoplayEmbedUrl,
+  type LinkPreviewDisplay,
+} from "./linkPreview";

package/src/ui/headless/community/linkPreview.ts

@@ -0,0 +1,71 @@
+import type { CommunityLinkPreview } from "../../../data/queries/useCommunity";
+
+/**
+ * Link cards on community posts (community parity §6.2). The server puts the
+ * first link of a post on it as a card, shortly after it is published. These
+ * helpers decide what of that card is safe to render: an http(s) link only,
+ * and a video player only from the three privacy-respecting embed origins the
+ * server itself builds. Anything else falls back to a plain link card, and a
+ * preview with no safe link renders nothing at all.
+ */
+
+/** The only origins a post's video may play from. */
+export const COMMUNITY_EMBED_ORIGINS: readonly string[] = [
+  "https://www.youtube-nocookie.com",
+  "https://player.vimeo.com",
+  "https://www.loom.com",
+];
+
+/** The address, when it is an absolute http(s) URL. */
+export function safeHttpUrl(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.trim());
+    return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The video's player address, when the preview is a video from an allowed origin. */
+export function safeEmbedUrl(preview: Pick<CommunityLinkPreview, "kind" | "embedUrl"> | null | undefined): string | null {
+  if (!preview || preview.kind !== "video" || typeof preview.embedUrl !== "string") return null;
+  try {
+    const url = new URL(preview.embedUrl);
+    return url.protocol === "https:" && COMMUNITY_EMBED_ORIGINS.includes(url.origin) ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** "example.com": the host without `www.`, for a card with no site name. */
+export function linkPreviewHost(value: string | null | undefined): string | null {
+  const href = safeHttpUrl(value);
+  if (!href) return null;
+  return new URL(href).hostname.replace(/^www\./, "") || null;
+}
+
+/** How a post's preview renders: a video facade, a link card, or nothing. */
+export type LinkPreviewDisplay =
+  | { kind: "video"; href: string; embedUrl: string; imageUrl: string | null }
+  | { kind: "card"; href: string; imageUrl: string | null }
+  | null;
+
+export function linkPreviewDisplay(preview: CommunityLinkPreview | null | undefined): LinkPreviewDisplay {
+  if (!preview) return null;
+  const href = safeHttpUrl(preview.url);
+  if (!href) return null;
+  const imageUrl = safeHttpUrl(preview.imageUrl);
+  const embedUrl = safeEmbedUrl(preview);
+  return embedUrl ? { kind: "video", href, embedUrl, imageUrl } : { kind: "card", href, imageUrl };
+}
+
+/**
+ * The player address with autoplay on, used once the member has pressed play,
+ * so one click starts the video rather than showing a second play button.
+ */
+export function autoplayEmbedUrl(embedUrl: string): string {
+  const url = new URL(embedUrl);
+  url.searchParams.set("autoplay", "1");
+  return url.toString();
+}