tempest-react-sdk 0.21.0 → 0.22.0

package/dist/tempest-react-sdk.d.ts

@@ -38,6 +38,7 @@ import { LabelHTMLAttributes } from 'react';
 import { lazy } from 'react';
 import { Link } from 'react-router-dom';
 import { MemoryRouter } from 'react-router-dom';
+import { MouseEvent as MouseEvent_2 } from 'react';
 import { MouseEventHandler } from 'react';
 import { Navigate } from 'react-router-dom';
 import { NavigateOptions } from 'react-router-dom';
@@ -67,6 +68,7 @@ import { Table as Table_2 } from 'dexie';
 import { TextareaHTMLAttributes } from 'react';
 import { To } from 'react-router-dom';
 import { ToggleEventHandler } from 'react';
+import { TouchEvent as TouchEvent_2 } from 'react';
 import { TouchEventHandler } from 'react';
 import { TransitionEventHandler } from 'react';
 import { UIEventHandler } from 'react';
@@ -580,6 +582,24 @@ export declare type BannerVariant = "info" | "success" | "warning" | "danger";
  */
 export declare function bearingDeg(origin: Coordinate, destination: Coordinate): number;
 
+/**
+ * The Chromium-only `beforeinstallprompt` event. iOS Safari never fires it —
+ * for those users the app falls back to manual "Add to Home Screen"
+ * instructions. Ported into the SDK so consumers get the type without a global
+ * augmentation.
+ */
+export declare interface BeforeInstallPromptEvent extends Event {
+    /** Platforms the prompt can target (e.g. `["web", "android"]`). */
+    readonly platforms: readonly string[];
+    /** Resolves once the user accepts or dismisses the prompt. */
+    readonly userChoice: Promise<{
+        outcome: "accepted" | "dismissed";
+        platform: string;
+    }>;
+    /** Shows the native install prompt. */
+    prompt: () => Promise<void>;
+}
+
 /**
  * Fixed-bottom mobile tab bar. 3–5 items recommended. Pair with
  * `<Show below="md">` to render only on mobile.
@@ -723,6 +743,16 @@ export declare function buildApiError(status: number, body: unknown, headers?: H
     get(name: string): string | null;
 }, sentRequestId?: string): ApiError;
 
+/**
+ * Builds an `intent://` URL that re-opens the current page inside Chrome on
+ * Android. When Chrome is missing, the fallback URL points to the Play Store so
+ * the user can still recover. Returns `null` outside Android.
+ *
+ * @returns The `intent://` URL, or `null` when not on Android or without a DOM.
+ * @see https://developer.chrome.com/docs/multidevice/android/intents
+ */
+export declare function buildOpenInChromeIntent(): string | null;
+
 /**
  * Primary action button with variants, sizes and a loading state that
  * preserves layout via an absolutely-positioned spinner.
@@ -3406,6 +3436,17 @@ export declare interface InstallButtonProps extends Omit<ButtonProps, "onClick"
     onResult?: (outcome: InstallOutcome) => void;
 }
 
+/**
+ * Strategy the UI should use to install the app:
+ *
+ * - `"native"`: trigger `BeforeInstallPromptEvent.prompt()`.
+ * - `"ios"`: show iOS Safari Share → Add to Home Screen instructions.
+ * - `"manual"`: show generic browser-menu instructions (Chromium forks that
+ *   strip the prompt API, plus the timeout fallback when no event arrives).
+ * - `"none"`: nothing to offer (already installed or unsupported runtime).
+ */
+export declare type InstallMethod = "native" | "ios" | "manual" | "none";
+
 /**
  * Install a `notificationclick` handler that focuses an existing client when
  * possible and falls back to opening a new window.
@@ -3485,6 +3526,22 @@ export declare function installSkipWaitingListener(): void;
 
 export declare type InterpolationValues = Record<string, string | number>;
 
+/**
+ * Detects any Android browser.
+ *
+ * @returns `true` when the user agent reports Android.
+ */
+export declare function isAndroid(): boolean;
+
+/**
+ * Detects Android browsers that ship a Chromium fork with the
+ * `beforeinstallprompt` event stripped or unreliable. Those users must install
+ * via the browser menu manually, identical to iOS Safari.
+ *
+ * @returns `true` when running on such an Android browser.
+ */
+export declare function isAndroidWithoutPromptApi(): boolean;
+
 /**
  * Type guard for the {@link ApiError} shape. Matches both {@link TempestApiError}
  * instances and plain objects carrying `status` + `detail`.
@@ -3539,6 +3596,14 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/**
+ * Detects iOS / iPadOS Safari, including modern iPads that report `MacIntel`
+ * plus multi-touch instead of an `iPad` user agent.
+ *
+ * @returns `true` when running on iOS/iPadOS.
+ */
+export declare function isIOS(): boolean;
+
 /**
  * Return true when the JWT's `exp` claim is in the past (or missing).
  *
@@ -3588,6 +3653,15 @@ export declare function isPushSupported(): boolean;
 /** True when the Web Share API is available in this environment. */
 export declare function isShareSupported(): boolean;
 
