tempest-react-sdk 0.13.0 → 0.14.0

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

@@ -3054,6 +3054,63 @@ export declare interface InstallBackgroundSyncOptions {
     maxRetentionMinutes?: number;
 }
 
+/**
+ * Dismissible bottom banner that invites the user to install the PWA. Wired to
+ * {@link useBeforeInstallPrompt}: it renders only when the browser captured an
+ * install prompt and the app is not already running standalone — so on
+ * platforms that never fire `beforeinstallprompt` (e.g. iOS Safari) it stays
+ * hidden and you can surface manual instructions elsewhere.
+ *
+ * @example
+ * <InstallBanner
+ *     title="Instale o FAMACHApp"
+ *     description="Acesso offline e atalho na tela inicial."
+ *     storageKey="famacha:install-dismissed"
+ * />
+ */
+export declare function InstallBanner({ title, description, installLabel, dismissLabel, icon, storageKey, onResult, className, }: InstallBannerProps): JSX.Element | null;
+
+export declare interface InstallBannerProps {
+    /** Headline. Default `"Instale o app"`. */
+    title?: ReactNode;
+    /** Supporting copy under the title. */
+    description?: ReactNode;
+    /** Install button label. Default `"Instalar"`. */
+    installLabel?: string;
+    /** Accessible label for the dismiss button. Default `"Dispensar"`. */
+    dismissLabel?: string;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+    /**
+     * `localStorage` key used to remember dismissal across reloads. Omit to
+     * make dismissal last only for the current session (component state).
+     */
+    storageKey?: string;
+    /** Called with the user's choice after the install prompt resolves. */
+    onResult?: (outcome: InstallOutcome) => void;
+    className?: string;
+}
+
+/**
+ * Button wired to the PWA install prompt ({@link useBeforeInstallPrompt}).
+ * Renders nothing when the app can't be installed — no prompt captured yet,
+ * already installed, or running standalone — so you can drop it anywhere
+ * without guarding visibility yourself.
+ *
+ * Inherits every {@link Button} prop (`variant`, `size`, `leftIcon`, …).
+ *
+ * @example
+ * <InstallButton variant="primary" leftIcon={<Download />} />
+ */
+export declare function InstallButton({ label, onResult, ...props }: InstallButtonProps): JSX.Element | null;
+
+export declare interface InstallButtonProps extends Omit<ButtonProps, "onClick" | "children"> {
+    /** Button label. Default `"Instalar app"`. */
+    label?: ReactNode;
+    /** Called with the user's choice after the install prompt resolves. */
+    onResult?: (outcome: InstallOutcome) => void;
+}
+
 /**
  * Install a `notificationclick` handler that focuses an existing client when
  * possible and falls back to opening a new window.
@@ -3065,6 +3122,8 @@ export declare interface InstallNotificationClickHandlerOptions {
     resolveUrl?: (data: unknown) => string;
 }
 
+export declare type InstallOutcome = "accepted" | "dismissed" | "unsupported";
+
 /**
  * Precache the app shell at `install` and serve it offline:
  *  - reads `precache-manifest.json` (emitted by `tempestPwaManifest()`),
@@ -4993,13 +5052,33 @@ export declare interface SpacerProps extends HTMLAttributes<HTMLDivElement> {
     axis?: SpacerAxis;
 }
 
-/** Loading spinner with preset sizes (xs..xl). Provide `label` for screen readers. */
-export declare function Spinner({ size, className, label }: SpinnerProps): JSX.Element;
+/**
+ * Loading spinner with preset sizes (xs..xl). Provide `label` for screen
+ * readers, `caption` for a visible message, and `overlay` to center it inside a
+ * full-area container (e.g. a Suspense / route fallback).
+ *
+ * @example
+ * <Spinner />
+ * <Spinner size="lg" caption="Carregando…" overlay />
+ */
+export declare function Spinner({ size, className, label, caption, overlay, }: SpinnerProps): JSX.Element;
 
 export declare interface SpinnerProps {
     size?: SpinnerSize;
     className?: string;
+    /** Accessible label announced by screen readers. */
     label?: string;
+    /**
+     * Visible caption rendered under the spinner. When set, the spinner and
+     * caption are wrapped in a centered column.
+     */
+    caption?: ReactNode;
+    /**
+     * Center the spinner inside a full-area overlay (fills the nearest
+     * positioned ancestor; pair with a relative container or a route fallback).
+     * Implies the wrapped layout.
+     */
+    overlay?: boolean;
 }
 
 export declare type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
@@ -5411,7 +5490,7 @@ export declare type ThemeMode = "light" | "dark" | "system";
  * Pair with `themeInitScript()` in the HTML head to prevent the flash of
  * incorrect theme on first paint.
  */
-export declare function ThemeProvider({ children, defaultTheme, storageKey, target, attribute, }: ThemeProviderProps): JSX.Element;
+export declare function ThemeProvider({ children, defaultTheme, storageKey, target, attribute, themeColor, }: ThemeProviderProps): JSX.Element;
 
 export declare interface ThemeProviderProps {
     children: ReactNode;
@@ -5420,12 +5499,30 @@ export declare interface ThemeProviderProps {
     /** localStorage key used to persist the preference. Pass `null` to disable persistence. Default: `"tempest-theme"`. */
     storageKey?: string | null;
     /**
-     * Element that receives the `data-tempest-theme` attribute. Defaults to
+     * Element that receives the theme attribute(s). Defaults to
      * `document.documentElement`. Override when scoping the theme to a subtree.
      */
     target?: () => HTMLElement | null;
-    /** Attribute name written on the target. Default: `"data-tempest-theme"`. */
-    attribute?: string;
+    /**
+     * Attribute name(s) written on the target with the resolved theme
+     * (`"light"` / `"dark"`). Default: `"data-tempest-theme"`.
+     *
+     * Pass an array to mirror the theme onto more than one attribute — handy
+     * when the SDK components read `data-tempest-theme` but the host app's own
+     * CSS keys off a different attribute (e.g. `["data-tempest-theme",
+     * "data-theme"]`). Avoids a separate sync effect in the consumer.
+     */
+    attribute?: string | string[];
+    /**
+     * When set, keeps `<meta name="theme-color">` in sync with the resolved
+     * theme — `content` becomes `themeColor.dark` in dark mode and
+     * `themeColor.light` in light mode. The meta tag must already exist in the
+     * document `<head>`. No-op when omitted.
+     */
+    themeColor?: {
+        light: string;
+        dark: string;
+    };
 }
 
 /**
@@ -5826,6 +5923,12 @@ export declare interface UseBeforeInstallPromptResult {
     installable: boolean;
     /** True after the user accepts the install prompt. */
     installed: boolean;
+    /**
+     * True when the app is already running as an installed PWA (display-mode
+     * `standalone`/`fullscreen`/`minimal-ui`, or iOS `navigator.standalone`).
+     * Use it to hide install affordances for users who already installed.
+     */
+    isStandalone: boolean;
     /** Show the install prompt. Resolves with the user's choice. */
     prompt: () => Promise<"accepted" | "dismissed" | "unsupported">;
 }