@tristan2828/ui-foundation 4.38.0 → 4.39.0

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/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.38.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": {