@flamingo-stack/openframe-frontend-core 0.0.720 → 0.0.721

package/src/components/ui/mobile-app-qr.tsx

@@ -0,0 +1,40 @@
+import { MOBILE_APP_QR_PATH, MOBILE_APP_QR_VIEWBOX_SIZE } from '../../assets/mobile-app-qr';
+import { cn } from '../../utils/cn';
+import { MOBILE_APP_INSTALL_URL } from '../../utils/mobile-app';
+
+export interface MobileAppQrProps {
+  /** Sizes the code; the caller owns its footprint. */
+  className?: string;
+}
+
+/**
+ * The install QR code, drawn inline rather than loaded from `/public` so the
+ * modules take their colour from the surface they sit on.
+ *
+ * Dark modules, and the caller supplies a light plate. Decoders binarize the
+ * image and expect dark-on-light; inverting that is one of the two things they
+ * reliably fail on. The other is a missing quiet zone, which is why the 4-module
+ * margin is baked into the viewBox — keep it even when the plate is larger.
+ *
+ * That polarity holds only under the dark theme, where `text-ods-bg` is the dark
+ * value and `bg-ods-bg-inverted` the light one; both flip under `.theme-light`.
+ * Do not render this inside a light-theme scope: an inverted code is silently
+ * unscannable rather than visibly broken.
+ *
+ * The artwork is the asset `MOBILE_APP_QR_PATH` (`assets/mobile-app-qr`), which
+ * encodes {@link MOBILE_APP_INSTALL_URL}; the regeneration note lives there.
+ */
+export function MobileAppQr({ className }: MobileAppQrProps) {
+  return (
+    <svg
+      viewBox={`0 0 ${MOBILE_APP_QR_VIEWBOX_SIZE} ${MOBILE_APP_QR_VIEWBOX_SIZE}`}
+      fill="none"
+      shapeRendering="crispEdges"
+      role="img"
+      aria-label={`QR code for ${MOBILE_APP_INSTALL_URL}`}
+      className={cn('h-[120px] w-[120px] text-ods-bg', className)}
+    >
+      <path stroke="currentColor" d={MOBILE_APP_QR_PATH} />
+    </svg>
+  );
+}

package/src/components/ui/store-badges.tsx

@@ -299,32 +299,40 @@ export function GooglePlayBadge({ className }: StoreBadgeProps) {
 }
 
 export interface StoreBadgeLinksProps {
-  appStoreUrl: string;
-  googlePlayUrl: string;
+  /** The App Store listing. Absent or null: that badge is not drawn. */
+  appStoreUrl?: string | null;
+  /** The Google Play listing. Absent or null: that badge is not drawn. */
+  googlePlayUrl?: string | null;
   /** Opens both listings in a new tab. */
   openInNewTab?: boolean;
   className?: string;
 }
 
 /**
- * The pair of store badges as links — the canonical "get our mobile app" row.
+ * The store badges as links — the canonical "get our mobile app" row. A store
+ * with no listing has no badge, and with neither the row is not rendered.
  *
  * Both are rendered at the same height because Apple and Google each require
  * their badge to be no smaller than any other store's badge beside it, which is
  * only satisfiable by drawing them equal.
  */
 export function StoreBadgeLinks({ appStoreUrl, googlePlayUrl, openInNewTab = true, className }: StoreBadgeLinksProps) {
+  if (!appStoreUrl && !googlePlayUrl) return null;
   return (
     <div className={cn('flex flex-wrap items-center gap-[var(--spacing-system-lf)]', className)}>
       {/* `rel` on both branches: `noopener` is inert without a target, but `noreferrer` is
           not — dropping it on the same-window branch sent the tenant's hostname to Apple
           and Google as a Referer. */}
-      <a href={appStoreUrl} target={openInNewTab ? '_blank' : undefined} rel="noopener noreferrer">
-        <AppStoreBadge className="h-12 w-auto" />
-      </a>
-      <a href={googlePlayUrl} target={openInNewTab ? '_blank' : undefined} rel="noopener noreferrer">
-        <GooglePlayBadge className="h-12 w-auto" />
-      </a>
+      {appStoreUrl && (
+        <a href={appStoreUrl} target={openInNewTab ? '_blank' : undefined} rel="noopener noreferrer">
+          <AppStoreBadge className="h-12 w-auto" />
+        </a>
+      )}
+      {googlePlayUrl && (
+        <a href={googlePlayUrl} target={openInNewTab ? '_blank' : undefined} rel="noopener noreferrer">
+          <GooglePlayBadge className="h-12 w-auto" />
+        </a>
+      )}
     </div>
   );
 }

