@tribe-nest/forge 1.13.0

package/src/ui/headless/work/useWorkPortal.ts

@@ -0,0 +1,349 @@
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseQueryResult,
+} from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+
+/**
+ * Headless data layer for the read-only "Work" (project management) CLIENT
+ * PORTAL. Speaks the public, profile-scoped `/public/work/*` API through the
+ * Forge Axios client (`useForge().client`). For the two authed reads the bearer
+ * token IS the client identity (an external contact linked to a platform
+ * account, enforced server-side); the tokenized report needs no login at all.
+ *
+ * These are Tier-1 primitives: they return clean React Query results
+ * ({ data, isLoading, error, … }) and render nothing, so a creator can build a
+ * fully custom portal UI on top of them. The styled `WorkPortalProjects` /
+ * `WorkProjectReport` / `WorkTokenReport` blocks are built on exactly these.
+ */
+
+// ── Types (mirror WorkPublicService responses) ───────────────────────────────
+
+export interface WorkProjectSummary {
+  id: string;
+  name: string;
+  status: string;
+  currency: string;
+  dueDate: string | null;
+  startDate: string | null;
+  taskCount: number;
+  doneCount: number;
+}
+
+export interface WorkMilestone {
+  id: string;
+  name: string;
+  dueDate: string | null;
+  status: string;
+}
+
+export interface WorkTask {
+  id: string;
+  title: string;
+  done: boolean;
+  dueDate: string | null;
+}
+
+export interface WorkTimeReportRow {
+  taskId: string | null;
+  taskTitle: string;
+  hours: number;
+  amount: number;
+  amountCents: number;
+}
+
+export interface WorkTimeReport {
+  currency: string;
+  byTask: WorkTimeReportRow[];
+  totalHours: number;
+  totalAmount: number;
+  totalAmountCents: number;
+}
+
+export interface WorkProjectReportData {
+  project: {
+    id: string;
+    name: string;
+    status: string;
+    currency: string;
+    dueDate: string | null;
+    startDate: string | null;
+  };
+  milestones: WorkMilestone[];
+  tasks: WorkTask[];
+  timeReport: WorkTimeReport;
+}
+
+export interface WorkTaskComment {
+  id: string;
+  content: string;
+  accountId: string;
+  fullName: string;
+  createdAt: string;
+}
+
+export interface WorkTaskAttachment {
+  id: string;
+  mediaId: string;
+  name: string | null;
+  filename: string | null;
+  url: string | null;
+  type: string | null;
+  size: number | null;
+}
+
+export interface WorkProjectInvoice {
+  id: string;
+  invoiceNumber: string;
+  status: string;
+  total: number;
+  currency: string;
+  dueDate: string | null;
+  paidAt: string | null;
+  createdAt: string;
+  /** Still owing → the portal shows a Pay button. */
+  payable: boolean;
+}
+
+export interface WorkInviteContext {
+  projectId: string;
+  projectName: string;
+  profileName: string;
+  email: string;
+  firstName: string | null;
+}
+
+export interface WorkInviteAcceptResult {
+  token: string;
+  projectId: string;
+  account: { id: string; email: string; firstName: string | null; lastName: string | null };
+}
+
+// ── Query keys ───────────────────────────────────────────────────────────────
+
+const keys = {
+  projects: (profileId?: string) => ["work-portal-projects", profileId] as const,
+  report: (profileId: string | undefined, projectId: string) =>
+    ["work-portal-report", profileId, projectId] as const,
+  tokenReport: (token: string) => ["work-portal-token-report", token] as const,
+  taskComments: (profileId: string | undefined, projectId: string, taskId: string) =>
+    ["work-portal-task-comments", profileId, projectId, taskId] as const,
+  taskAttachments: (profileId: string | undefined, projectId: string, taskId: string) =>
+    ["work-portal-task-attachments", profileId, projectId, taskId] as const,
+  projectInvoices: (profileId: string | undefined, projectId: string) =>
+    ["work-portal-project-invoices", profileId, projectId] as const,
+};
+
+// ── Authed client's projects ─────────────────────────────────────────────────
+
+/** The authenticated client's (non-archived) client projects with a task/done
+ * summary — GET /public/work/projects. The token is the identity. */
+export function useWorkPortalProjects(): UseQueryResult<WorkProjectSummary[]> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkProjectSummary[]>({
+    queryKey: keys.projects(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/work/projects", { params: { profileId } });
+      return res.data as WorkProjectSummary[];
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+// ── Authed client's single-project report ────────────────────────────────────
+
+/** The authenticated client's overview + billable-only time report for one of
+ * their projects — GET /public/work/projects/:id/report. */
+export function useWorkProjectReport(projectId: string): UseQueryResult<WorkProjectReportData> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkProjectReportData>({
+    queryKey: keys.report(profileId, projectId),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/projects/${projectId}/report`, {
+        params: { profileId },
+      });
+      return res.data as WorkProjectReportData;
+    },
+    enabled: !!profileId && !!client && !!projectId,
+  });
+}
+
+// ── Public tokenized report (no login) ───────────────────────────────────────
+
+/** Login-free tokenized share of a project's time report — GET
+ * /public/work/time-report/:token. The signed token IS the authorization. */
+export function useWorkTokenReport(token: string): UseQueryResult<WorkProjectReportData> {
+  const { client } = useForge();
+  return useQuery<WorkProjectReportData>({
+    queryKey: keys.tokenReport(token),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/time-report/${token}`);
+      return res.data as WorkProjectReportData;
+    },
+    enabled: !!client && !!token,
+    retry: false,
+  });
+}
+
+// ── Authed client's task comments (read + post) ──────────────────────────────
+
+export interface UseWorkTaskCommentsResult {
+  comments: WorkTaskComment[];
+  isLoading: boolean;
+  error: unknown;
+  /** Post a new comment; resolves once the thread has been refreshed. */
+  addComment: (content: string) => Promise<void>;
+  isAdding: boolean;
+}
+
+/**
+ * The authenticated client's comment thread for a single task on one of their
+ * projects — GET/POST /public/work/projects/:projectId/tasks/:taskId/comments.
+ * Newest first. The bearer token IS the client identity (server-enforced).
+ * Posting invalidates the thread so the new comment appears. Tier-1 primitive:
+ * returns clean data + a bound mutation, renders nothing.
+ */
+export function useWorkTaskComments(projectId: string, taskId: string): UseWorkTaskCommentsResult {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  const query = useQuery<WorkTaskComment[]>({
+    queryKey: keys.taskComments(profileId, projectId, taskId),
+    queryFn: async () => {
+      const res = await client.get(
+        `/public/work/projects/${projectId}/tasks/${taskId}/comments`,
+        { params: { profileId } },
+      );
+      return res.data as WorkTaskComment[];
+    },
+    enabled: !!profileId && !!client && !!projectId && !!taskId,
+  });
+
+  const mutation = useMutation<WorkTaskComment, unknown, string>({
+    mutationFn: async (content: string) => {
+      const res = await client.post(
+        `/public/work/projects/${projectId}/tasks/${taskId}/comments`,
+        { content },
+        { params: { profileId } },
+      );
+      return res.data as WorkTaskComment;
+    },
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: keys.taskComments(profileId, projectId, taskId),
+      });
+    },
+  });
+
+  return {
+    comments: query.data ?? [],
+    isLoading: query.isLoading,
+    error: query.error,
+    addComment: async (content: string) => {
+      await mutation.mutateAsync(content);
+    },
+    isAdding: mutation.isPending,
+  };
+}
+
+// ── Authed client's task attachments (read-only) ─────────────────────────────
+
+/**
+ * Read-only attachments the team has added to a task on one of the client's
+ * projects — GET /public/work/projects/:projectId/tasks/:taskId/attachments.
+ * Tier-1 primitive: returns clean data, renders nothing.
+ */
+export function useWorkTaskAttachments(
+  projectId: string,
+  taskId: string,
+): UseQueryResult<WorkTaskAttachment[]> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkTaskAttachment[]>({
+    queryKey: keys.taskAttachments(profileId, projectId, taskId),
+    queryFn: async () => {
+      const res = await client.get(
+        `/public/work/projects/${projectId}/tasks/${taskId}/attachments`,
+        { params: { profileId } },
+      );
+      return res.data as WorkTaskAttachment[];
+    },
+    enabled: !!profileId && !!client && !!projectId && !!taskId,
+  });
+}
+
+// ── Authed client's invoices for a project ───────────────────────────────────
+
+/**
+ * The client's (non-draft) invoices for one of their projects —
+ * GET /public/work/projects/:id/invoices. Each carries a `payable` flag the
+ * portal turns into a Pay button (links to /i/invoice/:id). Tier-1 primitive.
+ */
+export function useWorkProjectInvoices(projectId: string): UseQueryResult<WorkProjectInvoice[]> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkProjectInvoice[]>({
+    queryKey: keys.projectInvoices(profileId, projectId),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/projects/${projectId}/invoices`, { params: { profileId } });
+      return res.data as WorkProjectInvoice[];
+    },
+    enabled: !!profileId && !!client && !!projectId,
+  });
+}
+
+// ── Client invite accept (public, no auth) ───────────────────────────────────
+
+/**
+ * Fetch the branded context for an invite link (GET /public/work/invite).
+ * Public — no bearer token needed; the link's token IS the credential.
+ * `null`/errored when the token or project is missing/invalid/expired.
+ */
+export function useWorkInvite(
+  token: string | undefined,
+  projectId: string | undefined,
+): UseQueryResult<WorkInviteContext> {
+  const { client } = useForge();
+  return useQuery<WorkInviteContext>({
+    queryKey: ["work-invite", token, projectId],
+    queryFn: async () => {
+      const res = await client.get(`/public/work/invite`, { params: { token, projectId } });
+      return res.data as WorkInviteContext;
+    },
+    enabled: !!client && !!token && !!projectId,
+    retry: false,
+  });
+}
+
+/**
+ * Accept an invite (POST /public/work/invite/accept): set a password and
+ * receive a fresh portal session token. The caller persists the token +
+ * navigates. Public — no bearer token needed.
+ */
+export function useAcceptWorkInvite() {
+  const { client } = useForge();
+  return useMutation<WorkInviteAcceptResult, unknown, { token: string; projectId: string; password: string }>({
+    mutationFn: async ({ token, projectId, password }) => {
+      const res = await client.post(`/public/work/invite/accept`, { token, projectId, password });
+      return res.data as WorkInviteAcceptResult;
+    },
+  });
+}
+
+// ── Presentational helpers ───────────────────────────────────────────────────
+
+/** Major-unit amount → display string using the project currency symbol. */
+export function formatWorkMoney(amount: number, currency = "USD"): string {
+  const symbols: Record<string, string> = { USD: "$", EUR: "€", GBP: "£", NGN: "₦", CAD: "$", AUD: "$" };
+  const symbol = symbols[currency?.toUpperCase()] ?? `${currency} `;
+  const n = Number.isFinite(amount) ? amount : 0;
+  return `${symbol}${n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+/** ISO date → short human date, or "—" when absent. */
+export function formatWorkDate(value: string | null | undefined): string {
+  if (!value) return "—";
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return "—";
+  return d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}

package/src/ui/index.ts

@@ -0,0 +1,144 @@
+// Forge UI — Tier-2 styled blocks (theme-aware, opinionated) + the theme
+// contract. Built on the Tier-1 headless primitives in `forge/ui/headless`.
+export {
+  ForgeThemeProvider,
+  useForgeTheme,
+  useThemeTokens,
+  resolveThemeTokens,
+  defaultForgeTheme,
+  type ForgeTheme,
+  type ResolvedThemeTokens,
+} from "./theme/ForgeThemeProvider";
+export { readableTextOn } from "./theme/contrast";
+export {
+  Button,
+  buttonStyle,
+  type ButtonProps,
+  type ButtonVariant,
+  type ButtonSize,
+} from "./styled/Button";
+export {
+  ForgePaymentProvider,
+  usePaymentRenderer,
+  type PaymentRenderer,
+  type PaymentRenderProps,
+} from "./payment/ForgePaymentProvider";
+
+// Re-export the headless layer so consumers can reach both tiers from `forge/ui`.
+export * from "./headless";
+
+// Currency formatting primitive (presentational helper).
+export { useFormatCurrency, useAmountFormatter, formatCurrency, getCurrencySymbol } from "./format/useFormatCurrency";
+
+// Content layer (Component 7) — editable field wrappers.
+export {
+  EditableText,
+  EditableRichText,
+  EditableImage,
+  EditableRegion,
+  type EditableTextProps,
+  type EditableRichTextProps,
+  type EditableImageProps,
+} from "./content/Editable";
+
+// Styled blocks
+export { DonationButton, type DonationButtonProps } from "./styled/DonationButton";
+export { OfferButton, type OfferButtonProps } from "./styled/OfferButton";
+export { Checkout, type CheckoutProps } from "./styled/Checkout";
+export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
+export { ForgeStripePayment } from "./payment/ForgeStripePayment";
+export { Cart, type CartProps } from "./styled/Cart";
+export { CurrencySwitcher, type CurrencySwitcherProps } from "./styled/CurrencySwitcher";
+export { UserMenu, type UserMenuProps } from "./styled/UserMenu";
+export { EmailListForm, type EmailListFormProps } from "./styled/EmailListForm";
+export { BlogComments, type BlogCommentsProps } from "./styled/BlogComments";
+export { PageActions, type PageActionsProps } from "./styled/PageActions";
+export { BlogPostFooter, type BlogPostFooterProps } from "./styled/BlogPostFooter";
+export { BotProtection, EMPTY_BOT_FIELDS, type BotFields } from "./styled/BotProtection";
+export { ContactForm, type ContactFormProps } from "./styled/ContactForm";
+export { Paywall, type PaywallProps } from "./styled/Paywall";
+export { ReactionBar, type ReactionBarProps } from "./styled/ReactionBar";
+export { ProductGrid, type ProductGridProps } from "./styled/ProductGrid";
+export { ProductDetail, type ProductDetailProps } from "./styled/ProductDetail";
+export { MembershipTiers, type MembershipTiersProps } from "./styled/MembershipTiers";
+export { EventsList, type EventsListProps } from "./styled/EventsList";
+export { EventTickets, type EventTicketsProps } from "./styled/EventTickets";
+export { EventCountdown, type EventCountdownProps } from "./styled/EventCountdown";
+export { EventDetail, type EventDetailProps } from "./styled/EventDetail";
+export { CoachingBooking, type CoachingBookingProps } from "./styled/CoachingBooking";
+export { CoachingDetail, type CoachingDetailProps } from "./styled/CoachingDetail";
+export { CourseCheckout, type CourseCheckoutProps } from "./styled/CourseCheckout";
+export { CourseDetail, type CourseDetailProps } from "./styled/CourseDetail";
+export { PostsFeed, type PostsFeedProps } from "./styled/PostsFeed";
+export { CoursesGrid, type CoursesGridProps } from "./styled/CoursesGrid";
+export { LoginForm, type LoginFormProps } from "./styled/LoginForm";
+export { SignupForm, type SignupFormProps } from "./styled/SignupForm";
+export { ForgotPasswordForm, type ForgotPasswordFormProps } from "./styled/ForgotPasswordForm";
+export { ResetPasswordForm, type ResetPasswordFormProps } from "./styled/ResetPasswordForm";
+export { AccountDashboard, type AccountDashboardProps, type AccountTabKey, ACCOUNT_TABS } from "./styled/AccountDashboard";
+export { AudioPlayer, type AudioPlayerProps } from "./styled/AudioPlayer";
+export { ForgeAnalytics, type ForgeAnalyticsProps } from "./analytics/ForgeAnalytics";
+export { PageMetaPixel, usePageMetaPixel, type PageMetaPixelProps } from "./analytics/PageMetaPixel";
+export { CookieConsent, type CookieConsentProps } from "./styled/CookieConsent";
+export { Loading, type LoadingProps } from "./styled/Loading";
+export {
+  ConfirmationStage,
+  ConfirmationCard,
+  ConfirmationRow,
+  CheckSeal,
+  WarnSeal,
+  Perforation,
+  alpha,
+} from "./styled/Confirmation";
+export { PlayButton, type PlayButtonProps } from "./styled/PlayButton";
+export { CoachingConfirmation, type CoachingConfirmationProps } from "./styled/CoachingConfirmation";
+export { EventConfirmation, type EventConfirmationProps } from "./styled/EventConfirmation";
+export { CourseConfirmation, type CourseConfirmationProps } from "./styled/CourseConfirmation";
+export { CheckoutConfirmation, type CheckoutConfirmationProps } from "./styled/CheckoutConfirmation";
+export { InvoiceConfirmation, type InvoiceConfirmationProps } from "./styled/InvoiceConfirmation";
+export { PaymentLinkConfirmation, type PaymentLinkConfirmationProps } from "./styled/PaymentLinkConfirmation";
+export { FormRenderer, FieldInput, type FormRendererProps } from "./styled/FormRenderer";
+export { SectionedFormRenderer, type SectionedFormRendererProps } from "./styled/SectionedFormRenderer";
+export { ChatRoom, type ChatRoomProps } from "./styled/ChatRoom";
+export { ChatAttachments } from "./styled/chat/ChatAttachments";
+export { ChatComposer, type ChatComposerProps } from "./styled/chat/ChatComposer";
+export { ChatThreadPanel, type ChatThreadPanelProps } from "./styled/chat/ChatThreadPanel";
+export { MessageBubble, type MessageBubbleProps } from "./styled/chat/MessageBubble";
+export { NewDmDialog, type NewDmDialogProps } from "./styled/chat/NewDmDialog";
+export { AiAgentWidget, type AiAgentWidgetProps } from "./styled/AiAgentWidget";
+export { Markdown } from "./styled/Markdown";
+export { useAiAgent, type AiAgentMessage } from "./headless/agent/useAiAgent";
+export { InvoicePayment, type InvoicePaymentProps } from "./styled/InvoicePayment";
+export { PaymentLinkPayment, type PaymentLinkPaymentProps } from "./styled/PaymentLinkPayment";
+export { BlogList, type BlogListProps } from "./styled/BlogList";
+export { BlogPost, type BlogPostProps } from "./styled/BlogPost";
+export { BlogCategory, type BlogCategoryProps } from "./styled/BlogCategory";
+export { PodcastList, type PodcastListProps } from "./styled/PodcastList";
+export { PodcastShow, type PodcastShowProps } from "./styled/PodcastShow";
+export { PodcastEpisode, type PodcastEpisodeProps } from "./styled/PodcastEpisode";
+export { ReplayList, type ReplayListProps } from "./styled/ReplayList";
+export { ConfirmSubscription, type ConfirmSubscriptionProps } from "./styled/ConfirmSubscription";
+export { LeadMagnet, type LeadMagnetProps } from "./styled/LeadMagnet";
+export { CohortPage, type CohortPageProps } from "./styled/CohortPage";
+export { CourseAccess, type CourseAccessProps } from "./styled/CourseAccess";
+export { DonationPage, type DonationPageProps } from "./styled/DonationPage";
+export { ReviewsSection, StarRow, type ReviewsSectionProps } from "./styled/ReviewsSection";
+export { ReviewForm, type ReviewFormProps } from "./styled/ReviewForm";
+export { PriceDisplay, priceTaxCaption, summarizeTaxQuote, type PriceDisplayProps } from "./format/PriceDisplay";
+export { usePricesIncludeTax } from "../data/queries/useWebsite";
+
+// PWA (installable code sites) — SW registration + install/push UX (Tier 2).
+export { PwaRegistration, type PwaRegistrationProps } from "./styled/PwaRegistration";
+export { InstallBanner, type InstallBannerProps } from "./styled/InstallBanner";
+// The single root component — providers + audio + analytics + PWA + consent in one.
+export { TribeNestApp, type TribeNestAppProps } from "./shell/TribeNestApp";
+export { PushOptIn, type PushOptInProps } from "./styled/PushOptIn";
+
+// Community (forum) styled blocks.
+export * from "./styled/community";
+
+// Work (project management) client-portal styled blocks.
+export * from "./styled/work";
+
+// Unified member home (`/i/members`) styled blocks.
+export * from "./styled/members";

package/src/ui/payment/ForgePaymentProvider.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { ForgeStripePayment } from "./ForgeStripePayment";
+
+/**
+ * What a payment block hands its renderer. Forge ships a built-in Stripe
+ * renderer (`ForgeStripePayment`, wired to the tenant's runtime `useSiteConfig`)
+ * and uses it by default; an app can still register its own UI (a different
+ * provider, custom styling) via `<ForgePaymentProvider>`.
+ */
+export interface PaymentRenderProps {
+  clientSecret?: string;
+  returnUrl: string;
+  amount: number;
+  currency?: string;
+  /** "redirect" (default) or "manual" (confirm in place, drive result via callbacks). */
+  mode?: "redirect" | "manual";
+  onSucceeded?: () => void;
+  onFailed?: (message?: string) => void;
+}
+
+export type PaymentRenderer = (props: PaymentRenderProps) => ReactNode;
+
+const PaymentRendererContext = createContext<PaymentRenderer | null>(null);
+
+/**
+ * OPTIONAL override — register a custom payment UI so every payment block
+ * (Donation, Offer, Checkout, …) uses it instead of Forge's built-in Stripe
+ * renderer. Most sites don't need this: leave it out and payment works out of
+ * the box via `ForgeStripePayment`.
+ */
+export function ForgePaymentProvider({ render, children }: { render: PaymentRenderer; children: ReactNode }) {
+  return <PaymentRendererContext.Provider value={render}>{children}</PaymentRendererContext.Provider>;
+}
+
+/** Forge's built-in default: the self-contained Stripe renderer. */
+const builtInStripeRenderer: PaymentRenderer = (props) => <ForgeStripePayment {...props} />;
+
+/**
+ * The payment renderer used by the payment blocks: the app's registered one if
+ * present, otherwise Forge's built-in Stripe renderer. Never null — payment
+ * always has a UI without any app wiring.
+ */
+export function usePaymentRenderer(): PaymentRenderer {
+  return useContext(PaymentRendererContext) ?? builtInStripeRenderer;
+}