+/**
+ * Reports whether the app is running as an installed PWA (Android Chrome, iOS,
+ * or desktop). Use it to suppress install CTAs once the user is already in the
+ * standalone shell.
+ *
+ * @returns `true` when the display mode is standalone or iOS reports standalone.
+ */
+export declare function isStandalone(): boolean;
+
 /**
  * Type guard asserting a value is a string primitive.
  *
@@ -3799,6 +3873,27 @@ export declare interface LoggerSink {
 
 export declare type LogLevel = "debug" | "info" | "warn" | "error";
 
+/**
+ * DOM event handlers produced by {@link useLongPressHandlers}, ready to spread
+ * onto a JSX element (`<div {...handlers}>`).
+ */
+export declare interface LongPressHandlers {
+    /** Starts the hold timer on mouse press. */
+    onMouseDown: (event: MouseEvent_2) => void;
+    /** Cancels the pending hold when the mouse is released. */
+    onMouseUp: () => void;
+    /** Cancels the pending hold when the pointer leaves the element. */
+    onMouseLeave: () => void;
+    /** Starts the hold timer on touch start. */
+    onTouchStart: (event: TouchEvent_2) => void;
+    /** Cancels the pending hold when the touch ends. */
+    onTouchEnd: () => void;
+    /** Cancels the pending hold when the finger moves. */
+    onTouchMove: () => void;
+    /** Fires the long-press immediately (desktop right-click parity). */
+    onContextMenu: (event: MouseEvent_2) => void;
+}
+
 /**
  * Memoize only the most recent call of `fn`, keyed by shallow-equal arguments.
  *
@@ -5014,6 +5109,11 @@ export declare interface RefreshIndicatorProps {
  * app keeps full control over the SW file — this helper only handles the
  * boilerplate around `register()` and `updatefound`.
  *
+ * With `autoUpdate` enabled it additionally polls `registration.update()` on
+ * an interval and (by default) reloads the page when a freshly activated worker
+ * takes control — a framework-agnostic equivalent of `vite-plugin-pwa`'s
+ * auto-update client, implemented directly on `navigator.serviceWorker`.
+ *
  * @returns The registration when it succeeds, or `null` when unsupported.
  */
 export declare function registerServiceWorker(options: RegisterServiceWorkerOptions): Promise<ServiceWorkerRegistration | null>;
@@ -5033,6 +5133,27 @@ export declare interface RegisterServiceWorkerOptions {
     onUpdate?: (waiting: ServiceWorker, registration: ServiceWorkerRegistration) => void;
     /** Called on registration failure. */
     onError?: (error: unknown) => void;
+    /**
+     * When `true`, poll the server for a fresh service worker on an interval
+     * (see {@link RegisterServiceWorkerOptions.updateIntervalMs}) and, unless
+     * {@link RegisterServiceWorkerOptions.reloadOnActivate} is disabled, reload
+     * the page as soon as a new worker takes control. Mirrors the auto-update
+     * behaviour of `vite-plugin-pwa` without depending on it. Default `false`.
+     */
+    autoUpdate?: boolean;
+    /**
+     * How often, in ms, to call `registration.update()` while `autoUpdate` is
+     * on. Browsers already re-check roughly every 24h; an hourly poll keeps
+     * long-lived sessions current without flooding the network. Default
+     * `3600000` (1 hour).
+     */
+    updateIntervalMs?: number;
+    /**
+     * When `autoUpdate` is on, reload the page once a new worker takes control
+     * (`controllerchange`), guarded against reload loops. Set to `false` to
+     * keep polling but leave the reload to the host app. Default `true`.
+     */
+    reloadOnActivate?: boolean;
 }
 
 /**
@@ -5410,6 +5531,33 @@ export declare interface SentryLike {
  */
 export declare function share(payload: SharePayload): Promise<ShareResult>;
 