package/src/hooks/index.ts

@@ -4,6 +4,7 @@ export * from './platform';
 export * from './use-toast';
 export * from './use-contact-submission';
 export * from './use-copy-to-clipboard';
+export * from './use-downloads';
 
 // Image authentication hooks
 export * from './use-batch-images';

package/src/hooks/use-downloads.ts

@@ -0,0 +1,138 @@
+'use client';
+
+import { useCallback, useEffect, useSyncExternalStore } from 'react';
+import { DOWNLOADS_API_PATH, type AppDownload, type DownloadsPublic } from '../types/downloads';
+import { contentFetch } from '../utils/embed-content-fetch';
+import { desktopOsOf } from '../utils/visitor-os';
+import { useVisitorOs } from './ui/use-visitor-os';
+
+export interface DownloadsState {
+  /** The server's answer; null until it lands. */
+  data: DownloadsPublic | null;
+  isLoading: boolean;
+  error: boolean;
+}
+
+interface Entry {
+  state: DownloadsState;
+  request: Promise<void> | null;
+  listeners: Set<() => void>;
+}
+
+const IDLE: DownloadsState = { data: null, isLoading: false, error: false };
+
+/**
+ * One entry per endpoint for the life of the page. Every download button on a
+ * page asks the same question, so they share ONE request and one answer: the
+ * list changes only when the server is redeployed, never while a page is open.
+ */
+const entries = new Map<string, Entry>();
+
+function entryFor(endpoint: string): Entry {
+  let entry = entries.get(endpoint);
+  if (!entry) {
+    entry = { state: IDLE, request: null, listeners: new Set() };
+    entries.set(endpoint, entry);
+  }
+  return entry;
+}
+
+function publish(endpoint: string, state: DownloadsState) {
+  const entry = entryFor(endpoint);
+  entry.state = state;
+  for (const listener of entry.listeners) listener();
+}
+
+function load(endpoint: string, force = false): void {
+  const entry = entryFor(endpoint);
+  if (entry.request || (entry.state.data && !force)) return;
+  publish(endpoint, { data: entry.state.data, isLoading: true, error: false });
+  entry.request = contentFetch(endpoint)
+    .then(async response => {
+      if (!response.ok) throw new Error(`Request failed (${response.status})`);
+      publish(endpoint, { data: (await response.json()) as DownloadsPublic, isLoading: false, error: false });
+    })
+    .catch(() => publish(endpoint, { data: entry.state.data, isLoading: false, error: true }))
+    .finally(() => {
+      entry.request = null;
+    });
+}
+
+/** Test seam: forget every answer. */
+export function resetDownloadsStore(): void {
+  entries.clear();
+}
+
+export interface UseDownloadsOptions {
+  /** GET endpoint for the public projection. Default `DOWNLOADS_API_PATH`; embedders pass their proxy path. */
+  endpoint?: string;
+  /** The server's copy (a host that read it during SSR): no request is made. */
+  initialData?: DownloadsPublic;
+  /** False: nothing is requested (a host that does not offer the desktop app). Default true. */
+  enabled?: boolean;
+}
+
+/**
+ * What the OpenFrame desktop app is installed from, read FROM THE SERVER
+ * (`GET /api/downloads`). The links and package names live in the server's
+ * environment; no client holds a copy of its own. Every caller on a page shares
+ * one request.
+ */
+export function useDownloads({ endpoint = DOWNLOADS_API_PATH, initialData, enabled = true }: UseDownloadsOptions = {}) {
+  const entry = entryFor(endpoint);
+  // A server copy is the answer: held from the first render (server and client alike), and never re-requested.
+  // Written during render so THIS caller's first paint has it; a render cannot notify other callers.
+  if (initialData && entry.state.data !== initialData && !entry.request) {
+    entry.state = { data: initialData, isLoading: false, error: false };
+  }
+  // So the callers that rendered before this one (a header button above the page) are told after
+  // the commit: they re-read the shared answer instead of staying on the empty one they first saw.
+  useEffect(() => {
+    if (!initialData) return;
+    for (const listener of entry.listeners) listener();
+  }, [entry, initialData]);
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      entry.listeners.add(listener);
+      return () => {
+        entry.listeners.delete(listener);
+      };
+    },
+    [entry],
+  );
+  const state = useSyncExternalStore(
+    subscribe,
+    () => entry.state,
+    () => entry.state,
+  );
+
+  useEffect(() => {
+    if (enabled) load(endpoint);
+  }, [enabled, endpoint]);
+
+  const reload = useCallback(() => load(endpoint, true), [endpoint]);
+  // Until the effect has asked, an enabled caller with no answer is loading, not empty.
+  const isLoading = state.isLoading || (enabled && !state.data && !state.error);
+  return { data: state.data, isLoading, error: state.error, reload };
+}
+
+export interface VisitorDesktopDownload {
+  /** False until the visitor's system AND the server's list are both known. */
+  known: boolean;
+  /** This visitor's installer (the first one for their system); null when nothing installs on it. */
+  download: AppDownload | null;
+}
+
+/**
+ * The installer a download button offers THIS visitor: the server's first
+ * installer for the system they are on. `enabled: false` asks for nothing.
+ */
+export function useVisitorDesktopDownload(options: UseDownloadsOptions = {}): VisitorDesktopDownload {
+  const enabled = options.enabled ?? true;
+  const visitor = useVisitorOs();
+  const { data, error } = useDownloads(options);
+  if (!enabled || !visitor.known || (!data && !error)) return { known: false, download: null };
+  const os = desktopOsOf(visitor.os);
+  const download = data?.desktop.find(row => row.kind === 'binary' && row.url && row.os === os) ?? null;
+  return { known: true, download };
+}

