@scalewing/react 1.37.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @scalewing/react
 
+## 1.38.0
+
+### Minor Changes
+
+- ac063ea: `DataBar`: a decorative (`aria-hidden`) horizontal range bar for a table cell or a list row, from `from` to `to` on a track whose domain runs from `min` to `max`, such as where a statement's line leaves the running total. A domain from below zero to above it draws a zero line, so a column of differences diverges around it, the bar's end at zero square. `tone` (`DataBarTone`: `neutral`, `success`, `muted`, `strong`, `accent`; no danger tone, money out is `muted`) colours it from the semantic colours mixed into the surface. Values past the domain are clamped; non-finite numbers, a `min` not under `max` and an unknown tone throw a `RangeError`. The bar follows the writing direction and is drawn in the system text colour in forced colours. New exports `DataBar`, `DataBarProps`, `DataBarTone`, `dataBarTones`; new classes `sw-data-bar`, `sw-data-bar-fill`, `sw-data-bar-diverging`, `sw-data-bar-zero-start`, `sw-data-bar-zero-end` and `sw-data-bar-<tone>`; no new tokens, no new dependency. Request: `docs/requests/teisoro-data-bar.md`.
+- b95f9ea: `Pagination`: previous and next steps through a list shown a page at a time, in a `nav` landmark named by `aria-label` or `aria-labelledby`. It shows the consumer's `rangeLabel` (such as "1–25 of 130 changes") at the inline start, a polite live region, and the steps at the end: icon-only neutral `sm` Buttons named by `labels` (`PaginationLabels`: `previous`, `next`), square, 44 px on a coarse pointer, with a private chevron mirrored right to left. `page` and `pageCount` count from 1 and `onPageChange` receives the page a step goes to. At either end a step is `aria-disabled` (the neutral grey) but stays a Tab stop, so focus is not dropped at the last page, and a press there does nothing. Invalid pages or an empty step label (`labels.previous` or `labels.next`) throw a `RangeError`. New exports `Pagination`, `PaginationProps`, `PaginationLabels`; new classes `sw-pagination`, `sw-pagination-range`, `sw-pagination-steps`, `sw-pagination-step`, `sw-pagination-glyph`, `sw-pagination-glyph-previous` and `sw-pagination-glyph-next`; no new tokens, no new dependency. Request: `docs/requests/teisoro-pagination.md`.
+- 744ed13: `Table` `maxHeight` (opt-in): bounds a table's height by a row count, `{ rows: number }` (new type `TableMaxHeight`), and the rest of the rows scroll inside the table's own region. The region is as tall as that many single-line body rows plus the header row and the footer row when there is one, from the type and spacing tokens the cells are drawn with (compact density included; a sorting header as tall as its buttons, the 44 px touch target on a coarse pointer). The header pins to the region's top and a `TableFooter sticky` total to its bottom; the region stays a keyboard stop named after the table, and an edge with rows scrolled past it draws the scroll shade, cast from the pinned header or total, or from the region's own edge where nothing is pinned (none in forced colours). While the region has keyboard focus, the pinned header and total carry the part of its focus ring they cover. Printed, every row shows. Page pinning (`stickyHeader="page"`, a sticky footer in a table that fits) is unchanged for tables without `maxHeight`; with it, `stickyHeader` `'page'` or `false` throw a `RangeError`, as does a row count that is not a whole number from 1. New classes `sw-table-bounded`, `sw-scroll-more-top` and `sw-scroll-more-bottom`; no new tokens, no new dependency. Request: `docs/requests/teisoro-table-contained-scroll.md`.
+- b638b5e: `TableRow` `variant="total"`: a total mid-table, such as a subtotal the rows above add up to before the table goes on. Its cells are at weight 600 under a 2 px rule across its top (the cells' own collapsed border, kept in forced colours), as a `TableFooter` total is drawn, with no fill, so accent text keeps the contrast it has on the table's own surface. `tableRowVariants` is now `['default', 'sub', 'total']`. New class `sw-table-row-total`; no new tokens, no new dependency. Request: `docs/requests/teisoro-table-row-total.md`.
+
 ## 1.37.0
 
 ### Minor Changes

package/README.md

@@ -10,6 +10,7 @@ import {
   ActionBar,
   ActionMenu,
   BarChart,
+  DataBar,
   Box,
   Button,
   CalendarButton,
@@ -18,6 +19,7 @@ import {
   RadioGroup,
   SectionNav,
   Spinner,
+  Pagination,
   Progress,
   Tooltip,
   InfoTip,
@@ -418,7 +420,7 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 
 A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `'none'`) and `onSort` is its column's sort control: its children become a button in the header's own style with a chevron (before the name in a `numeric` or end-aligned column), and the cell carries `aria-sort` only while it is the sorted column. `sort` on a data cell, or one of the two without the other, throws a `TypeError`. `Table` `layout="fixed"` (default `auto`) sizes the columns from the header row alone, so a filter that hides a row moves no column, and `verticalAlign="top"` (default `middle`) starts every cell of a tall row on its first line. `TableCell` `width` is `min` (an auto table's column takes the least room its content allows, on one line; set it on each cell of the column) or a size, `xs` to `xl` (4, 6, 8, 12 and 16 rem); in a fixed table a column without a width shares what is left, so leave one column, such as a description, unsized. The HTML `width` attribute is not accepted. Unknown values throw a `RangeError`.
 
-A ledger read across as well as down takes `Table` `columnRules` (a hairline at the inline start of every cell after a row's first, mirrored right to left) and `TableCell` `tone` (`success`, `danger`, `muted` or `accent`: the cell's text in the theme colour, as `Text color` uses it; never the only signal, so keep the sign or the words). `TableRow` `variant="sub"` (default `"default"`) sets a row under the one above, as a batch's items: its row header, a `TableCell as="th" scope="row"`, is indented a `space-6` step with a guide bar at the indent (a sub row without a row header is not indented). `TableRow` `struck` keeps a voided row on the record: the subtle fill and the text muted and struck through, toned cells included; it works with either variant. A line-through is not read aloud, so say why in the row, such as a `Badge` "Voided": a Badge in a line of text is not struck, but one that is itself a flex item (a direct child of `Inline`) is, so put it in the title's line. A row header in the body or footer (`th scope="row"`) reads as body text. An unknown `tone` or `variant` throws a `RangeError`.
+A ledger read across as well as down takes `Table` `columnRules` (a hairline at the inline start of every cell after a row's first, mirrored right to left) and `TableCell` `tone` (`success`, `danger`, `muted` or `accent`: the cell's text in the theme colour, as `Text color` uses it; never the only signal, so keep the sign or the words). `TableRow` `variant="sub"` (default `"default"`) sets a row under the one above, as a batch's items: its row header, a `TableCell as="th" scope="row"`, is indented a `space-6` step with a guide bar at the indent (a sub row without a row header is not indented). `TableRow` `variant="total"` is a total mid-table, such as a subtotal the rows above add up to before the table goes on: its cells at weight 600 under a 2 px rule across its top (the cells' own collapsed top border, so forced colors keep it), as a `TableFooter` total is drawn, with no fill, so accent text in it keeps the contrast it has on the table's own surface. Name it with a row header and keep it in the body, after the rows it adds up (not the body's first row under a pinned header, whose rule would sit on its own); a cell's `tone` keeps its colour, and `struck` works on it. Its cells are all at weight 600, so a quiet link or a `TableCell onPress` action in it is no longer set apart by weight: keep a total row's name plain text (a `TableFooter` row is the same). `TableRow` `struck` keeps a voided row on the record: the subtle fill and the text muted and struck through, toned cells included; it works with any variant. A line-through is not read aloud, so say why in the row, such as a `Badge` "Voided": a Badge in a line of text is not struck, but one that is itself a flex item (a direct child of `Inline`) is, so put it in the title's line. A row header in the body or footer (`th scope="row"`) reads as body text. An unknown `tone` or `variant` throws a `RangeError`.
 
 `Table` `stickyHeader` pins the header: the whole `TableHeader` as one group, every row in it (the column headings and any row under them, such as a running total) with all its cells, `th` and `td`, each row under the one above, on the glass with its row and column rules. `true` (default) pins it to the top of the table's own scroll region, `false` lets it scroll away, and `'page'` pins it to the page's top as the page scrolls. With `'page'`, while the table fits its width its region stops being a scroll box (`sw-table-sticky-page`), so the header stays in view under any sticky `AppHeader` (which covers it); a table wider than its region scrolls sideways in it and pins inside it. Use it for a long table whose last row, such as a non-sticky `TableFooter` total, should scroll with the rows. An unknown value throws a `RangeError`.
 
@@ -430,8 +432,44 @@ A ledger read across as well as down takes `Table` `columnRules` (a hairline at
 
 `TableFooter` is the table's `tfoot`, for a total: its cells are set at weight 600 under a 2 px rule across its first row (drawn on each cell's `::before`, so forced colors keep it), and a `TableCell as="th" scope="row"` in it names the total. `sticky` pins the footer to the bottom edge on the header's glass (solid under Reduce Transparency, the system canvas in forced colors), on its own layer over the cells and the pinned header. While the table fits its width, a table with a sticky footer stops being a scroll box, so the footer pins to the page's bottom and the sticky header to its top as the page scrolls; a sticky `AppHeader` covers that header. A table wider than its region scrolls sideways in it and pins to the region instead. A sticky `ActionBar` covers a pinned footer, and so does a `Dialog`'s pinned footer, so do not pair them.
 
+`Table` `maxHeight` (opt-in, `{ rows: number }`, type `TableMaxHeight`) bounds the table's height by a row count, and the rest of the rows scroll inside the table's own region: the region is as tall as that many single-line body rows plus the header row and, when there is one, the footer row (from the type and spacing tokens the cells are drawn with, compact density included, a sorting header as tall as its buttons and the 44 px touch target on a coarse pointer; rows of two lines or with controls, a second header or footer row, and a horizontal scrollbar that takes room show fewer at a time). The header pins to the region's top and a `TableFooter sticky` total to its bottom, so a total over every row stays in view while the rows scroll; a non-sticky footer scrolls with the rows. The region stays a keyboard stop named after the table, and while rows are scrolled out past its top or bottom that edge draws the scroll shade (`sw-scroll-more-top`, `sw-scroll-more-bottom`): cast from the pinned header's last row (a header cell spanning rows from an earlier row casts none) or total over the rows under it, or from the region's own edge where nothing is pinned; none in forced colors. While the region has keyboard focus, the pinned header and total carry the part of its focus ring they cover (their side parts on the first and last cells, so avoid `rowSpan` in a bounded table's header). Printed, every row shows. A bounded table never pins to the page, and without `maxHeight` the page pinning above is unchanged. `stickyHeader` `'page'` or `false` with it, a value that is not `{ rows }`, or a row count that is not a whole number from 1 throw a `RangeError`.
+
+```tsx
+<Table aria-label="Closeouts" maxHeight={{ rows: 12 }}>
+  <TableHeader>…</TableHeader>
+  <TableBody>…</TableBody>
+  <TableFooter sticky>…</TableFooter>
+</Table>
+```
+
 `BarChart` `formatValue` writes the axis's values and each value without its own `valueLabel`, such as a currency. `diverging` puts zero in the middle of each track behind a hairline: a positive bar grows toward the inline end and a negative one toward the start, on one scale, and the axis reads minus the maximum, zero and the maximum. Without it every bar grows from the start. An item's `tone` (`BarChartTone`: `'accent'`, `'success'`, `'warning'` or `'danger'`, listed in the exported `barChartTones`) colors its bar by what it means in place of its sign's default (the accent, or danger for a negative value), such as a diverging chart's overage in `'warning'` and shortage in `'danger'`; a toned bar keeps its sign's place, every tone keeps 3:1 against the track, and an unknown tone throws a `RangeError`. Forced colors draw every bar in the system text color, so the value and its side of zero carry the meaning there.
 
