@scalewing/react 1.48.0 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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
+
+- 2ae2974: `Hero`: a public page's opening, a `section` named by its title. An optional `eyebrow` (muted label words), the `title` (the page's `h1` in the `hero` size), an optional `lead` and `actions`, and an optional `media` picture that keeps its own width beside the words from `md` and sits under them below it, where the actions stack to the full width. With no picture the words keep the reading width. New classes `sw-hero*`; a blank `title` throws a `RangeError`. No new tokens or dependencies. Request: `docs/requests/teisoro-hero.md`.
+- dc0c896: `EmptyState` (new): where a list or a page has nothing yet, a centred panel on the surface with a dashed hairline edge that fills its column (a page column or a Card). `title` is a heading at `titleAs` (`h2` by default, or `h3`; `emptyStateTitleElements`), `description` a muted line, `icon` a decorative glyph in a quiet square, `actions` a centred row that wraps (44 px Buttons on a coarse pointer). Forced colours keep the dashed edge. A blank `title` or `description` or an unknown `titleAs` throws a `RangeError`. New classes `sw-empty-state`, `sw-empty-state-icon`, `sw-empty-state-title`, `sw-empty-state-description`, `sw-empty-state-actions`. No new tokens or dependencies. Request: `docs/requests/futmas-empty-state.md`.
+- 6d3cbe8: `Grid` takes `fit` (`narrow` 15rem, `medium` 16.25rem, `wide` 18.75rem): as many columns as the grid's width holds at that minimum, sharing the row, one when the grid is narrower, so a row of cards reflows with no breakpoint. Not with `columns` or `columnsBelow`; either, or an unknown `fit`, throws a `RangeError`. New classes `sw-grid-fit-*` and the `gridFits` list and `GridFit` type. No new tokens or dependencies. Request: `docs/requests/teisoro-grid-fit.md`.
+- b466bbb: `Text` takes the tokens' new variants `hero` (an `h1` by default), `headline` (an `h2`) and `lead` (a `p`), each stepping down to its compact size below `md` like `display` and `heading`. New classes `sw-text-hero`, `sw-text-headline`, `sw-text-lead`, generated from the tokens. Needs `@scalewing/tokens` 1.7.0. Request: `docs/requests/teisoro-showcase-type.md`.
+- 7b57979: `Stepper` takes `unit` (opt-in), a short muted word after the count inside its frame, such as "min" or "players". The count is read with it (`aria-valuetext` "90 min") unless `valueText` says it in words; the unit itself is hidden from assistive technology. The frame draws the control surface, focus ring and the invalid, changed and disabled states; the count keeps its few-digit width, so the frame never follows it. A blank `unit` throws a `RangeError`. New classes `sw-stepper-count`, `sw-stepper-unit`. No new tokens or dependencies. Request: `docs/requests/futmas-stepper-unit.md`.
+
+### Patch Changes
+
+- Updated dependencies [b466bbb]
+  - @scalewing/tokens@1.7.0
+
 ## 1.48.0
 
 ### Minor Changes

package/README.md