package/src/types/downloads.ts

@@ -0,0 +1,82 @@
+/**
+ * The download page's wire shape and vocabulary: what the OpenFrame apps are
+ * installed from. The hub answers `DOWNLOADS_API_PATH` with `DownloadsPublic`;
+ * the lib's `<DownloadAppsPage>` renders it (hub SSR, openframe-frontend through
+ * its `/content` proxy, the embedding example).
+ */
+import type { DesktopOs } from '../utils/visitor-os';
+
+/** GET endpoint for the public downloads projection (the hub's path; embedders prefix their proxy). */
+export const DOWNLOADS_API_PATH = '/api/downloads';
+
+/** How long a copy stays fresh: the CDN window of the route, and the page's revalidation age. */
+export const DOWNLOADS_CACHE_SECONDS = 300;
+
+export const DOWNLOADS_TITLE = 'Download OpenFrame';
+export const DOWNLOADS_TAGLINE =
+  'Install it on the computer you manage IT from, and on your phone. One account everywhere.';
+/** The title and subtitle when a host offers the mobile app only. */
+export const DOWNLOADS_MOBILE_TITLE = 'Get the OpenFrame app';
+export const DOWNLOADS_MOBILE_TAGLINE =
+  'Alerts and tickets on your phone, signed in with the account you already have.';
+
+/**
+ * What a row is: an installer file, or a one-line package manager install. THE
+ * one declaration: the type, the server's rows and every reader derive from it.
+ */
+export const APP_DOWNLOAD_KINDS = ['binary', 'command'] as const;
+export type AppDownloadKind = (typeof APP_DOWNLOAD_KINDS)[number];
+
+/** One way to install the desktop app on one system. */
+export interface AppDownload {
+  id: string;
+  kind: AppDownloadKind;
+  os: DesktopOs;
+  /** `universal`, `x64`, `arm64`; null for a command. */
+  architecture: string | null;
+  /** The installer's address (`binary`). */
+  url: string | null;
+  /** The whole command to paste (`command`). */
+  command: string | null;
+  /** "macOS 13+". */
+  minOsLabel: string | null;
+  /** The package manager's name (`command`), or the button's own words (`binary`). */
+  label: string | null;
+}
+
+/** Where the mobile app is installed from. A store the server names no listing for is null, and is not offered. */
+export interface MobileAppLinks {
+  appStoreUrl: string | null;
+  googlePlayUrl: string | null;
+}
+
+/**
+ * Everything the download page shows. All of it is the server's: the lib holds
+ * no link of its own and falls back to none, so what is missing is not drawn.
+ */
+export interface DownloadsPublic {
+  /** The desktop installers and install commands, in the order they are offered. Per system, the first installer is the default. */
+  desktop: AppDownload[];
+  /** The mobile app's store listings. */
+  mobile: MobileAppLinks;
+}
+
+/** A system's name on a button and a card. */
+export const DESKTOP_OS_LABELS: Record<DesktopOs, string> = { mac: 'Mac', windows: 'Windows', linux: 'Linux' };
+
+/** An architecture's name beside a button, when a system has more than one installer. */
+export const DOWNLOAD_ARCHITECTURE_LABELS: Record<string, string> = {
+  universal: 'Apple Silicon and Intel',
+  x64: 'x64',
+  arm64: 'ARM',
+};
+
+/** What a host learns when a visitor takes an install action on the page. */
+export interface DownloadActionEvent {
+  /** `installer`: a download button. `command`: a copied install command. */
+  action: 'installer' | 'command';
+  /** The row's id (`mac`, `windows-arm64`, `homebrew`). */
+  id: string;
+  os: DesktopOs;
+  architecture: string | null;
+}

