@lotics/app-sdk 0.18.0 → 0.20.0

package/dist/src/hooks.d.ts

@@ -1,18 +1,42 @@
 import type { AppWorkflows, AppQueries } from "./types.js";
+import type { ResolvedMember } from "./members.js";
 interface QueryState<R> {
     rows: R[];
     loading: boolean;
     error: string | null;
     /**
-     * Re-run the underlying query against the current AST. Use after a known
-     * mutation point — a successful `useWorkflow(alias)()` call — to pull the
-     * latest state.
-     *
-     * The iframe SDK does not subscribe to realtime invalidation channels in
-     * v1; refetch is the explicit refresh path. Future SDK versions may add a
-     * `subscribe` RPC op for push-based invalidation.
+     * Re-run the query from the first page. Use after a known mutation point —
+     * a successful `useWorkflow(alias)()` call — to pull the latest state.
      */
     refetch: () => void;
+    /**
+     * Fetch the next page and append it to `rows`. No-op when `pageSize` was not
+     * set or there are no more rows (`hasMore` is false). `loadingMore` is true
+     * while it runs.
+     */
+    loadMore: () => void;
+    /** True when the last page came back full, so more rows may exist. */
+    hasMore: boolean;
+    /** True while a `loadMore` request is in flight. */
+    loadingMore: boolean;
+}
+/** Options for `useQuery`. */
+export interface QueryOptions {
+    /**
+     * Page size. Omit to fetch all rows in one request (the server still caps
+     * the maximum). Set it to paginate: the first render loads one page, and
+     * `loadMore()` appends the next.
+     */
+    pageSize?: number;
+    /**
+     * When `false`, the query does not run: `rows` stays empty, `loading` is
+     * false, and no request is sent. Flip it back to `true` to fetch. This is the
+     * primitive for search-as-you-type (skip until the user types) and for detail
+     * queries (skip until a row is selected) — a parameterized search filter
+     * matches everything on an empty term, so an always-on query would dump the
+     * whole table on first paint. Default `true`.
+     */
+    enabled?: boolean;
 }
 /**
  * Trigger a workflow by alias from the app's manifest.
@@ -48,7 +72,7 @@ export interface WorkflowResult {
     message?: string;
     files?: UploadedFile[];
 }
-type UseQueryParams<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>] : [params: AppQueries[K]];
+type UseQueryArgs<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: QueryOptions] : [params: AppQueries[K], opts?: QueryOptions];
 /**
  * Read rows from a query the app's author declared in `lotics.queries`.
  *
@@ -65,8 +89,8 @@ type UseQueryParams<K extends keyof AppQueries & string> = AppQueries[K] extends
  * with the declared alias → param-type map, so an undeclared alias is a
  * compile-time error and params are typed per the manifest.
  */
