@lotics/app-sdk 0.21.0 → 0.23.0

package/dist/src/hooks.d.ts

@@ -2,7 +2,15 @@ import type { AppWorkflows, AppQueries } from "./types.js";
 import type { ResolvedMember } from "./members.js";
 interface QueryState<R> {
     rows: R[];
+    /**
+     * True only on the initial load — a request is in flight and there are no
+     * rows yet. Stays false during background revalidation and while typing a new
+     * query (the previous rows remain visible), so consumers never blank data to a
+     * spinner on refetch. Use `isValidating` for a subtle refetch indicator.
+     */
     loading: boolean;
+    /** True whenever any request is in flight (initial load or revalidation). */
+    isValidating: boolean;
     error: string | null;
     /**
      * Re-run the query from the first page. Use after a known mutation point —
@@ -37,6 +45,14 @@ export interface QueryOptions {
      * whole table on first paint. Default `true`.
      */
     enabled?: boolean;
+    /**
+     * When `false`, the query does not auto-refetch on window focus / tab return /
+     * network reconnect (`refetch()` still works). Default `true`, right for
+     * dashboards that should stay fresh. Set `false` for transient queries — a
+     * search bound to an ephemeral term, or on-demand detail — where a refocus
+     * re-run is wasted work and a visible reload.
+     */
+    revalidateOnFocus?: boolean;
 }
 /**
  * Trigger a workflow by alias from the app's manifest.

package/dist/src/hooks.js

@@ -9,17 +9,16 @@
  * a workflow attaches it, so file upload keeps that same property.
  *
  * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
- * does the actual API calls, results stream back through `rpc()`. Hooks manage
- * their own local cache via `useState`; we intentionally don't ship a global
- * store in v1.
+ * does the actual API calls, results stream back through `rpc()`. `useQuery`
+ * caches through SWR keyed by (alias, params, pageSize): reads dedupe and the
+ * cache survives unmount/remount. Mutation / member hooks keep their own local
+ * `useState` — they have nothing to share.
  */
 import { useCallback, useEffect, useState } from "react";
+import useSWRInfinite from "swr/infinite";
 import { rpc } from "./rpc.js";
 import { getMockRows } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
