@scalewing/react 1.49.0 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @scalewing/react
 
+## 1.50.0
+
+### Minor Changes
+
+- d707587: `ScreenPreview`: a drawn stand-in for an app's screen on a public page, a `figure` whose screen is one image (`role="img"`) named by `label`, with an optional `eyebrow`, `title` and visible `caption`. `frame="card"` (default) or `"device"`, a 20rem phone from `md` and the card below it. Its content is `PreviewGroup`s of `PreviewRow`s (`kind` `plain`, `total`, `note`, `filled`, `alert`) and `PreviewTiles` (three to a row on a phone, six from `md`). New classes `sw-screen-preview*`, `sw-preview-*`, with `screenPreviewFrames` and `previewRowKinds`; a blank label, an unknown frame or kind, or bad tiles throw a `RangeError`. No new tokens or dependencies. Request: `docs/requests/teisoro-screen-preview.md`.
+- 7a647d3: `ThemeProvider` takes `frame` (`none` by default, or `site`): `site` writes `data-frame="site"` and makes the themed root a column at least the window's height whose last child (the footer) is pushed to its foot, so a short page's footer meets the window's foot. `themeFrames` and `ThemeFrame` list the frames; an unknown one throws a `RangeError`. No new tokens or dependencies. Request: `docs/requests/teisoro-site-frame.md`.
+
 ## 1.49.0
 
 ### Minor Changes

package/README.md