@@ -35,10 +35,16 @@ import {
   InfoTip,
   Separator,
   Band,
+  Hero,
+  ScreenPreview,
+  PreviewGroup,
+  PreviewRow,
+  PreviewTiles,
   SiteFooter,
   SiteHeader,
   DescriptionList,
   DescriptionItem,
+  EmptyState,
   FixtureGroup,
   FixtureRow,
   ListGroup,
@@ -79,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>
 ```
@@ -189,7 +205,7 @@ A chosen photo can show itself: `value.preview` is the address of a small image
 />
 ```
 
-`Stepper` is a whole-number count changed with − and + or typed. The count is a native text input with `role="spinbutton"` and `inputmode="numeric"`, named by `label` (visible above it, or `labelVisuallyHidden` where table headers say it) and the one tab stop: ArrowUp and ArrowDown step it by `step` (default 1), Home goes to `min` and End to a finite `max` (a range below zero takes `inputmode="text"`, since a phone's numeric pad has no minus key). The − and + buttons are pointer targets outside the tab order, named by `decrementLabel` and `incrementLabel` (your copy), and a press on one leaves focus where it was; the count and both buttons sit in a `group` named by the label. − is disabled at `min` (default 0) and + at `max` (no upper bound when left out). `value` is a count or `null` for an empty box, which the buttons treat as `min` and `placeholder` can fill. Typed text is refused unless it is digits (with a leading minus when `min` is below zero), so `onChange` only receives a whole number or `null`; a typed count is reported as typed even outside the bounds, so say why in `error` (a polite message, `aria-invalid` and the danger border, as `Field`'s), and the buttons then move it back inside them. `aria-describedby` takes ids of elements that describe the count, such as the value it adds up to, read before an `error`'s message. `changed` takes `Field`'s changed look; `readOnly` keeps the count focusable and hides the buttons in their own room; `disabled` stops all three. `limitAppearance="plain"` (default `"faded"`) keeps − at `min` and + at `max` in their usual look instead of faded, for a count sheet where a faded − reads as broken; they are still disabled, a disabled or read-only Stepper is unchanged, forced colors still grey them, and an unknown value throws a `RangeError`. The count is a few digits wide and keeps that width (`width="fixed"`), or fills its container (`width="full"`, for a table cell). Bounds that are not whole numbers, `min` above `max`, or a `step` that is not above zero throw a `RangeError`.
+`Stepper` is a whole-number count changed with − and + or typed. The count is a native text input with `role="spinbutton"` and `inputmode="numeric"`, named by `label` (visible above it, or `labelVisuallyHidden` where table headers say it) and the one tab stop: ArrowUp and ArrowDown step it by `step` (default 1), Home goes to `min` and End to a finite `max` (a range below zero takes `inputmode="text"`, since a phone's numeric pad has no minus key). The − and + buttons are pointer targets outside the tab order, named by `decrementLabel` and `incrementLabel` (your copy), and a press on one leaves focus where it was; the count and both buttons sit in a `group` named by the label. − is disabled at `min` (default 0) and + at `max` (no upper bound when left out). `value` is a count or `null` for an empty box, which the buttons treat as `min` and `placeholder` can fill. Typed text is refused unless it is digits (with a leading minus when `min` is below zero), so `onChange` only receives a whole number or `null`; a typed count is reported as typed even outside the bounds, so say why in `error` (a polite message, `aria-invalid` and the danger border, as `Field`'s), and the buttons then move it back inside them. `aria-describedby` takes ids of elements that describe the count, such as the value it adds up to, read before an `error`'s message. `changed` takes `Field`'s changed look; `readOnly` keeps the count focusable and hides the buttons in their own room; `disabled` stops all three. `limitAppearance="plain"` (default `"faded"`) keeps − at `min` and + at `max` in their usual look instead of faded, for a count sheet where a faded − reads as broken; they are still disabled, a disabled or read-only Stepper is unchanged, forced colors still grey them, and an unknown value throws a `RangeError`. The count is a few digits wide and keeps that width (`width="fixed"`), or fills its container (`width="full"`, for a table cell). `unit` (opt-in) is a short muted word after the count inside its frame, such as "min" or "players": the frame (`sw-stepper-count`) draws the control surface, focus ring and the invalid, changed and disabled states, a press on the word focuses the count, and the count keeps its few-digit width with its digits against the word, so the frame never follows it. The word (`sw-stepper-unit`) is hidden from assistive technology; the count is read with it (`aria-valuetext` "90 min", none while the box is empty), and a `valueText` you pass wins. The default joins the count and the word as given, so a word that changes with the count ("players") reads "1 players": pass `valueText` in your language's right form ("1 player", "11 players"). A blank `unit` throws a `RangeError`. Bounds that are not whole numbers, `min` above `max`, or a `step` that is not above zero throw a `RangeError`.
 
 ```tsx
 <Stepper
@@ -840,6 +856,24 @@ The consumer needs no PDF.js dependency of its own. With another bundler, build
 <Skeleton label="Loading rangers" variant="rows" lines={4} />
 ```
 
+`EmptyState` is where a list or a page has nothing yet: a centred panel on the surface with a dashed hairline edge (the md radius) that fills its column, so it sits in a page column or inside a `Card`. `title` (required) says what is empty ("No teams in Spring 2027 yet"), a heading at `titleAs` (`emptyStateTitleElements`: `"h2"` by default in a page, `"h3"` inside a card under its own heading) in title type. `description` is a muted line under it, usually what to do next. `icon` is a decorative glyph (Lucide in your app) in a quiet subtle-fill square over the title, hidden from assistive technology. `actions` are the ways out, such as a primary and a neutral `Button`, in a centred row that wraps (a 44 px target on a touch screen). The panel is a plain `div`, not a landmark or a live region: if it replaces a list after a person's action, say so yourself. An empty slot (nothing, an empty Fragment or array, or blank words) draws no box. Inside a bordered `Card` (the default glass or `outlined`) the dashed edge sits just inside the card's own hairline and reads as a double edge: where the empty panel is the card's whole content, use it in place of the card, or in an `elevated` or `filled` Card, which draw no hairline. Forced colours keep the dashed edge. A blank `title` or `description` or an unknown `titleAs` throws a `RangeError`.
+
+```tsx
+<EmptyState
+  icon={<Users />}
+  title="No nests counted yet"
+  description="Bring back last spring's nests, or paste a list."
+  actions={
+    <>
+      <Button onPress={copy}>Copy last spring's 12 nests</Button>
+      <Button variant="neutral" onPress={paste}>
+        Paste a list
+      </Button>
+    </>
+  }
+/>
+```
+
 `GlyphTile` is a small rounded square in a categorical colour with the consumer's glyph in white: the mark of a kind beside its name, such as a service in a list. `hue` is one of the `@scalewing/tokens` categorical colours (`green`, `blue`, `orange`, `purple`, `teal`, `rose`, or `neutral`); which kind takes which hue is yours. `size` is `sm` (24), `md` (28, the default) or `lg` (32); the glyph is drawn at spacing step 4 in white, which keeps 3:1 on every fill; pass the SVG (a Lucide component) as the tile's direct child, since only a direct-child SVG is sized. It is always `aria-hidden`, so put the kind's name in visible text beside it. An unknown `hue` or `size` throws a `RangeError`. It may hold up to three letters in place of the glyph, such as initials (`<GlyphTile hue="neutral" size="sm">NSL</GlyphTile>`): words given as its children are drawn in one line at weight 600 and sized from the tile, not the text round it (one letter at half its side, two at 0.42, three at a third), so they fit every size; blank words or more than three letters throw a `RangeError`.
 
 ```tsx
@@ -1018,6 +1052,35 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 />
 ```
 
+`Hero` is a public page's opening, a `section` named by its title: an optional `eyebrow` (muted label words), the `title` (the page's one `h1`, in the `hero` size), an optional `lead` (the `lead` size) and `actions` (links or buttons in a wrapping row, stacked to the full width below `md`), with an optional `media` picture. From `md` the picture keeps its own width at the row's end and the words take the rest; below `md` it sits centred under the words. With no picture the words keep the reading width (`--sw-reading-max`). Put it in the page's column (`sw-container`); it sets no gutter or fill of its own. The title always names the section (`aria-labelledby` is not a prop). Leave out `actions` or `media` rather than passing an empty fragment, which keeps its row or column. A blank `title` throws a `RangeError`.
+
+```tsx
+<Hero
+  eyebrow="For birdwatchers"
+  title="Every heron counted."
+  lead="The north marsh in every season, from the hide to the shore."
+  actions={<ButtonLink href="/visit">Plan a visit</ButtonLink>}
+  media={<img alt="The heron hide at dawn" src="/hide.jpg" />}
+/>
+```
+
+`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
@@ -1181,7 +1244,7 @@ A row can also carry three trailing parts. `unread` marks it new for the person,
 
 `--sw-color-accentSubtle` is the accent tint from `@scalewing/tokens`: a quiet fill behind accent text or glyphs that keeps 4.5:1. The stylesheet and every palette file set it, and a palette that moves the accent or surface retints it.
 
-`Text` steps `display` and `heading` down to the compact token sizes below the `md` breakpoint; consumers do not size type per viewport.
+`Text` steps `hero`, `display`, `headline`, `heading` and `lead` down to the compact token sizes below the `md` breakpoint; consumers do not size type per viewport. `hero` (an `h1`), `headline` (an `h2`) and `lead` (a `p`) are a public page's sizes: its one opening title, its section titles and the sentence under them; an app's screens keep `display` and `heading`.
 
 `sw-container-reading` centres a column at the reading width (`--sw-reading-max`, 46rem, `Article`'s), as `sw-container` centres a page's column at the container width (72rem): `width: 100%`, the max width and auto inline margins, full width below it. Use it for a form or text that reads better narrower than the page, such as an open form of one column. As with `sw-container`, the width is the content box's, so put padding or a border on a child.
 
@@ -1193,6 +1256,16 @@ A row can also carry three trailing parts. `unread` marks it new for the person,
 
 `Grid` places children in one to four (or six) equal-width columns with a token `gap` step. `columnsBelow={{ md: 2 }}` drops to fewer columns below the `md` breakpoint so tiles and stat cards stay readable on a phone. It accepts every `Box` prop.
 
+`fit` (`narrow` 15rem, `medium` 16.25rem, `wide` 18.75rem) fits the columns to the grid's width instead of a fixed count: as many columns as fit at that minimum, sharing the row, and one column when the grid is narrower than it, so a row of cards reflows on a tablet and stacks on a phone with no breakpoint. A fitted grid takes no `columns` or `columnsBelow` (either throws a `RangeError`, as an unknown `fit` does); keep `columnSpan` for fixed-column grids. `gridFits` lists the names.
+
+```tsx
+<Grid fit="narrow" gap={4}>
+  {habitats.map((habitat) => (
+    <Card key={habitat.id}>…</Card>
+  ))}
+</Grid>
+```
+
 Every `Box`-based component (`Box`, `Stack`, `Inline`, `Card`, `Grid`, …) takes `columnSpan` (1, 2, 3, 4 or 6) to cover several columns of the `Grid` it sits in directly, through the generated `sw-grid-span-*` classes. A span is capped at the columns the grid has at the current width, so it never adds an implicit column, and `columnsBelow` still decides the phone layout. A form about twice the width of a side panel, stacking below `md`:
 
 ```tsx