package/src/types/index.ts

@@ -55,6 +55,7 @@ export * from './waitlist';
 // Business logic types
 export * from './faq';
 export * from './trust-center';
+export * from './downloads';
 export * from './content-ref';
 export * from './report';
 export * from './stack';

package/src/utils/index.ts

@@ -118,6 +118,8 @@ export * from './video-bite-id';
 // OS type utilities
 export * from './os-utils';
 export * from './visitor-os';
+// Also exported via the granular subpath `./utils/mobile-app` (server and Edge consumers).
+export * from './mobile-app';
 // Phone utilities
 export * from './country-phone-utils';
 export * from './compliance-standards';

package/src/utils/mobile-app.ts

@@ -0,0 +1,57 @@
+/**
+ * The download page's own addresses: where it lives, the parameter that sends a
+ * phone on to its store, and the URL the install QR code encodes. The store
+ * listings and installer links are NOT here: they are the server's
+ * (`DownloadsPublic`, read through `useDownloads`).
+ *
+ * Pure and server-safe; also published as the granular subpath
+ * `./utils/mobile-app`, for an Edge proxy and other server-only consumers.
+ */
+import type { MobileAppLinks } from '../types/downloads';
+import { detectVisitorOs } from './visitor-os';
+
+/** The website's download page: every installer and the mobile app. */
+export const DOWNLOAD_PAGE_PATH = '/download';
+
+/**
+ * On the download page: "send a phone or a tablet on to its store". The install
+ * QR code carries it, because whoever scans a code is holding the phone the app
+ * goes on. Anyone who opens the page without it reads the page.
+ */
+export const DOWNLOAD_PAGE_STORE_PARAM = 'store';
+
+/**
+ * The one URL the install QR code encodes: the website's download page, asking
+ * it to send a phone on to its store.
+ *
+ * Absolute and on the production host on purpose: a code must point at
+ * production whichever deployment rendered the page it came from. `MobileAppQr`
+ * draws this value as committed path data, so the two change together: see the
+ * regeneration note on that component.
+ */
+export const MOBILE_APP_INSTALL_URL = `https://www.flamingo.run${DOWNLOAD_PAGE_PATH}?${DOWNLOAD_PAGE_STORE_PARAM}=1`;
+
+/** The download page as it is printed for a human to read or type: no scheme, no `www`, no query. */
+export const MOBILE_APP_INSTALL_HOST_PATH = MOBILE_APP_INSTALL_URL.replace(/^https:\/\/(www\.)?/, '').replace(
+  /\?.*$/,
+  '',
+);
+
+/**
+ * The store for a phone or tablet, or `null` for every other system and for a
+ * store the server names no listing for (`links` is the server's answer).
+ *
+ * The server passes the request's User-Agent; a browser also passes
+ * `navigator.maxTouchPoints`, the only signal that tells an iPad asking for the
+ * desktop site (it calls itself a Macintosh) from a real Mac.
+ */
+export function resolveMobileStoreUrl(
+  links: MobileAppLinks,
+  userAgent: string | null | undefined,
+  maxTouchPoints?: number,
+): string | null {
+  const os = detectVisitorOs(userAgent, { maxTouchPoints });
+  if (os === 'ios') return links.appStoreUrl;
+  if (os === 'android') return links.googlePlayUrl;
+  return null;
+}