+`DataBar` is a horizontal range bar for a table cell or a list row: a bar from `from` to `to` (whichever is larger is its far end) on a track whose domain runs from `min` to `max`, such as where a statement's line leaves the running total. It fills its container's width, a spacing step 4 tall with no track fill, and its ends follow the writing direction. It is decorative (`aria-hidden`): the figure is the cell's own text, so keep the value beside it, and a cell holding both is named by the figure alone. `tone` (`DataBarTone`, listed in `dataBarTones`; default `'neutral'`) says what the bar is: `'neutral'` for where it started, `'success'` for what came in, `'muted'` for what went out (there is no danger tone: an outflow is not an error), `'strong'` for a subtotal and `'accent'` for what was counted or recorded. Each is a semantic colour mixed into the surface, 1.5:1 or more on it, the three greys 1.5:1 or more apart, in every palette and scheme. A domain from below zero to above it (`min < 0 < max`) draws a hairline at zero, so a column of differences diverges around it (`from={0} to={value}`), and the bar's end at zero is square. Values past the domain are clamped to it; non-finite numbers, a `min` not under `max`, or an unknown tone throw a `RangeError`. Forced colors draw the bar and the zero line in the system text color.
+
+A bar in its own column reads as empty cells to assistive technology, which is fine while the figure's cell carries the value; a bar and its figure can also share one cell, side by side in a `Grid`.
+
+```tsx
+<TableCell numeric>
+  <Grid align="center" columns={2} gap={2}>
+    <DataBar from={0} to={-6} min={-10} max={10} tone="muted" />
+    <span>−6</span>
+  </Grid>
+</TableCell>
+```
+
+`Pagination` steps through a list shown a page at a time, for a list with no total to keep in view (a list that adds up scrolls inside itself instead, with `Table` `maxHeight`). It is a `nav` landmark named by `aria-label` or `aria-labelledby` (one is required), holding the consumer's words for what the page shows (`rangeLabel`, such as "1–25 of 130 changes", in the muted caption at the inline start and announced politely when it changes) and the previous and next steps at the end: icon-only neutral `sm` Buttons, square, the 44 px touch target on a coarse pointer, named by `labels` (`PaginationLabels`: `previous`, `next`) with a private chevron glyph mirrored right to left. `page` (from 1) and `pageCount` place it; a step calls `onPageChange` with the page it goes to. At either end its step looks disabled (`aria-disabled`, the neutral grey) but stays a Tab stop, so focus is never dropped when the last page is reached, and a press there does nothing. Pages that are not whole numbers in range, or an empty step label (`labels.previous` or `labels.next`), throw a `RangeError`. The row wraps on a narrow column, the steps staying at the end.
+
+```tsx
+<Pagination
+  aria-label="Change pages"
+  page={page}
+  pageCount={6}
+  onPageChange={setPage}
+  rangeLabel="1–25 of 130 changes"
+  labels={{ previous: 'Previous page', next: 'Next page' }}
+/>
+```
+
 `Spinner` shows indeterminate loading in small, medium, or large sizes. Supply localized `label` for the one announced status in a loading region. Use `decorative` on additional indicators beside that status so screen readers do not hear the same message repeatedly. Reduced motion leaves a static accented ring.
 
 `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`.

