@tristan2828/ui-foundation 4.37.0 → 4.38.0

package/conventions/docs/cell-patterns.md

@@ -25,15 +25,15 @@
 - [15. Yes/no you flip in the row](#15-yesno-you-flip-in-the-row) · lines 538–647
   - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
 - [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
-- [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–753
-- [18. Editable value](#18-editable-value) · lines 755–1170
-  - [A list of sub-items](#a-list-of-sub-items) · lines 1014–1071
-  - [In a table's rows](#in-a-tables-rows) · lines 1073–1158
-  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1160–1170
-- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1172–1238
-- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1240–1304
-- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1306–1371
-- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1373–1401
+- [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–759
+- [18. Editable value](#18-editable-value) · lines 761–1176
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1020–1077
+  - [In a table's rows](#in-a-tables-rows) · lines 1079–1164
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1166–1176
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1178–1244
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1246–1310
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1312–1377
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1379–1407
 
 <!-- /index -->
 
@@ -731,6 +731,12 @@ const save = useSaveWidgetField(widget.id) // one per control
   page. When the save answers, the view takes the record the server
   returned, so a server-side effect shows (a computed field, a flag the
   change cleared). Never write a quick action's mutation by hand.
+- **A refresh the save always needs goes on the hook**: another query
+  the change affects (a summary, a related list) is invalidated in
+  `useRecordUpdate`'s own `onSuccess`, never `mutate(change, { onSuccess })`,
+  which TanStack skips once the control unmounts (a popover closed
+  mid-save). Per-call effects (navigate, a toast in the call's words)
+  stay on `mutate()`.
 - **A list is sent whole, built from the latest record**: pass a function
   of the record (`(current) => ({ checklist: ... })`), not a list read from
   props. Saves of one record run one at a time and each request is built

package/dist/hooks/use-record-update.d.ts

@@ -35,6 +35,17 @@ export type RecordUpdateOptions<TRecord extends {
      * `AppError`, and `refusalReason` words it.
      */
     toastOnError?: boolean;
+    /**
+     * After a save the server accepted, once the caches hold its record:
+     * a refresh the save always needs (another query it changes). Runs
+     * even when the calling component has unmounted, unlike a `mutate()`
+     * callback; keep per-call effects (navigate, a toast) on `mutate()`.
+     */
+    onSuccess?: (saved: TRecord, change: RecordChange<TRecord, TUpdate>) => unknown;
+    /** After a refused save, once it has rolled back (and toasted, unless `toastOnError: false`). */
+    onError?: (error: AppError, change: RecordChange<TRecord, TUpdate>) => unknown;
+    /** After every save, accepted or refused, following `onSuccess` or `onError`. */
+    onSettled?: (saved: TRecord | undefined, error: AppError | null, change: RecordChange<TRecord, TUpdate>) => unknown;
 };
 type Entry<TRecord, TUpdate> = {
     change: RecordChange<TRecord, TUpdate>;
@@ -52,7 +63,7 @@ export declare function refusalReason(error: AppError, sent?: object): string;
  */
 export declare function recordUpdateMutationOptions<TRecord extends {
     id: RecordId;
-}, TUpdate extends Partial<TRecord>>(queryClient: QueryClient, { id, detailKey, listsKey, update, name, optimistic, toastOnError }: RecordUpdateOptions<TRecord, TUpdate>): MutationOptions<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+}, TUpdate extends Partial<TRecord>>(queryClient: QueryClient, { id, detailKey, listsKey, update, name, optimistic, toastOnError, onSuccess, onError, onSettled, }: RecordUpdateOptions<TRecord, TUpdate>): MutationOptions<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
     entry: Entry<TRecord, TUpdate>;
 }>;
 /**
@@ -61,7 +72,8 @@ export declare function recordUpdateMutationOptions<TRecord extends {
  * with the entity's query keys and its gateway PATCH, then
  * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
  * `isPending` is that control's own save in flight. A refusal rolls back
- * and shows a toast by itself.
+ * and shows a toast by itself. A refresh every save needs goes in the
+ * options' `onSuccess`, which runs even if the control has unmounted.
  */
 export declare function useRecordUpdate<TRecord extends {
     id: RecordId;

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

@@ -30,6 +30,13 @@
 // `toastOnError: false`: nothing changes on screen until the server
 // agrees, and a refusal comes back to the field (`mutateAsync` rejects)
 // instead of a toast.
+//
+// A follow-up the save needs once the server answers (refetching a
+// summary or a related list) goes in the hook's own `onSuccess`,
+// `onError` or `onSettled`, not `mutate(change, { onSuccess })`: TanStack
+// runs a `mutate()` callback only while the calling component is still
+// mounted, so a popover closed mid-save would skip it. These run on the
+// mutation, after the package's own cache work, either way (#250).
 import { hashKey, useMutation, useQueryClient, } from '@tanstack/react-query';
 import { toast } from 'sonner';
 const states = new WeakMap();
@@ -62,7 +69,7 @@ export function refusalReason(error, sent) {
  * The mutation options behind `useRecordUpdate`, for a given QueryClient.
  * Exported for tests and for code outside React; screens use the hook.
  */
-export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsKey, update, name, optimistic = true, toastOnError = true }) {
+export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsKey, update, name, optimistic = true, toastOnError = true, onSuccess, onError, onSettled, }) {
     const key = hashKey(detailKey);
     const lists = { queryKey: listsKey };
     const map = recordStates(queryClient);
@@ -133,25 +140,27 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
             render(state);
             return { entry };
         },
-        onError: (error, _change, context) => {
+        onError: (error, change, context) => {
             const state = map.get(key);
-            if (!state || !context)
-                return;
-            // What was sent: the change built on the record it was sent against.
-            const record = state.confirmed;
-            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)}`);
+            if (state && context) {
+                // What was sent: the change built on the record it was sent against.
+                const record = state.confirmed;
+                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)}`);
+            }
+            return onError?.(error, change);
         },
-        onSuccess: (saved, _change, context) => {
+        onSuccess: (saved, change, context) => {
             const state = map.get(key);
-            if (!state || !context)
-                return;
-            state.confirmed = saved;
-            settle(state, context.entry);
+            if (state && context) {
+                state.confirmed = saved;
+                settle(state, context.entry);
+            }
+            return onSuccess?.(saved, change);
         },
+        onSettled: (saved, error, change) => onSettled?.(saved, error, change),
     };
 }
 /**
@@ -160,7 +169,8 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
  * with the entity's query keys and its gateway PATCH, then
  * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
  * `isPending` is that control's own save in flight. A refusal rolls back
- * and shows a toast by itself.
+ * and shows a toast by itself. A refresh every save needs goes in the
+ * options' `onSuccess`, which runs even if the control has unmounted.
  */
 export function useRecordUpdate(options) {
     const queryClient = useQueryClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "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": {