@lotics/app-sdk 0.22.0 → 0.24.0

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 {
@@ -37,127 +36,72 @@ 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 ?? {});
-    // 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, 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(() => {
-        // 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, isValidating: false, error: null, hasMore: false });
-            return;
+    // 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: [], isValidating: false, error: null, hasMore: false });
-            return;
-        }
-        let cancelled = false;
-        // 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", {
+        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,
-                isValidating: false,
-                error: null,
-                hasMore: pageSize != null && rows.length === pageSize,
-            });
-        })
-            .catch((err) => {
-            if (cancelled)
-                return;
-            // Keep the last good rows on a failed revalidation; surface the error.
-            setState((s) => ({ ...s, isValidating: false, error: err.message }));
+            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(() => {
-        if (!revalidateOnFocus)
-            return;
-        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);
-        };
-    }, [revalidateOnFocus]);
+        void swr.mutate();
+    }, [swr]);
     const loadMore = useCallback(() => {
-        if (pageSize == null || loadingMore || state.isValidating || !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.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 };
+        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/dist/src/index.d.ts

@@ -27,8 +27,8 @@ export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
-export { row, readLinks } from "./row.js";
-export type { ResolvedLink } from "./row.js";
+export { row, readLinks, readFiles } from "./row.js";
+export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/index.js

@@ -20,6 +20,6 @@ export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
-export { row, readLinks } from "./row.js";
+export { row, readLinks, readFiles } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/row.d.ts

@@ -44,6 +44,27 @@ export interface ResolvedLink {
 declare function link(v: unknown): ResolvedLink | null;
 /** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
 export declare function readLinks(v: unknown): ResolvedLink[];
+/**
+ * A `files`-field cell entry, as the app query serializes it. The server
+ * presigns each file (24h) so `url`/`thumbnail_url` load directly — including
+ * from the sandboxed app iframe and for public apps — so the app can preview or
+ * download without deriving its own URL.
+ */
+export interface AppFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    /** Presigned serving URL — render in an <Image>/preview or pass to openExternal. */
+    url: string;
+    /** Presigned thumbnail URL for images, when the server produced one. */
+    thumbnail_url?: string;
+}
+/**
+ * files field → the attached files with their presigned `url` (empty if none).
+ * Skips entries the server didn't presign (no `url`) so a consumer never renders
+ * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ */
+export declare function readFiles(v: unknown): AppFile[];
 export declare const row: {
     opt: typeof opt;
     text: typeof text;

package/dist/src/row.js

@@ -89,4 +89,33 @@ export function readLinks(v) {
     }
     return v.map(asLink).filter((x) => x !== null);
 }
+/**
+ * files field → the attached files with their presigned `url` (empty if none).
+ * Skips entries the server didn't presign (no `url`) so a consumer never renders
+ * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ */
+export function readFiles(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const f of v) {
+        if (!f || typeof f !== "object")
+            continue;
+        const id = f.id;
+        const url = f.url;
+        if (typeof id !== "string" || !id || typeof url !== "string" || !url)
+            continue;
+        const filename = f.filename;
+        const mime = f.mime_type;
+        const thumb = f.thumbnail_url;
+        out.push({
+            id,
+            filename: typeof filename === "string" ? filename : "",
+            mime_type: typeof mime === "string" ? mime : "",
+            url,
+            thumbnail_url: typeof thumb === "string" ? thumb : undefined,
+        });
+    }
+    return out;
+}
 export const row = { opt, text, num, bool, date, link };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.22.0",
+  "version": "0.24.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",