@lotics/app-sdk 0.77.3 → 0.77.4

package/docs/data_fetching.md

@@ -407,15 +407,30 @@ pieces. Compose these — don't hand-roll search:
   search constraint and would dump the table on first paint. `enabled` makes "nothing loads until
   you type" true. Add `revalidateOnFocus: false` — re-running an ephemeral search on refocus is
   wasted work.
+- **Debounce the term — `enabled` is not a substitute.** `enabled` decides *whether* to ask, not
+  *how often*: wire an input's own state into `params` and every keystroke past the first is a
+  fresh cache key and a fresh request. A six-letter name costs six, and on a list screen each one
+  is several — `usePaginatedQuery` re-counts whenever `params` change, and any sibling query
+  taking the same term goes with it. Keep the input's value in one state and debounce the COMMIT
+  into a second (`useDebouncedCallback` from `@lotics/ui/use_debounced_callback`, ~250 ms). The
+  two values are genuinely different — what is being typed, and what the rows on screen answer —
+  and anything reporting on the results (an empty state, a count, a "showing N for X" line) reads
+  the committed one, or it describes a set the server was never asked for. `Combobox` already
+  debounces its own `onSearchChange`; this is for a search box you built yourself.
 - **`useRecents(key, { max })`** — persist the picked option locally; pass its list as
   `recentOptions` ([./navigation_and_state.md](./navigation_and_state.md)).
 
 ```tsx
-const [term, setTerm] = useState("");            // live input stays local
+const [typed, setTyped] = useState("");          // the input's own value, every keystroke
+const [term, setTerm] = useState("");            // what the server is asked, once typing settles
+const commit = useDebouncedCallback(setTerm, 250);
+
+<SearchInput value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
+
 const { rows, loading } = useQuery(
   "searchCustomers",
   { q: term },
-  { enabled: term.trim().length > 0, revalidateOnFocus: false },
+  { enabled: term.length > 0, revalidateOnFocus: false },
 );
 ```
 

package/package.json

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