@lotics/app-sdk 0.20.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.
@@ -130,21 +146,33 @@ interface MembersState {
     loading: boolean;
     error: string | null;
 }
+/** Options for `useMembers`. */
+export interface MembersOptions {
+    /**
+     * Restrict to one member group (a group ID). The group must be declared on a
+     * `member` workflow input's `group` — listing an undeclared group errors. Omit
+     * to list the whole org roster.
+     */
+    group?: string;
+}
 /**
  * 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
+ * "assign to a member" picker. Each member is `{ id, name, email, image }`
+ * (`image` = avatar URL, may be null). 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.
+ * whose manifest declares a `member`-typed input. Passing `{ group }` restricts
+ * to that group, and is only honored if some member input declares that
+ * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers();
- * // <Picker options={members.map((m) => ({ value: m.id, label: m.name || m.email || m.id }))} />
+ * const { members } = useMembers({ group: "grp_..." });
+ * // <Picker options={members.map((m) => ({
+ * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
+ * // }))} />
  * ```
  */
-export declare function useMembers(): MembersState;
+export declare function useMembers(opts?: MembersOptions): MembersState;
 export {};

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
@@ -187,21 +195,25 @@ export function useFileUpload() {
 }
 /**
  * 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
+ * "assign to a member" picker. Each member is `{ id, name, email, image }`
+ * (`image` = avatar URL, may be null). 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.
+ * whose manifest declares a `member`-typed input. Passing `{ group }` restricts
+ * to that group, and is only honored if some member input declares that
+ * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers();
- * // <Picker options={members.map((m) => ({ value: m.id, label: m.name || m.email || m.id }))} />
+ * const { members } = useMembers({ group: "grp_..." });
+ * // <Picker options={members.map((m) => ({
+ * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
+ * // }))} />
  * ```
  */
-export function useMembers() {
+export function useMembers(opts) {
+    const group = opts?.group;
     const [state, setState] = useState({
         members: [],
         loading: true,
@@ -210,7 +222,7 @@ export function useMembers() {
     useEffect(() => {
         let cancelled = false;
         setState((s) => ({ ...s, loading: true, error: null }));
-        rpc("members", {})
+        rpc("members", { group })
             .then((r) => {
             if (!cancelled)
                 setState({ members: r.members ?? [], loading: false, error: null });
@@ -222,6 +234,6 @@ export function useMembers() {
         return () => {
             cancelled = true;
         };
-    }, []);
+    }, [group]);
     return state;
 }

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
-export type { UploadedFile, QueryOptions, WorkflowResult } from "./hooks.js";
+export type { UploadedFile, QueryOptions, WorkflowResult, MembersOptions } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/members.d.ts

@@ -18,6 +18,9 @@ export interface ResolvedMember {
     /** Present only on authenticated responses. Omitted on public-app
      *  responses (no PII exposure to anonymous visitors). */
     email?: string | null;
+    /** Avatar URL. Present on the `useMembers` roster (may be null when the
+     *  member has no profile image); absent on resolved `select_member` cells. */
+    image?: string | null;
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedMember[]`. Returns `[]` for

package/dist/src/rpc.js

@@ -218,16 +218,17 @@ function rpcStandalone(op, payload) {
         case "upload":
             return standaloneUpload(payload.file);
         case "members":
-            return standaloneMembers();
+            return standaloneMembers(payload);
         case "context":
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
     }
 }
-async function standaloneMembers() {
+async function standaloneMembers(p) {
     const { app_id } = await boot();
-    const r = (await apiCall("GET", `/v1/apps/${app_id}/members`, undefined, {
+    const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";
+    const r = (await apiCall("GET", `/v1/apps/${app_id}/members${qs}`, undefined, {
         appId: app_id,
     }));
     return { members: r.members ?? [] };

package/package.json

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