@lotics/app-sdk 0.87.4 → 0.87.6

package/dist/src/hooks.js

@@ -71,6 +71,14 @@ function swrConfig(revalidateOnFocus) {
         revalidateOnFocus,
         revalidateOnReconnect: revalidateOnFocus,
         shouldRetryOnError: false,
+        // A query's KEY carries its params, filter and sort, so anything derived
+        // from the rows on screen re-keys the moment they change. Without this SWR
+        // answers a new key with `undefined`, `rows` falls to `[]`, and every list
+        // renders empty for a frame — unmounting each row's images, which remount
+        // blank. That is the behaviour the `loading` contract above already
+        // promises against, and what the product app sets globally for the same
+        // reason.
+        keepPreviousData: true,
     };
 }
 /**
@@ -289,9 +297,7 @@ export function usePaginatedQuery(alias, params, opts) {
         offset: page * pageSize,
         sort,
         filter,
-    }), 
-    // Keep the previous page's rows on screen while the next page loads.
-    { keepPreviousData: true, ...swrConfig(revalidateOnFocus) });
+    }), swrConfig(revalidateOnFocus));
     // Not counted when the caller supplies the total, when the hook is disabled,
     // or under a fixture — see `useCountRead` for why the key drops page and sort.
     const countSwr = useCountRead(alias, params, filter, !mockRows && enabled && !callerOwnsTotal, revalidateOnFocus);

package/dist/src/row.d.ts

@@ -86,7 +86,9 @@ export interface AppFile {
 /**
  * files field → the attached files with their presigned `url` (empty if none).
  * Skips entries the server didn't presign (no `url`) so a consumer never renders
- * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
+ * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
+ * it per app.
  */
 export declare function readFiles(v: unknown): AppFile[];
 /**

package/dist/src/row.js

@@ -113,7 +113,9 @@ export function readLinks(v) {
 /**
  * files field → the attached files with their presigned `url` (empty if none).
  * Skips entries the server didn't presign (no `url`) so a consumer never renders
- * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
+ * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
+ * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
+ * it per app.
  */
 export function readFiles(v) {
     if (!Array.isArray(v))

package/docs/data_fetching.md

@@ -136,8 +136,11 @@ server validates system conditions by `type` and never reads `field_key` on them
   are no rows yet. It stays `false` during background revalidation of a key that already has rows,
   so consumers never blank loaded data to a spinner on refetch. A key *change* (new params, sort,
   filter, or page) is a fresh load: `loading` goes `true` again unless that key is already cached —
-  `usePaginatedQuery` keeps the previous page's rows on screen during it, which is why skeletons
-  gate on `loading && rows.length === 0`, never `loading` alone. **`isValidating`** is `true`
+  but the previous key's rows STAY on screen while it resolves, for every query, so `rows` never
+  empties mid-flight. That is why skeletons gate on `loading && rows.length === 0`, never `loading`
+  alone: a filter derived from what is on screen re-keys on every keystroke, and gating on
+  `loading` swaps the list for a spinner each time — which unmounts everything the rows contained,
+  images included. **`isValidating`** is `true`
   whenever any request is in flight — use it for a subtle refresh indicator.
 - **`error`** is a `string | null`. A failed query surfaces immediately — there is **no automatic
   retry** (no retry loop that masks the error). The last successful rows for the same key stay

package/docs/workflows.md

@@ -489,7 +489,7 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 | `set` | `{ fld_x: value }` | write the whole value. `null` **clears** the field |
 | `set_skip_null` | `{ fld_x: value }` | same shape, but `null`/`undefined` entries are **dropped** — absent means "leave unchanged" |
 | `add_to` / `remove_from` / `replace` | `{ fld_x: [items] }` | surgical edits on multi-value fields (files, multi select, multi member, record links) |
-| `increment` | `{ fld_x: delta }` | move a **number** field by a signed amount. Negative decrements; there is no separate decrement op |
+| `increment` | `{ fld_x: delta }` | move a **number** field by a signed amount, the SAME delta on every record named. Negative decrements; there is no separate decrement op |
 | `field_edits` | `[{ field, op, value }]` | the multi-value ops with the field named by a **string expression** — the only way to target a field chosen at run time. `increment` has no value-form: its payload is a scalar, not an item list |
 
 `add_to`, `remove_from` and `increment` are RELATIVE: the server resolves them against the record
@@ -505,6 +505,23 @@ stating its value.
 and visibly so. It is rejected on formula, rollup, lookup and autonumber fields: those come from
 their own definition, so change what they aggregate instead.
 
+A **different** delta per record is per-record mode with `row_op: "increment"` — every row value is
+read as a delta rather than a value to write. That is the shape a stock move needs, since each item
+moves by its own quantity:
+
+```ts
+await update_records({
+  table_id: "tbl_items",
+  record_ids: ids,
+  field_keys: ["fld_stock"],
+  rows: [[-12], [-3]],
+  row_op: "increment",
+});
+```
+
+It also removes the read: the deltas are what the workflow already computed, so there is nothing to
+look up first.
+
 Inside `set` and `create_records.records`: `null` clears (persisted), `undefined` or an omitted
 key preserves. So passing a possibly-null read straight through is safe. Use
 `coalesce(x, fallback)` only when you want a real fallback, never to "strip" null.

package/package.json

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