-// A tab return can fire both `focus` and `visibilitychange` back-to-back;
-// coalesce them into a single revalidation.
-const FOCUS_REVALIDATE_THROTTLE_MS = 2000;
 export function useWorkflow(alias) {
     return useCallback(async (inputs) => {
         try {
@@ -36,120 +35,73 @@ export function useWorkflow(alias) {
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
-    // Stringified params key — structurally-equal-but-new param objects don't
-    // re-fire the effect every render.
-    const paramsKey = JSON.stringify(params ?? {});
-    // Bumping this token re-fires the effect (first page) without changing
-    // alias/params. State transitions happen inside the effect so loading /
-    // error / rows flow consistently.
-    const [refetchToken, setRefetchToken] = useState(0);
-    // Initialize from the fixture when mock mode is on and the app registered
-    // rows for this alias — avoids a flash of `loading: true` on first paint.
-    const [state, setState] = useState(() => {
-        const mockRows = getMockRows(alias);
-        if (mockRows)
-            return { rows: mockRows, loading: false, error: null, hasMore: false };
-        // A disabled query starts idle (no loading flash), not pending.
-        return { rows: [], loading: enabled, error: null, hasMore: false };
-    });
-    const [loadingMore, setLoadingMore] = useState(false);
-    useEffect(() => {
-        // Re-check on every effect run so HMR updates to the fixture propagate
-        // without a hard reload. Fixture short-circuits the RPC.
-        const mockRows = getMockRows(alias);
-        if (mockRows) {
-            setState({ rows: mockRows, loading: false, error: null, hasMore: false });
-            return;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    // A registered fixture short-circuits the network in mock / dev mode.
+    const mockRows = getMockRows(alias);
+    // The cache key is (alias, params, pageSize, pageIndex), built HERE so an app
+    // never constructs a key — it just calls `useQuery("hoSo")`. SWR canonicalizes
+    // the params object via its stable hash, so every `useQuery` with the same
+    // (alias, params, pageSize) dedupes to one request and one shared cache entry,
+    // and that entry survives unmount/remount — navigating back to a screen shows
+    // cached rows instantly and revalidates in the background (no flash). A `null`
+    // key disables the fetch (mock / disabled / past the last page).
+    const getKey = (index, prev) => {
+        if (mockRows || !enabled)
+            return null;
+        // Non-paginated has only page 0; paginated stops once a short page returns.
+        if (index > 0 && (pageSize == null || prev == null || prev.rows.length < pageSize)) {
+            return null;
         }
-        if (!enabled) {
-            setState({ rows: [], loading: false, error: null, hasMore: false });
-            return;
-        }
-        let cancelled = false;
-        setState((s) => ({ ...s, loading: true, error: null }));
-        rpc("query", {
+        return ["app-query", alias, params ?? {}, pageSize ?? null, index];
+    };
+    const swr = useSWRInfinite(getKey, (key) => {
+        const index = Number(key[4]);
+        return rpc("query", {
             alias,
             params: params ?? {},
             limit: pageSize,
-            offset: 0,
-        })
-            .then((result) => {
-            if (cancelled)
-                return;
-            const rows = result.rows ?? [];
-            setState({
-                rows,
-                loading: false,
-                error: null,
-                hasMore: pageSize != null && rows.length === pageSize,
-            });
-        })
-            .catch((err) => {
-            if (cancelled)
-                return;
-            setState({ rows: [], loading: false, error: err.message, hasMore: false });
+            offset: pageSize != null ? index * pageSize : 0,
         });
-        return () => {
-            cancelled = true;
-        };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [alias, paramsKey, refetchToken, pageSize, enabled]);
+    }, {
+        // loadMore appends pages — don't re-fetch earlier pages when `size` grows.
+        revalidateFirstPage: false,
+        // The opt-out covers focus AND reconnect, per the documented contract.
+        revalidateOnFocus,
+        revalidateOnReconnect: revalidateOnFocus,
+        // Surface a failed query immediately and keep the last good rows — no
+        // silent retry loop that would mask the error from the app.
+        shouldRetryOnError: false,
+    });
+    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves
+    // (the typed `QueryPage[]` understates this) — operate on resolved pages only,
+    // so a page being appended never crashes the flatten or skews the counts.
+    const pages = (swr.data ?? []).filter((p) => p != null);
+    const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
+    const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
+    const hasMore = pageSize != null && lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
+    // Appending a page: more pages are requested than have resolved.
+    const loadingMore = swr.isValidating && swr.size > pages.length;
     const refetch = useCallback(() => {
-        setRefetchToken((n) => n + 1);
-    }, []);
-    // Revalidate on focus / reconnect. An app can't hold a realtime socket, so
-    // freshness comes from re-running the query (first page) when the user
-    // returns to it or the network comes back — plus the explicit `refetch()`
-    // an app calls after a `useWorkflow()` mutation. Throttled so a tab return
-    // that fires both `focus` and `visibilitychange` only refetches once.
-    useEffect(() => {
-        let last = 0;
-        const revalidate = () => {
-            if (document.visibilityState === "hidden")
-                return;
-            const now = performance.now();
-            if (now - last < FOCUS_REVALIDATE_THROTTLE_MS)
-                return;
-            last = now;
-            setRefetchToken((n) => n + 1);
-        };
-        window.addEventListener("focus", revalidate);
-        window.addEventListener("online", revalidate);
-        document.addEventListener("visibilitychange", revalidate);
-        return () => {
-            window.removeEventListener("focus", revalidate);
-            window.removeEventListener("online", revalidate);
-            document.removeEventListener("visibilitychange", revalidate);
-        };
-    }, []);
+        void swr.mutate();
+    }, [swr]);
     const loadMore = useCallback(() => {
-        if (pageSize == null || loadingMore || state.loading || !state.hasMore)
+        if (pageSize == null || !hasMore || loadingMore)
             return;
-        setLoadingMore(true);
-        rpc("query", {
-            alias,
-            params: params ?? {},
-            limit: pageSize,
-            offset: state.rows.length,
-        })
-            .then((result) => {
-            const page = result.rows ?? [];
-            setState((cur) => ({
-                ...cur,
-                rows: [...cur.rows, ...page],
-                hasMore: page.length === pageSize,
-            }));
-        })
-            .catch((err) => {
-            // Keep the rows we have — a failed page-append shouldn't blank the
-            // list — but surface the error instead of swallowing it. `hasMore`
-            // stays true, so the app can retry `loadMore()`.
-            setState((cur) => ({ ...cur, error: err.message }));
-        })
-            .finally(() => setLoadingMore(false));
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [alias, paramsKey, pageSize, loadingMore, state.loading, state.hasMore, state.rows.length]);
-    return { ...state, refetch, loadMore, loadingMore };
+        void swr.setSize((n) => n + 1);
+    }, [pageSize, hasMore, loadingMore, swr]);
+    return {
+        rows,
+        // `loading` = initial load (validating with nothing to show yet);
+        // `isValidating` = any request in flight. Gating a skeleton on `loading`
+        // never flashes on revalidation; use `isValidating` for a subtle indicator.
+        loading: mockRows ? false : swr.isLoading,
+        isValidating: mockRows ? false : swr.isValidating,
+        error: swr.error ? swr.error.message : null,
+        refetch,
+        loadMore,
+        hasMore,
+        loadingMore,
+    };
 }
 /**
  * Upload files from an app. The bytes are stored via a presigned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -18,7 +18,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "posthog-js": "^1.352.0"
+    "posthog-js": "^1.352.0",
+    "swr": "^2.4.1"
   },
   "peerDependencies": {
     "react": "^19.2.0",