+/**
+ * Try the Web Share API with the given `Blob` as a file; fall back to a
+ * download anchor when the browser cannot share files (desktop Firefox, older
+ * iOS Safari, etc.).
+ *
+ * A companion to {@link share} for the common "export a generated artifact"
+ * flow: on mobile it opens the native share sheet, and everywhere else it
+ * triggers a plain download. Returns early when the user shares or cancels the
+ * dialog; otherwise it downloads.
+ *
+ * @param blob - The binary payload to share or download.
+ * @param fileName - The file name presented to the user.
+ * @param options - Optional `title` for the share dialog.
+ * @returns A promise that resolves once the share or download completes.
+ *
+ * @example
+ * const zip = new Blob([bytes], { type: "application/zip" });
+ * await shareOrDownloadBlob(zip, "export.zip");
+ */
+export declare function shareOrDownloadBlob(blob: Blob, fileName: string, options?: ShareOrDownloadOptions): Promise<void>;
+
+/** Options for {@link shareOrDownloadBlob}. */
+export declare interface ShareOrDownloadOptions {
+    /** Title passed to the Web Share dialog. Defaults to the file name. */
+    title?: string;
+}
+
 export declare interface SharePayload {
     title?: string;
     text?: string;
@@ -6912,6 +7060,75 @@ export declare function useI18n(): I18nContextValue;
  */
 export declare function useIdle(timeout?: number): boolean;
 
+/**
+ * React hook that resolves how (and whether) to offer PWA installation.
+ *
+ * It caches the `beforeinstallprompt` event, detects iOS/iPadOS, detects
+ * Android Chromium forks that lack the prompt API, detects standalone display
+ * mode, and applies a decline cooldown persisted in `localStorage`. The
+ * resulting `method` tells the UI which install affordance to render.
+ *
+ * The decline persistence is pluggable through
+ * {@link UseInstallPromptOptions.declineStorageKey} and
+ * {@link UseInstallPromptOptions.declineCooldownMs} — no app-specific storage
+ * layer is required, and it is SSR-guarded.
+ *
+ * @param options - Optional storage key, cooldown, and fallback-delay tuning.
+ * @returns The install state plus `install()` and `recordDecline()` actions.
+ *
+ * @example
+ * const { method, install } = useInstallPrompt();
+ * if (method === "native") return <button onClick={install}>Install</button>;
+ */
+export declare function useInstallPrompt(options?: UseInstallPromptOptions): UseInstallPromptResult;
+
+/** Options for {@link useInstallPrompt}. */
+export declare interface UseInstallPromptOptions {
+    /**
+     * `localStorage` key used to persist the decline timestamp. Defaults to
+     * `"tempest:install-declined-at"`.
+     */
+    declineStorageKey?: string;
+    /**
+     * How long, in ms, the install CTA stays hidden after the user declines.
+     * Defaults to 7 days.
+     */
+    declineCooldownMs?: number;
+    /**
+     * How long, in ms, to wait for a `beforeinstallprompt` event before
+     * resolving to the `"manual"` method. Defaults to `3000`.
+     */
+    manualFallbackDelayMs?: number;
+}
+
+/** State returned by {@link useInstallPrompt}. */
+export declare interface UseInstallPromptResult {
+    /** The cached `beforeinstallprompt` event, or `null` when unavailable. */
+    deferredPrompt: BeforeInstallPromptEvent | null;
+    /** True when the app can be installed through any supported method. */
+    canInstall: boolean;
+    /** True when running on iOS/iPadOS Safari. */
+    isIOS: boolean;
+    /** True when already running as an installed PWA. */
+    isStandalone: boolean;
+    /** True when the browser is an Android Chromium fork with no prompt API. */
+    isManualAndroid: boolean;
+    /** True when no `beforeinstallprompt` arrived within the timeout window. */
+    promptTimedOut: boolean;
+    /** The resolved install strategy the UI should follow. */
+    method: InstallMethod;
+    /** An `intent://` URL to re-open the page in Chrome on Android, else `null`. */
+    openInChromeIntent: string | null;
+    /**
+     * Triggers the native prompt.
+     *
+     * @returns `true` when the user accepted the install, `false` otherwise.
+     */
+    install: () => Promise<boolean>;
+    /** Records that the user declined the CTA, starting the cooldown window. */
+    recordDecline: () => void;
+}
+
 /**
  * Track whether the referenced element intersects the viewport. Useful for
  * lazy-loading images, "load more" sentinels, and animation triggers.
@@ -7006,6 +7223,52 @@ export { useLocation }
  */
 export declare function useLongPress<T extends HTMLElement>(ref: RefObject<T | null>, fn: () => void, options?: UseLongPressOptions): void;
 
+/**
+ * Returns DOM event handlers that detect a long press (touch or mouse hold)
+ * and invoke `onLongPress` once after `delayMs`.
+ *
+ * Cancels on touch movement or pointer release. Also wires `contextmenu` to
+ * fire `onLongPress` immediately so a right-click on desktop opens selection
+ * mode the same way an Android long-press does on mobile.
+ *
+ * The hook does not `preventDefault` on the underlying click — the consumer
+ * decides whether the subsequent click should still fire. Track that with the
+ * returned `wasLongPress()` guard to tell "long-press fired" apart from a
+ * "regular click".
+ *
+ * Unlike {@link useLongPress}, which attaches pointer listeners to a `ref`,
+ * this variant returns handler props you spread directly onto an element and
+ * exposes a `wasLongPress()` guard.
+ *
+ * @param onLongPress - Callback invoked once the hold threshold is reached.
+ * @param options - Optional `delayMs` and `disabled` flags.
+ * @returns The spreadable handlers plus a `wasLongPress()` guard.
+ *
+ * @example
+ * const longPress = useLongPressHandlers(() => enterSelectionMode(), { delayMs: 600 });
+ * <button {...longPress} onClick={() => { if (!longPress.wasLongPress()) navigate(); }}>
+ *   Item
+ * </button>
+ */
+export declare function useLongPressHandlers(onLongPress: () => void, options?: UseLongPressHandlersOptions): UseLongPressHandlersResult;
+
+/** Options accepted by {@link useLongPressHandlers}. */
+export declare interface UseLongPressHandlersOptions {
+    /** Hold duration in ms before `onLongPress` fires. Defaults to `500`. */
+    delayMs?: number;
+    /** When `true`, the hook is inert and every handler is a no-op. */
+    disabled?: boolean;
+}
+
+/** Return shape of {@link useLongPressHandlers}. */
+export declare type UseLongPressHandlersResult = LongPressHandlers & {
+    /**
+     * Reads whether the most recent interaction fired a long-press. Use it in
+     * the element's `onClick` to suppress the click that follows a long-press.
+     */
+    wasLongPress: () => boolean;
+};
+
 export declare interface UseLongPressOptions {
     /** Press duration in ms. Default `500`. */
     delay?: number;
@@ -8043,6 +8306,32 @@ export declare type WithSelectors<S> = S extends {
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
 
+/**
+ * Write a minimal single-sheet Office Open XML (`.xlsx`) workbook and return
+ * its bytes. No extra dependency beyond `fflate` — the archive is assembled and
+ * deflated in-process.
+ *
+ * The output is UTF-8 throughout, so accents round-trip in
+ * Excel/LibreOffice/Google Sheets without the BOM-detection fragility that
+ * plagues CSV exports. The XML stays compact: inline strings (no shared-string
+ * table), no styles, no merged cells. Numeric cells use the native `"n"` type
+ * so spreadsheets recognise them as numbers; `null` renders as an empty cell.
+ *
+ * @param headers - Column headers written as the first row.
+ * @param rows - Data rows; each value is a string, a number, or `null` (empty).
+ * @returns The `.xlsx` file contents as a `Uint8Array`.
+ *
+ * @example
+ * const bytes = writeXlsx(
+ *   ["Name", "Score"],
+ *   [["Ada", 99], ["Alan", null]],
+ * );
+ * const blob = new Blob([bytes], {
+ *   type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+ * });
+ */
+export declare function writeXlsx(headers: readonly string[], rows: readonly (readonly (string | number | null)[])[]): Uint8Array;
+
 /**
  * Minimal `react-hook-form` resolver built on top of zod. Mirrors the shape
  * produced by `@hookform/resolvers/zod` so it can be passed straight to