package/dist/accessible-name.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A component's accessible name, given one way: `aria-label` with the words,
+ * or `aria-labelledby` with the id of an element that holds them, never both.
+ * Shared by the components whose name is required (a group, a list of tabs,
+ * a navigation landmark).
+ */
+export type AccessibleName = {
+    'aria-label': string;
+    'aria-labelledby'?: never;
+} | {
+    'aria-label'?: never;
+    'aria-labelledby': string;
+};

package/dist/accessible-name.js

@@ -0,0 +1 @@
+export {};

package/dist/components/DataBar.d.ts

@@ -0,0 +1,48 @@
+import { type HTMLAttributes } from 'react';
+import { type DataBarTone, dataBarTones } from '../css/css-data-bar.js';
+export type { DataBarTone };
+export { dataBarTones };
+export type DataBarProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'aria-hidden'> & {
+    /** One end of the range, in the domain's units. */
+    from: number;
+    /** The other end; the bar runs between the two whichever is larger. */
+    to: number;
+    /** The domain's least value, at the track's inline start. */
+    min: number;
+    /** The domain's greatest value, at the track's inline end. */
+    max: number;
+    /**
+     * What the bar means (default `neutral`): `success` for money in,
+     * `muted` for money out (an outflow is not an error, so there is no
+     * danger tone), `strong` for a subtotal and `accent` for a counted or
+     * recorded figure.
+     */
+    tone?: DataBarTone;
+};
+/**
+ * A horizontal range bar for a table cell or a list row: a bar from `from`
+ * to `to` on a track whose domain runs from `min` to `max`, such as where a
+ * statement's line leaves the running total, or a day's difference on a
+ * domain from below zero to above it, which draws a zero line. It is
+ * decorative (`aria-hidden`): the figure is the cell's own text, so keep
+ * the value beside it. Values past the domain are clamped to it;
+ * non-finite numbers, a `min` not under `max` or an unknown tone throw a
+ * `RangeError`.
+ */
+export declare const DataBar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLSpanElement>, "children" | "aria-hidden"> & {
+    /** One end of the range, in the domain's units. */
+    from: number;
+    /** The other end; the bar runs between the two whichever is larger. */
+    to: number;
+    /** The domain's least value, at the track's inline start. */
+    min: number;
+    /** The domain's greatest value, at the track's inline end. */
+    max: number;
+    /**
+     * What the bar means (default `neutral`): `success` for money in,
+     * `muted` for money out (an outflow is not an error, so there is no
+     * danger tone), `strong` for a subtotal and `accent` for a counted or
+     * recorded figure.
+     */
+    tone?: DataBarTone;
+} & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/components/DataBar.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from '../class-names.js';
+import { dataBarTones } from '../css/css-data-bar.js';
+import { dataBarGeometry } from '../data-bar-geometry.js';
+export { dataBarTones };
+/**
+ * A horizontal range bar for a table cell or a list row: a bar from `from`
+ * to `to` on a track whose domain runs from `min` to `max`, such as where a
+ * statement's line leaves the running total, or a day's difference on a
+ * domain from below zero to above it, which draws a zero line. It is
+ * decorative (`aria-hidden`): the figure is the cell's own text, so keep
+ * the value beside it. Values past the domain are clamped to it;
+ * non-finite numbers, a `min` not under `max` or an unknown tone throw a
+ * `RangeError`.
+ */
+export const DataBar = forwardRef(function DataBar({ className, from, max, min, style, to, tone = 'neutral', ...rest }, ref) {
+    if (!dataBarTones.includes(tone))
+        throw new RangeError(`DataBar tone must be one of ${dataBarTones.join(', ')}; received ${String(tone)}`);
+    const { start, size, zero, zeroEnd } = dataBarGeometry(from, to, min, max);
+    return (_jsx("span", { ref: ref, className: cx('sw-data-bar', `sw-data-bar-${tone}`, zero !== null && 'sw-data-bar-diverging', zeroEnd !== null && `sw-data-bar-zero-${zeroEnd}`, className), style: {
+            ...style,
+            ...(zero === null ? {} : { '--sw-data-bar-zero': zero }),
+        }, ...rest, "aria-hidden": "true", children: _jsx("span", { className: "sw-data-bar-fill", style: {
+                '--sw-data-bar-start': start,
+                '--sw-data-bar-size': size,
+            } }) }));
+});

