@tristan2828/ui-foundation 4.9.0 → 4.9.1

package/conventions/docs/add-an-entity.md

@@ -178,7 +178,12 @@ is a filled-in example while the Widgets demo is still here).
    a toast naming the row and the server's reason; the lists refetch
    after). Its specs cover a flip that saves, the keyboard, and a failed
    save putting the switch back. Copy `useSaveWidgetField` whenever the
-   plan has a `toggle` or any quick action, and only then.
+   plan has a `toggle` or any quick action, and only then. It finds the
+   record under the entity's own detail and list keys: on a screen that
+   holds it in a query of its own, a plain change (`{ field: value }`) is
+   still sent but only shows once that query refetches, and a change
+   built from the record (`(record) => …`) is refused, with a console
+   warning naming the keys searched.
    - `src/routes/widgets/use-widgets.ts`, `use-widget-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)

package/dist/hooks/use-record-update.js

@@ -21,6 +21,10 @@
 //   or the AppError's).
 // - **The lists refetch once the last save settles**, so a filter on the
 //   field drops the row once the server agrees.
+// - **A record in neither cache** (the screen holds it in a query of its
+//   own) still saves an object change, shown once that query refetches; a
+//   function change has nothing to build on and is refused like any other
+//   refusal. Both warn in the console, naming the keys searched.
 //
 // Editing in place uses the same save with `optimistic: false` and
 // `toastOnError: false`: nothing changes on screen until the server
@@ -35,6 +39,11 @@ function recordStates(queryClient) {
         states.set(queryClient, (map = new Map()));
     return map;
 }
+// A function change with no record in either cache to build it from.
+const notLoaded = {
+    kind: 'server',
+    message: "It isn't loaded on this page. Reload and try again",
+};
 function resolve(change, record) {
     return typeof change === 'function' ? change(record) : change;
 }
@@ -94,9 +103,19 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
         scope: { id: `record-update:${key}` },
         mutationFn: (change) => {
             const confirmed = map.get(key)?.confirmed ?? cached();
-            if (!confirmed)
-                return Promise.reject(new Error('The record to update is not loaded'));
-            return update(id, resolve(change, confirmed));
+            if (confirmed)
+                return update(id, resolve(change, confirmed));
+            // The screen holds the record somewhere these keys don't reach (a
+            // query gathering a related list's records, say). An object change
+            // needs no current record, so it's still sent; a function change
+            // can't be built, and says so rather than doing nothing. Warned in
+            // every build: the package has no dev flag every app's bundler sets.
+            console.warn(`useRecordUpdate: record ${String(id)} isn't cached under ${JSON.stringify(detailKey)} ` +
+                `or any list under ${JSON.stringify(listsKey)}, so the change isn't shown until the server answers` +
+                (typeof change === 'function' ? ', and a change built from the record can\'t be sent' : ''));
+            if (typeof change === 'function')
+                return Promise.reject(notLoaded);
+            return update(id, change);
         },
         onMutate: async (change) => {
             let state = map.get(key);
@@ -120,7 +139,8 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
                 return;
             // What was sent: the change built on the record it was sent against.
             const record = state.confirmed;
-            const sent = record && resolve(context.entry.change, record);
+            const { change } = context.entry;
+            const sent = record ? resolve(change, record) : typeof change === 'function' ? undefined : change;
             settle(state, context.entry);
             if (toastOnError)
                 toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {