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

package/src/components/help-center-pages/index.ts

@@ -22,6 +22,7 @@ export { ProductReleasesListPage, type ProductReleasesListPageProps } from './pr
 export { DeliveryPage, type DeliveryPageProps } from './delivery-page';
 export { OnboardingGuidesCatalogPage, type OnboardingGuidesCatalogPageProps } from './onboarding-guides-catalog-page';
 export { TrustCenterPage, TrustCenterPageSkeleton, type TrustCenterPageProps } from './trust-center-page';
+export { DownloadAppsPage, type DownloadAppsPageProps, type DownloadAppsWebOption } from './download-apps-page';
 
 // Existing full-pages re-exported for a single Help Center import site.
 export { FaqDocumentPage, type FaqDocumentPageProps } from '../faq';

package/src/components/ui/button/button.tsx

@@ -339,6 +339,8 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function ButtonI
           download={download}
           prefetch={false}
           className={cn(shellClasses, isDisabled && 'pointer-events-none')}
+          // The click still reaches the caller (a download is what analytics counts).
+          onClick={onClick as unknown as React.MouseEventHandler<HTMLAnchorElement> | undefined}
           aria-label={props['aria-label']}
         >
           {splitContent}
@@ -423,6 +425,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function ButtonI
         download={download}
         prefetch={false}
         className={cn(classes, isDisabled && 'pointer-events-none')}
+        onClick={onClick as unknown as React.MouseEventHandler<HTMLAnchorElement> | undefined}
         aria-label={props['aria-label']}
       >
         {content}

package/src/components/ui/index.ts

@@ -73,6 +73,7 @@ export * from './status-badge';
 export * from './palette-badge';
 export * from './department-badge';
 export * from './store-badges';
+export * from './mobile-app-qr';
 export * from './status-indicator';
 export * from './toaster';
 // TODO: Add other UI components as they are moved to ui-kit

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

@@ -0,0 +1,35 @@
+import type { MobileAppInstallLink } from '../../types/downloads';
+import { cn } from '../../utils/cn';
+
+export interface MobileAppQrProps {
+  /** The server's install link: the address and the artwork that encodes it. */
+  install: MobileAppInstallLink;
+  /** Sizes the code; the caller owns its footprint. */
+  className?: string;
+}
+
+/**
+ * The install QR code, drawn inline: the modules are the ODS accent colour and
+ * the background is transparent, so the code sits directly on whatever surface
+ * it is placed on. The artwork and the address it encodes are the server's
+ * (`MobileAppInstallLink`): this component holds neither.
+ *
+ * On a dark surface that is a light-on-dark code. Phone cameras read both
+ * polarities; what they need is contrast between the accent and the surface, and
+ * the quiet zone, which the server bakes into the viewBox as a transparent
+ * margin. Place it on a plain surface (a card, the page), never over an image
+ * or a surface close to the accent in brightness.
+ */
+export function MobileAppQr({ install, className }: MobileAppQrProps) {
+  return (
+    <svg
+      viewBox={`0 0 ${install.qrViewBoxSize} ${install.qrViewBoxSize}`}
+      shapeRendering="crispEdges"
+      role="img"
+      aria-label={`QR code for ${install.url}`}
+      className={cn('h-[120px] w-[120px] text-ods-accent', className)}
+    >
+      <path fill="currentColor" d={install.qrPath} />
+    </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,99 @@
+/**
+ * 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;
+}
+
+/**
+ * The install link a phone opens to reach its store, and the QR code that
+ * encodes it. Both are the server's: the link is an address on the website
+ * (answered there with a redirect by device), and the artwork is drawn from it
+ * on the server, so the two can never disagree and the lib names no host.
+ */
+export interface MobileAppInstallLink {
+  /** The absolute address the code encodes. */
+  url: string;
+  /** The side of the artwork's square viewBox, quiet zone included. */
+  qrViewBoxSize: number;
+  /** The dark modules as one SVG path of filled rectangles (`fill` draws them). */
+  qrPath: string;
+}
+
+/** 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;
+  /** The install link and its QR code. Absent or null: no code is drawn. */
+  install?: MobileAppInstallLink | 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/format.ts

@@ -1059,3 +1059,18 @@ export function formatWebinarTimeMeta(
   const time = formatProgramTimeRange(at, { startAt: opts.startAt, withZoneLabel: opts.withZoneLabel });
   return [time, duration].filter(Boolean).join(' · ');
 }
+
+/**
+ * A web address as it is shown to a person to read or type, not to follow: no
+ * scheme, no query or fragment, no trailing slash.
+ * `https://www.example.com/mobile?from=qr` reads `example.com/mobile`.
+ *
+ * `www` is dropped by default, because nobody types it; `keepWww` keeps it where
+ * the address is shown as the site's own name.
+ */
+export function formatUrlForDisplay(url: string, options: { keepWww?: boolean } = {}): string {
+  return url
+    .replace(options.keepWww ? /^https?:\/\//i : /^https?:\/\/(www\.)?/i, '')
+    .replace(/[?#].*$/, '')
+    .replace(/\/$/, '');
+}

package/src/utils/index.ts

@@ -16,7 +16,7 @@ export {
 // Number / currency / byte / date formatters live in `./format` (single
 // source of truth). Re-exported here so existing callers that pull from
 // the barrel keep working without changing imports.
-export { formatDate, formatNumber, formatPrice, formatBytes } from './format';
+export { formatDate, formatNumber, formatPrice, formatBytes, formatUrlForDisplay } from './format';
 export { TRIAL_DAYS, TRIAL_LABELS } from './trial';
 export {
   VENDOR_CLASSIFICATIONS,
@@ -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,34 @@
+/**
+ * The download page's address, and what a server needs to send a phone on to
+ * its store. No link lives here: the store listings, the installer links and
+ * the install link the QR code encodes are all 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';
+
+/**
+ * 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 (the install link's redirect).
+ * A browser may also pass `navigator.maxTouchPoints`, the only signal that tells
+ * an iPad asking for the desktop site (it calls itself a Macintosh) from a real
+ * Mac; the server cannot, so that iPad lands on the download page and its badges.
+ */
+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;
+}