@lotics/app-sdk 0.21.0 → 0.22.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

@@ -36,6 +36,7 @@ export function useWorkflow(alias) {
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     // Stringified params key — structurally-equal-but-new param objects don't
     // re-fire the effect every render.
     const paramsKey = JSON.stringify(params ?? {});
@@ -48,9 +49,9 @@ export function useQuery(alias, params, opts) {
     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 };
+            return { rows: mockRows, isValidating: false, error: null, hasMore: false };
+        // A disabled query starts idle; an enabled one is validating its first page.
+        return { rows: [], isValidating: enabled, error: null, hasMore: false };
     });
     const [loadingMore, setLoadingMore] = useState(false);
     useEffect(() => {
@@ -58,15 +59,17 @@ export function useQuery(alias, params, opts) {
         // without a hard reload. Fixture short-circuits the RPC.
         const mockRows = getMockRows(alias);
         if (mockRows) {
-            setState({ rows: mockRows, loading: false, error: null, hasMore: false });
+            setState({ rows: mockRows, isValidating: false, error: null, hasMore: false });
             return;
         }
         if (!enabled) {
-            setState({ rows: [], loading: false, error: null, hasMore: false });
+            setState({ rows: [], isValidating: false, error: null, hasMore: false });
             return;
         }
         let cancelled = false;
-        setState((s) => ({ ...s, loading: true, error: null }));
+        // Keep prior rows in flight (stale-while-revalidate) — `loading` only shows
+        // when there's nothing to show yet, so refetches and keystrokes don't blank.
+        setState((s) => ({ ...s, isValidating: true, error: null }));
         rpc("query", {
             alias,
             params: params ?? {},
@@ -79,7 +82,7 @@ export function useQuery(alias, params, opts) {
             const rows = result.rows ?? [];
             setState({
                 rows,
-                loading: false,
+                isValidating: false,
                 error: null,
                 hasMore: pageSize != null && rows.length === pageSize,
             });
@@ -87,7 +90,8 @@ export function useQuery(alias, params, opts) {
             .catch((err) => {
             if (cancelled)
                 return;
-            setState({ rows: [], loading: false, error: err.message, hasMore: false });
+            // Keep the last good rows on a failed revalidation; surface the error.
+            setState((s) => ({ ...s, isValidating: false, error: err.message }));
         });
         return () => {
             cancelled = true;
@@ -103,6 +107,8 @@ export function useQuery(alias, params, opts) {
     // an app calls after a `useWorkflow()` mutation. Throttled so a tab return
     // that fires both `focus` and `visibilitychange` only refetches once.
     useEffect(() => {
+        if (!revalidateOnFocus)
+            return;
         let last = 0;
         const revalidate = () => {
             if (document.visibilityState === "hidden")
@@ -121,9 +127,9 @@ export function useQuery(alias, params, opts) {
             window.removeEventListener("online", revalidate);
             document.removeEventListener("visibilitychange", revalidate);
         };
-    }, []);
+    }, [revalidateOnFocus]);
     const loadMore = useCallback(() => {
-        if (pageSize == null || loadingMore || state.loading || !state.hasMore)
+        if (pageSize == null || loadingMore || state.isValidating || !state.hasMore)
             return;
         setLoadingMore(true);
         rpc("query", {
@@ -148,8 +154,10 @@ export function useQuery(alias, params, opts) {
         })
             .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 };
+    }, [alias, paramsKey, pageSize, loadingMore, state.isValidating, state.hasMore, state.rows.length]);
+    // `loading` = initial load only (validating with nothing to show yet).
+    const loading = state.isValidating && state.rows.length === 0;
+    return { ...state, loading, refetch, loadMore, 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.22.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {