@tristan2828/ui-foundation 4.37.0 → 4.39.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/timed-screens.md

@@ -3,13 +3,14 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [The view](#the-view) · lines 34–69
-- [The clock](#the-clock) · lines 71–101
-- [Sound](#sound) · lines 103–150
-- [Background tabs](#background-tabs) · lines 152–206
-  - [Interruptions](#interruptions) · lines 186–206
-- [Motion](#motion) · lines 208–212
-- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 214–368
+- [The view](#the-view) · lines 36–109
+  - [The dark stage](#the-dark-stage) · lines 73–109
+- [The clock](#the-clock) · lines 111–141
+- [Sound](#sound) · lines 143–190
+- [Background tabs](#background-tabs) · lines 192–246
+  - [Interruptions](#interruptions) · lines 226–246
+- [Motion](#motion) · lines 248–252
+- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 254–408
 
 <!-- /index -->
 
@@ -19,7 +20,8 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 
 | Part | What it does |
 |---|---|
-| `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen and a held wake lock |
+| `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen, a held wake lock, and `dark` for the dark stage |
+| `SessionStage`, `sessionStageLit`, `sessionStageMain`, `sessionStageQuiet` | The stage under the header: a tone, a glow of it behind the centre, the time lit in it, quiet outline controls |
 | `useSessionClock` | A clock that doesn't drift, with pause, resume and seek: `idle`, `running`, `done` |
 | `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
 | `unlockAudio`, `chime`, `sequence`, `cancelCues`, `say`, `hush`, `vibrate` | Sound cues with no audio files, booked ahead where they must be on time |
@@ -29,7 +31,7 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 
 All of them are imported from `@tristan2828/ui-foundation`. The package's
 Storybook has the whole thing working together: `app/SessionView`, the
-Timer story.
+Timer story, and the same run on the dark stage, DarkStage.
 
 ## The view
 
@@ -68,6 +70,44 @@ const primary = useRef<HTMLButtonElement>(null)
   piece by piece. That fights the primitive's own classes on every
   upgrade, and gets the details above wrong.
 
+### The dark stage
+
+For a screen followed in a dim room: always dark while it runs, whatever
+the app's theme. A black stage, the time lit in the phase's colour with a
+soft glow of it behind, everything else dimmed, the controls quiet
+outlines.
+
+```tsx
+<SessionView open onOpenChange={close} title="Timer" dark={darkStage}>
+  <SessionStage tone={darkStage ? phaseTone : 'neutral'} glow={darkStage}>
+    <div role="timer" className={cn('font-mono text-[17cqi]', darkStage && sessionStageLit)}>{time}</div>
+    <Button variant="outline" className={cn(darkStage && sessionStageQuiet)}>Skip</Button>
+  </SessionStage>
+</SessionView>
+```
+
+- **`dark` scopes the dark tokens to the view.** It puts theme.css's
+  `.dark` on the view itself, so every token and `dark:` variant inside
+  is the dark theme's and the page under it keeps its own. A popup opened
+  from the view (a menu, a select) portals to `<body>` and keeps the app's
+  theme.
+- **`SessionStage`** is the box the run draws in, filling the view below
+  the header. `tone` is the phase's (`neutral`, `success`, `info`,
+  `warning`, `destructive`); `glow` washes it behind the centre, faintly
+  for `neutral`. It sets `--stage-tone` and `--stage-tone-text` for
+  what's inside.
+- **`sessionStageLit`** on the big time: the tone's text shade (white
+  for `neutral`) with a glow around the figures. **`sessionStageQuiet`**
+  on an outline `Button`: no fill, a faint border, dimmed text that
+  brightens on hover. **`sessionStageMain`** on the main control (Start,
+  Done, `variant="outline"`): an outline too, in the foreground colour.
+- **Contrast is checked in dark only**, since the stage is never light:
+  the package's axe run covers the DarkStage story in both app themes. An
+  app's own Playwright runs axe on its screen with the stage on, under a
+  light and a dark app theme.
+- **Make it a setting**, remembered per device like Mute, when the app's
+  own look is the default: off, the view and stage are as before.
+
 ## The clock
 
 `useSessionClock({ running?, endsAt? })` returns

package/dist/components/app/session-view.d.ts

@@ -13,7 +13,23 @@ export type SessionViewProps = {
     fullscreenControl?: boolean;
     /** What takes focus on open (default: the first focusable control, which is the header's). */
     initialFocus?: DialogPrimitive.Popup.Props['initialFocus'];
+    /** Render the view with the dark theme's tokens, whatever the app's theme. */
+    dark?: boolean;
     /** On the area below the header, which holds `children`. */
     className?: string;
 };
-export declare function SessionView({ open, onOpenChange, title, children, keepAwake, fullscreenControl, initialFocus, className, }: SessionViewProps): React.JSX.Element;
+export declare function SessionView({ open, onOpenChange, title, children, keepAwake, fullscreenControl, initialFocus, dark, className, }: SessionViewProps): React.JSX.Element;
+export type SessionStageTone = 'neutral' | 'success' | 'info' | 'warning' | 'destructive';
+export type SessionStageProps = React.ComponentProps<'div'> & {
+    /** The phase's tone: what the glow and `sessionStageLit` take. */
+    tone?: SessionStageTone;
+    /** A soft wash of the tone behind the centre of the stage. */
+    glow?: boolean;
+};
+export declare function SessionStage({ tone, glow, className, style, ...props }: SessionStageProps): React.JSX.Element;
+/** The big time on a stage: the tone's text shade, with a glow of the tone around the figures. */
+export declare const sessionStageLit = "text-[var(--stage-tone-text)] [text-shadow:0_0_0.3em_color-mix(in_oklab,var(--stage-tone)_55%,transparent)]";
+/** A quiet outline control on a stage: no fill, a faint border, dimmed text that brightens on hover. */
+export declare const sessionStageQuiet = "border-foreground/25 bg-transparent text-muted-foreground shadow-none hover:border-foreground hover:bg-transparent hover:text-foreground dark:border-foreground/25 dark:bg-transparent dark:hover:border-foreground dark:hover:bg-transparent";
+/** The main control on a stage (Start, Done): an outline too, in the foreground colour. */
+export declare const sessionStageMain = "border-foreground bg-transparent text-foreground shadow-none hover:bg-foreground/10 hover:text-foreground dark:border-foreground dark:bg-transparent dark:hover:bg-foreground/10";

package/dist/components/app/session-view.js

@@ -8,6 +8,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Optional: a "Full screen" control that also asks the browser for real
 // fullscreen and quietly isn't there where the browser can't (iOS Safari
 // on a phone), and keepAwake, which holds a screen wake lock while open.
+// `dark` renders the view in the dark theme whatever the app's (the dark
+// stage, #253): the dark tokens are scoped to the view, so the page under
+// it keeps its own. SessionStage, below, is the stage under the header.
 // Recipes for its states in Playwright: docs/foundation/timed-screens.md.
 import * as React from 'react';
 import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
@@ -16,10 +19,12 @@ import { cn } from 'cn';
 import { Button } from '../ui/button.js';
 import { Dialog, DialogClose, DialogPortal, DialogTitle } from '../ui/dialog.js';
 import { useWakeLock } from '../../hooks/use-wake-lock.js';
-export function SessionView({ open, onOpenChange, title, children, keepAwake = false, fullscreenControl = false, initialFocus, className, }) {
+export function SessionView({ open, onOpenChange, title, children, keepAwake = false, fullscreenControl = false, initialFocus, dark = false, className, }) {
     useWakeLock(open && keepAwake);
     const fullscreen = useDocumentFullscreen(open);
-    return (_jsx(Dialog, { open: open, onOpenChange: (next) => onOpenChange(next), children: _jsx(DialogPortal, { children: _jsxs(DialogPrimitive.Popup, { "data-slot": "session-view", initialFocus: initialFocus, className: cn('fixed inset-0 z-50 flex flex-col bg-background text-foreground outline-none', 
+    return (_jsx(Dialog, { open: open, onOpenChange: (next) => onOpenChange(next), children: _jsx(DialogPortal, { children: _jsxs(DialogPrimitive.Popup, { "data-slot": "session-view", "data-look": dark ? 'dark' : undefined, initialFocus: initialFocus, className: cn('fixed inset-0 z-50 flex flex-col bg-background text-foreground outline-none', 
+                // theme.css's .dark block remaps the tokens for this subtree only.
+                dark && 'dark scheme-dark', 
                 // The insets are 0 unless the page's viewport meta has viewport-fit=cover.
                 'pt-[env(safe-area-inset-top)] pr-[env(safe-area-inset-right)] pb-[env(safe-area-inset-bottom)] pl-[env(safe-area-inset-left)]', 'duration-150 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0'), children: [_jsxs("header", { className: "flex items-center gap-1 px-4 py-2", children: [_jsx(DialogTitle, { className: "min-w-0 flex-1 truncate type-section-title", children: title }), fullscreenControl && fullscreen.supported && (_jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Full screen", "aria-pressed": fullscreen.active, onClick: fullscreen.toggle, children: fullscreen.active ? _jsx(Minimize2Icon, {}) : _jsx(Maximize2Icon, {}) })), _jsx(DialogClose, { render: _jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Close" }), children: _jsx(XIcon, {}) })] }), _jsx("div", { className: cn('flex min-h-0 flex-1 flex-col overflow-auto px-4 pb-4', className), children: children })] }) }) }));
 }
@@ -66,3 +71,29 @@ function useDocumentFullscreen(open) {
     };
     return { supported, active, toggle };
 }
+// Each tone's solid fill (the glow) and its text shade (the lit time).
+// Neutral glows with the foreground, faintly, and lights in it.
+const STAGE_TONES = {
+    neutral: { solid: 'var(--foreground)', text: 'var(--foreground)', wash: '8%' },
+    success: { solid: 'var(--success)', text: 'var(--success-text)', wash: '24%' },
+    info: { solid: 'var(--info)', text: 'var(--info-text)', wash: '24%' },
+    warning: { solid: 'var(--warning)', text: 'var(--warning-text)', wash: '26%' },
+    destructive: { solid: 'var(--destructive)', text: 'var(--destructive-text)', wash: '24%' },
+};
+// The stage: the area a timed screen draws its run in, filling the view
+// below the header. It sets --stage-tone (the tone's solid) and
+// --stage-tone-text (its text shade) for what's inside, and with `glow` a
+// radial wash of the tone on the page colour, fading out to the edges. Made
+// for a dark SessionView, where the wash reads as light; on a light page it
+// is a faint tint.
+export function SessionStage({ tone = 'neutral', glow = false, className, style, ...props }) {
+    const t = STAGE_TONES[tone];
+    return (_jsx("div", { "data-slot": "session-stage", "data-tone": tone, "data-glow": glow || undefined, className: cn('relative flex min-h-0 flex-1 flex-col', glow &&
+            'bg-[radial-gradient(ellipse_70%_60%_at_50%_52%,color-mix(in_oklab,var(--stage-tone)_var(--stage-wash),var(--background))_0,var(--background)_75%)]', className), style: { '--stage-tone': t.solid, '--stage-tone-text': t.text, '--stage-wash': t.wash, ...style }, ...props }));
+}
+/** The big time on a stage: the tone's text shade, with a glow of the tone around the figures. */
+export const sessionStageLit = 'text-[var(--stage-tone-text)] [text-shadow:0_0_0.3em_color-mix(in_oklab,var(--stage-tone)_55%,transparent)]';
+/** A quiet outline control on a stage: no fill, a faint border, dimmed text that brightens on hover. */
+export const sessionStageQuiet = 'border-foreground/25 bg-transparent text-muted-foreground shadow-none hover:border-foreground hover:bg-transparent hover:text-foreground dark:border-foreground/25 dark:bg-transparent dark:hover:border-foreground dark:hover:bg-transparent';
+/** The main control on a stage (Start, Done): an outline too, in the foreground colour. */
+export const sessionStageMain = 'border-foreground bg-transparent text-foreground shadow-none hover:bg-foreground/10 hover:text-foreground dark:border-foreground dark:bg-transparent dark:hover:bg-foreground/10';

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

@@ -25,7 +25,7 @@ export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
-export { SessionView, type SessionViewProps } from './components/app/session-view.js';
+export { SessionStage, SessionView, sessionStageLit, sessionStageMain, sessionStageQuiet, type SessionStageProps, type SessionStageTone, type SessionViewProps, } from './components/app/session-view.js';
 export { AllowReminders, type AllowRemindersProps } from './components/app/allow-reminders.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';

package/dist/index.js

@@ -28,7 +28,7 @@ export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
-export { SessionView } from './components/app/session-view.js';
+export { SessionStage, SessionView, sessionStageLit, sessionStageMain, sessionStageQuiet, } from './components/app/session-view.js';
 export { AllowReminders } from './components/app/allow-reminders.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';

package/package.json

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