@tristan2828/ui-foundation 4.36.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/conventions/docs/design-language.md

@@ -12,11 +12,11 @@
 - [Typography](#typography) · lines 242–324
   - [Written text (notes)](#written-text-notes) · lines 273–324
 - [Density](#density) · lines 326–383
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 385–460
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 462–520
-- [Notices](#notices) · lines 522–550
-- [A value over time](#a-value-over-time) · lines 552–585
-- [A list as a board](#a-list-as-a-board) · lines 587–638
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 385–463
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 465–523
+- [Notices](#notices) · lines 525–553
+- [A value over time](#a-value-over-time) · lines 555–588
+- [A list as a board](#a-list-as-a-board) · lines 590–641
 
 <!-- /index -->
 
@@ -424,7 +424,10 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
 - **Three to six rows.** A widget is a sample, not the list: ask the API
   for that many (the query's page size) and put the rest behind the
   header `link` ("All", "All doing"), which goes to the full list
-  filtered the same way. Set `skeletonRows` to the number it usually holds, so the card
+  filtered the same way. A widget about a service outside the app links
+  its header there instead: `link={{ href: 'https://…', label: 'Open
+  <service>' }}` opens it in a new tab, with the external-link mark and
+  "(opens in a new tab)" for a screen reader. Set `skeletonRows` to the number it usually holds, so the card
   keeps its height when the data arrives.
 - **Each widget owns its four states.** Loading is a skeleton of rows,
   empty is one quiet line the app writes ("Nothing waiting", not "No

package/conventions/docs/reminders.md

@@ -68,6 +68,18 @@ Scope it to the signed-in user, as Widgets are.
   sends a reminder when today is one of its days in its time zone and the
   time has come, once a day at most. More than 15 minutes late (the
   backend was down) and it's skipped for the day rather than sent late.
+- **Reminders in a table of the app's own** (another schema, another
+  name, as an app with a schema per module keeps them): define its table
+  model with the same columns (`id`, `user_id`, `title`, `body`, `url`,
+  `time_of_day`, `days`, `time_zone`, `enabled`, `last_sent_on`) and hand
+  it to the job, `reminders.register(model=MyReminder)` in place of
+  `reminders.register()`. Left out, the job reads the package's
+  `reminders` table. Neither table is on `SQLModel.metadata` until the
+  app uses it: `push_subscriptions` arrives with `foundation_backend.push`
+  (and `foundation_backend.reminders`, which sends through it), the
+  package's `reminders` only with its `Reminder` model (imported, or the
+  job run without a model). So an app without push, or with its own
+  table, gets neither from `create_all` or autogenerate.
 - **Something else to send?** Call `send_push` from the app's own code or
   job: a message when a long task finishes, a daily summary. The `url` is
   always the app's own path.

package/dist/components/app/widget-card.d.ts

@@ -14,14 +14,12 @@ export interface WidgetCardProps {
     headingLevel?: 2 | 3 | 4 | 5 | 6;
     /**
      * A link on the right of the header to everything the widget samples:
-     * `{ to: '/tasks?status=doing', label: 'All doing' }`. Its accessible
-     * name is `label`, described by the title, so several "All" links on one
-     * page stay distinct.
+     * `{ to: '/tasks?status=doing', label: 'All doing' }`, or an outside
+     * address, opened in a new tab: `{ href: 'https://example.com', label:
+     * 'Open Example' }`. Its accessible name is `label`, described by the
+     * title, so several "All" links on one page stay distinct.
      */
-    link?: {
-        to: To;
-        label: string;
-    };
+    link?: WidgetCardLink;
     isLoading: boolean;
     error?: AppError | null;
     onRetry?: () => void;
@@ -44,6 +42,15 @@ export interface WidgetCardProps {
     children?: ReactNode;
     className?: string;
 }
+export type WidgetCardLink = {
+    to: To;
+    label: string;
+    href?: never;
+} | {
+    href: string;
+    label: string;
+    to?: never;
+};
 export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, children, className, }: WidgetCardProps): import("react").JSX.Element;
 /** The rows of a WidgetCard: a list with a divider between rows. */
 export declare function WidgetList({ children, className }: {

package/dist/components/app/widget-card.js

@@ -24,6 +24,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // where that's blocked). The body is hidden, not unmounted, so whatever
 // the app keeps in it stays put.
 //
+// The header's link is an app route (`to`) or, for a widget about a
+// service outside the app, its address (`href`, #248): that one opens in a
+// new tab, with the outside-link mark and a screen reader's "(opens in a
+// new tab)", as WidgetListItem's `href` does.
+//
 // WidgetList and WidgetListItem are the common body: rows with dividers,
 // each a primary link (or plain text) truncated to one line, an optional
 // muted note ("2 h ago") and an optional trailing element (a badge, a
@@ -52,7 +57,7 @@ export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoadin
     const state = error ? 'error' : isLoading ? 'loading' : isEmpty ? 'empty' : 'success';
     const [folded, setFolded] = useRememberedFlag(collapsible && storageKey !== undefined ? `${storageKey}:collapsed` : undefined, defaultCollapsed);
     const collapsed = collapsible && folded;
-    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, "data-collapsed": collapsed || undefined, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), (link || collapsible) && (_jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label })), collapsible && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-labelledby": headingId, "aria-expanded": !collapsed, "aria-controls": contentId, onClick: () => setFolded(!collapsed), 
+    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, "data-collapsed": collapsed || undefined, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), (link || collapsible) && (_jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [link?.href !== undefined ? (_jsxs("a", { href: link.href, target: "_blank", rel: "noreferrer", "aria-describedby": headingId, className: cn(HEADER_LINK_CLASS, 'inline-flex items-center gap-1'), children: [link.label, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })) : (link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label }))), collapsible && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-labelledby": headingId, "aria-expanded": !collapsed, "aria-controls": contentId, onClick: () => setFolded(!collapsed), 
                                     // The button's own open look (a filled background) would
                                     // read as pressed: the chevron says it.
                                     className: "-my-1 -mr-1.5 aria-expanded:not-hover:bg-transparent", children: _jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('transition-transform', collapsed && '-rotate-90') }) }))] }))] }), _jsx(CardContent, { id: contentId, hidden: collapsed, "aria-busy": state === 'loading' || undefined, children: error ? (_jsx(ErrorState, { error: error, onRetry: onRetry, size: "compact" })) : state === 'loading' ? (_jsx(WidgetListSkeleton, { rows: skeletonRows })) : state === 'empty' ? (_jsx("p", { "data-state": "empty", className: "py-2 type-body text-muted-foreground", children: emptyMessage })) : (children) })] }) }));

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/dist/index.d.ts

@@ -40,7 +40,7 @@ export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from '.
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
 export { ModuleCard, ModuleStrip, type CategorySlot, type ModuleCardLink, type ModuleCardPlace, type ModuleCardProps, type ModuleStripProps, } from './components/app/module-card.js';
-export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
+export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardLink, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.js';

package/package.json

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