package/dist/components/EmptyState.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+export declare const emptyStateTitleElements: readonly ["h2", "h3"];
+/** The title's heading level: `h2` (the default) in a page, `h3` in a card under its own heading. */
+export type EmptyStateTitleElement = (typeof emptyStateTitleElements)[number];
+export type EmptyStateProps = {
+    /** What is empty, in the consumer's words ("No teams in Spring 2027 yet"). */
+    title: string;
+    /** `h2` (the default) in a page column; `h3` inside a card under its own heading. */
+    titleAs?: EmptyStateTitleElement;
+    /** A muted line under the title: what to do next. Not blank. */
+    description?: string;
+    /** A decorative glyph over the title (Lucide in the consumer), hidden from assistive technology. */
+    icon?: ReactNode;
+    /** The ways out, such as Buttons, in a centred row that wraps. */
+    actions?: ReactNode;
+};
+/**
+ * Where a list or a page has nothing yet: a centred panel on the surface
+ * with a dashed hairline edge, an optional decorative glyph, a title, a
+ * muted line and the actions that fill it. It fills its column, so it fits
+ * a page column or a Card.
+ */
+export declare function EmptyState({ title, titleAs, description, icon, actions, }: EmptyStateProps): import("react").JSX.Element;

package/dist/components/EmptyState.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, Fragment, isValidElement } from 'react';
+import { isOneOf } from '../is-one-of.js';
+import { Text } from './Text.js';
+export const emptyStateTitleElements = ['h2', 'h3'];
+/** Fails closed on blank words or an unknown heading level. */
+function assertEmptyState({ title, titleAs, description }) {
+    if (typeof title !== 'string' || !title.trim())
+        throw new RangeError('EmptyState title must be nonempty');
+    if (titleAs !== undefined && !isOneOf(emptyStateTitleElements, titleAs))
+        throw new RangeError(`Unknown EmptyState titleAs: ${String(titleAs)}`);
+    if (description !== undefined &&
+        (typeof description !== 'string' || !description.trim()))
+        throw new RangeError('EmptyState description must be nonempty');
+}
+/**
+ * Whether a slot draws anything: nothing, a boolean, blank words, an empty
+ * array or a Fragment holding only those is no content, so the slot's box
+ * (and its gap) is left out.
+ */
+function hasContent(node) {
+    return Children.toArray(node).some((child) => {
+        if (typeof child === 'string')
+            return child.trim() !== '';
+        if (isValidElement(child) &&
+            child.type === Fragment)
+            return hasContent(child.props.children);
+        return true;
+    });
+}
+/**
+ * Where a list or a page has nothing yet: a centred panel on the surface
+ * with a dashed hairline edge, an optional decorative glyph, a title, a
+ * muted line and the actions that fill it. It fills its column, so it fits
+ * a page column or a Card.
+ */
+export function EmptyState({ title, titleAs = 'h2', description, icon, actions, }) {
+    assertEmptyState({ title, titleAs, description });
+    return (_jsxs("div", { className: "sw-empty-state", children: [hasContent(icon) ? (_jsx("span", { "aria-hidden": "true", className: "sw-empty-state-icon", children: icon })) : null, _jsx(Text, { as: titleAs, className: "sw-empty-state-title", variant: "title", children: title }), description !== undefined ? (_jsx(Text, { as: "p", className: "sw-empty-state-description", color: "muted", children: description })) : null, hasContent(actions) ? (_jsx("div", { className: "sw-empty-state-actions", children: actions })) : null] }));
+}

