@tribe-nest/forge 3.60.0 → 3.63.0

package/src/ui/styled/portal/PortalActivity.tsx

@@ -0,0 +1,167 @@
+import {
+  CalendarCheck,
+  CheckCircle2,
+  FileCheck2,
+  FileSignature,
+  MessageSquare,
+  Receipt,
+  ShoppingBag,
+  Stamp,
+  type LucideIcon,
+} from "lucide-react";
+import { useForgeLocale, useForgeT, type ForgeT } from "../../../i18n";
+import { internalPath } from "../../../runtime/pages";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import { usePortalActivity, type PortalActivityItem, type PortalActivityKind } from "../../headless/portal/usePortal";
+import { Loading } from "../Loading";
+import { PortalEmpty, PortalHeading, PortalLink, PortalList, usePortalButtons } from "./shared";
+
+const ICONS: Record<PortalActivityKind, LucideIcon> = {
+  invoice_issued: Receipt,
+  invoice_paid: CheckCircle2,
+  document_sent: FileSignature,
+  document_signed: FileCheck2,
+  milestone_completed: CheckCircle2,
+  comment_added: MessageSquare,
+  approval_requested: Stamp,
+  approval_decided: Stamp,
+  order_placed: ShoppingBag,
+  booking_confirmed: CalendarCheck,
+  message_received: MessageSquare,
+};
+
+/** One sentence per event, written for the person reading it. */
+export function activitySentence(item: PortalActivityItem, tr: ForgeT): string {
+  const vars = { title: item.title };
+  switch (item.kind) {
+    case "invoice_issued":
+      return tr("forge.portal_activity.invoice_issued", vars);
+    case "invoice_paid":
+      return tr("forge.portal_activity.invoice_paid", vars);
+    case "document_sent":
+      return tr("forge.portal_activity.document_sent", vars);
+    case "document_signed":
+      return tr("forge.portal_activity.document_signed", vars);
+    case "milestone_completed":
+      return tr("forge.portal_activity.milestone_completed", vars);
+    case "comment_added":
+      return tr("forge.portal_activity.comment_added", vars);
+    case "approval_requested":
+      return tr("forge.portal_activity.approval_requested", vars);
+    case "approval_decided":
+      return item.detail === "changes_requested"
+        ? tr("forge.portal_activity.approval_changes", vars)
+        : tr("forge.portal_activity.approval_approved", vars);
+    case "order_placed":
+      return tr("forge.portal_activity.order_placed", vars);
+    case "booking_confirmed":
+      return tr("forge.portal_activity.booking_confirmed", vars);
+    case "message_received":
+      return tr("forge.portal_activity.message_received", vars);
+  }
+}
+
+/** Where an event leads: the thing it happened to. */
+export function activityHref(item: PortalActivityItem): string {
+  switch (item.kind) {
+    case "invoice_issued":
+    case "invoice_paid":
+      return internalPath("invoice/$invoiceId", { invoiceId: item.entityId });
+    case "document_sent":
+    case "document_signed":
+      return internalPath("account/documents");
+    case "order_placed":
+      return internalPath("account/orders");
+    case "booking_confirmed":
+      return internalPath("account/bookings");
+    case "message_received":
+      return internalPath("account/messages");
+    default:
+      return item.projectId
+        ? internalPath("account/projects/$projectId", { projectId: item.projectId })
+        : internalPath("account/projects");
+  }
+}
+
+/** "3 hours ago", "yesterday", in the site's language. */
+export function useRelativeTime() {
+  const locale = useForgeLocale();
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+  return (iso: string) => {
+    const seconds = Math.round((Date.parse(iso) - Date.now()) / 1000);
+    const abs = Math.abs(seconds);
+    if (abs < 60) return rtf.format(0, "minute");
+    if (abs < 3600) return rtf.format(Math.round(seconds / 60), "minute");
+    if (abs < 86400) return rtf.format(Math.round(seconds / 3600), "hour");
+    if (abs < 86400 * 30) return rtf.format(Math.round(seconds / 86400), "day");
+    return new Date(iso).toLocaleDateString(locale, { day: "numeric", month: "short", year: "numeric" });
+  };
+}
+
+export function ActivityRows({ items }: { items: PortalActivityItem[] }) {
+  const t = useThemeTokens();
+  const tr = useForgeT();
+  const ago = useRelativeTime();
+  return (
+    <PortalList>
+      {items.map((item) => {
+        const Icon = ICONS[item.kind];
+        return (
+          <li key={item.id} data-testid="portal-activity-item" style={{ borderBottom: `1px solid ${t.border}` }}>
+            <PortalLink
+              href={activityHref(item)}
+              className="fg:flex fg:items-start fg:gap-3 fg:py-3"
+              style={{ color: t.text, textDecoration: "none" }}
+            >
+              <Icon size={16} aria-hidden style={{ marginTop: 3, color: t.muted, flexShrink: 0 }} />
+              <span className="fg:min-w-0 fg:flex-1">
+                <span style={{ display: "block", fontSize: 15, lineHeight: 1.45 }}>{activitySentence(item, tr)}</span>
+                {item.projectName ? (
+                  <span style={{ display: "block", fontSize: 13, color: t.muted }}>{item.projectName}</span>
+                ) : null}
+              </span>
+              <time dateTime={item.occurredAt} style={{ fontSize: 13, color: t.muted, whiteSpace: "nowrap" }}>
+                {ago(item.occurredAt)}
+              </time>
+            </PortalLink>
+          </li>
+        );
+      })}
+    </PortalList>
+  );
+}
+
+/** The whole timeline (`/i/account/activity`). */
+export function PortalActivity() {
+  const tr = useForgeT();
+  const buttons = usePortalButtons();
+  const { data, isLoading, fetchNextPage, hasNextPage, isFetchingNextPage } = usePortalActivity(30);
+  const items = data?.pages.flatMap((p) => p.items) ?? [];
+
+  return (
+    <div data-testid="portal-activity">
+      <PortalHeading title={tr("forge.portal_activity.title")} />
+      {isLoading ? (
+        <Loading />
+      ) : items.length === 0 ? (
+        <PortalEmpty title={tr("forge.portal_activity.empty_title")} body={tr("forge.portal_activity.empty_body")} />
+      ) : (
+        <>
+          <ActivityRows items={items} />
+          {hasNextPage ? (
+            <div style={{ marginTop: 20 }}>
+              <button
+                type="button"
+                style={buttons.quiet}
+                disabled={isFetchingNextPage}
+                onClick={() => void fetchNextPage()}
+              >
+                {isFetchingNextPage ? tr("forge.portal_activity.loading") : tr("forge.portal_activity.load_more")}
+              </button>
+            </div>
+          ) : null}
+        </>
+      )}
+    </div>
+  );
+}

