@lotics/app-sdk 0.19.0 → 0.20.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.

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);
     }, []);

package/dist/src/index.d.ts

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