@@ -36,6 +36,10 @@ import {
   Separator,
   Band,
   Hero,
+  ScreenPreview,
+  PreviewGroup,
+  PreviewRow,
+  PreviewTiles,
   SiteFooter,
   SiteHeader,
   DescriptionList,
@@ -81,6 +85,16 @@ The accent does not keep 4.5:1 on the grey in every palette, so keep links and a
 </ThemeProvider>
 ```
 
+`frame="site"` (opt-in; `themeFrames`, default `"none"`) makes the themed node a public site's page: a column at least the window's height (the canvas already keeps that height) whose last child is pushed to its foot, so a page shorter than the window still has its footer at the window's foot. It writes `data-frame="site"` on the themed node. Put the header, `main` and footer as the provider's direct children, the footer last: anything rendered after it as a direct child (a live region, a toast host) would take the footer's place at the foot, so put those inside `main`. An unknown frame throws a `RangeError`.
+
+```tsx
+<ThemeProvider frame="site" colorScheme="light">
+  <SiteHeader … />
+  <main>…</main>
+  <SiteFooter … />
+</ThemeProvider>
+```
+
 ```html
 <div class="sw-padding-top-4 sw-padding-x-4"></div>
 ```
@@ -1050,6 +1064,23 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 />
 ```
 
+`ScreenPreview` is a drawn stand-in for an app's screen on a public page, until a real screenshot replaces it: a `figure` whose screen is one image (`role="img"`) named by `label`, its alternative text, so a screen reader hears that sentence instead of the rows; an optional `caption` shows under it as the `figcaption`. An optional `eyebrow` and `title` head the screen. Its content is `PreviewGroup`s of `PreviewRow`s (`label` at the start, `value` at the end in tabular numerals; `kind` `plain`, `total` in bold past a hairline, `note` a small label over its words, `filled` on the quiet fill, or `alert` on the danger tint) and `PreviewTiles` (`items` of `{ id, label, value }`, three to a row on a phone, six from `md`). `frame="card"` (default) is a surface card whose groups are parted by hairlines; `frame="device"` draws a 20rem phone from `md` (a bezel in the text colour round a quiet screen with a surface header and each group a card) and the card below `md`. A blank `label`, an unknown `frame` or `kind`, no tiles, or a blank or repeated tile id throws a `RangeError`.
+
+```tsx
+<ScreenPreview
+  frame="device"
+  label="Today's census: 14 herons, 6 egrets, 20 birds in all"
+  eyebrow="Census · Today"
+  title="Birds on the marsh"
+  caption="A photo of the real board goes here."
+>
+  <PreviewGroup>
+    <PreviewRow label="Grey herons" value="14" />
+    <PreviewRow kind="total" label="All birds" value="20" />
+  </PreviewGroup>
+</ScreenPreview>
+```
+
 `SiteFooter` is a public site's footer on the dark inverse band (`Band tone="inverse"`, so a brand moves it with a theme overlay of `inverse`). Supply `brand` (such as a logo for a dark background), an optional `tagline`, and `groups`: each `{ id, label, links }` is a `nav` named by its label, which shows above its links (hidden from assistive technology, since the `nav` already carries it). Each link is `{ id, label, href, current?, lang?, hrefLang? }`; `lang` and `hrefLang` pass through to the link unchecked; `current` sets `aria-current="page"` and draws it in the band's words at label weight, the others in its muted words, underlined on hover and focus. `legal` and `end` fill the bottom row past a hairline, such as the copyright and a language switch. Below `md` the brand takes the full width and the groups two columns; from `md` the brand and the groups share one spread row. Links get the 44 px target on a coarse pointer. Put it last in the page's `body` (outside a `section` or `article`) so it is the page's `contentinfo` landmark. No groups, a group with no links, blank or repeated ids, blank labels or a blank `href` throw a `RangeError`.
 
 ```tsx

package/dist/components/ScreenPreview.d.ts

@@ -0,0 +1,25 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type ScreenPreviewFrame, screenPreviewFrames } from '../css/css-screen-preview.js';
+export { screenPreviewFrames, type ScreenPreviewFrame };
+export type ScreenPreviewProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'role' | 'style' | 'title'> & {
+    /** What the drawn screen shows, said in words: its alternative text. */
+    label: string;
+    /** `card` (default), or `device`, a phone's bezel from `md`. */
+    frame?: ScreenPreviewFrame;
+    /** A small line above the screen's title, such as where in the app it is. */
+    eyebrow?: ReactNode;
+    /** The screen's own title. */
+    title?: ReactNode;
+    /** A visible caption under the screen, such as what will replace it. */
+    caption?: ReactNode;
+    /** `PreviewGroup`s, `PreviewRow`s and `PreviewTiles`. */
+    children: ReactNode;
+};
+/**
+ * A drawn stand-in for an app's screen on a public page: a `figure` whose
+ * screen is one image (`role="img"`) named by `label`, so its rows are
+ * read as that one sentence, with an optional visible `caption`. Its
+ * content is `PreviewGroup`s of `PreviewRow`s and `PreviewTiles`. A blank
+ * label or an unknown frame throws a `RangeError`.
+ */
+export declare function ScreenPreview({ caption, children, className, eyebrow, frame, label, title, ...rest }: ScreenPreviewProps): import("react").JSX.Element;

package/dist/components/ScreenPreview.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
+import { screenPreviewFrameClass, screenPreviewFrames, } from '../css/css-screen-preview.js';
+import { isOneOf } from '../is-one-of.js';
+export { screenPreviewFrames };
+/**
+ * A drawn stand-in for an app's screen on a public page: a `figure` whose
+ * screen is one image (`role="img"`) named by `label`, so its rows are
+ * read as that one sentence, with an optional visible `caption`. Its
+ * content is `PreviewGroup`s of `PreviewRow`s and `PreviewTiles`. A blank
+ * label or an unknown frame throws a `RangeError`.
+ */
+export function ScreenPreview({ caption, children, className, eyebrow, frame = 'card', label, title, ...rest }) {
+    if (!label.trim())
+        throw new RangeError('A ScreenPreview needs a label, its alternative text');
+    if (!isOneOf(screenPreviewFrames, frame))
+        throw new RangeError(`Unknown ScreenPreview frame: ${String(frame)}`);
+    const header = eyebrow || title ? (_jsxs("div", { className: "sw-screen-preview-header", children: [eyebrow ? (_jsx("span", { className: "sw-screen-preview-eyebrow", children: eyebrow })) : null, title ? (_jsx("span", { className: "sw-screen-preview-title", children: title })) : null] })) : null;
+    return (_jsxs("figure", { ...rest, className: cx('sw-screen-preview', screenPreviewFrameClass(frame), className), children: [_jsx("div", { className: "sw-screen-preview-bezel", children: _jsxs("div", { "aria-label": label, className: "sw-screen-preview-screen", role: "img", children: [header, _jsx("div", { className: "sw-screen-preview-body", children: children })] }) }), caption ? (_jsx("figcaption", { className: "sw-screen-preview-caption", children: caption })) : null] }));
+}

package/dist/components/screen-preview/PreviewGroup.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+/**
+ * Rows of a `ScreenPreview` that belong together: parted from the next
+ * group by a hairline on a card, each a card of its own in a device frame.
+ */
+export declare function PreviewGroup({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/components/screen-preview/PreviewGroup.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Rows of a `ScreenPreview` that belong together: parted from the next
+ * group by a hairline on a card, each a card of its own in a device frame.
+ */
+export function PreviewGroup({ children }) {
+    return _jsx("div", { className: "sw-preview-group", children: children });
+}

package/dist/components/screen-preview/PreviewRow.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+import { type PreviewRowKind, previewRowKinds } from '../../css/css-screen-preview.js';
+export { previewRowKinds, type PreviewRowKind };
+export type PreviewRowProps = {
+    label: ReactNode;
+    value: ReactNode;
+    /**
+     * `plain` (default) a label and its figure; `total` the same in bold past
+     * a hairline; `note` a small label over its words; `filled` on the quiet
+     * fill; `alert` on the danger tint.
+     */
+    kind?: PreviewRowKind;
+};
+/** One row of a `ScreenPreview`: a label at its start and a value at its end. */
+export declare function PreviewRow({ kind, label, value }: PreviewRowProps): import("react").JSX.Element;

package/dist/components/screen-preview/PreviewRow.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+import { previewRowKindClass, previewRowKinds, } from '../../css/css-screen-preview.js';
+import { isOneOf } from '../../is-one-of.js';
+export { previewRowKinds };
+/** One row of a `ScreenPreview`: a label at its start and a value at its end. */
+export function PreviewRow({ kind = 'plain', label, value }) {
+    if (!isOneOf(previewRowKinds, kind))
+        throw new RangeError(`Unknown PreviewRow kind: ${String(kind)}`);
+    return (_jsxs("div", { className: cx('sw-preview-row', previewRowKindClass(kind)), children: [_jsx("span", { className: "sw-preview-row-label", children: label }), _jsx("span", { className: "sw-preview-row-value", children: value })] }));
+}

package/dist/components/screen-preview/PreviewTiles.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+/** One tile: `id` keys it and is never shown; `label` sits over `value`. */
+export type PreviewTile = {
+    id: string;
+    label: ReactNode;
+    value: ReactNode;
+};
+export type PreviewTilesProps = {
+    items: readonly PreviewTile[];
+};
+/**
+ * A row of small tiles in a `ScreenPreview`, each a label over its value,
+ * such as counts by kind: three to a row on a phone, six from `md`. No
+ * items, or a blank or repeated id, throws a `RangeError`.
+ */
+export declare function PreviewTiles({ items }: PreviewTilesProps): import("react").JSX.Element;

package/dist/components/screen-preview/PreviewTiles.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A row of small tiles in a `ScreenPreview`, each a label over its value,
+ * such as counts by kind: three to a row on a phone, six from `md`. No
+ * items, or a blank or repeated id, throws a `RangeError`.
+ */
+export function PreviewTiles({ items }) {
+    if (items.length === 0)
+        throw new RangeError('PreviewTiles needs an item');
+    if (items.some((item) => !item.id.trim()))
+        throw new RangeError('PreviewTiles items need nonempty ids');
+    if (new Set(items.map((item) => item.id)).size !== items.length)
+        throw new RangeError('PreviewTiles items need unique ids');
+    return (_jsx("div", { className: "sw-preview-tiles", children: items.map((item) => (_jsxs("div", { className: "sw-preview-tile", children: [_jsx("span", { className: "sw-preview-tile-label", children: item.label }), _jsx("span", { className: "sw-preview-tile-value", children: item.value })] }, item.id))) }));
+}

package/dist/css/css-components.js

@@ -52,6 +52,7 @@ import { cssTooltipClasses } from './css-tooltip.js';
 import { cssInfoTipClasses } from './css-info-tip.js';
 import { cssSeparatorClasses } from './css-separator.js';
 import { cssBandClasses } from './css-band.js';
+import { cssScreenPreviewClasses } from './css-screen-preview.js';
 import { cssHeroClasses } from './css-hero.js';
 import { cssSiteFooterClasses } from './css-site-footer.js';
 import { cssSiteHeaderClasses } from './css-site-header.js';
@@ -202,6 +203,8 @@ ${cssSectionNavClasses()}
 
 ${cssBandClasses()}
 
+${cssScreenPreviewClasses()}
+
 ${cssHeroClasses()}
 
 ${cssSiteFooterClasses()}

package/dist/css/css-document.js

@@ -1,6 +1,7 @@
 import { typographyVariants } from '@scalewing/tokens';
 import { cssBoxLinkClasses } from './css-box-link.js';
 import { cssCanvasGroupedRules } from './css-canvas-grouped.js';
+import { cssThemeFrameRules } from './css-theme-frame.js';
 const body = typographyVariants.body;
 /** The native controls that take typed text: the canvas's text controls. */
 export const typedInputs = [
@@ -87,6 +88,8 @@ body {
 
 ${cssCanvasGroupedRules()}
 
+${cssThemeFrameRules()}
+
 [data-theme] a {
   color: var(--sw-color-accent);
   text-decoration: none;

package/dist/css/css-screen-preview.d.ts

@@ -0,0 +1,10 @@
+/** How a drawn screen is framed: a plain card, or a phone from `md`. */
+export declare const screenPreviewFrames: readonly ["card", "device"];
+export type ScreenPreviewFrame = (typeof screenPreviewFrames)[number];
+/** What a drawn row shows: a figure, a total, a note, a filled or an alert row. */
+export declare const previewRowKinds: readonly ["plain", "total", "note", "filled", "alert"];
+export type PreviewRowKind = (typeof previewRowKinds)[number];
+export declare function screenPreviewFrameClass(frame: ScreenPreviewFrame): string;
+export declare function previewRowKindClass(kind: PreviewRowKind): string;
+export declare function cssScreenPreviewClasses(): string;
+export declare function screenPreviewClassCatalog(): string[];

package/dist/css/css-screen-preview.js

@@ -0,0 +1,232 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { breakpointQuery } from './breakpoints.js';
+import { toneTintFill, toneTintInk } from './tone-tint.js';
+const { caption, label, title } = typographyVariants;
+/** How a drawn screen is framed: a plain card, or a phone from `md`. */
+export const screenPreviewFrames = ['card', 'device'];
+/** What a drawn row shows: a figure, a total, a note, a filled or an alert row. */
+export const previewRowKinds = [
+    'plain',
+    'total',
+    'note',
+    'filled',
+    'alert',
+];
+export function screenPreviewFrameClass(frame) {
+    return `sw-screen-preview-${frame}`;
+}
+export function previewRowKindClass(kind) {
+    return `sw-preview-row-${kind}`;
+}
+/*
+ * The card frame, and the device frame below `md`: one surface card whose
+ * groups are parted by hairlines. Rows set their label at the start and
+ * their figure at the end in tabular numerals.
+ */
+function cardRules() {
+    return `.sw-screen-preview {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+  margin: 0;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.sw-screen-preview-screen {
+  background: var(--sw-color-surface);
+  border-radius: var(--sw-radius-md);
+  color: var(--sw-color-text);
+  display: flex;
+  flex-direction: column;
+  font-family: var(--sw-font-sans);
+  font-size: ${label.fontSize}px;
+  font-variant-numeric: tabular-nums;
+  gap: var(--sw-space-3);
+  line-height: ${label.lineHeight}px;
+  padding: var(--sw-space-4);
+}
+
+.sw-screen-preview-header {
+  display: flex;
+  flex-direction: column;
+}
+
+.sw-screen-preview-eyebrow {
+  color: var(--sw-color-muted);
+  font-size: ${caption.fontSize}px;
+  line-height: ${caption.lineHeight}px;
+}
+
+.sw-screen-preview-title {
+  font-size: ${title.fontSize}px;
+  font-weight: ${title.fontWeight};
+  line-height: ${title.lineHeight}px;
+}
+
+.sw-screen-preview-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+}
+
+.sw-preview-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+}
+
+.sw-preview-group + .sw-preview-group {
+  border-top: 1px solid var(--sw-color-border);
+  padding-top: var(--sw-space-2);
+}
+
+.sw-screen-preview-caption {
+  color: var(--sw-color-muted);
+  font-size: ${caption.fontSize}px;
+  line-height: ${caption.lineHeight}px;
+}`;
+}
+function rowRules() {
+    return `.sw-preview-row {
+  display: flex;
+  gap: var(--sw-space-3);
+  justify-content: space-between;
+  min-width: 0;
+}
+
+.sw-preview-row-value {
+  text-align: end;
+}
+
+.${previewRowKindClass('total')} {
+  border-top: 1px solid var(--sw-color-border);
+  font-weight: ${label.fontWeight};
+  padding-top: var(--sw-space-2);
+}
+
+.${previewRowKindClass('note')} {
+  flex-direction: column;
+  gap: 0;
+}
+
+.${previewRowKindClass('note')} .sw-preview-row-label {
+  color: var(--sw-color-muted);
+  font-size: ${caption.fontSize}px;
+  line-height: ${caption.lineHeight}px;
+}
+
+.${previewRowKindClass('note')} .sw-preview-row-value {
+  text-align: start;
+}
+
+.${previewRowKindClass('filled')},
+.${previewRowKindClass('alert')} {
+  border-radius: var(--sw-radius-sm);
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+.${previewRowKindClass('filled')} {
+  background: var(--sw-color-subtle);
+}
+
+.${previewRowKindClass('alert')} {
+  background: ${toneTintFill('danger')};
+  color: ${toneTintInk('danger')};
+}
+
+.sw-preview-tiles {
+  display: grid;
+  gap: var(--sw-space-2);
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.sw-preview-tile {
+  align-items: center;
+  background: var(--sw-color-subtle);
+  border-radius: var(--sw-radius-sm);
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding: var(--sw-space-2);
+}
+
+.sw-preview-tile-label {
+  color: var(--sw-color-muted);
+  font-size: ${caption.fontSize}px;
+  line-height: ${caption.lineHeight}px;
+}`;
+}
+/*
+ * From `md` the device frame draws a phone: a dark bezel (the text colour)
+ * round a quiet screen whose header is a surface strip and whose groups
+ * are surface cards. Below `md` it is the card, since the page is already
+ * a phone.
+ */
+function wideRules() {
+    const device = `.${screenPreviewFrameClass('device')}`;
+    return `@media ${breakpointQuery('from', 'md')} {
+  .${screenPreviewFrameClass('card')} .sw-screen-preview-screen { padding: var(--sw-space-5); }
+  .sw-preview-tiles { grid-template-columns: repeat(6, minmax(0, 1fr)); }
+  ${device} { width: 20rem; }
+  ${device} .sw-screen-preview-bezel {
+    background: var(--sw-color-text);
+    border-radius: calc(var(--sw-radius-lg) + var(--sw-space-3));
+    padding: var(--sw-space-3);
+  }
+  ${device} .sw-screen-preview-screen {
+    background: var(--sw-color-subtle);
+    border-radius: var(--sw-radius-lg);
+    gap: 0;
+    overflow: hidden;
+    padding: 0;
+  }
+  ${device} .sw-screen-preview-header {
+    background: var(--sw-color-surface);
+    border-bottom: 1px solid var(--sw-color-border);
+    padding: var(--sw-space-4);
+  }
+  ${device} .sw-screen-preview-body { gap: var(--sw-space-3); padding: var(--sw-space-3); }
+  ${device} .sw-preview-group {
+    background: var(--sw-color-surface);
+    border-radius: var(--sw-radius-md);
+    padding: var(--sw-space-3);
+  }
+  ${device} .sw-preview-group + .sw-preview-group { border-top: 0; }
+  ${device} .sw-screen-preview-caption { text-align: center; }
+}
+
+@media (forced-colors: active) {
+  .sw-screen-preview-screen { border: 1px solid CanvasText; }
+}
+
+@media (forced-colors: active) and ${breakpointQuery('from', 'md')} {
+  .${screenPreviewFrameClass('device')} .sw-screen-preview-screen { border: 0; }
+  .${screenPreviewFrameClass('device')} .sw-screen-preview-bezel { border: 1px solid CanvasText; }
+}`;
+}
+export function cssScreenPreviewClasses() {
+    return [cardRules(), rowRules(), wideRules()].join('\n\n');
+}
+export function screenPreviewClassCatalog() {
+    return [
+        'sw-screen-preview',
+        ...screenPreviewFrames.map(screenPreviewFrameClass),
+        'sw-screen-preview-bezel',
+        'sw-screen-preview-screen',
+        'sw-screen-preview-header',
+        'sw-screen-preview-eyebrow',
+        'sw-screen-preview-title',
+        'sw-screen-preview-body',
+        'sw-screen-preview-caption',
+        'sw-preview-group',
+        'sw-preview-row',
+        ...previewRowKinds.map(previewRowKindClass),
+        'sw-preview-row-label',
+        'sw-preview-row-value',
+        'sw-preview-tiles',
+        'sw-preview-tile',
+        'sw-preview-tile-label',
+        'sw-preview-tile-value',
+    ];
+}

package/dist/css/css-theme-frame.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How the themed root lays out its children: `none` (default) leaves them
+ * in the document's flow; `site` is a public site's page, a column at least
+ * the window's height whose last child (the footer) is pushed to its foot,
+ * so a short page's footer still meets the window's foot.
+ */
+export declare const themeFrames: readonly ["none", "site"];
+export type ThemeFrame = (typeof themeFrames)[number];
+export declare function assertThemeFrame(frame: unknown): asserts frame is ThemeFrame;
+export declare function cssThemeFrameRules(): string;

package/dist/css/css-theme-frame.js

@@ -0,0 +1,26 @@
+/**
+ * How the themed root lays out its children: `none` (default) leaves them
+ * in the document's flow; `site` is a public site's page, a column at least
+ * the window's height whose last child (the footer) is pushed to its foot,
+ * so a short page's footer still meets the window's foot.
+ */
+export const themeFrames = ['none', 'site'];
+export function assertThemeFrame(frame) {
+    if (!themeFrames.includes(frame))
+        throw new RangeError(`Unknown ThemeProvider frame: ${String(frame)}`);
+}
+/*
+ * The themed root already keeps the window's height (the document canvas);
+ * the site frame makes it a column and gives its last child the space the
+ * content leaves above it.
+ */
+export function cssThemeFrameRules() {
+    return `[data-theme][data-frame='site'] {
+  display: flex;
+  flex-direction: column;
+}
+
+[data-theme][data-frame='site'] > :last-child {
+  margin-top: auto;
+}`;
+}

package/dist/css/stylesheet.js

@@ -28,6 +28,7 @@ import { tooltipClassCatalog } from './css-tooltip.js';
 import { infoTipClassCatalog } from './css-info-tip.js';
 import { separatorClassCatalog } from './css-separator.js';
 import { bandClassCatalog } from './css-band.js';
+import { screenPreviewClassCatalog } from './css-screen-preview.js';
 import { heroClassCatalog } from './css-hero.js';
 import { siteFooterClassCatalog } from './css-site-footer.js';
 import { siteHeaderClassCatalog } from './css-site-header.js';
@@ -142,6 +143,7 @@ export function utilityClassCatalog() {
         ...infoTipClassCatalog(),
         ...separatorClassCatalog(),
         ...bandClassCatalog(),
+        ...screenPreviewClassCatalog(),
         ...heroClassCatalog(),
         ...siteFooterClassCatalog(),
         ...siteHeaderClassCatalog(),

package/dist/index.d.ts

@@ -72,6 +72,7 @@ export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, tableC
 export { Text, type TextAlign, type TextElement, type TextProps, } from './components/Text.js';
 export { ThemeProvider, useTheme, type ThemeProviderProps, } from './theme/ThemeProvider.js';
 export { themeCanvases, type ThemeCanvas } from './css/css-canvas-grouped.js';
+export { themeFrames, type ThemeFrame } from './css/css-theme-frame.js';
 export { utilityClassCatalog } from './css/stylesheet.js';
 export type { VisibilityProps } from './visibility-classes.js';
 export type { Breakpoint, BreakpointDirection, VisibilityBreakpoint, } from './css/breakpoints.js';
@@ -80,6 +81,13 @@ export { Band, bandElements, bandTones, bandWidths, } from './components/Band.js
 export type { BandElement, BandProps, BandTone, BandWidth, } from './components/Band.js';
 export { SiteHeader } from './components/SiteHeader.js';
 export type { SiteHeaderItem, SiteHeaderLabels, SiteHeaderProps, } from './components/SiteHeader.js';
+export { ScreenPreview, screenPreviewFrames, } from './components/ScreenPreview.js';
+export type { ScreenPreviewFrame, ScreenPreviewProps, } from './components/ScreenPreview.js';
+export { PreviewGroup } from './components/screen-preview/PreviewGroup.js';
+export { PreviewRow, previewRowKinds, } from './components/screen-preview/PreviewRow.js';
+export type { PreviewRowKind, PreviewRowProps, } from './components/screen-preview/PreviewRow.js';
+export { PreviewTiles } from './components/screen-preview/PreviewTiles.js';
+export type { PreviewTile, PreviewTilesProps, } from './components/screen-preview/PreviewTiles.js';
 export { Hero } from './components/Hero.js';
 export type { HeroProps } from './components/Hero.js';
 export { SiteFooter } from './components/SiteFooter.js';

package/dist/index.js

@@ -68,10 +68,15 @@ export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, tableC
 export { Text, } from './components/Text.js';
 export { ThemeProvider, useTheme, } from './theme/ThemeProvider.js';
 export { themeCanvases } from './css/css-canvas-grouped.js';
+export { themeFrames } from './css/css-theme-frame.js';
 export { utilityClassCatalog } from './css/stylesheet.js';
 export { breakpointQuery } from './css/breakpoints.js';
 export { Band, bandElements, bandTones, bandWidths, } from './components/Band.js';
 export { SiteHeader } from './components/SiteHeader.js';
+export { ScreenPreview, screenPreviewFrames, } from './components/ScreenPreview.js';
+export { PreviewGroup } from './components/screen-preview/PreviewGroup.js';
+export { PreviewRow, previewRowKinds, } from './components/screen-preview/PreviewRow.js';
+export { PreviewTiles } from './components/screen-preview/PreviewTiles.js';
 export { Hero } from './components/Hero.js';
 export { SiteFooter } from './components/SiteFooter.js';
 export { Separator } from './components/Separator.js';

package/dist/styles.css

@@ -632,6 +632,15 @@ body {
   background-color: var(--sw-canvas-grouped);
 }
 
+[data-theme][data-frame='site'] {
+  display: flex;
+  flex-direction: column;
+}
+
+[data-theme][data-frame='site'] > :last-child {
+  margin-top: auto;
+}
+
 [data-theme] a {
   color: var(--sw-color-accent);
   text-decoration: none;
@@ -4606,6 +4615,178 @@ body {
   .sw-band-inverse { border-block: 1px solid CanvasText; }
 }
 
+.sw-screen-preview {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+  margin: 0;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.sw-screen-preview-screen {
+  background: var(--sw-color-surface);
+  border-radius: var(--sw-radius-md);
+  color: var(--sw-color-text);
+  display: flex;
+  flex-direction: column;
+  font-family: var(--sw-font-sans);
+  font-size: 15px;
+  font-variant-numeric: tabular-nums;
+  gap: var(--sw-space-3);
+  line-height: 20px;
+  padding: var(--sw-space-4);
+}
+
+.sw-screen-preview-header {
+  display: flex;
+  flex-direction: column;
+}
+
+.sw-screen-preview-eyebrow {
+  color: var(--sw-color-muted);
+  font-size: 13px;
+  line-height: 18px;
+}
+
+.sw-screen-preview-title {
+  font-size: 20px;
+  font-weight: 600;
+  line-height: 28px;
+}
+
+.sw-screen-preview-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+}
+
+.sw-preview-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-2);
+}
+
+.sw-preview-group + .sw-preview-group {
+  border-top: 1px solid var(--sw-color-border);
+  padding-top: var(--sw-space-2);
+}
+
+.sw-screen-preview-caption {
+  color: var(--sw-color-muted);
+  font-size: 13px;
+  line-height: 18px;
+}
+
+.sw-preview-row {
+  display: flex;
+  gap: var(--sw-space-3);
+  justify-content: space-between;
+  min-width: 0;
+}
+
+.sw-preview-row-value {
+  text-align: end;
+}
+
+.sw-preview-row-total {
+  border-top: 1px solid var(--sw-color-border);
+  font-weight: 600;
+  padding-top: var(--sw-space-2);
+}
+
+.sw-preview-row-note {
+  flex-direction: column;
+  gap: 0;
+}
+
+.sw-preview-row-note .sw-preview-row-label {
+  color: var(--sw-color-muted);
+  font-size: 13px;
+  line-height: 18px;
+}
+
+.sw-preview-row-note .sw-preview-row-value {
+  text-align: start;
+}
+
+.sw-preview-row-filled,
+.sw-preview-row-alert {
+  border-radius: var(--sw-radius-sm);
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+.sw-preview-row-filled {
+  background: var(--sw-color-subtle);
+}
+
+.sw-preview-row-alert {
+  background: color-mix(in srgb, var(--sw-color-danger) 10%, var(--sw-color-surface));
+  color: color-mix(in srgb, var(--sw-color-danger) 70%, var(--sw-color-text));
+}
+
+.sw-preview-tiles {
+  display: grid;
+  gap: var(--sw-space-2);
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.sw-preview-tile {
+  align-items: center;
+  background: var(--sw-color-subtle);
+  border-radius: var(--sw-radius-sm);
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding: var(--sw-space-2);
+}
+
+.sw-preview-tile-label {
+  color: var(--sw-color-muted);
+  font-size: 13px;
+  line-height: 18px;
+}
+
+@media (min-width: 48rem) {
+  .sw-screen-preview-card .sw-screen-preview-screen { padding: var(--sw-space-5); }
+  .sw-preview-tiles { grid-template-columns: repeat(6, minmax(0, 1fr)); }
+  .sw-screen-preview-device { width: 20rem; }
+  .sw-screen-preview-device .sw-screen-preview-bezel {
+    background: var(--sw-color-text);
+    border-radius: calc(var(--sw-radius-lg) + var(--sw-space-3));
+    padding: var(--sw-space-3);
+  }
+  .sw-screen-preview-device .sw-screen-preview-screen {
+    background: var(--sw-color-subtle);
+    border-radius: var(--sw-radius-lg);
+    gap: 0;
+    overflow: hidden;
+    padding: 0;
+  }
+  .sw-screen-preview-device .sw-screen-preview-header {
+    background: var(--sw-color-surface);
+    border-bottom: 1px solid var(--sw-color-border);
+    padding: var(--sw-space-4);
+  }
+  .sw-screen-preview-device .sw-screen-preview-body { gap: var(--sw-space-3); padding: var(--sw-space-3); }
+  .sw-screen-preview-device .sw-preview-group {
+    background: var(--sw-color-surface);
+    border-radius: var(--sw-radius-md);
+    padding: var(--sw-space-3);
+  }
+  .sw-screen-preview-device .sw-preview-group + .sw-preview-group { border-top: 0; }
+  .sw-screen-preview-device .sw-screen-preview-caption { text-align: center; }
+}
+
+@media (forced-colors: active) {
+  .sw-screen-preview-screen { border: 1px solid CanvasText; }
+}
+
+@media (forced-colors: active) and (min-width: 48rem) {
+  .sw-screen-preview-device .sw-screen-preview-screen { border: 0; }
+  .sw-screen-preview-device .sw-screen-preview-bezel { border: 1px solid CanvasText; }
+}
+
 .sw-hero {
   align-items: center;
   display: grid;

package/dist/theme/ThemeProvider.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from 'react';
 import { type ColorScheme, type PaletteId, type Theme, type ThemeColors } from '@scalewing/tokens';
 import { type ThemeCanvas } from '../css/css-canvas-grouped.js';
+import { type ThemeFrame } from '../css/css-theme-frame.js';
 export type ThemeProviderProps = {
     colorScheme?: ColorScheme | 'system';
     palette?: PaletteId;
@@ -14,7 +15,15 @@ export type ThemeProviderProps = {
      * colours keep it. An unknown value throws a `RangeError`.
      */
     canvas?: ThemeCanvas;
+    /**
+     * `none` (default) leaves the children in the document's flow; `site`
+     * (opt-in) makes the themed root a public site's page: a column at least
+     * the window's height whose last child (the footer) sits at its foot, so
+     * a short page's footer meets the window's foot. An unknown value throws
+     * a `RangeError`.
+     */
+    frame?: ThemeFrame;
     children: ReactNode;
 };
-export declare function ThemeProvider({ colorScheme, palette, colors, canvas, children, }: ThemeProviderProps): import("react").JSX.Element;
+export declare function ThemeProvider({ colorScheme, palette, colors, canvas, frame, children, }: ThemeProviderProps): import("react").JSX.Element;
 export declare function useTheme(): Theme;

package/dist/theme/ThemeProvider.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useMemo, useState, } from 'react';
 import { createTheme, secondaryActionBorder, semanticColorKeys, } from '@scalewing/tokens';
 import { assertThemeCanvas, } from '../css/css-canvas-grouped.js';
+import { assertThemeFrame } from '../css/css-theme-frame.js';
 const ThemeContext = createContext(null);
 function schemeFromMedia() {
     if (typeof window === 'undefined' ||
@@ -25,8 +26,9 @@ function themeCssVars(theme) {
     vars['--sw-glass-specular'] = theme.glass.specular;
     return vars;
 }
-export function ThemeProvider({ colorScheme = 'system', palette, colors, canvas = 'default', children, }) {
+export function ThemeProvider({ colorScheme = 'system', palette, colors, canvas = 'default', frame = 'none', children, }) {
     assertThemeCanvas(canvas);
+    assertThemeFrame(frame);
     const [systemScheme, setSystemScheme] = useState(schemeFromMedia);
     useEffect(() => {
         if (colorScheme !== 'system' || typeof window.matchMedia !== 'function') {
@@ -42,7 +44,7 @@ export function ThemeProvider({ colorScheme = 'system', palette, colors, canvas
     }, [colorScheme]);
     const resolvedScheme = colorScheme === 'system' ? systemScheme : colorScheme;
     const theme = useMemo(() => createTheme({ colorScheme: resolvedScheme, palette, colors }), [colors, palette, resolvedScheme]);
-    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsx("div", { "data-canvas": canvas === 'default' ? undefined : canvas, "data-palette": palette, "data-theme": theme.colorScheme, style: themeCssVars(theme), children: children }) }));
+    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsx("div", { "data-canvas": canvas === 'default' ? undefined : canvas, "data-frame": frame === 'none' ? undefined : frame, "data-palette": palette, "data-theme": theme.colorScheme, style: themeCssVars(theme), children: children }) }));
 }
 export function useTheme() {
     const theme = useContext(ThemeContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",