tempest-react-sdk 0.12.0 → 0.14.0

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

@@ -243,6 +243,66 @@ export declare interface ApiError {
     body?: unknown;
 }
 
+/**
+ * Mobile-first top app bar for PWAs — leading (back / brand) + title +
+ * trailing actions, sticky with safe-area padding out of the box.
+ *
+ * Consumers customise via tokens (`--tempest-*`) and slots; the SDK ships the
+ * layout, sticky/safe-area behaviour, and accessible back button so apps don't
+ * hand-roll one per screen. For a desktop three-slot nav use [[Navbar]].
+ *
+ * @example
+ * // Detail screen with back + a trailing action
+ * <AppBar
+ *     title="Profile"
+ *     showBack
+ *     onBack={() => navigate(-1)}
+ *     actions={<IconButton icon={<Settings />} onClick={openSettings} />}
+ * />
+ *
+ * @example
+ * // Home screen — brand left, centered title disabled
+ * <AppBar brand={<Logo />} actions={<UserMenu />} />
+ */
+export declare function AppBar({ title, leading, showBack, onBack, backLabel, backIcon, brand, actions, centered, sticky, tone, bordered, safeArea, className, ...props }: AppBarProps): JSX.Element;
+
+export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Page title — string or any node. Rendered as the bar's `<h1>`. */
+    title?: ReactNode;
+    /**
+     * Replace the whole left slot. When set, the auto back button and `brand`
+     * are ignored — you own the leading content.
+     */
+    leading?: ReactNode;
+    /** Show a back button in the left slot. Ignored when `leading` is set. */
+    showBack?: boolean;
+    /**
+     * Back-button handler. Defaults to `window.history.back()`. With a router,
+     * pass `onBack={() => navigate(-1)}`.
+     */
+    onBack?: () => void;
+    /** Accessible label for the back button. Default `"Go back"`. */
+    backLabel?: string;
+    /** Custom back icon. Default a left arrow. */
+    backIcon?: ReactNode;
+    /** Brand / logo node shown in the left slot (after the back button). */
+    brand?: ReactNode;
+    /** Right slot — action buttons / menu. One node or many. */
+    actions?: ReactNode;
+    /** Center the title (three-column grid). Default `false` (left-aligned). */
+    centered?: boolean;
+    /** Stick to the top of the scroll container. Default `true`. */
+    sticky?: boolean;
+    /** Visual tone. Default `"surface"`. */
+    tone?: AppBarTone;
+    /** Thin bottom border. Default `true`. */
+    bordered?: boolean;
+    /** Add `env(safe-area-inset-top)` padding (iOS notch / PWA). Default `true`. */
+    safeArea?: boolean;
+}
+
+export declare type AppBarTone = "surface" | "primary" | "transparent";
+
 /**
  * Compose the Tempest app-wide providers in one place: error boundary →
  * TanStack Query → theme → i18n. Query and theme are on by default; i18n and
@@ -2994,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.
@@ -3005,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()`),
@@ -4933,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";
@@ -5351,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;
@@ -5360,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;
+    };
 }
 
 /**
@@ -5766,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">;
 }