package/src/ui/styled/portal/PortalBilling.tsx

@@ -0,0 +1,197 @@
+import { useState } from "react";
+import { useForgeT } from "../../../i18n";
+import { internalPath } from "../../../runtime/pages";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import { usePortalDocuments, usePortalInvoices, type PortalInvoice } from "../../headless/portal/usePortal";
+import { Loading } from "../Loading";
+import { PortalEmpty, PortalHeading, PortalLink, PortalList, PortalRow, portalMoney, usePortal, usePortalButtons } from "./shared";
+
+/** An invoice still owed. Paid, cancelled and refunded ones are history. */
+const OPEN_STATUSES = new Set(["sent", "overdue", "initiated_payment", "payment_failed", "viewed"]);
+
+/**
+ * Every invoice the creator has sent this person (`/i/account/invoices`).
+ *
+ * Owed invoices first, with the amount and the due date on the row and a Pay
+ * button; settled ones below, read-only. Each opens the hosted invoice page,
+ * which is where paying and the PDF already live.
+ */
+export function PortalInvoices() {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const [filter, setFilter] = useState<"open" | "all">("open");
+  const { data, isLoading } = usePortalInvoices("all");
+  const invoices = data?.data ?? [];
+  const open = invoices.filter((inv) => OPEN_STATUSES.has(inv.status));
+  const shown = filter === "open" ? open : invoices;
+
+  return (
+    <div data-testid="portal-invoices">
+      <PortalHeading
+        title={tr("forge.portal_billing.invoices_title")}
+        lead={
+          open.length > 0
+            ? tr("forge.portal_billing.invoices_lead_open", { count: open.length })
+            : invoices.length > 0
+              ? tr("forge.portal_billing.invoices_lead_settled")
+              : undefined
+        }
+      />
+      {isLoading ? (
+        <Loading />
+      ) : invoices.length === 0 ? (
+        <PortalEmpty title={tr("forge.portal_billing.invoices_empty_title")} body={tr("forge.portal_billing.invoices_empty_body")} />
+      ) : (
+        <>
+          <div role="tablist" aria-label={tr("forge.portal_billing.filter_label")} className="fg:mb-4 fg:flex fg:gap-5">
+            {(["open", "all"] as const).map((key) => (
+              <button
+                key={key}
+                type="button"
+                role="tab"
+                aria-selected={filter === key}
+                onClick={() => setFilter(key)}
+                style={{
+                  padding: "4px 0",
+                  background: "transparent",
+                  border: "none",
+                  borderBottom: `2px solid ${filter === key ? t.primary : "transparent"}`,
+                  color: filter === key ? t.text : t.muted,
+                  fontWeight: filter === key ? 600 : 500,
+                  fontFamily: t.fontFamily,
+                  fontSize: 14,
+                  cursor: "pointer",
+                }}
+              >
+                {key === "open"
+                  ? tr("forge.portal_billing.filter_open", { count: open.length })
+                  : tr("forge.portal_billing.filter_all", { count: invoices.length })}
+              </button>
+            ))}
+          </div>
+          {shown.length === 0 ? (
+            <PortalEmpty title={tr("forge.portal_billing.nothing_owed")} />
+          ) : (
+            <PortalList>
+              {shown.map((inv) => (
+                <InvoiceRow key={inv.id} invoice={inv} />
+              ))}
+            </PortalList>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function InvoiceRow({ invoice }: { invoice: PortalInvoice }) {
+  const t = useThemeTokens();
+  const tr = useForgeT();
+  const { formatDate } = usePortal();
+  const buttons = usePortalButtons();
+  const owed = OPEN_STATUSES.has(invoice.status);
+  const overdue = invoice.status === "overdue";
+  // Literal keys, so the translation spec can see every one of them.
+  const statusLabel: Record<string, string> = {
+    sent: tr("forge.portal_billing.status_sent"),
+    viewed: tr("forge.portal_billing.status_sent"),
+    overdue: tr("forge.portal_billing.status_overdue"),
+    initiated_payment: tr("forge.portal_billing.status_processing"),
+    payment_failed: tr("forge.portal_billing.status_failed"),
+    paid: tr("forge.portal_billing.status_paid"),
+    cancelled: tr("forge.portal_billing.status_cancelled"),
+    refunded: tr("forge.portal_billing.status_refunded"),
+  };
+  const href = internalPath("invoice/$invoiceId", { invoiceId: invoice.id });
+
+  return (
+    <PortalRow testId="portal-invoice">
+      <div className="fg:min-w-0 fg:flex-1">
+        <p style={{ margin: 0, fontWeight: 600 }}>{invoice.invoiceNumber}</p>
+        <p className="fg:flex fg:flex-wrap fg:gap-x-3" style={{ margin: "2px 0 0", fontSize: 13, color: t.muted }}>
+          <span style={overdue || invoice.status === "payment_failed" ? { color: t.text, fontWeight: 600 } : undefined}>
+            {statusLabel[invoice.status] ?? invoice.status}
+          </span>
+          {owed && invoice.dueDate ? (
+            <span>{tr("forge.portal_billing.due_on", { date: formatDate(invoice.dueDate) })}</span>
+          ) : null}
+          {invoice.paidAt ? <span>{tr("forge.portal_billing.paid_on", { date: formatDate(invoice.paidAt) })}</span> : null}
+          {invoice.projectName ? <span>{invoice.projectName}</span> : null}
+        </p>
+      </div>
+      <span style={{ fontWeight: 600, fontVariantNumeric: "tabular-nums" }}>
+        {portalMoney(invoice.total, invoice.currency)}
+      </span>
+      <PortalLink href={href} style={owed ? buttons.primary : buttons.quiet}>
+        {owed ? tr("forge.portal_billing.pay") : tr("forge.portal_billing.view")}
+      </PortalLink>
+    </PortalRow>
+  );
+}
+
+/**
+ * Documents sent to this person (`/i/account/documents`): the ones waiting for
+ * their signature first, then everything already signed or closed. Each opens
+ * the signing page, which keeps its own email check.
+ */
+export function PortalDocuments() {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const { formatDate } = usePortal();
+  const buttons = usePortalButtons();
+  const { data: documents, isLoading } = usePortalDocuments();
+  const waiting = (documents ?? []).filter((d) => d.needsAction);
+  const rest = (documents ?? []).filter((d) => !d.needsAction);
+
+  const row = (doc: NonNullable<typeof documents>[number]) => (
+    <PortalRow key={doc.documentId} testId="portal-document">
+      <div className="fg:min-w-0 fg:flex-1">
+        <p style={{ margin: 0, fontWeight: 600 }}>{doc.title}</p>
+        <p className="fg:flex fg:flex-wrap fg:gap-x-3" style={{ margin: "2px 0 0", fontSize: 13, color: t.muted }}>
+          {doc.completedAt ? (
+            <span>{tr("forge.portal_billing.signed_on", { date: formatDate(doc.completedAt) })}</span>
+          ) : (
+            <span>{tr("forge.portal_billing.sent_on", { date: formatDate(doc.sentAt) })}</span>
+          )}
+          {doc.needsAction && doc.expiresAt ? (
+            <span style={{ color: t.text }}>{tr("forge.portal_billing.expires_on", { date: formatDate(doc.expiresAt) })}</span>
+          ) : null}
+        </p>
+      </div>
+      <PortalLink
+        href={internalPath("documents/$token", { token: doc.token })}
+        style={doc.needsAction ? buttons.primary : buttons.quiet}
+      >
+        {doc.needsAction ? tr("forge.portal_billing.review_and_sign") : tr("forge.portal_billing.open")}
+      </PortalLink>
+    </PortalRow>
+  );
+
+  return (
+    <div data-testid="portal-documents">
+      <PortalHeading
+        title={tr("forge.portal_billing.documents_title")}
+        lead={waiting.length > 0 ? tr("forge.portal_billing.documents_lead_waiting", { count: waiting.length }) : undefined}
+      />
+      {isLoading ? (
+        <Loading />
+      ) : !documents || documents.length === 0 ? (
+        <PortalEmpty title={tr("forge.portal_billing.documents_empty_title")} body={tr("forge.portal_billing.documents_empty_body")} />
+      ) : (
+        <>
+          {waiting.length > 0 ? <PortalList style={{ marginBottom: 32 }}>{waiting.map(row)}</PortalList> : null}
+          {rest.length > 0 ? (
+            <>
+              {waiting.length > 0 ? (
+                <h2 style={{ margin: "0 0 8px", fontSize: 18, fontWeight: 600, fontFamily: t.headingFontFamily }}>
+                  {tr("forge.portal_billing.documents_done")}
+                </h2>
+              ) : null}
+              <PortalList>{rest.map(row)}</PortalList>
+            </>
+          ) : null}
+        </>
+      )}
+    </div>
+  );
+}

package/src/ui/styled/portal/PortalFiles.tsx

@@ -0,0 +1,279 @@
+import { useState, type ReactNode } from "react";
+import { FileSignature, FileText, Paperclip, Receipt, ShoppingBag } from "lucide-react";
+import { useForgeT } from "../../../i18n";
+import { useForge } from "../../../provider/ForgeProvider";
+import { internalPath } from "../../../runtime/pages";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import { useWorkOpenSharedDocument } from "../../headless/work/useWorkPortal";
+import {
+  usePortalFiles,
+  type PortalFile,
+  type PortalFileSource,
+  type PortalFileSourceFilter,
+} from "../../headless/portal/usePortalFiles";
+import { Loading } from "../Loading";
+import { PortalEmpty, PortalHeading, PortalLink, PortalList, PortalRow, usePortal, usePortalButtons } from "./shared";
+
+const FILTERS: PortalFileSourceFilter[] = ["all", "purchase", "project", "task", "document", "invoice"];
+
+const ICONS: Record<PortalFileSource, typeof FileText> = {
+  project: FileText,
+  task: Paperclip,
+  document: FileSignature,
+  invoice: Receipt,
+  purchase: ShoppingBag,
+};
+
+/** "1.2 MB". Sizes are bytes; nothing here is worth a locale-aware unit. */
+export function formatFileSize(bytes: number | null): string | null {
+  if (bytes == null || !Number.isFinite(bytes) || bytes <= 0) return null;
+  const units = ["B", "KB", "MB", "GB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+
+/**
+ * Every file this person has with the creator (`/i/account/files`): files
+ * shared on their projects, attachments on their tasks, signed documents,
+ * invoice PDFs and the downloads they paid for, newest first, with a filter
+ * per kind.
+ *
+ * Nothing on the page holds an address it was not given for that purpose: a
+ * shared project file asks for a 60-second link on the click, and a signed
+ * document or invoice downloads through the endpoint that checks it.
+ */
+export function PortalFiles() {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const buttons = usePortalButtons();
+  const [filter, setFilter] = useState<PortalFileSourceFilter>("all");
+  const { data, isLoading, hasNextPage, fetchNextPage, isFetchingNextPage } = usePortalFiles(filter);
+  const files = data?.pages.flatMap((p) => p.data) ?? [];
+
+  // Literal keys, so the translation spec can see every one of them.
+  const filterLabel: Record<PortalFileSourceFilter, string> = {
+    all: tr("forge.portal_files.filter_all"),
+    project: tr("forge.portal_files.filter_project"),
+    task: tr("forge.portal_files.filter_task"),
+    document: tr("forge.portal_files.filter_document"),
+    invoice: tr("forge.portal_files.filter_invoice"),
+    purchase: tr("forge.portal_files.filter_purchase"),
+  };
+
+  // With nothing at all, the tabs would only filter an empty list.
+  const nothingAtAll = !isLoading && filter === "all" && files.length === 0;
+
+  return (
+    <div data-testid="portal-files">
+      <PortalHeading title={tr("forge.portal_files.title")} />
+      {nothingAtAll ? (
+        <PortalEmpty title={tr("forge.portal_files.empty_title")} body={tr("forge.portal_files.empty_body")} />
+      ) : (
+        <>
+          <div
+            role="tablist"
+            aria-label={tr("forge.portal_files.filter_label")}
+            className="fg:mb-4 fg:flex fg:flex-wrap fg:gap-x-5 fg:gap-y-2"
+          >
+            {FILTERS.map((key) => (
+              <button
+                key={key}
+                type="button"
+                role="tab"
+                aria-selected={filter === key}
+                data-testid={`portal-files-filter-${key}`}
+                onClick={() => setFilter(key)}
+                style={{
+                  padding: "4px 0",
+                  background: "transparent",
+                  border: "none",
+                  borderBottom: `2px solid ${filter === key ? t.primary : "transparent"}`,
+                  color: filter === key ? t.text : t.muted,
+                  fontWeight: filter === key ? 600 : 500,
+                  fontFamily: t.fontFamily,
+                  fontSize: 14,
+                  cursor: "pointer",
+                }}
+              >
+                {filterLabel[key]}
+              </button>
+            ))}
+          </div>
+          {isLoading ? (
+            <Loading />
+          ) : files.length === 0 ? (
+            <PortalEmpty title={tr("forge.portal_files.filter_empty")} />
+          ) : (
+            <>
+              <PortalList>
+                {files.map((file) => (
+                  <FileRow key={`${file.source}:${file.id}`} file={file} />
+                ))}
+              </PortalList>
+              {hasNextPage ? (
+                <div className="fg:mt-6 fg:flex fg:justify-center">
+                  <button
+                    type="button"
+                    data-testid="portal-files-more"
+                    onClick={() => void fetchNextPage()}
+                    disabled={isFetchingNextPage}
+                    style={{ ...buttons.quiet, opacity: isFetchingNextPage ? 0.6 : 1 }}
+                  >
+                    {tr("forge.portal_files.show_more")}
+                  </button>
+                </div>
+              ) : null}
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function FileRow({ file }: { file: PortalFile }) {
+  const t = useThemeTokens();
+  const tr = useForgeT();
+  const { formatDate } = usePortal();
+  const [error, setError] = useState<string | null>(null);
+  const Icon = ICONS[file.source];
+  const size = formatFileSize(file.size);
+  const title = file.source === "invoice" ? tr("forge.portal_files.invoice_title", { number: file.title }) : file.title;
+
+  return (
+    <PortalRow testId="portal-file">
+      <span
+        aria-hidden
+        className="fg:flex fg:h-9 fg:w-9 fg:shrink-0 fg:items-center fg:justify-center"
+        style={{ borderRadius: t.cornerRadius, border: `1px solid ${t.border}`, color: t.muted }}
+      >
+        <Icon size={16} />
+      </span>
+      <div className="fg:min-w-0 fg:flex-1">
+        <p className="fg:truncate" style={{ margin: 0, fontWeight: 600 }} title={file.filename ?? undefined}>
+          {title}
+        </p>
+        <p className="fg:flex fg:flex-wrap fg:gap-x-3" style={{ margin: "2px 0 0", fontSize: 13, color: t.muted }}>
+          {file.projectName ? <span>{file.projectName}</span> : null}
+          <span>{formatDate(file.createdAt)}</span>
+          {size ? <span>{size}</span> : null}
+        </p>
+        {error ? (
+          <p role="alert" style={{ margin: "4px 0 0", fontSize: 13, color: t.text, fontWeight: 600 }}>
+            {error}
+          </p>
+        ) : null}
+      </div>
+      <FileAction file={file} onError={setError} />
+    </PortalRow>
+  );
+}
+
+function FileAction({ file, onError }: { file: PortalFile; onError: (message: string | null) => void }) {
+  const tr = useForgeT();
+  const { apiUrl } = useForge();
+  const buttons = usePortalButtons();
+  const api = (apiUrl ?? "").replace(/\/$/, "");
+  const external = (href: string, label: ReactNode, download = false) => (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      download={download || undefined}
+      data-testid="portal-file-action"
+      style={buttons.quiet}
+    >
+      {label}
+    </a>
+  );
+
+  switch (file.open.kind) {
+    case "project_document":
+      return (
+        <ProjectDocumentAction projectId={file.open.projectId} documentId={file.open.documentId} onError={onError} />
+      );
+    case "task_attachment":
+      return external(file.open.url, tr("forge.portal_files.open"));
+    case "signed_document":
+      return api ? (
+        external(
+          `${api}/public/documents/${encodeURIComponent(file.open.token)}/download`,
+          tr("forge.portal_files.download"),
+          true,
+        )
+      ) : (
+        <PortalLink href={internalPath("documents/$token", { token: file.open.token })} style={buttons.quiet}>
+          {tr("forge.portal_files.open")}
+        </PortalLink>
+      );
+    case "invoice_pdf":
+      return api ? (
+        external(
+          `${api}/public/invoices/${encodeURIComponent(file.open.invoiceId)}/pdf`,
+          tr("forge.portal_files.download"),
+          true,
+        )
+      ) : (
+        <PortalLink href={internalPath("invoice/$invoiceId", { invoiceId: file.open.invoiceId })} style={buttons.quiet}>
+          {tr("forge.portal_files.open")}
+        </PortalLink>
+      );
+    case "purchase_download":
+      // The download page, never a file address: it signs each file on the
+      // click, after checking it is this person's.
+      return (
+        <PortalLink
+          href={internalPath("downloads/$token", { token: file.open.token })}
+          data-testid="portal-file-action"
+          style={buttons.quiet}
+        >
+          {tr("forge.portal_files.download")}
+        </PortalLink>
+      );
+  }
+}
+
+/**
+ * A shared project file has no address until the click asks for one: a
+ * sixty-second signed read, minted and audited per open, followed once.
+ */
+function ProjectDocumentAction({
+  projectId,
+  documentId,
+  onError,
+}: {
+  projectId: string;
+  documentId: string;
+  onError: (message: string | null) => void;
+}) {
+  const tr = useForgeT();
+  const buttons = usePortalButtons();
+  const open = useWorkOpenSharedDocument(projectId);
+
+  const onClick = async () => {
+    onError(null);
+    try {
+      const { url } = await open.mutateAsync(documentId);
+      window.open(url, "_blank", "noopener");
+    } catch {
+      onError(tr("forge.portal_files.open_error"));
+    }
+  };
+
+  return (
+    <button
+      type="button"
+      data-testid="portal-file-action"
+      onClick={() => void onClick()}
+      disabled={open.isPending}
+      style={{ ...buttons.quiet, cursor: open.isPending ? "wait" : "pointer", opacity: open.isPending ? 0.6 : 1 }}
+    >
+      {tr("forge.portal_files.open")}
+    </button>
+  );
+}