package/dist/components/Grid.d.ts

@@ -1,14 +1,22 @@
 import { type SpacingStep } from '@scalewing/tokens';
 import { type Breakpoint } from '../css/breakpoints.js';
-import { type GridColumns } from '../css/css-grid.js';
+import { type GridColumns, type GridFit, gridFits } from '../css/css-grid.js';
 import { type BoxProps } from './Box.js';
 import { type Align } from './Stack.js';
-export type { GridColumns };
+export { gridFits, type GridColumns, type GridFit };
 export type GridProps = BoxProps & {
     /** Where each child sits in the height of its row; unset, children stretch. */
     align?: Align;
     columns?: GridColumns;
     columnsBelow?: Partial<Record<Breakpoint, GridColumns>>;
+    /**
+     * Fits the columns to the grid's width instead of a fixed count: as many
+     * as fit at the named minimum (`narrow` 15rem, `medium` 16.25rem, `wide`
+     * 18.75rem), sharing the row, one column when narrower. Not with
+     * `columns` or `columnsBelow`; a child's `columnSpan` is ignored in a
+     * fitted grid, where every child takes one column.
+     */
+    fit?: GridFit;
     gap?: SpacingStep;
 };
-export declare function Grid({ align, className, columns, columnsBelow, gap, ...rest }: GridProps): import("react").JSX.Element;
+export declare function Grid({ align, className, columns, columnsBelow, fit, gap, ...rest }: GridProps): import("react").JSX.Element;