-export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...rest: UseQueryParams<K>): QueryState<Record<string, unknown>>;
-export declare function useQuery(alias: string, params?: Record<string, unknown>): QueryState<Record<string, unknown>>;
+export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: UseQueryArgs<K>): QueryState<Record<string, unknown>>;
+export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<Record<string, unknown>>;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;
@@ -100,4 +124,27 @@ interface FileUploadState {
  * ```
  */
 export declare function useFileUpload(): FileUploadState;
+interface MembersState {
+    /** Members of the app's organization, for assign / member-picker UIs. */
+    members: ResolvedMember[];
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * List the members of the app's organization — the candidate set for an
+ * "assign to a member" picker. Resolves through the host (member-only; an
+ * anonymous public visitor gets an error). Names may be empty for members
+ * without a display name set — fall back to `email`.
+ *
+ * Gated: the app must DECLARE that it works with members — it needs a workflow
+ * whose manifest declares a `member`-typed input (i.e. it assigns members).
+ * Without one the host returns an error, so member access stays a declared,
+ * auditable surface rather than something any app can read ambiently.
+ *
+ * ```tsx
+ * const { members } = useMembers();
+ * // <Picker options={members.map((m) => ({ value: m.id, label: m.name || m.email || m.id }))} />
+ * ```
+ */
+export declare function useMembers(): MembersState;
 export {};

package/dist/src/hooks.js

@@ -17,6 +17,9 @@ import { useCallback, useEffect, useState } from "react";
 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 {
@@ -30,55 +33,123 @@ export function useWorkflow(alias) {
         }
     }, [alias]);
 }
-export function useQuery(alias, params) {
+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 without changing alias/params. The
-    // refetch callback mutates only this counter; state transitions still
-    // happen inside the effect so loading / error / rows flow consistently.
+    // 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.
-    // Computed lazily so subsequent renders don't re-read `window.location`.
     const [state, setState] = useState(() => {
         const mockRows = getMockRows(alias);
         if (mockRows)
-            return { rows: mockRows, loading: false, error: null };
-        return { rows: [], loading: true, error: null };
+            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 (mount-time
-        // re-registration) propagate without a hard reload. When the fixture has
-        // an entry we short-circuit the RPC — partial mocking still works because
-        // aliases without fixture entries fall through to the live path below.
+        // 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 });
+            setState({ rows: mockRows, loading: false, error: null, hasMore: false });
+            return;
+        }
+        if (!enabled) {
+            setState({ rows: [], loading: false, error: null, hasMore: false });
             return;
         }
         let cancelled = false;
-        setState((s) => ({ rows: s.rows, loading: true, error: null }));
-        rpc("query", { alias, params: params ?? {} })
+        setState((s) => ({ ...s, loading: true, error: null }));
+        rpc("query", {
+            alias,
+            params: params ?? {},
+            limit: pageSize,
+            offset: 0,
+        })
             .then((result) => {
             if (cancelled)
                 return;
-            setState({ rows: result.rows ?? [], loading: false, error: null });
+            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 });
+            setState({ rows: [], loading: false, error: err.message, hasMore: false });
         });
         return () => {
             cancelled = true;
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [alias, paramsKey, refetchToken]);
+    }, [alias, paramsKey, refetchToken, pageSize, enabled]);
     const refetch = useCallback(() => {
         setRefetchToken((n) => n + 1);
     }, []);
-    return { ...state, refetch };
+    // 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);
+        };
+    }, []);
+    const loadMore = useCallback(() => {
+        if (pageSize == null || loadingMore || state.loading || !state.hasMore)
+            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 };
 }
 /**
  * Upload files from an app. The bytes are stored via a presigned
@@ -114,3 +185,43 @@ export function useFileUpload() {
     }, []);
     return { upload, uploading: inFlight > 0, error };
 }
+/**
+ * List the members of the app's organization — the candidate set for an
+ * "assign to a member" picker. Resolves through the host (member-only; an
+ * anonymous public visitor gets an error). Names may be empty for members
+ * without a display name set — fall back to `email`.
+ *
+ * Gated: the app must DECLARE that it works with members — it needs a workflow
+ * whose manifest declares a `member`-typed input (i.e. it assigns members).
+ * Without one the host returns an error, so member access stays a declared,
+ * auditable surface rather than something any app can read ambiently.
+ *
+ * ```tsx
+ * const { members } = useMembers();
+ * // <Picker options={members.map((m) => ({ value: m.id, label: m.name || m.email || m.id }))} />
+ * ```
+ */
+export function useMembers() {
+    const [state, setState] = useState({
+        members: [],
+        loading: true,
+        error: null,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        setState((s) => ({ ...s, loading: true, error: null }));
+        rpc("members", {})
+            .then((r) => {
+            if (!cancelled)
+                setState({ members: r.members ?? [], loading: false, error: null });
+        })
+            .catch((err) => {
+            if (!cancelled)
+                setState({ members: [], loading: false, error: err.message });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    return state;
+}

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
-export type { UploadedFile, WorkflowResult } from "./hooks.js";
+export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
+export type { UploadedFile, QueryOptions, WorkflowResult } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
@@ -31,3 +31,5 @@ export { row, readLinks } from "./row.js";
 export type { ResolvedLink } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";
+export { useRecents } from "./use_recents.js";
+export type { RecentsApi, RecentsOptions } from "./use_recents.js";

package/dist/src/index.js

@@ -15,10 +15,11 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
+export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
 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 { useOptimistic } from "./use_optimistic.js";
+export { useRecents } from "./use_recents.js";

package/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "context" | "openExternal";
+export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:

package/dist/src/rpc.js

@@ -217,12 +217,21 @@ function rpcStandalone(op, payload) {
             return standaloneWorkflow(payload);
         case "upload":
             return standaloneUpload(payload.file);
+        case "members":
+            return standaloneMembers();
         case "context":
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
     }
 }
+async function standaloneMembers() {
+    const { app_id } = await boot();
+    const r = (await apiCall("GET", `/v1/apps/${app_id}/members`, undefined, {
+        appId: app_id,
+    }));
+    return { members: r.members ?? [] };
+}
 /**
  * Open an external URL in a new tab, scheme-validated. In standalone mode the
  * app is a normal top-level page (`<slug>.lotics.app`), so `window.open` is not
@@ -257,7 +266,7 @@ async function standaloneContext() {
 }
 async function standaloneQuery(p) {
     const { app_id } = await boot();
-    const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params }, { appId: app_id }));
+    const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params, limit: p.limit, offset: p.offset }, { appId: app_id }));
     return { rows: r.rows ?? [] };
 }
 async function standaloneWorkflow(p) {

package/dist/src/use_recents.d.ts

@@ -0,0 +1,19 @@
+export interface RecentsApi<T> {
+    /** Remembered items, most-recent first (deduped by `keyOf`, capped at `max`). */
+    recents: T[];
+    /** Record `item` as most-recent: moves an existing match to the front, caps,
+     *  and persists. Call this on select. */
+    remember: (item: T) => void;
+    /** Drop one remembered item (matched by `keyOf`). */
+    forget: (item: T) => void;
+    /** Clear the whole list. */
+    clear: () => void;
+}
+export interface RecentsOptions<T> {
+    /** Stable identity per item — used to dedup and to match `forget`. Default:
+     *  `JSON.stringify`. Pass the item's id for objects you'll re-create. */
+    keyOf?: (item: T) => string;
+    /** Maximum items kept. Default 5. */
+    max?: number;
+}
+export declare function useRecents<T>(key: string, options?: RecentsOptions<T>): RecentsApi<T>;

package/dist/src/use_recents.js

@@ -0,0 +1,71 @@
+/**
+ * Remember a small, most-recent-first list of items across sessions — the
+ * "recently used" affordance a search box shows when focused but empty.
+ *
+ * Persistence is `localStorage`, namespaced per `key`, so two comboboxes on one
+ * page keep separate lists and a deployed app's recents survive reloads. The
+ * SDK is the right home (not `@lotics/ui`): `localStorage` is web-only, and
+ * `@lotics/ui` also builds for native, where it doesn't exist. The list is
+ * always state-backed, so the hook keeps working in-memory if storage is
+ * unavailable (private mode / quota) — recents is an enhancement, never a
+ * reason to crash the app.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+const PREFIX = "lotics.recents.";
+function read(storageKey) {
+    try {
+        const raw = localStorage.getItem(storageKey);
+        if (raw == null)
+            return [];
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        // Storage unavailable or corrupt JSON: start empty, keep working in-memory.
+        return [];
+    }
+}
+function write(storageKey, items) {
+    try {
+        localStorage.setItem(storageKey, JSON.stringify(items));
+    }
+    catch {
+        // Storage unavailable (private mode / quota): the in-memory list still
+        // updates; only cross-reload persistence is lost.
+    }
+}
+export function useRecents(key, options = {}) {
+    const storageKey = PREFIX + key;
+    // Config is captured in refs so the returned callbacks stay referentially
+    // stable across renders even when the caller passes an inline `keyOf`.
+    const keyOfRef = useRef(options.keyOf ?? ((item) => JSON.stringify(item)));
+    keyOfRef.current = options.keyOf ?? ((item) => JSON.stringify(item));
+    const maxRef = useRef(options.max ?? 5);
+    maxRef.current = options.max ?? 5;
+    const [recents, setRecents] = useState(() => read(storageKey).slice(0, maxRef.current));
+    // Re-hydrate when the namespace changes (a different list on the same screen).
+    useEffect(() => {
+        setRecents(read(storageKey).slice(0, maxRef.current));
+    }, [storageKey]);
+    const remember = useCallback((item) => {
+        setRecents((prev) => {
+            const k = keyOfRef.current(item);
+            const next = [item, ...prev.filter((p) => keyOfRef.current(p) !== k)].slice(0, maxRef.current);
+            write(storageKey, next);
+            return next;
+        });
+    }, [storageKey]);
+    const forget = useCallback((item) => {
+        setRecents((prev) => {
+            const k = keyOfRef.current(item);
+            const next = prev.filter((p) => keyOfRef.current(p) !== k);
+            write(storageKey, next);
+            return next;
+        });
+    }, [storageKey]);
+    const clear = useCallback(() => {
+        write(storageKey, []);
+        setRecents([]);
+    }, [storageKey]);
+    return { recents, remember, forget, clear };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {