@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/styled/app/AppHomeMark.tsx

@@ -0,0 +1,66 @@
+import { Home } from "lucide-react";
+import { useAppHomeHref, useSiteApp } from "../../../data/queries/useSiteApp";
+import { useForgeT } from "../../../i18n";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+
+export interface AppHomeMarkProps {
+  /** SPA navigation; a plain click otherwise follows the link. */
+  go?: (href: string) => void;
+  /** Side of the square mark, in pixels. */
+  size: number;
+  testId: string;
+  /** Draw the app's name beside the mark. */
+  withName?: boolean;
+}
+
+/**
+ * The way back to the site app's Home from a screen with its own shell (a
+ * community, the client portal). It follows the Home rule (`useAppHomeHref`):
+ * the creator's own start page when they chose one, `/i/app` otherwise.
+ *
+ * The app's icon when it has one, else a house.
+ */
+export function AppHomeMark({ go, size, testId, withName = false }: AppHomeMarkProps) {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const href = useAppHomeHref();
+  const { data: app } = useSiteApp();
+  const name = withName ? app?.appName : null;
+
+  return (
+    <a
+      href={href}
+      data-testid={testId}
+      aria-label={name ? undefined : tr("forge.app_home.mark_label")}
+      onClick={(event) => {
+        if (!go || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        event.preventDefault();
+        go(href);
+      }}
+      className="fg:inline-flex fg:min-w-0 fg:shrink-0 fg:items-center fg:gap-2"
+      style={{ color: t.text, textDecoration: "none" }}
+    >
+      <span
+        className="fg:inline-flex fg:shrink-0 fg:items-center fg:justify-center"
+        style={{
+          width: size,
+          height: size,
+          borderRadius: Math.round(size * 0.28),
+          border: app?.iconUrl ? "none" : `1px solid ${t.border}`,
+          overflow: "hidden",
+        }}
+      >
+        {app?.iconUrl ? (
+          <img src={app.iconUrl} alt="" style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+        ) : (
+          <Home size={Math.round(size * 0.5)} aria-hidden />
+        )}
+      </span>
+      {name ? (
+        <span className="fg:truncate" style={{ fontSize: 15, fontWeight: 600 }}>
+          {name}
+        </span>
+      ) : null}
+    </a>
+  );
+}

package/src/ui/styled/app/AppPrompts.tsx

@@ -0,0 +1,464 @@
+import { useContext, useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { Bell, LayoutGrid, MessageCircle, PlusSquare, Share, Smartphone } from "lucide-react";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import { useForgeT } from "../../../i18n";
+import { useForge } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { useSiteApp } from "../../../data/queries/useSiteApp";
+import {
+  captureInstallPrompt,
+  hasStoredInstallPrompt,
+  isIOSDevice,
+  isStandaloneDisplay,
+  promptStoredInstall,
+  subscribeInstallPrompt,
+} from "../../../data/queries/usePWA";
+import {
+  useNotificationMatrix,
+  usePushSubscription,
+  useUpdateNotificationMatrix,
+} from "../../../data/queries/useNotifications";
+import {
+  APP_PUSH_CATEGORIES,
+  clearPendingAppInstall,
+  decideAppInstall,
+  decideAppPush,
+  pushPreferencePatch,
+  readInstallDismissedAt,
+  readPendingAppInstall,
+  readPushAnswer,
+  rememberInstallDismissed,
+  rememberPushAnswer,
+  subscribeAppInstallRequests,
+  type AppInstallContext,
+  type AppInstallMode,
+  type AppPushCategoryKey,
+} from "../../headless/siteApp/appPrompts";
+import { CommunitySheet } from "../communities/shared";
+import { shareRuntimeValue } from "../../../runtime/registry";
+
+/** Literal keys, so the translation spec can see every one of them. */
+const INSTALL_TITLE_KEYS: Record<AppInstallContext, string> = {
+  joined_community: "forge.app_prompts.install_title_joined",
+  purchase: "forge.app_prompts.install_title_purchase",
+  booking: "forge.app_prompts.install_title_booking",
+  invite_accepted: "forge.app_prompts.install_title_invite",
+};
+
+const PUSH_CATEGORY_KEYS: Record<AppPushCategoryKey, string> = {
+  messages: "forge.app_prompts.push_category_messages",
+  community: "forge.app_prompts.push_category_community",
+  events: "forge.app_prompts.push_category_events",
+};
+
+// ---- One host per page ---------------------------------------------------------
+//
+// `<AppPrompts />` is mounted by the hosted pages' frame AND by every
+// `<AppBar />`, so a page can easily hold two. Only the first mounted one
+// draws; the rest wait, and take over if it unmounts.
+
+// Shared through the runtime registry, because the site's copy of Forge (an
+// `<AppBar />` on a custom start page) and the hosted pages' copy can both mount one.
+const hosts = () =>
+  shareRuntimeValue<{ owner: symbol | null; listeners: Set<() => void> }>("state:app-prompts-host", () => ({
+    owner: null,
+    listeners: new Set(),
+  }));
+
+function useIsPromptHost(): boolean {
+  const id = useRef(Symbol("app-prompts")).current;
+  const [isHost, setIsHost] = useState(false);
+  useEffect(() => {
+    const state = hosts();
+    const claim = () => {
+      if (!state.owner) state.owner = id;
+      setIsHost(state.owner === id);
+    };
+    claim();
+    state.listeners.add(claim);
+    return () => {
+      state.listeners.delete(claim);
+      if (state.owner === id) {
+        state.owner = null;
+        state.listeners.forEach((listener) => listener());
+      }
+    };
+  }, [id]);
+  return isHost;
+}
+
+/**
+ * The site app's two prompts: install, after a moment worth coming back for
+ * (`requestAppInstall`), and notifications, on the first launch of the
+ * installed app. Renders nothing until one is due. Mount it once anywhere in
+ * the page; `<AppBar />` already includes it, and so does every hosted `/i/`
+ * page.
+ */
+export function AppPrompts() {
+  const isHost = useIsPromptHost();
+  if (!isHost) return null;
+  return (
+    <>
+      <AppInstallPrompt />
+      <AppPushPrompt />
+    </>
+  );
+}
+
+// ---- Install ------------------------------------------------------------------
+
+function AppInstallPrompt() {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const app = useSiteApp();
+  const [tick, setTick] = useState(0);
+  const [shown, setShown] = useState<{ context: AppInstallContext; mode: AppInstallMode } | null>(null);
+
+  useEffect(() => {
+    captureInstallPrompt();
+    const bump = () => setTick((n) => n + 1);
+    const offRequests = subscribeAppInstallRequests(bump);
+    const offPrompt = subscribeInstallPrompt(bump);
+    return () => {
+      offRequests();
+      offPrompt();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (shown) return;
+    const request = readPendingAppInstall();
+    if (!request) return;
+    // Wait for the website's answer; until it arrives the setting is unknown.
+    // An unknown host (a preview) answers 404, which settles it as "off".
+    if (!app.data && !app.isError) return;
+    const mode = decideAppInstall({
+      installPrompt: app.data?.installPrompt,
+      isStandalone: isStandaloneDisplay(),
+      isIOS: isIOSDevice(),
+      hasNativePrompt: hasStoredInstallPrompt(),
+      dismissedAt: readInstallDismissedAt(),
+      now: Date.now(),
+    });
+    // Asked once: shown now or not at all, so a later page does not raise it out of nowhere.
+    clearPendingAppInstall();
+    if (mode) setShown({ context: request.context, mode });
+  }, [tick, shown, app.data, app.isError]);
+
+  if (!shown) return null;
+  const name = app.data?.shortName || app.data?.appName || tr("forge.app_prompts.this_app");
+
+  const notNow = () => {
+    rememberInstallDismissed();
+    setShown(null);
+  };
+
+  return (
+    <CommunitySheet
+      open
+      onOpenChange={(open) => {
+        if (!open) notNow();
+      }}
+      testId={`app-install-${shown.mode}`}
+      title={tr(INSTALL_TITLE_KEYS[shown.context])}
+      closeLabel={tr("forge.app_prompts.aria_close")}
+    >
+      <div className="fg:flex fg:flex-col fg:gap-5" data-context={shown.context}>
+        <AppIdentity iconUrl={app.data?.iconUrl ?? null} name={name}>
+          {shown.mode === "ios" ? tr("forge.app_prompts.ios_lead") : tr("forge.app_prompts.install_lead", { app: name })}
+        </AppIdentity>
+
+        {shown.mode === "ios" ? (
+          <ol className="fg:m-0 fg:flex fg:list-none fg:flex-col fg:gap-2 fg:p-0" data-testid="app-install-ios-steps">
+            <IosStep n={1} icon={<Share size={20} aria-hidden />}>
+              {tr("forge.app_prompts.ios_step_share")}
+            </IosStep>
+            <IosStep n={2} icon={<PlusSquare size={20} aria-hidden />}>
+              {tr("forge.app_prompts.ios_step_add")}
+            </IosStep>
+          </ol>
+        ) : (
+          <ul className="fg:m-0 fg:flex fg:list-none fg:flex-col fg:gap-3 fg:p-0">
+            <Benefit icon={<Smartphone size={18} aria-hidden />}>{tr("forge.app_prompts.benefit_one_tap")}</Benefit>
+            <Benefit icon={<Bell size={18} aria-hidden />}>{tr("forge.app_prompts.benefit_notifications")}</Benefit>
+            <Benefit icon={<LayoutGrid size={18} aria-hidden />}>{tr("forge.app_prompts.benefit_one_place")}</Benefit>
+          </ul>
+        )}
+
+        <div className="fg:flex fg:flex-col fg:gap-2">
+          {shown.mode === "native" ? (
+            <button
+              type="button"
+              data-testid="app-install-accept"
+              style={primaryButton(t)}
+              onClick={() => {
+                void promptStoredInstall();
+                setShown(null);
+              }}
+            >
+              {tr("forge.app_prompts.install_accept")}
+            </button>
+          ) : null}
+          <button type="button" data-testid="app-install-not-now" style={quietButton(t)} onClick={notNow}>
+            {tr("forge.app_prompts.not_now")}
+          </button>
+        </div>
+      </div>
+    </CommunitySheet>
+  );
+}
+
+// ---- Notifications --------------------------------------------------------------------
+
+function AppPushPrompt() {
+  const auth = useContext(PublicAuthContext);
+  const { profileId } = useForge();
+  const app = useSiteApp();
+  const push = usePushSubscription(profileId ?? "");
+  const [standalone, setStandalone] = useState(false);
+  const [permission, setPermission] = useState<NotificationPermission | null>(null);
+  const [answered, setAnswered] = useState(() => (typeof window === "undefined" ? null : readPushAnswer()));
+
+  useEffect(() => {
+    setStandalone(isStandaloneDisplay());
+    setPermission(typeof Notification !== "undefined" ? Notification.permission : null);
+    setAnswered(readPushAnswer());
+  }, []);
+
+  const due = decideAppPush({
+    pushPrompt: app.data?.pushPrompt,
+    isStandalone: standalone,
+    isSignedIn: !!auth?.user,
+    isSupported: push.isSupported && !push.isLoading,
+    permission,
+    answer: answered,
+  });
+
+  if (!due || push.isSubscribed) return null;
+  return (
+    <AppPushSheet
+      name={app.data?.shortName || app.data?.appName || null}
+      subscribe={push.subscribe}
+      onAnswered={(answer) => {
+        rememberPushAnswer(answer);
+        setAnswered(answer);
+      }}
+    />
+  );
+}
+
+/**
+ * The first-launch notifications sheet. Offers a switch per category the
+ * member's preference matrix knows; a server without the matrix gets one
+ * plain opt-in.
+ */
+function AppPushSheet({
+  name,
+  subscribe,
+  onAnswered,
+}: {
+  name: string | null;
+  subscribe: () => Promise<boolean>;
+  onAnswered: (answer: "accepted" | "declined") => void;
+}) {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const matrix = useNotificationMatrix();
+  const update = useUpdateNotificationMatrix();
+  const [busy, setBusy] = useState(false);
+  const known = new Set(Object.keys(matrix.data?.defaults ?? {}));
+  const categories = APP_PUSH_CATEGORIES.filter((category) => category.types.some((type) => known.has(type)));
+  const [chosen, setChosen] = useState<Record<AppPushCategoryKey, boolean> | null>(null);
+
+  // Start from what the member already has: a category is on when any of its types pushes.
+  const current: Record<AppPushCategoryKey, boolean> =
+    chosen ??
+    (Object.fromEntries(
+      APP_PUSH_CATEGORIES.map((category) => [
+        category.key,
+        !matrix.data || category.types.some((type) => matrix.data!.preferences?.[`${type}.push`] !== false && known.has(type)),
+      ]),
+    ) as Record<AppPushCategoryKey, boolean>);
+
+  const accept = async () => {
+    setBusy(true);
+    const ok = await subscribe();
+    if (ok && categories.length > 0) {
+      try {
+        await update.mutateAsync({ preferences: pushPreferencePatch(current, known) });
+      } catch {
+        /* the subscription stands; the choices can be changed in notification settings */
+      }
+    }
+    setBusy(false);
+    onAnswered(ok ? "accepted" : "declined");
+  };
+
+  const appName = name ?? tr("forge.app_prompts.this_app");
+  // Wait for the member's settings, so the sheet does not open as one switch
+  // and then grow three. A server without them answers an error: one switch.
+  if (matrix.isLoading) return null;
+
+  return (
+    <CommunitySheet
+      open
+      onOpenChange={(open) => {
+        if (!open) onAnswered("declined");
+      }}
+      testId="app-push-prompt"
+      title={tr("forge.app_prompts.push_title")}
+      closeLabel={tr("forge.app_prompts.aria_close")}
+    >
+      <div className="fg:flex fg:flex-col fg:gap-5">
+        <p style={{ margin: 0, fontSize: 15, color: t.muted }}>
+          {categories.length > 0
+            ? tr("forge.app_prompts.push_lead_categories", { app: appName })
+            : tr("forge.app_prompts.push_lead_single", { app: appName })}
+        </p>
+        {categories.length > 0 ? (
+          <fieldset
+            data-testid="app-push-categories"
+            style={{ margin: 0, padding: 0, border: "none", borderTop: `1px solid ${t.border}` }}
+          >
+            <legend className="fg:sr-only">{tr("forge.app_prompts.push_title")}</legend>
+            {categories.map((category) => (
+              <label
+                key={category.key}
+                data-testid={`app-push-category-${category.key}`}
+                className="fg:flex fg:items-center fg:gap-3"
+                style={{ padding: "14px 0", borderBottom: `1px solid ${t.border}`, cursor: "pointer" }}
+              >
+                <MessageCircle size={18} aria-hidden style={{ color: t.muted, flexShrink: 0 }} />
+                <span style={{ flex: 1, fontWeight: 600, fontSize: 15 }}>{tr(PUSH_CATEGORY_KEYS[category.key])}</span>
+                <input
+                  type="checkbox"
+                  checked={current[category.key]}
+                  onChange={(event) => setChosen({ ...current, [category.key]: event.target.checked })}
+                  style={{ width: 22, height: 22, accentColor: t.primary }}
+                />
+              </label>
+            ))}
+          </fieldset>
+        ) : null}
+        <div className="fg:flex fg:flex-col fg:gap-2">
+          <button
+            type="button"
+            data-testid="app-push-accept"
+            disabled={busy}
+            style={{ ...primaryButton(t), opacity: busy ? 0.7 : 1 }}
+            onClick={() => void accept()}
+          >
+            {tr("forge.app_prompts.push_accept")}
+          </button>
+          <button type="button" data-testid="app-push-later" style={quietButton(t)} onClick={() => onAnswered("declined")}>
+            {tr("forge.app_prompts.push_later")}
+          </button>
+        </div>
+      </div>
+    </CommunitySheet>
+  );
+}
+
+// ---- Pieces ------------------------------------------------------------------------------
+
+type Tokens = ReturnType<typeof useThemeTokens>;
+
+function primaryButton(t: Tokens): CSSProperties {
+  return {
+    minHeight: 52,
+    borderRadius: Math.max(t.cornerRadius, 10),
+    border: "none",
+    background: t.primary,
+    color: t.textPrimary,
+    fontWeight: 700,
+    fontSize: 16,
+    fontFamily: t.fontFamily,
+    cursor: "pointer",
+  };
+}
+
+function quietButton(t: Tokens): CSSProperties {
+  return {
+    minHeight: 48,
+    borderRadius: Math.max(t.cornerRadius, 10),
+    border: "none",
+    background: "transparent",
+    color: t.muted,
+    fontWeight: 600,
+    fontSize: 15,
+    fontFamily: t.fontFamily,
+    cursor: "pointer",
+  };
+}
+
+function AppIdentity({ iconUrl, name, children }: { iconUrl: string | null; name: string; children: ReactNode }) {
+  const t = useThemeTokens();
+  return (
+    <div className="fg:flex fg:items-center fg:gap-3">
+      {iconUrl ? (
+        <img src={iconUrl} alt="" style={{ width: 56, height: 56, borderRadius: 16, objectFit: "cover", flexShrink: 0 }} />
+      ) : (
+        <span
+          aria-hidden
+          className="fg:flex fg:items-center fg:justify-center"
+          style={{
+            width: 56,
+            height: 56,
+            borderRadius: 16,
+            background: t.primary,
+            color: t.textPrimary,
+            fontWeight: 800,
+            fontSize: 22,
+            flexShrink: 0,
+          }}
+        >
+          {name.trim().charAt(0).toUpperCase()}
+        </span>
+      )}
+      <p style={{ margin: 0, fontSize: 14, color: t.muted }}>{children}</p>
+    </div>
+  );
+}
+
+function Benefit({ icon, children }: { icon: ReactNode; children: ReactNode }) {
+  const t = useThemeTokens();
+  return (
+    <li className="fg:flex fg:items-center fg:gap-3" style={{ fontSize: 15 }}>
+      <span
+        className="fg:flex fg:items-center fg:justify-center"
+        style={{ width: 32, height: 32, borderRadius: 10, background: t.surface, color: t.primary, flexShrink: 0 }}
+      >
+        {icon}
+      </span>
+      {children}
+    </li>
+  );
+}
+
+function IosStep({ n, icon, children }: { n: number; icon: ReactNode; children: ReactNode }) {
+  const t = useThemeTokens();
+  return (
+    <li
+      className="fg:flex fg:items-center fg:gap-3"
+      style={{ padding: 14, borderRadius: Math.max(t.cornerRadius, 10), background: t.surface, fontSize: 15 }}
+    >
+      <span
+        className="fg:flex fg:items-center fg:justify-center"
+        style={{
+          width: 26,
+          height: 26,
+          borderRadius: 13,
+          background: t.text,
+          color: t.background,
+          fontSize: 13,
+          fontWeight: 700,
+          flexShrink: 0,
+        }}
+      >
+        {n}
+      </span>
+      <span style={{ flex: 1 }}>{children}</span>
+      <span style={{ color: t.primary, display: "inline-flex" }}>{icon}</span>
+    </li>
+  );
+}

package/src/ui/styled/app/_tests/AppBar.spec.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ForgeThemeProvider } from "../../../theme/ForgeThemeProvider";
+import { AppBar } from "../AppBar";
+import { account, get, installAdapter, restoreAdapter, wrapper } from "../../../headless/_tests/communityHarness";
+import { siteApp } from "../../../headless/_tests/siteAppHarness";
+
+/**
+ * The site app's bottom bar as drawn: Home first (the Home rule), the
+ * configured items, More last with everything else, and the height it
+ * publishes for whatever else is pinned to the bottom of the screen.
+ */
+
+const theme = { colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 };
+
+function mount(node: ReactNode, opts: Parameters<typeof wrapper>[0] = {}) {
+  const Wrapper = wrapper({ community: null, ...opts });
+  return render(
+    <Wrapper>
+      <ForgeThemeProvider theme={theme}>{node}</ForgeThemeProvider>
+    </Wrapper>,
+  );
+}
+
+const barIds = () =>
+  Array.from(screen.getByTestId("app-bar").children).map((el) => el.getAttribute("data-testid"));
+
+const realMatchMedia = window.matchMedia;
+
+beforeEach(() => {
+  // A phone: below `lg`.
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches: query.includes("max-width"),
+    media: query,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  })) as never;
+});
+
+afterEach(() => {
+  restoreAdapter();
+  window.matchMedia = realMatchMedia;
+});
+
+describe("AppBar", () => {
+  it("is Home, the configured items, then More, with Home at the creator's start page", async () => {
+    installAdapter([get("/public/websites/app", () => siteApp({ barItems: ["events", "shop"], startUrl: "/members" }))]);
+    mount(<AppBar currentPath="/i/events" prompts={false} />);
+
+    await waitFor(() => expect(barIds()).toEqual(["app-bar-home", "app-bar-events", "app-bar-shop", "app-bar-more"]));
+    expect(screen.getByTestId("app-bar-home").getAttribute("href")).toBe("/members");
+    expect(screen.getByTestId("app-bar-events").getAttribute("aria-current")).toBe("page");
+
+    fireEvent.click(screen.getByTestId("app-bar-more"));
+    const sheet = await screen.findByTestId("app-more-sheet");
+    const rows = Array.from(sheet.querySelectorAll("a[data-testid^='app-more-']")).map((el) => el.getAttribute("data-testid"));
+    expect(rows).toEqual(["app-more-communities", "app-more-portal", "app-more-inbox", "app-more-courses"]);
+    expect(within(sheet).getByTestId("app-more-inbox").getAttribute("href")).toBe("/i/account/notifications");
+  });
+
+  it("draws the default bar, Home at /i/app, before and without the settings", () => {
+    installAdapter([
+      get("/public/websites/app", () => {
+        throw { status: 404 };
+      }),
+    ]);
+    mount(<AppBar currentPath="/i/app" prompts={false} />);
+    expect(barIds()).toEqual(["app-bar-home", "app-bar-communities", "app-bar-portal", "app-bar-inbox", "app-bar-more"]);
+    expect(screen.getByTestId("app-bar-home").getAttribute("href")).toBe("/i/app");
+    expect(screen.getByTestId("app-bar-home").getAttribute("aria-current")).toBe("page");
+  });
+
+  it("navigates in-app, and shows the member's unread count on Inbox", async () => {
+    installAdapter([
+      get("/public/websites/app", () => siteApp()),
+      get("/public/notifications/inbox", () => ({ data: [], unreadCount: 3 })),
+    ]);
+    const navigate = vi.fn();
+    mount(<AppBar currentPath="/i/app" navigate={navigate} prompts={false} />, { user: account() });
+    expect((await screen.findByTestId("app-bar-inbox-badge")).textContent).toBe("3");
+    fireEvent.click(screen.getByTestId("app-bar-communities"), { button: 0 });
+    expect(navigate).toHaveBeenCalledWith("/i/communities");
+  });
+
+  it("publishes its height on the root, as the community bar does, and takes it back on unmount", () => {
+    installAdapter([get("/public/websites/app", () => siteApp())]);
+    const view = mount(<AppBar currentPath="/i/app" prompts={false} />);
+    expect(document.documentElement.style.getPropertyValue("--forge-bottom-bar-height")).toBe("56px");
+    // The page ends above the bar.
+    expect(screen.getByTestId("app-bar-spacer")).toBeTruthy();
+    view.unmount();
+    expect(document.documentElement.style.getPropertyValue("--forge-bottom-bar-height")).toBe("");
+  });
+});