package/dist/components/Grid.js

@@ -1,12 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
 import { breakpoints } from '../css/breakpoints.js';
-import { gridColumnsBelowClass, gridColumnsClass, } from '../css/css-grid.js';
+import { gridColumnsBelowClass, gridColumnsClass, gridFitClass, gridFits, } from '../css/css-grid.js';
 import { spacingClass } from '../css/spacing-classes.js';
 import { assertGridCount } from '../grid-counts.js';
+import { isOneOf } from '../is-one-of.js';
 import { Box } from './Box.js';
-export function Grid({ align, className, columns = 1, columnsBelow, gap = 0, ...rest }) {
-    assertGridCount('columns', columns);
+export { gridFits };
+export function Grid({ align, className, columns, columnsBelow, fit, gap = 0, ...rest }) {
+    if (fit !== undefined) {
+        if (!isOneOf(gridFits, fit))
+            throw new RangeError(`Unknown Grid fit: ${String(fit)}`);
+        if (columns !== undefined || columnsBelow !== undefined)
+            throw new RangeError('A fitted Grid takes no columns or columnsBelow; fit sets them');
+    }
+    const fixedColumns = columns ?? 1;
+    assertGridCount('columns', fixedColumns);
     const belowClasses = breakpoints.flatMap((breakpoint) => {
         const count = columnsBelow?.[breakpoint];
         if (count === undefined)
@@ -14,5 +23,5 @@ export function Grid({ align, className, columns = 1, columnsBelow, gap = 0, ...
         assertGridCount('columnsBelow', count);
         return [gridColumnsBelowClass(breakpoint, count)];
     });
-    return (_jsx(Box, { className: cx('sw-grid', gridColumnsClass(columns), ...belowClasses, spacingClass('gap', 'all', gap), align && `sw-align-${align}`, className), ...rest }));
+    return (_jsx(Box, { className: cx('sw-grid', fit ? gridFitClass(fit) : gridColumnsClass(fixedColumns), ...belowClasses, spacingClass('gap', 'all', gap), align && `sw-align-${align}`, className), ...rest }));
 }

package/dist/components/Hero.d.ts

@@ -0,0 +1,26 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type HeroProps = Omit<HTMLAttributes<HTMLElement>, 'aria-labelledby' | 'children' | 'style' | 'title'> & {
+    /** The page's title, its one `h1`, in the `hero` size. */
+    title: ReactNode;
+    /** A short line above the title saying who or what the page is for. */
+    eyebrow?: ReactNode;
+    /** The sentence under the title, in the `lead` size. */
+    lead?: ReactNode;
+    /**
+     * Links or buttons in a row, stacked to the full width below `md`. Leave
+     * it out rather than passing an empty fragment, which keeps the row.
+     */
+    actions?: ReactNode;
+    /**
+     * A picture beside the words from `md`, under them below it. Leave it out
+     * rather than passing an empty fragment, which keeps its column.
+     */
+    media?: ReactNode;
+};
+/**
+ * A public page's opening, as a `section` named by its title: an optional
+ * eyebrow, the title (`h1`, `hero` size), an optional lead (`lead` size)
+ * and actions, with an optional picture beside them from `md`. The title
+ * always names the section. A blank title throws a `RangeError`.
+ */
+export declare function Hero({ actions, className, eyebrow, lead, media, title, ...rest }: HeroProps): import("react").JSX.Element;

package/dist/components/Hero.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cx } from '../class-names.js';
+import { Text } from './Text.js';
+function isBlank(node) {
+    return (node === undefined ||
+        node === null ||
+        node === false ||
+        (typeof node === 'string' && node.trim() === ''));
+}
+/**
+ * A public page's opening, as a `section` named by its title: an optional
+ * eyebrow, the title (`h1`, `hero` size), an optional lead (`lead` size)
+ * and actions, with an optional picture beside them from `md`. The title
+ * always names the section. A blank title throws a `RangeError`.
+ */
+export function Hero({ actions, className, eyebrow, lead, media, title, ...rest }) {
+    const titleId = useId();
+    if (isBlank(title))
+        throw new RangeError('A Hero needs a title');
+    const withMedia = !isBlank(media);
+    return (_jsxs("section", { ...rest, "aria-labelledby": titleId, className: cx('sw-hero', withMedia && 'sw-hero-with-media', className), children: [_jsxs("div", { className: "sw-hero-text", children: [isBlank(eyebrow) ? null : (_jsx(Text, { color: "muted", as: "p", variant: "label", children: eyebrow })), _jsx(Text, { id: titleId, variant: "hero", children: title }), isBlank(lead) ? null : _jsx(Text, { variant: "lead", children: lead }), isBlank(actions) ? null : (_jsx("div", { className: "sw-hero-actions", children: actions }))] }), withMedia ? _jsx("div", { className: "sw-hero-media", children: media }) : null] }));
+}

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

@@ -36,8 +36,18 @@ export type StepperProps = {
     disabled?: boolean;
     /** Readable and focusable, never changed: the buttons are hidden and keep their room. */
     readOnly?: boolean;
-    /** Says the count in words for assistive technology (`aria-valuetext`), such as "12 straps". */
+    /**
+     * Says the count in words for assistive technology (`aria-valuetext`),
+     * such as "12 straps". It wins over the count and `unit` read together.
+     */
     valueText?: string;
+    /**
+     * A short muted word after the count, inside its frame, such as "min".
+     * Without `valueText` the count is read with it ("90 min"), word for
+     * word: a unit that changes with the count ("players") reads "1 players",
+     * so pass `valueText` with the right form ("1 player"). Not blank.
+     */
+    unit?: string;
     /**
      * Ids of elements that describe the count, such as the value it adds up
      * to; read before an `error`'s message.

package/dist/components/Stepper.js

@@ -2,9 +2,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useId, useState, } from 'react';
 import { cx } from '../class-names.js';
-import { assertStepperBounds, readStepperEntry, stepperMoves, stepperText, } from '../stepper-count.js';
+import { assertStepperBounds, assertStepperUnit, readStepperEntry, stepperMoves, stepperText, stepperValueText, } from '../stepper-count.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
 import { FieldLabelText } from './FieldLabelText.js';
+import { StepperCountFrame } from './stepper/StepperCountFrame.js';
 export const stepperLimitAppearances = ['faded', 'plain'];
 /** Keeps focus where it was (the count, or nowhere) when a button is pressed. */
 function keepFocus(event) {
@@ -15,9 +16,10 @@ function keepFocus(event) {
  * tab stop (the count, a spin button that ArrowUp and ArrowDown step), with
  * the buttons as pointer targets beside it. − stops at `min`, + at `max`.
  */
-export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden = false, value, onChange, min = 0, max = Number.POSITIVE_INFINITY, step = 1, decrementLabel, incrementLabel, error, changed = false, disabled = false, readOnly = false, valueText, 'aria-describedby': describedBy, placeholder, name, width = 'fixed', limitAppearance = 'faded', }, ref) {
+export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden = false, value, onChange, min = 0, max = Number.POSITIVE_INFINITY, step = 1, decrementLabel, incrementLabel, error, changed = false, disabled = false, readOnly = false, valueText, unit, 'aria-describedby': describedBy, placeholder, name, width = 'fixed', limitAppearance = 'faded', }, ref) {
     const bounds = { min, max, step };
     assertStepperBounds(bounds);
+    assertStepperUnit(unit);
     if (!stepperLimitAppearances.includes(limitAppearance))
         throw new RangeError(`Unknown Stepper limitAppearance: ${String(limitAppearance)}`);
     if (value !== null && !Number.isSafeInteger(value))
@@ -76,10 +78,10 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
     return (_jsxs("div", { className: cx('sw-stepper', width === 'full' && 'sw-stepper-full', invalid && 'sw-stepper-invalid', changed && !invalid && 'sw-stepper-changed', readOnly && 'sw-stepper-readonly', limitAppearance === 'plain' &&
             !disabled &&
             !readOnly &&
-            'sw-stepper-limit-plain'), children: [_jsx("label", { className: labelVisuallyHidden ? 'sw-sr-only' : undefined, htmlFor: inputId, id: labelId, children: _jsx(FieldLabelText, { label: label }) }), _jsxs("div", { "aria-labelledby": labelId, className: "sw-stepper-track", role: "group", children: [_jsx("button", { "aria-controls": inputId, "aria-label": decrementLabel, className: "sw-stepper-button", disabled: moves.down === null, onClick: () => move(moves.down), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: '−' }) }), _jsx("input", { ref: ref, "aria-describedby": [describedBy?.trim() || null, invalid ? errorId : null]
-                            .filter((id) => id !== null)
-                            .join(' ') || undefined, "aria-invalid": invalid || undefined, "aria-valuemax": Number.isFinite(max) ? max : undefined, "aria-valuemin": min, "aria-valuenow": value ?? undefined, "aria-valuetext": valueText, autoComplete: "off", className: "sw-stepper-input", disabled: disabled, id: inputId, 
-                        // iOS's numeric pad has no minus key, so a range below zero takes
-                        // the text keyboard.
-                        inputMode: allowsNegative ? 'text' : 'numeric', name: name, onBlur: () => setDraft(null), onChange: onType, onKeyDown: onKeyDown, placeholder: placeholder, readOnly: readOnly, role: "spinbutton", type: "text", value: text }), _jsx("button", { "aria-controls": inputId, "aria-label": incrementLabel, className: "sw-stepper-button", disabled: moves.up === null, onClick: () => move(moves.up), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: "+" }) })] }), _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
+            'sw-stepper-limit-plain'), children: [_jsx("label", { className: labelVisuallyHidden ? 'sw-sr-only' : undefined, htmlFor: inputId, id: labelId, children: _jsx(FieldLabelText, { label: label }) }), _jsxs("div", { "aria-labelledby": labelId, className: "sw-stepper-track", role: "group", children: [_jsx("button", { "aria-controls": inputId, "aria-label": decrementLabel, className: "sw-stepper-button", disabled: moves.down === null, onClick: () => move(moves.down), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: '−' }) }), _jsx(StepperCountFrame, { unit: unit, children: _jsx("input", { ref: ref, "aria-describedby": [describedBy?.trim() || null, invalid ? errorId : null]
+                                .filter((id) => id !== null)
+                                .join(' ') || undefined, "aria-invalid": invalid || undefined, "aria-valuemax": Number.isFinite(max) ? max : undefined, "aria-valuemin": min, "aria-valuenow": value ?? undefined, "aria-valuetext": stepperValueText(value, unit, valueText), autoComplete: "off", className: "sw-stepper-input", disabled: disabled, id: inputId, 
+                            // iOS's numeric pad has no minus key, so a range below zero takes
+                            // the text keyboard.
+                            inputMode: allowsNegative ? 'text' : 'numeric', name: name, onBlur: () => setDraft(null), onChange: onType, onKeyDown: onKeyDown, placeholder: placeholder, readOnly: readOnly, role: "spinbutton", type: "text", value: text }) }), _jsx("button", { "aria-controls": inputId, "aria-label": incrementLabel, className: "sw-stepper-button", disabled: moves.up === null, onClick: () => move(moves.up), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: "+" }) })] }), _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
 });

