tempest-react-sdk 0.22.0 → 0.23.0

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

@@ -789,6 +789,25 @@ export declare const CACHE_TIME: {
     readonly LONG: number;
 };
 
+/** A cache-name matcher: a prefix string, a `RegExp`, or a predicate. */
+export declare type CacheFilter = string | RegExp | ((name: string) => boolean);
+
+/**
+ * Main-thread helpers to inspect and clear the Cache Storage buckets a service
+ * worker fills — for a "X MB cacheado" readout and a "limpar cache" action
+ * (e.g. on logout). All guard `caches` so they no-op safely under SSR / older
+ * browsers.
+ */
+/** Per-cache usage summary returned by {@link inspectCaches}. */
+export declare interface CacheReport {
+    /** The Cache Storage bucket name. */
+    name: string;
+    /** Number of cached responses. */
+    entries: number;
+    /** Approximate total bytes, or `null` when byte measurement was skipped. */
+    bytes: number | null;
+}
+
 /**
  * Standalone month-grid date picker. Renders a header with the month/year and
  * prev/next buttons, a weekday row, and a 6x7 grid of day buttons. Selection and
@@ -987,8 +1006,12 @@ export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInpu
 /**
  * Multi-value input. Type a value and press Enter (or comma / Tab) to push a
  * chip. Backspace on empty input removes the last chip.
+ *
+ * Name the field with `label` (associated through `htmlFor`) or, when the label
+ * lives elsewhere in the layout, with `aria-label`. The placeholder is not an
+ * accessible name — it disappears as soon as the first chip is added.
  */
-export declare function ChipInput({ value, onChange, label, placeholder, helperText, error, commitKeys, normalize, className, }: ChipInputProps): JSX.Element;
+export declare function ChipInput({ value, onChange, label, placeholder, helperText, error, commitKeys, normalize, className, id, "aria-label": ariaLabel, }: ChipInputProps): JSX.Element;
 
 export declare interface ChipInputProps {
     value: string[];
@@ -997,6 +1020,13 @@ export declare interface ChipInputProps {
     placeholder?: string;
     helperText?: string;
     error?: string;
+    /** Id for the inner input. Generated when omitted. */
+    id?: string;
+    /**
+     * Accessible name for the inner input when there is no visible `label`.
+     * Without either, screen readers announce an unnamed text field.
+     */
+    "aria-label"?: string;
     /** Keys that commit the current draft as a chip. Default: Enter, comma, Tab. */
     commitKeys?: string[];
     /** Lowercase + trim each chip + dedupe. Default: true. */
@@ -1036,6 +1066,18 @@ export declare function clampLatitude(latitude: number): number;
 
 declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
 
+/**
+ * Delete Cache Storage buckets whose name passes `filter` (all of them when no
+ * filter is given).
+ *
+ * @param filter - Which caches to delete.
+ * @returns The names of the caches that were deleted.
+ *
+ * @example
+ * await clearCaches("tempest-"); // drop every SDK-managed cache on logout
+ */
+export declare function clearCaches(filter?: CacheFilter): Promise<string[]>;
+
 /**
  * Wraps its children in a `<div>` and invokes `onOutside` whenever a
  * `mousedown` or `touchstart` event occurs outside that subtree.
@@ -2106,6 +2148,11 @@ export declare interface DataProviderOptions {
  * - Search matches a case-insensitive substring across `searchKeys`
  *   (or every string/number column when not provided).
  * - Pagination is hidden when the result fits on a single page.
+ *
+ * The header memo depends on `columns` and `sort` only: `toggleSort` is
+ * recreated each render but always closes over the same setter, so including it
+ * would rebuild every header on every render without changing behaviour. That
+ * is why `exhaustive-deps` is silenced on that dependency array.
  */
 export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, initialSort, rowKey, emptyMessage, className, ...rest }: DataTableProps<T>): JSX.Element;
 
@@ -2572,6 +2619,13 @@ export declare interface ErrorTextProps extends HTMLAttributes<HTMLParagraphElem
 
 export declare function estimatePasswordStrength(value: string): PasswordStrength;
 
+/**
+ * Read the origin's current storage usage and quota.
+ *
+ * @returns The estimate, or `{ usage: null, quota: null }` when unsupported.
+ */
+export declare function estimateStorage(): Promise<StorageEstimate_2>;
+
 /**
  * Offline travel estimate between two coordinates. No network — distance comes
  * from {@link haversineKm} scaled by circuity, duration from a mode-adjusted
@@ -3218,6 +3272,24 @@ export declare interface HideProps {
     children: ReactNode;
 }
 
+/**
+ * Resolve a conflict by keeping whichever record carries the higher version
+ * number (monotonic counter / row version). The remote record wins ties.
+ *
+ * @typeParam T - The record shape.
+ * @param local - The current local record, or `undefined` when new.
+ * @param remote - The incoming remote record.
+ * @param getVersion - Reads the monotonic version number.
+ * @returns The winning record.
+ *
+ * @example
+ * applyRemote: async (dto) => {
+ *     const local = await store.get(dto.id);
+ *     await store.save(higherVersionWins(local, dto, (r) => r.version));
+ * }
+ */
+export declare function higherVersionWins<T>(local: T | undefined, remote: T, getVersion: (record: T) => number): T;
+
 /**
  * Content preview shown when the trigger is hovered or focused.
  *
@@ -3343,6 +3415,24 @@ export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputEl
 
 export declare type InputSize = "sm" | "md" | "lg";
 
+/**
+ * Report entry counts (and optionally byte sizes) for the Cache Storage
+ * buckets whose name passes `filter`.
+ *
+ * @param options - `filter` narrows which caches to include; `measureBytes`
+ *   (default `true`) reads each response to sum sizes — set `false` for a fast,
+ *   count-only report.
+ * @returns One {@link CacheReport} per matching cache. Empty when unsupported.
+ *
+ * @example
+ * const reports = await inspectCaches({ filter: "tempest-" });
+ * const totalMb = reports.reduce((n, r) => n + (r.bytes ?? 0), 0) / 1e6;
+ */
+export declare function inspectCaches(options?: {
+    filter?: CacheFilter;
+    measureBytes?: boolean;
+}): Promise<CacheReport[]>;
+
 /**
  * Install the background-sync queue: on a failed mutating request, the request
  * is serialized to IndexedDB and a sync is registered; the original fetch still
@@ -3377,6 +3467,13 @@ export declare interface InstallBackgroundSyncOptions {
     queueName?: string;
     /** Drop queued requests older than this (minutes) on replay. Default `1440` (24h). */
     maxRetentionMinutes?: number;