package/dist/components/Pagination.d.ts

@@ -0,0 +1,34 @@
+import { type HTMLAttributes } from 'react';
+import { type AccessibleName } from '../accessible-name.js';
+/** The steps' accessible names, in the product's words. */
+export type PaginationLabels = {
+    /** Names the step to the page before, such as "Previous page". */
+    previous: string;
+    /** Names the step to the page after, such as "Next page". */
+    next: string;
+};
+export type PaginationProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'aria-label' | 'aria-labelledby'> & AccessibleName & {
+    /** The page shown, from 1. */
+    page: number;
+    /** How many pages there are, from 1. */
+    pageCount: number;
+    /** Called with the page a step goes to; never past either end. */
+    onPageChange: (page: number) => void;
+    /**
+     * What the page shows, in the product's words, such as "1–25 of 130
+     * changes". It is announced politely when it changes.
+     */
+    rangeLabel: string;
+    labels: PaginationLabels;
+};
+/**
+ * Previous and next steps through a list shown a page at a time, beside
+ * the consumer's words for what the page shows, in a navigation landmark
+ * named by `aria-label` or `aria-labelledby`. Each step is an icon-only
+ * neutral Button named by `labels`. At either end its step looks disabled
+ * (`aria-disabled`) but stays a Tab stop, so focus is never dropped when
+ * the last page is reached, and a press there does nothing. Invalid pages
+ * or an empty step label (`labels.previous` or `labels.next`) throw a
+ * `RangeError`.
+ */
+export declare const Pagination: import("react").ForwardRefExoticComponent<PaginationProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Pagination.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from '../class-names.js';
+import { assertPaginationLabels, assertPaginationPages, paginationStep, } from '../pagination-pages.js';
+import { Button } from './Button.js';
+/**
+ * Previous and next steps through a list shown a page at a time, beside
+ * the consumer's words for what the page shows, in a navigation landmark
+ * named by `aria-label` or `aria-labelledby`. Each step is an icon-only
+ * neutral Button named by `labels`. At either end its step looks disabled
+ * (`aria-disabled`) but stays a Tab stop, so focus is never dropped when
+ * the last page is reached, and a press there does nothing. Invalid pages
+ * or an empty step label (`labels.previous` or `labels.next`) throw a
+ * `RangeError`.
+ */
+export const Pagination = forwardRef(function Pagination({ className, labels, onPageChange, page, pageCount, rangeLabel, ...rest }, ref) {
+    assertPaginationPages(page, pageCount);
+    assertPaginationLabels(labels);
+    const step = (direction) => {
+        const target = paginationStep(page, pageCount, direction);
+        return (_jsx(Button, { "aria-disabled": target === null || undefined, "aria-label": labels[direction], className: "sw-pagination-step", disabledAppearance: "neutral", onPress: () => {
+                if (target !== null)
+                    onPageChange(target);
+            }, size: "sm", variant: "neutral", children: _jsx("span", { "aria-hidden": "true", className: `sw-pagination-glyph sw-pagination-glyph-${direction}` }) }));
+    };
+    return (_jsxs("nav", { ref: ref, className: cx('sw-pagination', className), ...rest, children: [_jsx("span", { "aria-atomic": "true", "aria-live": "polite", className: "sw-pagination-range", children: rangeLabel }), _jsxs("span", { className: "sw-pagination-steps", children: [step('previous'), step('next')] })] }));
+});