package/dist/components/Text.js

@@ -7,7 +7,10 @@ const defaultElement = {
     data: 'span',
     display: 'h1',
     heading: 'h2',
+    headline: 'h2',
+    hero: 'h1',
     label: 'span',
+    lead: 'p',
     title: 'h3',
 };
 export const Text = forwardRef(function Text({ align, as, className, color = 'text', style, truncate = false, variant = 'body', ...rest }, ref) {

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/components/stepper/StepperCountFrame.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+export type StepperCountFrameProps = {
+    /** The count's input. */
+    children: ReactNode;
+    /** A short word after the count; no frame is drawn without one. */
+    unit?: string;
+};
+/**
+ * The count with its unit inside one control frame ("90 min"), as Field's
+ * suffix: the frame draws the control surface and focus ring, and the input
+ * inside it drops its own. The unit is hidden from assistive technology,
+ * which hears it in the count's `aria-valuetext` instead. Without a unit the
+ * input is the frame, unchanged.
+ */
+export declare function StepperCountFrame({ children, unit }: StepperCountFrameProps): import("react").JSX.Element;

package/dist/components/stepper/StepperCountFrame.js

@@ -0,0 +1,25 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * A press on the frame's own chrome (the unit or the padding) focuses the
+ * count, as the text cursor over it promises. A press on the input itself
+ * keeps the browser's own caret placement and selection.
+ */
+function focusCount(event) {
+    const input = event.currentTarget.querySelector('input');
+    if (!input || input.disabled || event.target === input)
+        return;
+    event.preventDefault();
+    input.focus();
+}
+/**
+ * The count with its unit inside one control frame ("90 min"), as Field's
+ * suffix: the frame draws the control surface and focus ring, and the input
+ * inside it drops its own. The unit is hidden from assistive technology,
+ * which hears it in the count's `aria-valuetext` instead. Without a unit the
+ * input is the frame, unchanged.
+ */
+export function StepperCountFrame({ children, unit }) {
+    if (unit === undefined)
+        return _jsx(_Fragment, { children: children });
+    return (_jsxs("span", { className: "sw-stepper-count", onMouseDown: focusCount, children: [children, _jsx("span", { "aria-hidden": "true", className: "sw-stepper-unit", children: unit.trim() })] }));
+}