+    /**
+     * Also drain the queue on the `periodicsync` event carrying this tag,
+     * complementing the one-off `sync` replay so long-pending mutations retry
+     * even without a fresh navigation. Register the periodic sync from the main
+     * thread with {@link registerPeriodicSync}. Default `${queueName}-periodic`.
+     */
+    periodicSyncTag?: string;
 }
 
 /**
@@ -3484,6 +3581,13 @@ export declare interface InstallPrecacheOptions {
     navigateFallbackDenylist?: RegExp[];
     /** Activate the new worker immediately after precaching. Default `true`. */
     skipWaiting?: boolean;
+    /**
+     * Enable the Navigation Preload API on `activate`, so the browser fetches
+     * the navigation request in parallel with the worker boot and the handler
+     * serves `event.preloadResponse` — cutting first-navigation latency after
+     * the worker starts. Silently ignored where unsupported. Default `true`.
+     */
+    navigationPreload?: boolean;
 }
 
 /**
@@ -3729,6 +3833,31 @@ export declare interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement
     required?: boolean;
 }
 
+/**
+ * Conflict-resolution helpers for the `applyRemote` callback of
+ * {@link createOfflineSync}. Each takes the current local record (or
+ * `undefined` when the record is new locally) and the incoming remote record,
+ * and returns the winner. Ties resolve to the remote copy, treating the server
+ * as authoritative.
+ */
+/**
+ * Resolve a conflict by keeping whichever record was written last, comparing a
+ * timestamp field. The remote record wins ties.
+ *
+ * @typeParam T - The record shape.
+ * @param local - The current local record, or `undefined` when new.
+ * @param remote - The incoming remote record.
+ * @param getTimestamp - Reads the comparison timestamp (epoch ms, ISO string or `Date`).
+ * @returns The winning record.
+ *
+ * @example
+ * applyRemote: async (dto) => {
+ *     const local = await store.get(dto.id);
+ *     await store.save(lastWriteWins(local, dto, (r) => r.updatedAt));
+ * }
+ */
+export declare function lastWriteWins<T>(local: T | undefined, remote: T, getTimestamp: (record: T) => number | string | Date): T;
+
 declare interface LayoutProps {
     /** Field arrangement. `stack` stacks fields vertically, `inline` lines them up in a wrapping row, `grid` arranges them in `columns` equal-width tracks. Default `stack`. */
     layout?: FormLayout;
@@ -3980,8 +4109,13 @@ export declare type Messages = Record<string, string>;
 /**
  * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
  * header/body/footer. Locks body scroll while open.
+ *
+ * The `dialog` role needs an accessible name: a `title` supplies it via
+ * `aria-labelledby`, and a titleless dialog should pass `aria-label`. The
+ * header heading is only rendered when there is a title, so a close-button-only
+ * header does not leave an empty `h3` behind.
  */
-export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, }: ModalProps): ReactPortal | null;
+export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, "aria-label": ariaLabel, }: ModalProps): ReactPortal | null;
 
 export declare interface ModalProps {
     open: boolean;
@@ -3998,6 +4132,11 @@ export declare interface ModalProps {
     fullscreen?: boolean;
     /** Auto-fullscreen on mobile viewports (< 640px). Default `false`. */
     fullscreenOnMobile?: boolean;
+    /**
+     * Accessible name for the dialog. Only needed when there is no `title` —
+     * with a `title` the dialog is named by it through `aria-labelledby`.
+     */
+    "aria-label"?: string;
 }
 
 /** Imperative API returned by {@link useModals}. */
@@ -4103,6 +4242,10 @@ export declare interface MultiSelectProps {
     className?: string;
 }
 
+declare interface MutationContext<TData> {
+    previous: TData | undefined;
+}
+
 /**
  * Top app bar. Three-slot layout (logo / nav / actions) that collapses
  * gracefully on mobile (nav slot wraps below).
@@ -4311,6 +4454,67 @@ export declare interface OAuthError {
     raw?: unknown;
 }
 
+/**
+ * Fixed bar that appears while the browser is offline and, by default, flashes
+ * a brief confirmation when the connection returns. Backed by {@link useOnline}
+ * — no props needed for the common case.
+ *
+ * Renders nothing while online (after any flash has elapsed), so it is safe to
+ * mount unconditionally at the app root.
+ *
+ * @example
+ * <OfflineIndicator position="top" />
+ */
+export declare function OfflineIndicator({ position, offlineLabel, onlineLabel, onlineFlashMs, className, children, ...props }: OfflineIndicatorProps): JSX.Element | null;
+
+export declare type OfflineIndicatorPosition = "top" | "bottom";
+
+export declare interface OfflineIndicatorProps extends HTMLAttributes<HTMLDivElement> {
+    /** Where to pin the fixed bar. Default `"bottom"`. */
+    position?: OfflineIndicatorPosition;
+    /** Message shown while offline. */
+    offlineLabel?: ReactNode;
+    /** Message flashed briefly when connectivity returns. */
+    onlineLabel?: ReactNode;
+    /**
+     * How long (ms) to keep the "back online" flash visible. `0` hides it
+     * entirely. Default `3000`.
+     */
+    onlineFlashMs?: number;
+    /** Override the offline body entirely (icon + label ignored). */
+    children?: ReactNode;
+}
+
+/** Handle returned by {@link persistQueryClientOffline}. */
+export declare interface OfflineQueryPersistence {
+    /**
+     * Load the persisted snapshot into the `QueryClient`. Call once on boot,
+     * before rendering queries, so cached data is available offline.
+     */
+    restore: () => Promise<void>;
+    /** Write the current cache snapshot immediately (bypassing the throttle). */
+    flush: () => Promise<void>;
+    /** Stop persisting and drop the pending write. */
+    unsubscribe: () => void;
+    /** Delete the persisted snapshot (e.g. on logout). */
+    clear: () => Promise<void>;
+}
+
+/** Options for {@link persistQueryClientOffline}. */
+export declare interface OfflineQueryPersistenceOptions {
+    /** The `QueryClient` to snapshot and restore. */
+    queryClient: QueryClient;
+    /** IndexedDB database name for the snapshot. Default `"TempestQueryCache"`. */
+    databaseName?: string;
+    /** Row key under which the snapshot is stored. Default `"tanstack-query"`. */
+    key?: string;
+    /**
+     * Minimum gap between snapshot writes, in ms — cache churn is coalesced into
+     * one trailing write per window. Default `1000`.
+     */
+    throttleMs?: number;
+}
+
 export declare interface OfflineStore<TItem, TKey extends string | number> {
     /** Insert or replace a record. */
     put: (item: TItem, owner?: string) => Promise<TKey>;
@@ -4388,6 +4592,23 @@ export declare interface OfflineSync<TPayload> {
     clearOutbox: () => Promise<void>;
     /** Reset the pull watermark (e.g. on logout / account switch). */
     resetWatermark: () => void;
+    /** Read the current reactive {@link SyncState} snapshot synchronously. */
+    getState: () => SyncState;
+    /**
+     * Subscribe to {@link SyncState} changes. The listener fires on every
+     * enqueue, flush transition and outbox clear.
+     *
+     * @param listener - Called with the new snapshot on each change.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (listener: (state: SyncState) => void) => () => void;
+    /**
+     * Release resources held by the engine — currently the cross-tab
+     * `BroadcastChannel` when `crossTab` is enabled. Safe to call when none was
+     * opened. Optional in long-lived apps (the channel is reclaimed on tab
+     * close); call it in tests and on teardown.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -4436,6 +4657,22 @@ export declare interface OfflineSyncConfig<TPayload, TRemote> {
      * non-browser environments). When it returns `false`, `flush` is skipped.
      */
     isOnline?: () => boolean;
+    /**
+     * Broadcast {@link SyncState} across browser tabs of the same origin via a
+     * `BroadcastChannel`, so every tab shows a coherent pending count / phase
+     * (e.g. one tab flushing drops the badge to zero everywhere). The outbox is
+     * already a shared IndexedDB; this only shares the in-memory state. Silently
+     * ignored where `BroadcastChannel` is unavailable. Default `false`.
+     *
+     * When the Web Locks API is available, `flush` is additionally coordinated
+     * *across* tabs: only one tab runs at a time and others skip while the lock
+     * is held (they pick up the result via the broadcast). Delivery should still
+     * be idempotent (upsert by client id). Without Web Locks, `flush` falls back
+     * to per-tab single-flight.
+     */
+    crossTab?: boolean;
+    /** Channel name when `crossTab` is on. Default `tempest-sync:${databaseName}`. */
+    broadcastChannelName?: string;
 }
 
 /** Offset-paginated response envelope (fastapi-pagination `Page[T]`). */
@@ -4526,6 +4763,16 @@ export declare interface OSRMBackendOptions {
     modeDurationFactors?: Partial<Record<TravelMode, number>>;
 }
 
+/** The outbox entry a mutation's variables map to. */
+export declare interface OutboxDraft<TPayload> {
+    /** The mutation kind. */
+    op: OutboxOp;
+    /** Primary key of the affected record. */
+    recordId: string;
+    /** Record snapshot for `create`/`update` (omit for `delete`). */
+    payload?: TPayload;
+}
+
 /**
  * A single queued mutation.
  *
@@ -4689,6 +4936,27 @@ export declare interface PermissionsFromTokenOptions {
     claim?: string;
 }
 
+/**
+ * Persist a TanStack `QueryClient` cache to IndexedDB (via
+ * {@link createOfflineStore}) and restore it on boot — so a reload or a cold
+ * offline start shows the last-known data instead of empty screens.
+ *
+ * Self-contained: uses `dehydrate`/`hydrate` from `@tanstack/react-query`
+ * directly, so no `@tanstack/react-query-persist-client` dependency is needed.
+ * Writes are throttled and subscribe to the query cache; call `unsubscribe` on
+ * teardown. Dexie is a peer dependency of the offline store — install it.
+ *
+ * @param options - The client plus storage/throttle configuration.
+ * @returns A handle with `restore`, `flush`, `clear` and `unsubscribe`.
+ *
+ * @example
+ * const persistence = persistQueryClientOffline({ queryClient });
+ * await persistence.restore(); // before first render
+ * // ... later, on logout:
+ * await persistence.clear();
+ */
+export declare function persistQueryClientOffline(options: OfflineQueryPersistenceOptions): OfflineQueryPersistence;
+
 export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
@@ -4873,8 +5141,13 @@ export declare interface PostHogLike {
     reset?: () => void;
 }
 
-/** Linear progress bar with determinate / indeterminate modes. */
-export declare function Progress({ value, max, variant, indeterminate, showLabel, label, className, }: ProgressProps): JSX.Element;
+/**
+ * Linear progress bar with determinate / indeterminate modes.
+ *
+ * The `progressbar` role requires an accessible name: it comes from
+ * `aria-labelledby`, then explicit `aria-label`, then the visible `label`.
+ */
+export declare function Progress({ value, max, variant, indeterminate, showLabel, label, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, }: ProgressProps): JSX.Element;
 
 export declare interface ProgressProps {
     /** Value between 0 and `max` (or 0-100 by default). Ignored when `indeterminate`. */
@@ -4887,6 +5160,14 @@ export declare interface ProgressProps {
     showLabel?: boolean;
     /** Optional left-aligned descriptor (e.g. "Enviando arquivo…"). */
     label?: string;
+    /**
+     * Accessible name for the bar. Defaults to `label` when that is set —
+     * provide it explicitly whenever the bar renders without a visible label,
+     * otherwise screen readers announce an unnamed progressbar.
+     */
+    "aria-label"?: string;
+    /** Id of an existing element that names the bar (alternative to `aria-label`). */
+    "aria-labelledby"?: string;
     className?: string;
 }
 
@@ -5102,6 +5383,42 @@ export declare interface RefreshIndicatorProps {
     className?: string;
 }
 
+/**
+ * Request a Periodic Background Sync registration.
+ *
+ * Checks the `periodic-background-sync` permission first and only registers
+ * when it is granted, so calling this unconditionally is safe. The browser
+ * ultimately decides whether and how often the `periodicsync` event fires.
+ *
+ * @param options - The registration, tag and interval.
+ * @returns `true` when the periodic sync was registered, else `false`
+ *   (unsupported, permission denied, or registration threw).
+ *
+ * @example
+ * const reg = await navigator.serviceWorker.ready;
+ * await registerPeriodicSync({ registration: reg, minIntervalMinutes: 360 });
+ */
+export declare function registerPeriodicSync(options: RegisterPeriodicSyncOptions): Promise<boolean>;
+
+/**
+ * Main-thread helper to register a Periodic Background Sync, the counterpart to
+ * the `periodicsync` listener installed by `installBackgroundSync`. Chrome-only
+ * and gated behind the `periodic-background-sync` permission plus a site
+ * engagement heuristic; degrades to a no-op (returns `false`) everywhere else.
+ */
+/** Options for {@link registerPeriodicSync}. */
+export declare interface RegisterPeriodicSyncOptions {
+    /** The active service-worker registration. */
+    registration: ServiceWorkerRegistration;
+    /** Sync tag; must match `installBackgroundSync`'s `periodicSyncTag`. Default `tempest-bg-sync-periodic`. */
+    tag?: string;
+    /**
+     * Minimum interval between runs, in minutes. The browser treats this as a
+     * floor and may space runs out much further. Default `720` (12h).
+     */
+    minIntervalMinutes?: number;
+}
+
 /**
  * Register a service worker with consistent update-detection wiring.
  *
@@ -5190,6 +5507,24 @@ export declare interface RelativeTimeProps extends HTMLAttributes<HTMLTimeElemen
     locale?: "pt" | "en";
 }
 
+/**
+ * Build an `applyOptimistic` that removes the entry matching the item's id
+ * (by `idField`) from the list. For `delete` mutations, pass variables carrying
+ * at least the id field.
+ *
+ * @typeParam T - The list item shape.
+ * @param idField - The identity field. Default `"id"`.
+ * @returns An `(current, item) => T[]` patcher for a list cache.
+ *
+ * @example
+ * useOfflineMutation<{ id: string }, Note[], Note>({
+ *     sync, queryKey: ["notes"],
+ *     toEntry: ({ id }) => ({ op: "delete", recordId: id }),
+ *     applyOptimistic: removeById(),
+ * });
+ */
+export declare function removeById<T, V extends Partial<Record<keyof T, unknown>> = T>(idField?: keyof T): (current: T[] | undefined, item: V) => T[];
+
 export declare interface ReorderPayload {
     from: number;
     to: number;
@@ -5200,6 +5535,17 @@ export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     params?: Record<string, string | number | boolean | undefined | null>;
 }
 
+/**
+ * Ask the browser to make this origin's storage persistent, so IndexedDB and
+ * the Cache Storage are not silently evicted under disk pressure — essential
+ * for durable offline-first data.
+ *
+ * The browser may grant silently, prompt, or deny based on engagement heuristics.
+ *
+ * @returns `true` when storage is (now or already) persisted, else `false`.
+ */
+export declare function requestPersistentStorage(): Promise<boolean>;
+
 /**
  * A two-pane split layout with a draggable divider. The first pane is sized via
  * `flex-basis` as a percentage; the second pane fills the rest. Drag the divider
@@ -5879,6 +6225,15 @@ export declare const storage: {
     remove(key: string): void;
 };
 
+/** Raw usage/quota reading from the Storage API, in bytes. */
+declare interface StorageEstimate_2 {
+    /** Bytes currently used by this origin, or `null` when unknown. */
+    usage: number | null;
+    /** Total bytes available to this origin, or `null` when unknown. */
+    quota: number | null;
+}
+export { StorageEstimate_2 as StorageEstimate }
+
 export { SubmitHandler }
 
 /** Toggle switch backed by a checkbox input. Accessible via keyboard. */
@@ -5889,6 +6244,17 @@ export declare interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputE
     wrapperClassName?: string;
 }
 
+/**
+ * Coarse lifecycle phase of the sync engine, surfaced through
+ * {@link OfflineSync.getState} / {@link OfflineSync.subscribe} for reactive UI.
+ *
+ * - `"idle"` — nothing in flight and the last run (if any) fully succeeded.
+ * - `"syncing"` — a `flush` run is currently in progress.
+ * - `"offline"` — the last run was skipped because the device was offline.
+ * - `"error"` — the last run left at least one entry queued after a failure.
+ */
+export declare type SyncPhase = "idle" | "syncing" | "offline" | "error";
+
 /** Outcome of a single {@link OfflineSync.flush} run. */
 export declare interface SyncRunSummary {
     /** The trigger passed to `flush`. */
@@ -5901,8 +6267,91 @@ export declare interface SyncRunSummary {
     durationMs: number;
     /** `true` when the run was skipped because the device was offline. */
     skipped: boolean;
+    /** Last delivery error message seen this run, or `null` when none failed. */
+    lastError: string | null;
+}
+
+/**
+ * Immutable snapshot of the engine's reactive state. A fresh object is emitted
+ * to subscribers on every change, so it is safe to use as a
+ * `useSyncExternalStore` snapshot (reference equality signals "no change").
+ */
+export declare interface SyncState {
+    /** Current lifecycle phase. */
+    phase: SyncPhase;
+    /** Number of mutations still queued in the outbox. */
+    pending: number;
+    /** Summary of the most recent `flush` run, or `null` before the first. */
+    lastSummary: SyncRunSummary | null;
+    /** Message of the most recent delivery failure, or `null`. */
+    lastError: string | null;
+    /** Epoch ms of the last non-skipped run, or `null` before the first. */
+    lastSyncedAt: number | null;
 }
 
+/**
+ * Compact status snapshot for a status badge/pill. Prefer this over
+ * {@link useOfflineSync} when a component only needs to *display* status and
+ * does not trigger flushes itself.
+ */
+export declare interface SyncStatus {
+    /** The dominant tone to render. */
+    tone: SyncTone;
+    /** Number of mutations still queued. */
+    pending: number;
+    /** `true` while a flush run is in progress. */
+    syncing: boolean;
+    /** `true` when the last run was skipped for being offline. */
+    offline: boolean;
+    /** Message of the most recent delivery failure, or `null`. */
+    lastError: string | null;
+}
+
+/**
+ * Compact pill showing offline-sync status: a tone-colored icon plus a label
+ * and optional pending count.
+ *
+ * Two modes: pass `sync` to have the badge observe an engine via
+ * `useSyncStatus` (zero wiring), or pass an explicit `tone` (+ `pending`) to
+ * keep it presentational and testable without IndexedDB.
+ *
+ * @example
+ * // Connected — auto-wires the engine:
+ * <SyncStatusBadge sync={notesSync} />
+ *
+ * // Presentational — you own the state:
+ * const { tone, pending } = useSyncStatus(notesSync);
+ * <SyncStatusBadge tone={tone} pending={pending} />
+ */
+export declare function SyncStatusBadge({ sync, ...rest }: SyncStatusBadgeProps): JSX.Element;
+
+export declare interface SyncStatusBadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /**
+     * The dominant tone. Required when `sync` is not passed. Ignored when `sync`
+     * is passed (the tone is derived from the engine).
+     */
+    tone?: SyncTone;
+    /**
+     * An `OfflineSync` engine to observe directly. When set, the badge wires
+     * `useSyncStatus` internally, so `tone` and `pending` come from the engine.
+     */
+    sync?: OfflineSync<unknown>;
+    /** Number of queued mutations, appended to the label when `> 0`. */
+    pending?: number;
+    /** Override the per-tone label text. */
+    labels?: Partial<Record<SyncTone, string>>;
+    /** Show the pending count next to the label. Default `true`. */
+    showPending?: boolean;
+    /** Render only the icon (no text). Default `false`. */
+    iconOnly?: boolean;
+}
+
+/**
+ * Presentation-ready tone for a sync status indicator. Collapses the engine's
+ * {@link SyncState} into the single most relevant signal for a badge/pill.
+ */
+export declare type SyncTone = "idle" | "syncing" | "pending" | "offline" | "error";
+
 /**
  * Why a sync run was triggered. The listed values are the common ones; any
  * string is accepted so apps can add their own telemetry labels.
@@ -6362,6 +6811,9 @@ export declare function ToggleGroup({ type, value, defaultValue, onValueChange,
  * A single selectable item inside a {@link ToggleGroup}. Reads and updates the
  * group's shared state through context.
  *
+ * Icon-only items need an explicit `aria-label` (forwarded to the button):
+ * an SVG child gives screen readers nothing to announce.
+ *
  * @param props - {@link ToggleGroupItemProps}.
  * @returns A `role="button"` element exposing its state via `aria-pressed`.
  */
@@ -6585,6 +7037,36 @@ export declare function unprojectMercator(point: MercatorPoint): Coordinate;
  */
 export declare function unregisterAllServiceWorkers(): Promise<number>;
 
+/**
+ * Fixed toast prompting the user to activate a freshly installed service
+ * worker. Presentational — pair with {@link useServiceWorkerUpdate}, feeding
+ * `updateAvailable` to `open` and `applyUpdate` to `onUpdate`.
+ *
+ * Renders nothing while `open` is `false`.
+ *
+ * @example
+ * const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
+ * <UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />
+ */
+export declare function UpdatePrompt({ open, onUpdate, onDismiss, message, actionLabel, position, className, ...props }: UpdatePromptProps): JSX.Element | null;
+
+export declare type UpdatePromptPosition = "top" | "bottom";
+
+export declare interface UpdatePromptProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Whether the prompt is visible. Feed from `useServiceWorkerUpdate().updateAvailable`. */
+    open: boolean;
+    /** Called when the user confirms the update. Wire to `applyUpdate`. */
+    onUpdate: () => void;
+    /** Called when the user dismisses the prompt. Omit to hide the dismiss button. */
+    onDismiss?: () => void;
+    /** Body message. */
+    message?: ReactNode;
+    /** Confirm button label. Default `"Atualizar"`. */
+    actionLabel?: string;
+    /** Where to pin the fixed toast. Default `"bottom"`. */
+    position?: UpdatePromptPosition;
+}
+
 /** Variables accepted by the update mutation. */
 export declare interface UpdateVariables {
     /** The record id to update. */
@@ -6636,6 +7118,30 @@ export declare interface UploadWithProgressOptions {
     requestId?: () => string;
 }
 
+/**
+ * Ready-made `applyOptimistic` builders for {@link useOfflineMutation} over a
+ * list-shaped query cache (`TData = T[]`). They cover the two most common
+ * optimistic edits — insert-or-update and remove — so callers stop hand-writing
+ * the array spread. Both compare records by an id field (`"id"` by default) and
+ * treat the mutation variables as the record itself.
+ */
+/**
+ * Build an `applyOptimistic` that inserts the item when absent or shallow-merges
+ * it into the existing entry (matched by `idField`). New items append to the end.
+ *
+ * @typeParam T - The list item shape.
+ * @param idField - The identity field. Default `"id"`.
+ * @returns An `(current, item) => T[]` patcher for a list cache.
+ *
+ * @example
+ * useOfflineMutation<Note, Note[], Note>({
+ *     sync, queryKey: ["notes"],
+ *     toEntry: (n) => ({ op: "update", recordId: n.id, payload: n }),
+ *     applyOptimistic: upsertById(),
+ * });
+ */
+export declare function upsertById<T>(idField?: keyof T): (current: T[] | undefined, item: T) => T[];
+
 /**
  * Convert a base64url-encoded VAPID public key into the `Uint8Array` format
  * required by `PushManager.subscribe({ applicationServerKey })`.
@@ -7028,7 +7534,17 @@ export { UseFormReturn }
 
 export { useFormState }
 
-/** React hook around the Geolocation API. */
+/**
+ * React hook around the Geolocation API.
+ *
+ * The effect depends on the individual `PositionOptions` fields instead of the
+ * rest object, which is a new reference on every render and would restart the
+ * watch continuously. `exhaustive-deps` is silenced there because those fields
+ * are the whole of what the effect reads from it.
+ *
+ * @param options - Geolocation options plus `watch` and `disabled` switches.
+ * @returns The latest position, error and loading state.
+ */
 export declare function useGeolocation(options?: UseGeolocationOptions): GeolocationState;
 
 export declare interface UseGeolocationOptions extends PositionOptions {
@@ -7162,6 +7678,12 @@ export declare function useIsFirstRender(): boolean;
  * Bind a global keyboard shortcut. Supports modifier combinations and a
  * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
  *
+ * The effect depends on the individual `shortcut` fields rather than on the
+ * object itself: callers pass an inline literal (`{ key: "k", mod: true }`),
+ * which is a fresh reference on every render and would otherwise tear down and
+ * re-add the listener each time. `exhaustive-deps` is silenced for that line
+ * because the destructured fields are the complete dependency set.
+ *
  * @example
  * useKeyboardShortcut({ key: "k", mod: true }, () => openSearch());
  */
@@ -7378,6 +7900,126 @@ export declare interface UseOAuthCallbackResult<T> {
  */
 export declare function useObjectUrl(blob: Blob | null | undefined): string | null;
 
+/**
+ * Optimistic mutation that writes to an {@link OfflineSync} outbox instead of
+ * hitting the network directly, bridging the sync engine and TanStack Query.
+ *
+ * On `mutate` it enqueues the entry, optimistically patches the given query
+ * cache key and kicks a flush; if the enqueue itself throws, the cache is
+ * rolled back to its previous value. Server delivery happens later inside the
+ * engine's flush loop, so the UI updates instantly and survives reloads and
+ * offline periods.
+ *
+ * @typeParam TVariables - The `mutate(variables)` input shape.
+ * @typeParam TData - The cached query data optimistically patched.
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param options - Engine, variables→entry mapping and cache wiring.
+ * @returns The TanStack {@link UseMutationResult}; the mutation resolves to the
+ *   generated outbox entry id.
+ *
+ * @example
+ * const addNote = useOfflineMutation({
+ *     sync: notesSync,
+ *     queryKey: ["notes"],
+ *     toEntry: (note: Note) => ({ op: "create", recordId: note.id, payload: note }),
+ *     applyOptimistic: (current: Note[] = [], note) => [...current, note],
+ * });
+ * addNote.mutate(newNote);
+ */
+export declare function useOfflineMutation<TVariables, TData = unknown, TPayload = unknown>(options: UseOfflineMutationOptions<TVariables, TData, TPayload>): UseMutationResult<string, Error, TVariables, MutationContext<TData>>;
+
+/**
+ * Configuration for {@link useOfflineMutation}.
+ *
+ * @typeParam TVariables - The `mutate(variables)` input shape.
+ * @typeParam TData - The cached query data optimistically patched.
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface UseOfflineMutationOptions<TVariables, TData, TPayload> {
+    /** The engine the mutation enqueues into. */
+    sync: OfflineSync<TPayload>;
+    /** Map `mutate` variables into an outbox entry. */
+    toEntry: (variables: TVariables) => OutboxDraft<TPayload>;
+    /**
+     * Query key to optimistically patch and (optionally) invalidate. Omit to
+     * only enqueue without touching the React Query cache.
+     */
+    queryKey?: QueryKey;
+    /**
+     * Produce the next cached value from the current one and the variables.
+     * Runs in `onMutate`; the previous value is restored automatically if the
+     * enqueue throws. Requires `queryKey`.
+     */
+    applyOptimistic?: (current: TData | undefined, variables: TVariables) => TData;
+    /**
+     * Trigger a flush after enqueueing. `true` (default) uses
+     * `"after-mutation"`; pass a custom {@link SyncTrigger} string, or `false`
+     * to leave flushing to the caller / auto-flush hooks.
+     */
+    flush?: boolean | SyncTrigger;
+    /** Invalidate `queryKey` in `onSettled` so a later read refetches. Default `false`. */
+    invalidate?: boolean;
+}
+
+/**
+ * Subscribe a React component to an {@link OfflineSync} engine.
+ *
+ * Re-renders whenever the engine's {@link SyncState} changes (enqueue, flush
+ * transition, outbox clear) via `useSyncExternalStore`, and optionally wires
+ * auto-flush on mount, on the `online` event and on an interval. The engine
+ * itself is created once by the app and passed in — the hook never owns it, so
+ * multiple components can observe the same queue.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param sync - The engine returned by `createOfflineSync`.
+ * @param options - Auto-flush triggers.
+ * @returns The reactive state merged with `enqueue`/`flush` actions.
+ *
+ * @example
+ * const { pending, syncing, phase, flush } = useOfflineSync(notesSync, {
+ *     flushOnMount: true,
+ *     intervalMs: 30_000,
+ * });
+ * return <SyncStatusBadge pending={pending} syncing={syncing} phase={phase} />;
+ */
+export declare function useOfflineSync<TPayload>(sync: OfflineSync<TPayload>, options?: UseOfflineSyncOptions): UseOfflineSyncResult<TPayload>;
+
+/**
+ * Options for {@link useOfflineSync}. All auto-flush triggers are opt-in except
+ * `flushOnOnline`, which defaults to `true` so the app catches up the moment
+ * connectivity returns.
+ */
+export declare interface UseOfflineSyncOptions {
+    /** Flush once when the component mounts (trigger `"boot"`). Default `false`. */
+    flushOnMount?: boolean;
+    /**
+     * Flush when the browser fires the `online` event (trigger
+     * `"online-event"`). Default `true`.
+     */
+    flushOnOnline?: boolean;
+    /**
+     * Flush on this interval in milliseconds (trigger `"interval"`). `0`
+     * disables the timer. Default `0`.
+     */
+    intervalMs?: number;
+}
+
+/**
+ * Reactive view of an {@link OfflineSync} engine, plus its imperative actions.
+ * Extends {@link SyncState} so `phase`, `pending`, `lastSummary`, `lastError`
+ * and `lastSyncedAt` are read directly off the result.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface UseOfflineSyncResult<TPayload> extends SyncState {
+    /** `true` while a flush run is in progress (`phase === "syncing"`). */
+    syncing: boolean;
+    /** Queue a mutation. Mirrors {@link OfflineSync.enqueue}. */
+    enqueue: (op: OutboxOp, recordId: string, payload?: TPayload) => Promise<string>;
+    /** Trigger a flush run. Mirrors {@link OfflineSync.flush}. */
+    flush: (trigger?: SyncTrigger) => Promise<SyncRunSummary>;
+}
+
 /**
  * Query a single record by id through the active {@link useDataProvider}.
  *
@@ -7396,10 +8038,40 @@ export declare type UseOneOptions<T> = Omit<UseQueryOptions<T, Error, T>, "query
 };
 
 /**
- * Track the browser's `navigator.onLine` value and re-render on changes.
- * Returns `true` during SSR (assumption: server is online).
+ * Track connectivity and re-render on changes.
+ *
+ * With no options it mirrors `navigator.onLine` (assuming online during SSR and
+ * before the first event). Pass `pingUrl` to additionally probe real
+ * reachability — the browser's `onLine` flag lies behind captive portals and
+ * dead links, so the probe downgrades the result to `false` when the network is
+ * unusable even though `navigator.onLine` is `true`.
+ *
+ * @param options - Optional reachability-probe configuration.
+ * @returns `true` when the device is online (and reachable, when probing).
+ *
+ * @example
+ * const online = useOnline(); // navigator.onLine only
+ * const reallyOnline = useOnline({ pingUrl: "/health", intervalMs: 15_000 });
+ */
+export declare function useOnline(options?: UseOnlineOptions): boolean;
+
+/**
+ * Options for {@link useOnline}. Omit them for the cheap `navigator.onLine`
+ * behaviour; pass `pingUrl` to add a real-reachability probe on top.
  */
-export declare function useOnline(): boolean;
+export declare interface UseOnlineOptions {
+    /**
+     * URL to probe for real connectivity. `navigator.onLine` reports `true`
+     * behind a captive portal or when the machine has a link but no internet;
+     * a periodic `HEAD` to this URL catches those cases. When set, the result
+     * is `navigator.onLine && lastProbeSucceeded`.
+     */
+    pingUrl?: string;
+    /** How often to probe, in ms. Default `30000`. */
+    intervalMs?: number;
+    /** Abort a probe after this many ms and treat it as offline. Default `5000`. */
+    timeoutMs?: number;
+}
 
 /**
  * Offset-pagination hook over TanStack Query for the fastapi-pagination /
@@ -7646,6 +8318,52 @@ export declare function useScrollLock(active: boolean): void;
 
 export { useSearchParams }
 
+/**
+ * Register a service worker and expose a user-driven update flow.
+ *
+ * Wraps {@link registerServiceWorker}: when a fresh worker finishes installing
+ * while the page is still controlled by the old one, `updateAvailable` flips to
+ * `true`. Call `applyUpdate` — typically from an "atualizar" toast — to tell the
+ * waiting worker to activate and reload the page once it takes control.
+ *
+ * Skips cleanly when the runtime has no service-worker support (`registration`
+ * stays `null`, `updateAvailable` stays `false`).
+ *
+ * @param options - Registration options (`url` required); `autoUpdate` should
+ *   stay off so the reload is user-confirmed.
+ * @returns The update state and `applyUpdate` action.
+ *
+ * @example
+ * const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
+ * return (
+ *     <UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />
+ * );
+ */
+export declare function useServiceWorkerUpdate(options: UseServiceWorkerUpdateOptions): UseServiceWorkerUpdateResult;
+
+/**
+ * Options for {@link useServiceWorkerUpdate}. Mirrors the registration options
+ * minus the callbacks the hook owns internally (`onUpdate`); `onReady` and
+ * `onError` still pass through for host-side logging.
+ *
+ * Leave `autoUpdate` off (the default): this hook exists to hand the reload
+ * decision to the user, so a silent auto-reload would defeat the prompt.
+ */
+export declare type UseServiceWorkerUpdateOptions = Omit<RegisterServiceWorkerOptions, "onUpdate">;
+
+/** Reactive service-worker update state plus the apply action. */
+export declare interface UseServiceWorkerUpdateResult {
+    /** `true` once a new worker has installed and is waiting to activate. */
+    updateAvailable: boolean;
+    /**
+     * Activate the waiting worker and reload the page once it takes control.
+     * No-op when no update is waiting.
+     */
+    applyUpdate: () => void;
+    /** The active registration, or `null` before it resolves / when unsupported. */
+    registration: ServiceWorkerRegistration | null;
+}
+
 /**
  * Reactive `Set` wrapper. Mutating via `add` / `delete` / `clear` / `toggle`
  * triggers a re-render and yields a fresh `set` reference each time.
@@ -7673,6 +8391,50 @@ export declare interface UseSetResult<T> {
  */
 export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
+/**
+ * Track the origin's storage usage, quota and persistence flag, refreshing on
+ * demand. Pair with {@link requestPersistentStorage} to surface a "usando X de
+ * Y MB" meter and a "tornar armazenamento permanente" action.
+ *
+ * @param options - `pollMs` re-reads the estimate on an interval (`0` = off,
+ *   the default).
+ * @returns The reactive storage state and actions.
+ *
+ * @example
+ * const { usage, quota, ratio, persisted, requestPersist } = useStorageEstimate();
+ * return <Meter value={ratio ?? 0} onClick={requestPersist} />;
+ */
+export declare function useStorageEstimate(options?: {
+    pollMs?: number;
+}): UseStorageEstimateResult;
+
+/** Reactive storage-quota state exposed by {@link useStorageEstimate}. */
+export declare interface UseStorageEstimateResult extends StorageEstimate_2 {
+    /** `true` when the Storage API is available. */
+    supported: boolean;
+    /** `usage / quota` in `[0, 1]`, or `null` when either value is unknown. */
+    ratio: number | null;
+    /** Whether storage is persisted, `null` before the first read / unsupported. */
+    persisted: boolean | null;
+    /** `true` during the initial read or a `refresh`. */
+    loading: boolean;
+    /** Re-read usage/quota and the persisted flag from the browser. */
+    refresh: () => Promise<void>;
+    /** Request persistent storage; refreshes state and returns the outcome. */
+    requestPersist: () => Promise<boolean>;
+}
+
+/**
+ * Subscribe to an {@link OfflineSync} engine and return a display-only
+ * {@link SyncStatus}. A thin read-only companion to {@link useOfflineSync},
+ * intended to feed a `<SyncStatusBadge>` without exposing flush actions.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param sync - The engine returned by `createOfflineSync`.
+ * @returns The compact status snapshot.
+ */
+export declare function useSyncStatus<TPayload>(sync: OfflineSync<TPayload>): SyncStatus;
+
 /**
  * Access the active telemetry adapter. Returns `null` when no provider is
  * mounted (calls are silently dropped — useful for unit tests).