@lotics/app-sdk 0.19.0 → 0.21.0

package/dist/src/hooks.d.ts

@@ -28,6 +28,15 @@ export interface QueryOptions {
      * `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.
@@ -121,21 +130,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

@@ -35,6 +35,7 @@ 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 ?? {});
@@ -48,7 +49,8 @@ export function useQuery(alias, params, opts) {
         const mockRows = getMockRows(alias);
         if (mockRows)
             return { rows: mockRows, loading: false, error: null, hasMore: false };
-        return { rows: [], loading: true, 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(() => {
@@ -59,6 +61,10 @@ export function useQuery(alias, params, opts) {
             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) => ({ ...s, loading: true, error: null }));
         rpc("query", {
@@ -87,7 +93,7 @@ export function useQuery(alias, params, opts) {
             cancelled = true;
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [alias, paramsKey, refetchToken, pageSize]);
+    }, [alias, paramsKey, refetchToken, pageSize, enabled]);
     const refetch = useCallback(() => {
         setRefetchToken((n) => n + 1);
     }, []);
@@ -181,21 +187,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,
@@ -204,7 +214,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 });
@@ -216,6 +226,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";
@@ -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

@@ -22,3 +22,4 @@ 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/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/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.19.0",
+  "version": "0.21.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {