@scalewing/react 1.34.0 → 1.35.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.35.0
+
+### Minor Changes
+
+- 287d933: `Table` `stickyHeader="page"` pins the header row to the page's top while the page scrolls, without a sticky `TableFooter` (`docs/requests/teisoro-table-sticky-page.md`, Teisoro F-011 task 2180). While the table fits its width its region stops being a scroll box, as it already did for a sticky footer; a table wider than its region scrolls sideways in it and pins inside it. `true` (the default) and `false` are unchanged; any other value (including an untyped `null` or `0`, which used to mean not sticky) throws a `RangeError`. New type `TableStickyHeader` and generated class `sw-table-sticky-page`. No new tokens, no new dependency.
+
 ## 1.34.0
 
 ### Minor Changes

package/README.md

@@ -416,6 +416,14 @@ A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `
 
 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`.
 
+`Table` `stickyHeader` pins the header row: `true` (default) 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`.
+
+```tsx
+<Table aria-label="Site census" stickyHeader="page">
+  …
+</Table>
+```
+
 `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.
 
 `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.

package/dist/components/Table.d.ts

@@ -1,19 +1,23 @@
 import { type HTMLAttributes } from 'react';
-import { type TableLayout, type TableVerticalAlign } from './table/table-layout.js';
+import { type TableLayout, type TableStickyHeader, type TableVerticalAlign } from './table/table-layout.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, TableVerticalAlign };
+export type { TableLayout, TableStickyHeader, TableVerticalAlign };
 export type TableDensity = 'comfortable' | 'compact';
 export type TableProps = HTMLAttributes<HTMLTableElement> & {
     density?: TableDensity;
     /**
      * Pins the header row to the top of the table's own scroll region
-     * (default). In a table with a sticky `TableFooter` that fits its width
-     * the region does not scroll, so the header pins to the page's top.
+     * (`true`, default). `'page'` pins it to the page's top while the page
+     * scrolls: while the table fits its width its region stops being a
+     * scroll box (under any sticky AppHeader, which covers it); a table
+     * wider than its region scrolls sideways in it and pins to the region.
+     * A table with a sticky `TableFooter` that fits its width pins its
+     * header to the page with `true` too. `false` lets it scroll away.
      */
-    stickyHeader?: boolean;
+    stickyHeader?: TableStickyHeader;
     /**
      * `auto` (default) sizes each column by its content. `fixed` sizes the
      * columns from the header row's `width`s alone (`table-layout: fixed`),
@@ -42,10 +46,14 @@ export declare const Table: import("react").ForwardRefExoticComponent<HTMLAttrib
     density?: TableDensity;
     /**
      * Pins the header row to the top of the table's own scroll region
-     * (default). In a table with a sticky `TableFooter` that fits its width
-     * the region does not scroll, so the header pins to the page's top.
+     * (`true`, default). `'page'` pins it to the page's top while the page
+     * scrolls: while the table fits its width its region stops being a
+     * scroll box (under any sticky AppHeader, which covers it); a table
+     * wider than its region scrolls sideways in it and pins to the region.
+     * A table with a sticky `TableFooter` that fits its width pins its
+     * header to the page with `true` too. `false` lets it scroll away.
      */
-    stickyHeader?: boolean;
+    stickyHeader?: TableStickyHeader;
     /**
      * `auto` (default) sizes each column by its content. `fixed` sizes the
      * columns from the header row's `width`s alone (`table-layout: fixed`),

package/dist/components/Table.js

@@ -2,15 +2,16 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
 import { cx } from '../class-names.js';
 import { ScrollRegion } from './ScrollRegion.js';
-import { assertTableLayout, assertTableVerticalAlign, } from './table/table-layout.js';
+import { assertTableLayout, assertTableStickyHeader, assertTableVerticalAlign, } from './table/table-layout.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) {
     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 && 'sw-table-sticky', verticalAlign === 'top' && 'sw-table-top', columnRules && 'sw-table-column-rules', className), ...rest, children: children }) }));
+    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 }) }));
 });
 export const TableHeader = forwardRef(function TableHeader({ className, ...rest }, ref) {
     return _jsx("thead", { ref: ref, className: className, ...rest });

package/dist/components/table/table-layout.d.ts

@@ -5,6 +5,12 @@ export type { TableColumnWidth };
 export type TableLayout = 'auto' | 'fixed';
 /** Where a cell's content sits in a row taller than it. */
 export type TableVerticalAlign = 'middle' | 'top';
+/**
+ * Whether the header row pins: `true` to the top of the table's own scroll
+ * region, `'page'` to the page's top while the table fits its width.
+ */
+export type TableStickyHeader = boolean | 'page';
+export declare function assertTableStickyHeader(sticky: TableStickyHeader): void;
 export declare function assertTableLayout(layout: TableLayout): void;
 export declare function assertTableVerticalAlign(align: TableVerticalAlign): void;
 export declare function assertTableColumnWidth(width: TableColumnWidth | undefined): void;

package/dist/components/table/table-layout.js

@@ -1,5 +1,9 @@
 import { tableColumnWidths, } from '../../css/css-table-layout.js';
 export { tableColumnWidthClass } from '../../css/css-table-layout.js';
+export function assertTableStickyHeader(sticky) {
+    if (typeof sticky !== 'boolean' && sticky !== 'page')
+        throw new RangeError(`Unknown Table stickyHeader: ${String(sticky)}`);
+}
 export function assertTableLayout(layout) {
     if (layout !== 'auto' && layout !== 'fixed')
         throw new RangeError(`Unknown Table layout: ${String(layout)}`);

package/dist/css/css-table-footer.js

@@ -10,12 +10,8 @@ import { zIndex } from './stacking.js';
  * (solid surface under reduced transparency, the system canvas in forced
  * colours, as the pinned header cells), on the `stickyFooter` layer: over
  * the cells and the pinned header cells, under the ActionBar, which covers
- * it, so a page does not pair the two. A table's region is a scroll box,
- * which would pin it to the region's own bottom; while the table fits its
- * width (`sw-scroll-fits`) a region that holds a sticky footer stops being
- * one, so the footer pins to the page's bottom and the sticky header to
- * its top, under any sticky top chrome (an AppHeader covers it). A table
- * wider than its region scrolls sideways in it and pins to the region.
+ * it, so a page does not pair the two. Where it pins (the page or the
+ * table's own region) is `css-table-page-pin.ts`.
  */
 export function cssTableFooterClasses() {
     return `.sw-table tfoot :is(th, td) {
@@ -42,10 +38,6 @@ export function cssTableFooterClasses() {
   ${zIndex('stickyFooter')}
 }
 
-.sw-table-wrap.sw-scroll-fits:has(> .sw-table > .sw-table-footer-sticky) {
-  overflow: visible;
-}
-
 @media (forced-colors: active) {
   .sw-table tfoot > tr:first-child > :is(th, td)::before { border-color: CanvasText; }
   .sw-table .sw-table-footer-sticky :is(th, td),
@@ -53,5 +45,5 @@ export function cssTableFooterClasses() {
 }`;
 }
 export function tableFooterClassCatalog() {
-    return ['sw-table-footer-sticky', 'sw-scroll-fits'];
+    return ['sw-table-footer-sticky'];
 }

package/dist/css/css-table-page-pin.d.ts

@@ -0,0 +1,2 @@
+export declare function cssTablePagePinClasses(): string;
+export declare function tablePagePinClassCatalog(): string[];

package/dist/css/css-table-page-pin.js

@@ -0,0 +1,22 @@
+/*
+ * Where a table's pinned rows pin. A table's region is a scroll box (it
+ * scrolls a wide table sideways), and a sticky cell pins to its nearest
+ * scroll box: the region, which never scrolls vertically, so on a page
+ * that scrolls nothing would stay in view. While the table fits its width
+ * (`sw-scroll-fits`, set once the region is measured) a region that holds
+ * a sticky footer, or a table whose header pins to the page
+ * (`stickyHeader="page"`, `sw-table-sticky-page`), stops being a scroll
+ * box, so the footer pins to the page's bottom edge and the sticky header
+ * to its top, under any sticky top chrome (an AppHeader covers it). A
+ * table wider than its region scrolls sideways in it and pins to the
+ * region instead.
+ */
+export function cssTablePagePinClasses() {
+    return `.sw-table-wrap.sw-scroll-fits:has(> .sw-table > .sw-table-footer-sticky),
+.sw-table-wrap.sw-scroll-fits:has(> .sw-table-sticky-page) {
+  overflow: visible;
+}`;
+}
+export function tablePagePinClassCatalog() {
+    return ['sw-scroll-fits', 'sw-table-sticky-page'];
+}

package/dist/css/css-table.js

@@ -3,6 +3,7 @@ import { scrollRegionRules } from './css-scroll-region.js';
 import { cssTableLayoutClasses, tableLayoutClassCatalog, } from './css-table-layout.js';
 import { cssTableLedgerClasses, tableLedgerClassCatalog, } from './css-table-ledger.js';
 import { cssTableFooterClasses, tableFooterClassCatalog, } from './css-table-footer.js';
+import { cssTablePagePinClasses, tablePagePinClassCatalog, } from './css-table-page-pin.js';
 import { cssTablePressClasses, tablePressClassCatalog, } from './css-table-press.js';
 import { cssTableSortClasses, tableSortClassCatalog, } from './css-table-sort.js';
 import { zIndex } from './stacking.js';
@@ -96,6 +97,8 @@ ${cssTableLedgerClasses()}
 
 ${cssTableFooterClasses()}
 
+${cssTablePagePinClasses()}
+
 ${cssTablePressClasses()}
 
 ${selectedRowRules()}`;
@@ -114,6 +117,7 @@ export function tableClassCatalog() {
         ...tableSortClassCatalog(),
         ...tableLedgerClassCatalog(),
         ...tableFooterClassCatalog(),
+        ...tablePagePinClassCatalog(),
         ...tablePressClassCatalog(),
     ];
 }

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { Select } from './components/Select.js';
 export type { SelectAction, SelectOption, SelectProps, SelectWidth, } from './components/Select.js';
 export { MultiSelect, type MultiSelectAlign, type MultiSelectOption, type MultiSelectProps, } from './components/MultiSelect.js';
 export { Stack, type Align, type Justify, type StackProps, } from './components/Stack.js';
-export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, tableCellTones, tableRowVariants, type TableBodyProps, type TableCellProps, type TableCellTone, type TableColumnWidth, type TableDensity, type TableFooterProps, type TableHeaderProps, type TableLayout, type TableProps, type TableRowProps, type TableRowVariant, type TableSort, type TableVerticalAlign, } from './components/Table.js';
+export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, tableCellTones, tableRowVariants, type TableBodyProps, type TableCellProps, type TableCellTone, type TableColumnWidth, type TableDensity, type TableFooterProps, type TableHeaderProps, type TableLayout, type TableProps, type TableRowProps, type TableRowVariant, type TableSort, type TableStickyHeader, type TableVerticalAlign, } from './components/Table.js';
 export { Text, type TextAlign, type TextElement, type TextProps, } from './components/Text.js';
 export { ThemeProvider, useTheme, type ThemeProviderProps, } from './theme/ThemeProvider.js';
 export { utilityClassCatalog } from './css/stylesheet.js';

package/dist/styles.css

@@ -1831,16 +1831,17 @@ body {
   z-index: 2;
 }
 
-.sw-table-wrap.sw-scroll-fits:has(> .sw-table > .sw-table-footer-sticky) {
-  overflow: visible;
-}
-
 @media (forced-colors: active) {
   .sw-table tfoot > tr:first-child > :is(th, td)::before { border-color: CanvasText; }
   .sw-table .sw-table-footer-sticky :is(th, td),
   .sw-table-sticky thead th { background: Canvas; backdrop-filter: none; -webkit-backdrop-filter: none; }
 }
 
+.sw-table-wrap.sw-scroll-fits:has(> .sw-table > .sw-table-footer-sticky),
+.sw-table-wrap.sw-scroll-fits:has(> .sw-table-sticky-page) {
+  overflow: visible;
+}
+
 .sw-table-row-press {
   cursor: pointer;
 }

package/package.json

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