@tribe-nest/forge 3.60.0 → 3.63.0

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

@@ -0,0 +1,266 @@
+import { useMemo, useState } from "react";
+import { useCommunityUpgradeOpener, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { isNotFound } from "../../../data/queries/useCommunities";
+import {
+  useCommunityWikiMediaUrl,
+  useCommunityWikiPageContent,
+  useCommunityWikiPages,
+  type CommunityWikiPageSummary,
+} from "../../../data/queries/useCommunityWiki";
+import type { LexicalNodeJson } from "../community/lexical";
+import { communityAboutPath } from "./paths";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** How a wiki image's `src` is shown, if at all. */
+export type WikiImageSource = { kind: "url"; url: string } | { kind: "private"; mediaId: string } | null;
+
+const PRIVATE_MEDIA_PREFIX = "kbmedia:";
+const MEDIA_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Read a Knowledge Base image's `src`. A plain http(s) address (or a site
+ * path) is shown as it is. `kbmedia:<id>` is a PRIVATE image, shown through a
+ * short-lived signed read that only a viewer of the page can get. Anything
+ * else is never rendered: not `javascript:`, not `data:`, not a malformed id.
+ */
+export function wikiImageSource(src: unknown): WikiImageSource {
+  if (typeof src !== "string") return null;
+  const value = src.trim();
+  if (/^https?:\/\//i.test(value) || (value.startsWith("/") && !value.startsWith("//")))
+    return { kind: "url", url: value };
+  if (value.startsWith(PRIVATE_MEDIA_PREFIX)) {
+    const mediaId = value.slice(PRIVATE_MEDIA_PREFIX.length);
+    return MEDIA_ID.test(mediaId) ? { kind: "private", mediaId } : null;
+  }
+  return null;
+}
+
+export type WikiMediaImageStatus = "loading" | "ready" | "unavailable";
+
+/**
+ * Where a private image stands, from the signed-read request and the addresses
+ * the browser failed to load. The first failure (usually an expired address)
+ * asks for a fresh one; once that re-request has been made
+ * (`retriedAfterFailure`), a failed address reads as unavailable, so a broken
+ * file cannot loop.
+ */
+export function wikiMediaImageStatus(input: {
+  isLoading: boolean;
+  isError: boolean;
+  url: string | null;
+  failedUrls: ReadonlySet<string>;
+  retriedAfterFailure: boolean;
+}): WikiMediaImageStatus {
+  if (input.isError) return "unavailable";
+  if (!input.url) return input.isLoading ? "loading" : "unavailable";
+  if (input.failedUrls.has(input.url)) return input.retriedAfterFailure ? "unavailable" : "loading";
+  return "ready";
+}
+
+/** One entry of a page's table of contents. `id` is the heading's anchor. */
+export interface CommunityWikiTocEntry {
+  id: string;
+  text: string;
+  /** 1 for h1 through 6 for h6. */
+  level: number;
+}
+
+/** A table of contents is shown once a page has this many headings. */
+export const WIKI_TOC_MIN_HEADINGS = 2;
+
+/**
+ * The page list split the way a renderer draws it: every page in order, the
+ * ones this viewer can open, and the ones listed but locked to a tier they do
+ * not have. `publicOnly` keeps just the public pages (the About page, which a
+ * visitor and a member see alike).
+ */
+export function shapeWikiList(pages: CommunityWikiPageSummary[] | undefined, opts: { publicOnly?: boolean } = {}) {
+  const all = (Array.isArray(pages) ? pages : []).filter((page) => !opts.publicOnly || page.isPublic);
+  return {
+    all,
+    readable: all.filter((page) => !page.locked),
+    locked: all.filter((page) => page.locked),
+  };
+}
+
+/**
+ * What opens a locked page, for the copy beside it: the level the member has
+ * not reached yet (null when the level is not what is missing) and the names
+ * of the tiers that open it (empty when none are named).
+ */
+export function wikiUnlockParts(page: Pick<CommunityWikiPageSummary, "unlockLevel" | "unlockTiers">): {
+  level: number | null;
+  tiers: string;
+} {
+  const level = typeof page.unlockLevel === "number" && page.unlockLevel > 0 ? page.unlockLevel : null;
+  const tiers = (page.unlockTiers ?? []).map((tier) => tier.name).filter(Boolean).join(", ");
+  return { level, tiers };
+}
+
+/**
+ * The page the Wiki tab opens on when the address names none: the first page
+ * this viewer can read, in the wiki's order. Null when every page is locked or
+ * there are none.
+ */
+export function defaultWikiPageSlug(pages: CommunityWikiPageSummary[] | undefined): string | null {
+  return (Array.isArray(pages) ? pages : []).find((page) => !page.locked)?.slug ?? null;
+}
+
+/**
+ * Lexical JSON as a root node. The Knowledge Base stores the editor state as an
+ * object, but a string of JSON is accepted too, so a page never renders empty
+ * because of how its content was serialised.
+ */
+export function parseWikiContent(content: unknown): { root: LexicalNodeJson } | null {
+  let value = content;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (!value || typeof value !== "object") return null;
+  const maybe = value as { root?: LexicalNodeJson; children?: LexicalNodeJson[] };
+  if (maybe.root && typeof maybe.root === "object") return { root: maybe.root };
+  if (Array.isArray(maybe.children)) return { root: maybe as LexicalNodeJson };
+  return null;
+}
+
+/** The plain text of a node and everything under it. */
+export function lexicalNodeText(node: LexicalNodeJson): string {
+  if (typeof node.text === "string") return node.text;
+  return (node.children ?? []).map(lexicalNodeText).join("");
+}
+
+/** A URL-safe anchor for a heading ("Getting started!" to "getting-started"). */
+export function wikiHeadingSlug(text: string): string {
+  const slug = text
+    .normalize("NFKD")
+    // Drop the accents NFKD split off ("Über" to "Uber").
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "section";
+}
+
+/**
+ * The table of contents: every top-level heading in document order, each with
+ * a unique anchor (a repeated title gets `-2`, `-3`). The renderer gives the
+ * headings these same ids in the same order, which is why both read the root's
+ * direct children only. Empty headings are skipped.
+ */
+export function extractWikiToc(content: unknown): CommunityWikiTocEntry[] {
+  const parsed = parseWikiContent(content);
+  if (!parsed) return [];
+  const used = new Map<string, number>();
+  const toc: CommunityWikiTocEntry[] = [];
+  for (const node of parsed.root.children ?? []) {
+    if (node.type !== "heading") continue;
+    const text = lexicalNodeText(node).trim();
+    if (!text) continue;
+    const base = wikiHeadingSlug(text);
+    const seen = used.get(base) ?? 0;
+    used.set(base, seen + 1);
+    const tag = typeof node.tag === "string" ? node.tag : "h2";
+    const level = Math.min(6, Math.max(1, Number(tag.replace(/^h/, "")) || 2));
+    toc.push({ id: seen ? `${base}-${seen + 1}` : base, text, level });
+  }
+  return toc;
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/**
+ * A PRIVATE wiki image (`kbmedia:<id>`) on the page `pageSlug`: its signed
+ * address, re-requested before it expires, and again once if the browser
+ * fails to load it (`onImageError`). Only the wiki page view uses this: posts
+ * never carry private Knowledge Base media.
+ */
+export function useWikiMediaImage(pageSlug: string | undefined, mediaId: string | undefined) {
+  const query = useCommunityWikiMediaUrl(pageSlug, mediaId);
+  const [failedUrls, setFailedUrls] = useState<ReadonlySet<string>>(() => new Set());
+  const [retriedAfterFailure, setRetriedAfterFailure] = useState(false);
+  const url = query.data?.url ?? null;
+  const status = wikiMediaImageStatus({
+    isLoading: query.isLoading || query.isFetching,
+    isError: query.isError,
+    url,
+    failedUrls,
+    retriedAfterFailure,
+  });
+
+  return {
+    status,
+    url: status === "ready" ? url : null,
+    /** Call from the <img>'s onError: an expired address is replaced once. */
+    onImageError: () => {
+      if (!url || failedUrls.has(url)) return;
+      setFailedUrls((prev) => new Set(prev).add(url));
+      if (retriedAfterFailure) return;
+      void query.refetch().finally(() => setRetriedAfterFailure(true));
+    },
+  };
+}
+
+export interface UseCommunityWikiOptions {
+  /** Keep only the public pages (the About page). */
+  publicOnly?: boolean;
+  enabled?: boolean;
+}
+
+/**
+ * Headless wiki page list for the surrounding community: every page this
+ * viewer may see, the readable and locked ones, the page to open by default,
+ * and how to unlock a locked one. `unlock` opens the community's upgrade sheet
+ * with the page's first unlocking tier when a community home provides one;
+ * otherwise `unlockHref` is the About page with that tier preselected.
+ */
+export function useCommunityWiki(opts: UseCommunityWikiOptions = {}) {
+  const community = useOptionalCommunityContext();
+  const opener = useCommunityUpgradeOpener();
+  const query = useCommunityWikiPages({ enabled: opts.enabled });
+  const shaped = useMemo(
+    () => shapeWikiList(query.data, { publicOnly: opts.publicOnly }),
+    [query.data, opts.publicOnly],
+  );
+
+  return {
+    pages: shaped.all,
+    readablePages: shaped.readable,
+    lockedPages: shaped.locked,
+    /** The page to open when the address names none. */
+    defaultSlug: defaultWikiPageSlug(shaped.all),
+    isLoading: query.isLoading,
+    isError: query.isError && !isNotFound(query.error),
+    /** Open the upgrade sheet for a locked page, when a community home provides one. */
+    unlock: opener ? (page: CommunityWikiPageSummary) => opener.openUpgrade(page.unlockTiers[0]?.id ?? null) : null,
+    /** Where a locked page's upgrade leads when no upgrade sheet is on hand. */
+    unlockHref: (page: CommunityWikiPageSummary) =>
+      community?.slug ? communityAboutPath(community.slug, { tier: page.unlockTiers[0]?.id }) : null,
+  };
+}
+
+/**
+ * Headless wiki page: its content (parsed), the table of contents and whether
+ * to show it, and `notFound` when this viewer may not read the page (locked,
+ * hidden or gone: the server does not say which, by design).
+ */
+export function useCommunityWikiPage(pageSlug: string | undefined, opts: { enabled?: boolean } = {}) {
+  const query = useCommunityWikiPageContent(pageSlug, opts);
+  const content = useMemo(() => parseWikiContent(query.data?.content), [query.data]);
+  const toc = useMemo(() => extractWikiToc(content), [content]);
+  return {
+    page: query.data ?? null,
+    content,
+    toc,
+    showToc: toc.length >= WIKI_TOC_MIN_HEADINGS,
+    /** Anchor ids for the page's headings, in order, for the renderer. */
+    headingIds: toc.map((entry) => entry.id),
+    isLoading: query.isLoading,
+    notFound: isNotFound(query.error),
+    isError: query.isError && !isNotFound(query.error),
+  };
+}

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,
+  };
+}