package/dist/components/ScrollRegion.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from 'react';
+import { type CSSProperties, type ReactNode } from 'react';
 type ScrollRegionProps = {
     children: ReactNode;
     className: string;
@@ -6,6 +6,8 @@ type ScrollRegionProps = {
     'aria-labelledby'?: string;
     /** Adds `sw-scroll-fits` once measured with content that fits its width. */
     markFits?: boolean;
+    /** Generated custom properties only, such as a bounded table's row count. */
+    style?: CSSProperties;
 };
 /**
  * Private wrapper that scrolls wide content inside its own box (see
@@ -14,9 +16,11 @@ type ScrollRegionProps = {
  * keyboard and is announced as one group. While content is scrolled out past
  * an inline edge, that edge draws a shade (`sw-scroll-more-start`,
  * `sw-scroll-more-end`), so a phone, whose scrollbars hide, still shows that
- * the table goes on. With `markFits`, a measured region whose content fits
- * its width carries `sw-scroll-fits`, so a table with a sticky footer can
- * stop being a scroll box and pin its header and footer to the page.
+ * the table goes on. A region of bounded height that scrolls its rows marks
+ * its top and bottom the same way (`sw-scroll-more-top`,
+ * `sw-scroll-more-bottom`). With `markFits`, a measured region whose content
+ * fits its width carries `sw-scroll-fits`, so a table with a sticky footer
+ * can stop being a scroll box and pin its header and footer to the page.
  */
-export declare function ScrollRegion({ children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, markFits, }: ScrollRegionProps): import("react").JSX.Element;
+export declare function ScrollRegion({ children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, markFits, style, }: ScrollRegionProps): import("react").JSX.Element;
 export {};

package/dist/components/ScrollRegion.js

@@ -10,16 +10,18 @@ import { useScrollOverflow } from './use-scroll-overflow.js';
  * keyboard and is announced as one group. While content is scrolled out past
  * an inline edge, that edge draws a shade (`sw-scroll-more-start`,
  * `sw-scroll-more-end`), so a phone, whose scrollbars hide, still shows that
- * the table goes on. With `markFits`, a measured region whose content fits
- * its width carries `sw-scroll-fits`, so a table with a sticky footer can
- * stop being a scroll box and pin its header and footer to the page.
+ * the table goes on. A region of bounded height that scrolls its rows marks
+ * its top and bottom the same way (`sw-scroll-more-top`,
+ * `sw-scroll-more-bottom`). With `markFits`, a measured region whose content
+ * fits its width carries `sw-scroll-fits`, so a table with a sticky footer
+ * can stop being a scroll box and pin its header and footer to the page.
  */
-export function ScrollRegion({ children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, markFits = false, }) {
+export function ScrollRegion({ children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, markFits = false, style, }) {
     const ref = useRef(null);
     const overflow = useScrollOverflow(ref);
-    return (_jsx("div", { ref: ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx(className, overflow.start && 'sw-scroll-more-start', overflow.end && 'sw-scroll-more-end', markFits &&
+    return (_jsx("div", { ref: ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx(className, overflow.start && 'sw-scroll-more-start', overflow.end && 'sw-scroll-more-end', overflow.top && 'sw-scroll-more-top', overflow.bottom && 'sw-scroll-more-bottom', markFits &&
             overflow.measured &&
             !overflow.start &&
             !overflow.end &&
-            'sw-scroll-fits'), role: "group", tabIndex: 0, children: children }));
+            'sw-scroll-fits'), role: "group", style: style, tabIndex: 0, children: children }));
 }

package/dist/components/SectionNav.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import { type AccessibleName } from '../accessible-name.js';
 import { type Breakpoint } from '../css/breakpoints.js';
 import { type SectionNavAppearance } from '../css/css-section-nav-filled.js';
 export type { SectionNavAppearance };
@@ -29,14 +30,7 @@ export type SectionNavItem = {
      */
     countLabel?: string;
 };
-type SectionNavLabel = {
-    'aria-label': string;
-    'aria-labelledby'?: never;
-} | {
-    'aria-label'?: never;
-    'aria-labelledby': string;
-};
-export type SectionNavProps = SectionNavLabel & {
+export type SectionNavProps = AccessibleName & {
     items: readonly SectionNavItem[];
     /**
      * Called for a plain press on an item (the main button, no modifier key),

package/dist/components/SegmentedControl.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import { type AccessibleName } from '../accessible-name.js';
 export type SegmentedItem = {
     id: string;
     label: ReactNode;
@@ -11,13 +12,6 @@ export type SegmentedItem = {
      */
     icon?: ReactNode;
 };
-type SegmentedLabel = {
-    'aria-label': string;
-    'aria-labelledby'?: never;
-} | {
-    'aria-label'?: never;
-    'aria-labelledby': string;
-};
 /**
  * `compact` is the quiet chip track for a section switch; `filled` gives every
  * segment the same width and paints the selected one in the accent, for a
@@ -40,7 +34,7 @@ type SegmentedChange = {
     disabled: true;
     onChange?: (id: string) => void;
 };
-export type SegmentedControlProps = SegmentedLabel & SegmentedChange & {
+export type SegmentedControlProps = AccessibleName & SegmentedChange & {
     items: readonly SegmentedItem[];
     value: string;
     variant?: SegmentedControlVariant;

package/dist/components/Table.d.ts

@@ -1,10 +1,11 @@
 import { type HTMLAttributes } from 'react';
 import { type TableLayout, type TableStickyHeader, type TableVerticalAlign } from './table/table-layout.js';
+import { type TableMaxHeight } from './table/table-max-height.js';
 export { TableCell, type TableCellProps, type TableColumnWidth, type TableSort, } from './table/TableCell.js';
 export { TableRow, type TableRowProps, type TableRowVariant, } from './table/TableRow.js';
 export type { TableCellTone } from '../css/css-table-ledger.js';
 export { tableCellTones, tableRowVariants } from '../css/css-table-ledger.js';
-export type { TableLayout, TableStickyHeader, TableVerticalAlign };
+export type { TableLayout, TableMaxHeight, TableStickyHeader, TableVerticalAlign, };
 export type TableDensity = 'comfortable' | 'compact';
 export type TableProps = HTMLAttributes<HTMLTableElement> & {
     density?: TableDensity;
@@ -40,8 +41,30 @@ export type TableProps = HTMLAttributes<HTMLTableElement> & {
      * after a row's first, for a ledger read across as well as down.
      */
     columnRules?: boolean;
+    /**
+     * Bounds the table's height, counted in rows (`{ rows: 12 }`): its region
+     * is as tall as that many single-line body rows plus the header row (a
+     * sorting header as tall as its buttons, the touch target on a coarse
+     * pointer) and, when there is one, the footer row, and the rest of the
+     * rows scroll inside it. Rows of two lines or with controls, a second
+     * header or footer row and a horizontal scrollbar that takes room show
+     * fewer rows. The header pins to the region's top and a sticky
+     * `TableFooter` total to its bottom, so a total over every row stays in
+     * view. The region is a keyboard stop named after the table, its focus
+     * ring drawn over the pinned rows too, and an edge with rows scrolled
+     * out past it draws a shade (cast from the pinned header's last row or
+     * the total when there is one). Printed, every row shows. It keeps its
+     * header pinned to the region, so `stickyHeader` `'page'` or `false`
+     * throw with it, as do a value that is not `{ rows }` and a row count
+     * that is not a whole number from 1. Without it (the default) the table
+     * is as tall as its rows.
+     */
+    maxHeight?: TableMaxHeight;
 };
-/** A wide table scrolls inside its own `ScrollRegion`, named after the table. */
+/**
+ * A wide table scrolls inside its own `ScrollRegion`, named after the
+ * table; a bounded one (`maxHeight`) scrolls its rows in it too.
+ */
 export declare const Table: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLTableElement> & {
     density?: TableDensity;
     /**
@@ -76,6 +99,25 @@ export declare const Table: import("react").ForwardRefExoticComponent<HTMLAttrib
      * after a row's first, for a ledger read across as well as down.
      */
     columnRules?: boolean;
+    /**
+     * Bounds the table's height, counted in rows (`{ rows: 12 }`): its region
+     * is as tall as that many single-line body rows plus the header row (a
+     * sorting header as tall as its buttons, the touch target on a coarse
+     * pointer) and, when there is one, the footer row, and the rest of the
+     * rows scroll inside it. Rows of two lines or with controls, a second
+     * header or footer row and a horizontal scrollbar that takes room show
+     * fewer rows. The header pins to the region's top and a sticky
+     * `TableFooter` total to its bottom, so a total over every row stays in
+     * view. The region is a keyboard stop named after the table, its focus
+     * ring drawn over the pinned rows too, and an edge with rows scrolled
+     * out past it draws a shade (cast from the pinned header's last row or
+     * the total when there is one). Printed, every row shows. It keeps its
+     * header pinned to the region, so `stickyHeader` `'page'` or `false`
+     * throw with it, as do a value that is not `{ rows }` and a row count
+     * that is not a whole number from 1. Without it (the default) the table
+     * is as tall as its rows.
+     */
+    maxHeight?: TableMaxHeight;
 } & import("react").RefAttributes<HTMLTableElement>>;
 export type TableHeaderProps = HTMLAttributes<HTMLTableSectionElement>;
 export declare const TableHeader: import("react").ForwardRefExoticComponent<TableHeaderProps & import("react").RefAttributes<HTMLTableSectionElement>>;
@@ -87,7 +129,8 @@ export type TableFooterProps = HTMLAttributes<HTMLTableSectionElement> & {
      * scroll under it: to the page while the table fits its width (the
      * sticky header then pins to the page's top too, under any sticky
      * AppHeader, which covers it), or to the table's own region while the
-     * table scrolls sideways in it. A sticky ActionBar covers a pinned
+     * table scrolls sideways in it or is bounded (`Table maxHeight`), where
+     * it stays at the region's bottom. A sticky ActionBar covers a pinned
      * footer, and so does a Dialog's pinned footer, so do not pair them.
      */
     sticky?: boolean;
@@ -103,7 +146,8 @@ export declare const TableFooter: import("react").ForwardRefExoticComponent<HTML
      * scroll under it: to the page while the table fits its width (the
      * sticky header then pins to the page's top too, under any sticky
      * AppHeader, which covers it), or to the table's own region while the
-     * table scrolls sideways in it. A sticky ActionBar covers a pinned
+     * table scrolls sideways in it or is bounded (`Table maxHeight`), where
+     * it stays at the region's bottom. A sticky ActionBar covers a pinned
      * footer, and so does a Dialog's pinned footer, so do not pair them.
      */
     sticky?: boolean;

package/dist/components/Table.js

@@ -3,15 +3,21 @@ import { forwardRef } from 'react';
 import { cx } from '../class-names.js';
 import { ScrollRegion } from './ScrollRegion.js';
 import { assertTableLayout, assertTableStickyHeader, assertTableVerticalAlign, } from './table/table-layout.js';
+import { assertTableMaxHeight, tableMaxHeightStyle, } from './table/table-max-height.js';
 export { TableCell, } from './table/TableCell.js';
 export { TableRow, } from './table/TableRow.js';
 export { tableCellTones, tableRowVariants } from '../css/css-table-ledger.js';
-/** A wide table scrolls inside its own `ScrollRegion`, named after the table. */
-export const Table = forwardRef(function Table({ children, className, columnRules = false, density = 'comfortable', layout = 'auto', stickyHeader = true, verticalAlign = 'middle', ...rest }, ref) {
+/**
+ * A wide table scrolls inside its own `ScrollRegion`, named after the
+ * table; a bounded one (`maxHeight`) scrolls its rows in it too.
+ */
+export const Table = forwardRef(function Table({ children, className, columnRules = false, density = 'comfortable', layout = 'auto', maxHeight, stickyHeader = true, verticalAlign = 'middle', ...rest }, ref) {
     assertTableLayout(layout);
     assertTableStickyHeader(stickyHeader);
     assertTableVerticalAlign(verticalAlign);
-    return (_jsx(ScrollRegion, { "aria-label": rest['aria-label'], "aria-labelledby": rest['aria-labelledby'], className: "sw-table-wrap", markFits: true, children: _jsx("table", { ref: ref, className: cx('sw-table', density === 'compact' && 'sw-table-compact', layout === 'fixed' && 'sw-table-fixed', stickyHeader !== false && 'sw-table-sticky', stickyHeader === 'page' && 'sw-table-sticky-page', verticalAlign === 'top' && 'sw-table-top', columnRules && 'sw-table-column-rules', className), ...rest, children: children }) }));
+    assertTableMaxHeight(maxHeight, stickyHeader);
+    const bounded = maxHeight !== undefined;
+    return (_jsx(ScrollRegion, { "aria-label": rest['aria-label'], "aria-labelledby": rest['aria-labelledby'], className: cx('sw-table-wrap', bounded && 'sw-table-bounded'), markFits: !bounded, style: tableMaxHeightStyle(maxHeight), children: _jsx("table", { ref: ref, className: cx('sw-table', density === 'compact' && 'sw-table-compact', layout === 'fixed' && 'sw-table-fixed', stickyHeader !== false && 'sw-table-sticky', stickyHeader === 'page' && 'sw-table-sticky-page', verticalAlign === 'top' && 'sw-table-top', columnRules && 'sw-table-column-rules', className), ...rest, children: children }) }));
 });
 export const TableHeader = forwardRef(function TableHeader({ className, ...rest }, ref) {
     return _jsx("thead", { ref: ref, className: className, ...rest });

package/dist/components/Tabs.d.ts

@@ -1,16 +1,10 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+import { type AccessibleName } from '../accessible-name.js';
 export type TabItem = {
     id: string;
     label: ReactNode;
 };
-type TabsLabel = {
-    'aria-label': string;
-    'aria-labelledby'?: never;
-} | {
-    'aria-label'?: never;
-    'aria-labelledby': string;
-};
-export type TabsProps = TabsLabel & {
+export type TabsProps = AccessibleName & {
     /** Prefix for the tab and panel ids, so a `TabPanel` can point back at its tab. */
     id: string;
     items: readonly TabItem[];
@@ -58,4 +52,3 @@ export type TabPanelProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & {
 };
 /** The content of one tab, labelled by its tab and hidden while another tab is current. */
 export declare function TabPanel({ children, className, id, tabsId, value, ...rest }: TabPanelProps): import("react").JSX.Element;
-export {};

package/dist/components/table/TableRow.d.ts

@@ -7,7 +7,10 @@ export type TableRowProps = HTMLAttributes<HTMLTableRowElement> & {
      * `sub` sets the row under the one above it, as an item of a batch: its
      * row header (`TableCell as="th" scope="row"`) is indented with a guide
      * bar at the indent; a sub row without a row header is not indented.
-     * `default` is a row of its own.
+     * `total` is a total mid-table, such as a subtotal the rows above add up
+     * to: its cells at weight 600 under a 2 px rule, as a
+     * `TableFooter` total is; name it with a row header and keep it in the
+     * body. `default` is a row of its own.
      */
     variant?: TableRowVariant;
     /**
@@ -40,7 +43,10 @@ export declare const TableRow: import("react").ForwardRefExoticComponent<HTMLAtt
      * `sub` sets the row under the one above it, as an item of a batch: its
      * row header (`TableCell as="th" scope="row"`) is indented with a guide
      * bar at the indent; a sub row without a row header is not indented.
-     * `default` is a row of its own.
+     * `total` is a total mid-table, such as a subtotal the rows above add up
+     * to: its cells at weight 600 under a 2 px rule, as a
+     * `TableFooter` total is; name it with a row header and keep it in the
+     * body. `default` is a row of its own.
      */
     variant?: TableRowVariant;
     /**

package/dist/components/table/TableRow.js

@@ -25,5 +25,5 @@ export const TableRow = forwardRef(function TableRow({ className, onClick, press
             forwarding.current = false;
         }
     };
-    return (_jsx("tr", { ref: ref, "aria-selected": selected || undefined, className: cx(selected && 'sw-table-row-selected', variant === 'sub' && 'sw-table-row-sub', struck && 'sw-table-row-struck', pressable && 'sw-table-row-press', className), onClick: pressable || onClick ? press : undefined, ...rest }));
+    return (_jsx("tr", { ref: ref, "aria-selected": selected || undefined, className: cx(selected && 'sw-table-row-selected', variant === 'sub' && 'sw-table-row-sub', variant === 'total' && 'sw-table-row-total', struck && 'sw-table-row-struck', pressable && 'sw-table-row-press', className), onClick: pressable || onClick ? press : undefined, ...rest }));
 });

package/dist/components/table/table-max-height.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from 'react';
+import type { TableStickyHeader } from './table-layout.js';
+/**
+ * A table's bounded height, counted in rows: the table's region is as tall
+ * as `rows` single-line body rows plus its header row and, when it has one,
+ * its footer row, and the rest of the rows scroll inside the region. Rows
+ * taller than one line show fewer at a time.
+ */
+export type TableMaxHeight = {
+    rows: number;
+};
+/**
+ * A bounded table pins its header to its own region (`stickyHeader` true,
+ * the default); `'page'` and `false` contradict that and throw, as do a
+ * value that is not `{ rows }` and a row count that is not a whole number
+ * from 1.
+ */
+export declare function assertTableMaxHeight(maxHeight: TableMaxHeight | undefined, stickyHeader: TableStickyHeader): void;
+/** The row count the generated `sw-table-bounded` height reads. */
+export declare function tableMaxHeightStyle(maxHeight: TableMaxHeight | undefined): CSSProperties | undefined;

package/dist/components/table/table-max-height.js

@@ -0,0 +1,23 @@
+/**
+ * A bounded table pins its header to its own region (`stickyHeader` true,
+ * the default); `'page'` and `false` contradict that and throw, as do a
+ * value that is not `{ rows }` and a row count that is not a whole number
+ * from 1.
+ */
+export function assertTableMaxHeight(maxHeight, stickyHeader) {
+    if (maxHeight === undefined)
+        return;
+    if (typeof maxHeight !== 'object' || maxHeight === null)
+        throw new RangeError(`Table maxHeight must be a row count, { rows }: ${String(maxHeight)}`);
+    const rows = maxHeight.rows;
+    if (typeof rows !== 'number' || !Number.isInteger(rows) || rows < 1)
+        throw new RangeError(`Table maxHeight rows must be a whole number from 1: ${String(rows)}`);
+    if (stickyHeader !== true)
+        throw new RangeError(`Table maxHeight pins the header to the table's own region; stickyHeader ${String(stickyHeader)} cannot be used with it`);
+}
+/** The row count the generated `sw-table-bounded` height reads. */
+export function tableMaxHeightStyle(maxHeight) {
+    if (maxHeight === undefined)
+        return undefined;
+    return { '--sw-table-max-rows': maxHeight.rows };
+}

package/dist/components/use-scroll-overflow.d.ts

@@ -1,14 +1,16 @@
 import { type RefObject } from 'react';
-import { type ScrollOverflow } from '../scroll-overflow.js';
-/** A box's overflow, and whether it has been measured yet. */
-export type MeasuredScrollOverflow = ScrollOverflow & {
+import { type BlockScrollOverflow, type ScrollOverflow } from '../scroll-overflow.js';
+/** A box's overflow on both axes, and whether it has been measured yet. */
+export type MeasuredScrollOverflow = ScrollOverflow & BlockScrollOverflow & {
     measured: boolean;
 };
 /**
- * Follows which inline edges of a scroll box have more content past them:
- * on mount, on every scroll, and whenever the box or its content changes
- * size. Before mount (and on the server) it reports no overflow and
- * `measured: false`, so the box renders as it always has until it is
- * measured; a measured box with neither edge set fits its content.
+ * Follows which edges of a scroll box have more content past them, the
+ * inline start and end and the top and bottom: on mount, on every scroll,
+ * and whenever the box or its content changes size. Before mount (and on
+ * the server) it reports no overflow and `measured: false`, so the box
+ * renders as it always has until it is measured; a measured box with
+ * neither inline edge set fits its content's width. A box whose height
+ * follows its content never reports a block edge.
  */
 export declare function useScrollOverflow(ref: RefObject<HTMLElement | null>): MeasuredScrollOverflow;