@scalewing/react 1.58.0 → 1.59.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalewing/react
 
+## 1.59.1
+
+### Patch Changes
+
+- 3f78164: An xs `Field`'s own text input (`input` of a typed kind, or `textarea`) now draws at the xs size: the document canvas's `[data-theme]` typed-input rule outranked `.sw-field-xs`, so the control kept the md min-height (44 px) and the inherited font size beside a 28 px xs `Select`. The xs rule now matches it under `[data-theme]` (caption type, xs min-height and padding), and on a coarse pointer the control is the 44 px touch target. Adorned and search inputs keep their frames' rules. No API change.
+
+## 1.59.0
+
+### Minor Changes
+
+- 9ca5393: Muted words on a row's hover fill now keep 4.5:1: while a pressable `FixtureRow`, `ListRow` or `TableRow` shows the quiet fill (hovered, a ListRow or TableRow pressed, a TableRow's action focused), the parts on it read `--sw-color-muted` as the text colour, including the meta, details, a muted `TableCell`, the chevron and a consumer's `Text color="muted"` (muted was 4.14:1 on the fill in `ink` light, 3.47:1 in `harvest` dark). No prop, nothing changes at rest, toned words keep their tone, forced colours unchanged. `LiveRegion` (new, `LiveRegionProps`, `LiveRegionPoliteness`, `liveRegionPolitenesses`): a status line whose changing words are announced, an always-mounted region that starts empty (`role="status"` polite by default, or `role="alert"` with `politeness="assertive"`, `aria-atomic`), its string `children` swapped in as a new node on each change or `announceKey` change (the first words once it has been mounted 100 ms), drawn inline in `Text`'s look (`variant`, `color`) or `visuallyHidden`; an unknown politeness throws a `RangeError`, a look with `visuallyHidden` a `TypeError`. `AppShell` `skipLink` (opt-in, `AppShellSkipLink`: `{ label }`): a skip link first in the shell, hidden until focused, then fixed at the window's top start; a press moves focus to `main`, which gets an id and `tabindex="-1"` only with it, without changing the address; a blank label throws a `RangeError`. `Select` `disabled` (opt-in): a native disabled trigger, out of the Tab order and faded (`GrayText` in forced colours), its list never opens and `onChange` never runs. New class `sw-app-shell-skip-link` and stacking layer `skipLink` (7). SiteHeader's skip link now shares its look's rules (`css/skip-link.ts`); its output is unchanged apart from rule order.
+
 ## 1.58.0
 
 ### Minor Changes

package/README.md

@@ -52,6 +52,7 @@ import {
   DateToggleCalendar,
   ListGroup,
   ListRow,
+  LiveRegion,
   MarkdownView,
   DenominationGrid,
   FilterChips,
@@ -319,6 +320,8 @@ On a coarse pointer every `Select` size's trigger and each option in its open li
 />
 ```
 
+`Select` `disabled` (opt-in, default `false`) turns the control off, as `Button`'s `disabled` does: the trigger is a native disabled button, so it leaves the Tab order, is read as dimmed and fades to the disabled opacity (its frame, words and chevron `GrayText` in forced colours); its list cannot open, an open list closes when it is turned off, and `onChange` is never called. Say why it is off in the page's words, such as a polite `LiveRegion` beside it ("Locked while the census uploads").
+
 `Select` `width` is `'content'` (the default: the field is as wide as its longest option, as above) or `'full'`: the field and its trigger fill the container's inline size in a `Stack`, a `Grid` cell or any narrow column, such as a filter above full-width cards on a phone. In an `Inline` row it takes the space its siblings leave, so a `Button` beside it keeps its label on one line. The value still takes the free space and ellipsizes past it, the chevron stays at the inline end (the left, right to left), and the open list is exactly the trigger's width, so it never runs past the screen's edge; a long option wraps inside it, even a single long word.
 
 ```tsx
@@ -755,6 +758,14 @@ The layout follows the window, with generated media queries only. From 75rem (12
 </AppShell>
 ```
 
+`AppShell` `skipLink` (opt-in, `AppShellSkipLink`: `{ label }`) puts a "skip to main content" link first in the shell, before the top bar and the sidebar, in the consumer's words (`label`, such as "Skip to main content" or "Saltar al contenido principal"), so a keyboard user passes every destination on each page (WCAG 2.4.1). It is visually hidden until it has focus, then drawn as `SiteHeader`'s skip link (a pill on the surface in the text colour with the accent ring, the control height) fixed at the window's top start, over the sidebar, the compact bar and a page bar, however far the page has scrolled. The shell gives its `main` an id and `tabindex="-1"` only when the link is there, so no `href` is needed: a press (Enter included) moves focus to `main` without following the fragment, so a hash router's address and the history are unchanged, and the next Tab reaches the page's first control. `main` shows no ring while it holds that focus (it is not a control). Forced colours draw the link as a link on the system canvas. A blank `label` throws a `RangeError`.
+
+```tsx
+<AppShell skipLink={{ label: t('skipToMain') }} {...shellProps}>
+  {page}
+</AppShell>
+```
+
 ```tsx
 <Stack gap={3}>
   <Box paddingX={4}>
@@ -778,7 +789,7 @@ The layout follows the window, with generated media queries only. From 75rem (12
 
 `Table` aligns data in rows inside its own keyboard-reachable scroll region, named after the table. While the table is wider than the region, each inline edge with columns scrolled out past it draws a soft inset shade (`sw-scroll-more-start`, `sw-scroll-more-end`, mirrored right to left), so a phone, whose scrollbars stay hidden, still shows that the table goes on; a table that fits draws none, and in forced colors the system scrollbar is the cue. `TableCell` takes `numeric` (tabular numerals, end aligned), `align` and `truncate`; `density="compact"` densifies cells. `TableRow selected` sets `aria-selected` and marks the row with a 4 px accent bar at its inline start (3:1 or more against the surface and the page), the right edge in a right-to-left table. The bar is drawn inside the first cell's padding and takes no layout space, so no column moves when a row is picked, and the row takes no fill, so text, muted and accent text keep their contrast; forced colors keep the bar in the system highlight.
 
-`TableRow pressable` (opt-in) makes the whole row the pointer target of its one action, such as a search result that is picked: a plain primary press anywhere on it calls `click()` on the row's first link or button, so the action's own handler runs. Left alone: a modifier key or non-primary button, a press already handled, a press on another control, a press that ends a text selection (text stays selectable), and a disabled or missing action. Keep one control in the row: a control placed before the action (an icon button, say) would take the row's press. The row is not a control (no role, no tab stop), so keyboard and screen reader users use the action itself. It takes the pointer cursor and the quiet fill while hovered, pressed (a brief flash on touch) or while its action has keyboard focus (a `Highlight` outline in forced colours), and underlines its action on hover (`sw-table-row-press`). A consumer `onClick` runs once per press. Each click of a double click presses the action, as a native button's would, so keep it safe to repeat. `TableCell onPress` (a body cell or a row header in `TableBody`) makes the cell's children that action: a button in the cell's own text style at weight 600, underlined on hover and focus, with the accent focus ring (`sw-table-action`); a non-function value or one on a sortable header throws a `TypeError`.
+`TableRow pressable` (opt-in) makes the whole row the pointer target of its one action, such as a search result that is picked: a plain primary press anywhere on it calls `click()` on the row's first link or button, so the action's own handler runs. Left alone: a modifier key or non-primary button, a press already handled, a press on another control, a press that ends a text selection (text stays selectable), and a disabled or missing action. Keep one control in the row: a control placed before the action (an icon button, say) would take the row's press. The row is not a control (no role, no tab stop), so keyboard and screen reader users use the action itself. It takes the pointer cursor and the quiet fill while hovered, pressed (a brief flash on touch) or while its action has keyboard focus (a `Highlight` outline in forced colours), and underlines its action on hover (`sw-table-row-press`). On that fill a muted cell and muted words in the cells take the text colour (see "Muted words on a row's quiet fill" under `FixtureRow`). A consumer `onClick` runs once per press. Each click of a double click presses the action, as a native button's would, so keep it safe to repeat. `TableCell onPress` (a body cell or a row header in `TableBody`) makes the cell's children that action: a button in the cell's own text style at weight 600, underlined on hover and focus, with the accent focus ring (`sw-table-action`); a non-function value or one on a sortable header throws a `TypeError`.
 
 `TableSelectCell` is a table's select column: a cell (`as="td"`, the default, in a body row, or `as="th"` in a `TableHeader` row, which gets `scope="col"`) holding one `Checkbox` with `labelVisuallyHidden`. Its props are `label` (the box's name, not drawn: "Select all", "Select Mallard"), `checked`, `indeterminate`, `onCheckedChange` and `disabled`. The column is as wide as the box (`sw-table-select`), and 44 px wide on a coarse pointer, where the box is the 44 × 44 px target; a fixed table sizes columns from its header row, so put one in the header too. Mark a chosen row with `TableRow selected`; a press on the box is left alone by `TableRow pressable`. The consumer keeps the chosen set and works out "Select all"'s `checked` and `indeterminate`. A blank label or an unknown `as` throws a `RangeError`.
 
@@ -935,6 +946,23 @@ The consumer needs no PDF.js dependency of its own. With another bundler, build
 <Skeleton label="Loading rangers" variant="rows" lines={4} />
 ```
 
+`LiveRegion` is a status line whose words change and are read out. It renders a region that is always mounted and starts empty (`role="status"` with `aria-live="polite"`, or `role="alert"` with `aria-live="assertive"`, both `aria-atomic="true"`), and swaps its words in as a new keyed child each time `children` (a string, the words in the consumer's language) or `announceKey` changes, so new words are read, and the same words again when only the key changes (a second "Copied"). Empty `children` clears it and announces nothing. Screen readers miss words added the moment a region appears, so its first words wait until it has been mounted for 100 ms; later changes show at once (a re-render with the same words and key changes nothing, so nothing is re-read). `politeness` (`liveRegionPolitenesses`) is `'polite'` (default), read when the reader is idle, or `'assertive'`, read at once: keep that for an error the person must hear before going on. By default the words are drawn inline in a `span` with `Text`'s look (`variant`, default `body`, and `color`, default `text`); `visuallyHidden` keeps them for assistive technology only (`sw-sr-only`), for a change the page already shows another way, such as a button's label turning to "Copied". `id` names the region, for example for a control's `aria-describedby`. An unknown politeness throws a `RangeError`; `variant` or `color` with `visuallyHidden` throws a `TypeError`.
+
+Use `LiveRegion` rather than your own `role="status"` or `aria-live` whenever words change on a region already in the page: a save line ("Saving…", "Saved"), a count after a filter, a copy confirmation, a step's result. A `role="status"` element mounted with its words already inside is often not read, text replaced in place is read inconsistently across screen readers, and the same words twice are not read again; `LiveRegion` handles all three. Put it on the status line itself, never on a heading or a whole card, and keep one per message. Components that own their announcements keep them: `Toast` (`status` / `alert`), `Notice`, `Skeleton`, `Field`'s and `Select`'s error region, `Pagination`'s range, `ActionBar`'s and `Dialog`'s status lines, `ScheduleGrid`'s steps; do not wrap them in another region.
+
+```tsx
+<LiveRegion color="muted" variant="caption">
+  {saving ? 'Saving…' : 'Saved'}
+</LiveRegion>
+
+<Button onPress={copy}>{copied ? 'Copied' : 'Copy code'}</Button>
+<LiveRegion announceKey={copies} visuallyHidden>
+  {copies > 0 ? 'Code copied' : ''}
+</LiveRegion>
+
+<LiveRegion color="danger" politeness="assertive">{error}</LiveRegion>
+```
+
 `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
@@ -1265,6 +1293,8 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 </FixtureGroup>
 ```
 
+Muted words on a row's quiet fill: a pressable `FixtureRow` (and a detail under one with an `action` or `select`, which the fill spans), a pressable `ListRow` (hovered or pressed) and a `TableRow pressable` (hovered, pressed or with its action focused) show the quiet grey fill, on which the muted colour falls under 4.5:1 in most palettes (4.14:1 in `ink` light, 3.47:1 in `harvest` dark). While the fill shows, the parts on it read the muted token as the text colour, which keeps 4.5:1 there in every palette and scheme: the details, the meta, a muted `TableCell`, the chevron, and a consumer's `Text color="muted"` inside the row, with no prop and no change at rest. Toned words (a value's or a cell's success, danger or accent, a danger title, a Badge) keep their tone. Forced colours replace both colours and outline the hovered row in `Highlight`, as before.
+
 `FixtureRow` `flag` (opt-in, `FixtureFlag`: `{ label, tone? }`) marks an issue at the row's start, such as a clash: a round mark a space-4 across with a "!", in the tone's tint and ink (`warning`, amber, the default, for something that needs the person; `danger`, red), its edge keeping 3:1 on the surface in every palette and the text colour in forced colors. The mark is `aria-hidden` with `label` as its `title` tooltip, and `label` is read first in the row from a visually hidden span ("Can't-play clash Heron Marsh 8:00 Otter Pool"); with `aria-label` it is put before your words with a comma ("Can't-play clash, Heron Marsh vs Otter Pool, 8:00"), so do not repeat it there. From `md` the mark sits on the first line at the row's start, the home side kept clear of it; below `md` it leads the second line, before the details, so it never squeezes the home name. A row with nothing on that line below `md` (no `status`, and no `meta` or one hidden below `md` by `metaHideBelow`) keeps the mark inline on its first line instead, as from `md` (class `sw-fixture-row-flag-inline`), rather than gaining a line that holds only the flag. A blank `label` or an unknown `tone` throws a `RangeError`. `action` (opt-in) is a control after the row, such as a small neutral `Button` ("Move", named in your words: `aria-label="Move Heron Marsh vs Otter Pool"`): it is the row's sibling in its list item, outside a link or button row's press area and after it in the Tab order, a press on it never opens the row, and it stays centred on the row's height in the run's last column at every width (from `md` the row's one line, below `md` both lines), so every row's action lines up. Where `:has` is supported the hover fill spans the row and its action. An empty slot draws nothing. The run has a column for it at the end, and one for `select` at the start (`sw-fixture-list` is `auto minmax(0, 1fr) auto minmax(0, 1fr) auto auto auto`, six below `md`); a row spans every column but those two (`grid-column: 2 / -2`), and an `auto` column no row uses takes no space. New classes `sw-fixture-row-flagged`, `sw-fixture-flag`, `sw-fixture-flag-mark`, `sw-fixture-flag-warning`, `sw-fixture-flag-danger`, `sw-fixture-item-action` and `sw-fixture-action`.
 
 ```tsx

package/dist/components/AppShell.d.ts

@@ -1,5 +1,5 @@
 import { type AppShellProps } from './app-shell/types.js';
-export type { AppShellLabels, AppShellNavGroup, AppShellNavItem, AppShellProps, } from './app-shell/types.js';
+export type { AppShellLabels, AppShellNavGroup, AppShellNavItem, AppShellProps, AppShellSkipLink, } from './app-shell/types.js';
 /**
  * A web workspace's frame: a pinned side navigation of grouped
  * destinations beside the page (`main`), which scrolls with the document.
@@ -7,7 +7,8 @@ export type { AppShellLabels, AppShellNavGroup, AppShellNavItem, AppShellProps,
  * captions); from `lg` to 75rem it is a rail of glyphs with tooltips; below
  * `lg` a sticky top bar's menu button opens the same navigation in a modal
  * drawer from the inline start, its button optionally carrying a count.
- * `pageBar` is a sticky band at the top of `main` on every layout. Invalid
- * groups, items, counts or words throw a `RangeError`.
+ * `pageBar` is a sticky band at the top of `main` on every layout, and
+ * `skipLink` a first link that moves focus to `main`. Invalid groups,
+ * items, counts or words throw a `RangeError`.
  */
-export declare function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuCount, menuCountLabel, menuCountTone, menuIcon, navLabel, onNavigate, pageBar, railFooter, railHeader, }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuCount, menuCountLabel, menuCountTone, menuIcon, navLabel, onNavigate, pageBar, railFooter, railHeader, skipLink, }: AppShellProps): import("react").JSX.Element;

package/dist/components/AppShell.js

@@ -1,12 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
 import { breakpointQuery } from '../css/breakpoints.js';
 import { appShellWideQuery } from '../css/css-app-shell.js';
 import { appShellBarHeightVariable } from '../css/css-app-shell-page-bar.js';
 import { AppShellBar } from './app-shell/AppShellBar.js';
 import { AppShellDrawer } from './app-shell/AppShellDrawer.js';
 import { AppShellSidebar } from './app-shell/AppShellSidebar.js';
+import { SkipToMain } from './app-shell/SkipToMain.js';
 import { assertAppShellProps } from './app-shell/validate.js';
 import { useElementHeight } from './use-element-height.js';
 import { useMediaQuery } from './use-media-query.js';
@@ -18,10 +19,11 @@ const fromLg = breakpointQuery('from', 'lg');
  * captions); from `lg` to 75rem it is a rail of glyphs with tooltips; below
  * `lg` a sticky top bar's menu button opens the same navigation in a modal
  * drawer from the inline start, its button optionally carrying a count.
- * `pageBar` is a sticky band at the top of `main` on every layout. Invalid
- * groups, items, counts or words throw a `RangeError`.
+ * `pageBar` is a sticky band at the top of `main` on every layout, and
+ * `skipLink` a first link that moves focus to `main`. Invalid groups,
+ * items, counts or words throw a `RangeError`.
  */
-export function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuCount, menuCountLabel, menuCountTone, menuIcon, navLabel, onNavigate, pageBar, railFooter, railHeader, }) {
+export function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuCount, menuCountLabel, menuCountTone, menuIcon, navLabel, onNavigate, pageBar, railFooter, railHeader, skipLink, }) {
     assertAppShellProps({
         groups,
         labels,
@@ -29,10 +31,13 @@ export function AppShell({ barEnd, barTitle, children, footer, groups, header, l
         menuCountLabel,
         menuCountTone,
         navLabel,
+        skipLink,
     });
     const [menuOpen, setMenuOpen] = useState(false);
     const menuRef = useRef(null);
     const barRef = useRef(null);
+    const mainRef = useRef(null);
+    const mainId = useId();
     // Set by a dismissal (Escape, a press outside, the close button): only
     // that hands focus back to the menu button.
     const refocusRef = useRef(false);
@@ -58,7 +63,7 @@ export function AppShell({ barEnd, barTitle, children, footer, groups, header, l
         refocusRef.current = false;
         menuRef.current?.focus();
     }, [menuOpen]);
-    return (_jsxs("div", { className: "sw-app-shell", style: shellStyle, children: [_jsx(AppShellBar, { barEnd: barEnd, barRef: barRef, barTitle: barTitle, menuCount: menuCount, menuCountLabel: menuCountLabel, menuCountTone: menuCountTone, menuIcon: menuIcon, menuOpen: menuOpen, menuRef: menuRef, onOpenMenu: () => setMenuOpen(true), openMenuLabel: labels.openMenu }), _jsx(AppShellSidebar, { footer: footer, groups: groups, header: header, navLabel: navLabel, onNavigate: onNavigate, rail: sidebarShown && !wide, railFooter: railFooter, railHeader: railHeader }), _jsxs("main", { className: "sw-app-shell-main", children: [hasPageBar ? (_jsx("div", { className: "sw-app-shell-page-bar", children: pageBar })) : null, children] }), _jsx(AppShellDrawer, { closeLabel: labels.closeMenu, footer: footer, groups: groups, header: header, navLabel: navLabel, onChoose: () => setMenuOpen(false), onClose: () => {
+    return (_jsxs("div", { className: "sw-app-shell", style: shellStyle, children: [skipLink ? (_jsx(SkipToMain, { label: skipLink.label, mainId: mainId, mainRef: mainRef })) : null, _jsx(AppShellBar, { barEnd: barEnd, barRef: barRef, barTitle: barTitle, menuCount: menuCount, menuCountLabel: menuCountLabel, menuCountTone: menuCountTone, menuIcon: menuIcon, menuOpen: menuOpen, menuRef: menuRef, onOpenMenu: () => setMenuOpen(true), openMenuLabel: labels.openMenu }), _jsx(AppShellSidebar, { footer: footer, groups: groups, header: header, navLabel: navLabel, onNavigate: onNavigate, rail: sidebarShown && !wide, railFooter: railFooter, railHeader: railHeader }), _jsxs("main", { ref: mainRef, className: "sw-app-shell-main", id: skipLink ? mainId : undefined, tabIndex: skipLink ? -1 : undefined, children: [hasPageBar ? (_jsx("div", { className: "sw-app-shell-page-bar", children: pageBar })) : null, children] }), _jsx(AppShellDrawer, { closeLabel: labels.closeMenu, footer: footer, groups: groups, header: header, navLabel: navLabel, onChoose: () => setMenuOpen(false), onClose: () => {
                     refocusRef.current = true;
                     setMenuOpen(false);
                 }, onNavigate: onNavigate, open: menuOpen })] }));

package/dist/components/LiveRegion.d.ts

@@ -0,0 +1,44 @@
+import { type SemanticColorKey, type TypographyVariant } from '@scalewing/tokens';
+/** `polite` waits for the reader to finish; `assertive` interrupts it. */
+export declare const liveRegionPolitenesses: readonly ["polite", "assertive"];
+export type LiveRegionPoliteness = (typeof liveRegionPolitenesses)[number];
+export type LiveRegionProps = {
+    /**
+     * The words to announce now, in the consumer's language. Empty (or none)
+     * clears the region and announces nothing.
+     */
+    children?: string;
+    /**
+     * `polite` (the default) is a `status`, read when the reader is idle;
+     * `assertive` is an `alert`, read at once: keep it for an error the
+     * person must hear before they go on.
+     */
+    politeness?: LiveRegionPoliteness;
+    /**
+     * Changed to announce the same words again, such as a second "Copied".
+     * New words are announced without it.
+     */
+    announceKey?: string | number;
+    /**
+     * Keeps the words for assistive technology only (`sw-sr-only`), for a
+     * change the page already shows another way, such as a button's label
+     * turning to "Copied". Default `false`: the words are drawn inline as
+     * `Text` draws them.
+     */
+    visuallyHidden?: boolean;
+    /** The drawn words' type, as `Text`'s (default `body`). Not with `visuallyHidden`. */
+    variant?: TypographyVariant;
+    /** The drawn words' colour, as `Text`'s (default `text`). Not with `visuallyHidden`. */
+    color?: SemanticColorKey;
+    /** The region's id, such as for a control's `aria-describedby`. */
+    id?: string;
+};
+/**
+ * A status line whose words change and are announced: a region that is
+ * always mounted and starts empty (`role="status"`, or `"alert"` when
+ * assertive, with `aria-live` and `aria-atomic`), its words a keyed child
+ * swapped in on each change of `children` or `announceKey`, so new words,
+ * and the same words again, are read. Drawn inline in `Text`'s look, or
+ * visually hidden.
+ */
+export declare function LiveRegion({ announceKey, children, color, id, politeness, variant, visuallyHidden, }: LiveRegionProps): import("react").JSX.Element;

package/dist/components/LiveRegion.js

@@ -0,0 +1,54 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Text } from './Text.js';
+/** `polite` waits for the reader to finish; `assertive` interrupts it. */
+export const liveRegionPolitenesses = ['polite', 'assertive'];
+/*
+ * Screen readers miss words put into a live region in the same moment the
+ * region itself appears, so the first words wait until it has been in the
+ * page this long, as common announcers do. Later changes show at once.
+ */
+const regionSettleMs = 100;
+function assertLiveRegionProps({ color, politeness, variant, visuallyHidden, }) {
+    if (!liveRegionPolitenesses.includes(politeness))
+        throw new RangeError(`Unknown LiveRegion politeness: ${String(politeness)}`);
+    if (visuallyHidden && (variant !== undefined || color !== undefined))
+        throw new TypeError('LiveRegion variant and color draw words; a visuallyHidden region draws none');
+}
+/**
+ * A status line whose words change and are announced: a region that is
+ * always mounted and starts empty (`role="status"`, or `"alert"` when
+ * assertive, with `aria-live` and `aria-atomic`), its words a keyed child
+ * swapped in on each change of `children` or `announceKey`, so new words,
+ * and the same words again, are read. Drawn inline in `Text`'s look, or
+ * visually hidden.
+ */
+export function LiveRegion({ announceKey, children = '', color, id, politeness = 'polite', variant, visuallyHidden = false, }) {
+    assertLiveRegionProps({ color, politeness, variant, visuallyHidden });
+    const [settled, setSettled] = useState(false);
+    const [shown, setShown] = useState({
+        words: '',
+        announceKey,
+        key: 0,
+    });
+    // Words or a key that changed since the last swap are swapped in while
+    // rendering (React's state from the previous render), once settled.
+    if (settled &&
+        (shown.words !== children || shown.announceKey !== announceKey))
+        setShown({ words: children, announceKey, key: shown.key + 1 });
+    useEffect(() => {
+        const timer = window.setTimeout(() => setSettled(true), regionSettleMs);
+        return () => window.clearTimeout(timer);
+    }, []);
+    const region = {
+        'aria-atomic': true,
+        'aria-live': politeness,
+        id,
+        role: politeness === 'assertive' ? 'alert' : 'status',
+    };
+    const words = shown.words === '' ? null : _jsx("span", { children: shown.words }, shown.key);
+    if (visuallyHidden)
+        return (_jsx("span", { className: "sw-sr-only", ...region, children: words }));
+    return (_jsx(Text, { as: "span", color: color, variant: variant, ...region, children: words }));
+}

package/dist/components/Select.d.ts

@@ -39,6 +39,13 @@ export type SelectProps = SelectNaming & {
     requiredMark?: RequiredMark;
     /** A validation message under the control, wired as Field's error is. */
     error?: string;
+    /**
+     * Turns the control off, as `Button`'s `disabled`: the trigger is a
+     * native disabled button (out of the Tab order, read as dimmed, faded),
+     * its list cannot open (an open one closes) and `onChange` is never
+     * called. Say why it is off in the page's words. Default `false`.
+     */
+    disabled?: boolean;
     /**
      * `full` makes the field, its trigger and its open list fill the
      * container's inline size; the chosen label still ellipsizes past it.
@@ -46,4 +53,4 @@ export type SelectProps = SelectNaming & {
      */
     width?: SelectWidth;
 };
-export declare function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, onChange, options, size, value, placeholder, required, requiredMark, error, width, }: SelectProps): import("react").JSX.Element;
+export declare function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, disabled, onChange, options, size, value, placeholder, required, requiredMark, error, width, }: SelectProps): import("react").JSX.Element;

package/dist/components/Select.js

@@ -11,7 +11,7 @@ import { SelectValue } from './select/SelectValue.js';
 import { useSelectList } from './select/use-select-list.js';
 import { Stack } from './Stack.js';
 import { tabStop } from '../tab-stop.js';
-export function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, onChange, options, size = 'md', value, placeholder, required = false, requiredMark, error, width = 'content', }) {
+export function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, disabled = false, onChange, options, size = 'md', value, placeholder, required = false, requiredMark, error, width = 'content', }) {
     assertSelectNaming({ label, labelVisuallyHidden, labelledBy, requiredMark });
     assertRequiredMark(requiredMark ?? 'visible');
     if (placeholder !== undefined && !placeholder.trim())
@@ -27,7 +27,10 @@ export function Select({ action, label, labelVisuallyHidden, 'aria-labelledby':
     const showsPlaceholder = placeholder !== undefined &&
         !options.some((option) => option.value === value);
     const { commit, highlight, onTriggerKeyDown, open, openList, setHighlight, setOpen, } = useSelectList({ action, onChange, options, rootRef, value });
-    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: label === undefined || labelVisuallyHidden ? 0 : 1, children: [label === undefined ? null : (_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark ?? 'visible', size: size, visuallyHidden: labelVisuallyHidden ?? false }) })), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", id: triggerId, onBlur: (event) => {
+    // A control turned off while its list is open closes it.
+    if (disabled && open)
+        setOpen(false);
+    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: label === undefined || labelVisuallyHidden ? 0 : 1, children: [label === undefined ? null : (_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark ?? 'visible', size: size, visuallyHidden: labelVisuallyHidden ?? false }) })), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", disabled: disabled, id: triggerId, onBlur: (event) => {
                                 const next = event.relatedTarget;
                                 if (next instanceof Node && rootRef.current?.contains(next)) {
                                     return;

package/dist/components/app-shell/SkipToMain.d.ts

@@ -0,0 +1,14 @@
+import { type RefObject } from 'react';
+type SkipToMainProps = {
+    label: string;
+    mainId: string;
+    mainRef: RefObject<HTMLElement | null>;
+};
+/**
+ * The shell's first focusable element. A press (Enter included) moves
+ * focus to `main` itself rather than following the fragment, so a hash
+ * router's address and the history stay as they were; the `href` keeps it
+ * a real link to the same place.
+ */
+export declare function SkipToMain({ label, mainId, mainRef }: SkipToMainProps): import("react").JSX.Element;
+export {};

package/dist/components/app-shell/SkipToMain.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { tabStop } from '../../tab-stop.js';
+/**
+ * The shell's first focusable element. A press (Enter included) moves
+ * focus to `main` itself rather than following the fragment, so a hash
+ * router's address and the history stay as they were; the `href` keeps it
+ * a real link to the same place.
+ */
+export function SkipToMain({ label, mainId, mainRef }) {
+    return (_jsx("a", { className: "sw-app-shell-skip-link", href: `#${mainId}`, onClick: (event) => {
+            event.preventDefault();
+            mainRef.current?.focus();
+        }, tabIndex: tabStop, children: label }));
+}

package/dist/components/app-shell/types.d.ts

@@ -50,6 +50,15 @@ export type AppShellLabels = {
     openMenu: string;
     closeMenu: string;
 };
+/**
+ * A "skip to main content" link, the shell's first focusable element:
+ * hidden until it has focus, it moves focus to the shell's `main` (which
+ * the shell names with its own id), past the navigation.
+ */
+export type AppShellSkipLink = {
+    /** Its words, in the page's language ("Skip to main content"). */
+    label: string;
+};
 export type AppShellProps = {
     /** The navigation landmark's name, also the drawer's. */
     navLabel: string;
@@ -117,6 +126,14 @@ export type AppShellProps = {
      */
     pageBar?: ReactNode;
     labels: AppShellLabels;
+    /**
+     * A skip link before everything else in the shell: shown at the window's
+     * top start while it has focus, a press moves focus to `main` (given an
+     * id and `tabindex="-1"`, without changing the address), so a keyboard
+     * user passes the navigation's destinations (WCAG 2.4.1). Left out, the
+     * shell draws none.
+     */
+    skipLink?: AppShellSkipLink;
     /** The page, rendered in `main`. */
     children: ReactNode;
 };

package/dist/components/app-shell/validate.d.ts

@@ -1,7 +1,7 @@
 import { type AppShellProps } from './types.js';
 /**
- * Fails closed on the shell's words, the menu's count, its groups and
- * their items (ids unique across every group, each with an icon, which is
- * all the rail shows).
+ * Fails closed on the shell's words (a skip link's too), the menu's count,
+ * its groups and their items (ids unique across every group, each with an
+ * icon, which is all the rail shows).
  */
-export declare function assertAppShellProps({ groups, labels, menuCount, menuCountLabel, menuCountTone, navLabel, }: Pick<AppShellProps, 'groups' | 'labels' | 'menuCount' | 'menuCountLabel' | 'menuCountTone' | 'navLabel'>): void;
+export declare function assertAppShellProps({ groups, labels, menuCount, menuCountLabel, menuCountTone, navLabel, skipLink, }: Pick<AppShellProps, 'groups' | 'labels' | 'menuCount' | 'menuCountLabel' | 'menuCountTone' | 'navLabel' | 'skipLink'>): void;

package/dist/components/app-shell/validate.js

@@ -44,15 +44,17 @@ function assertMenuCount({ menuCount, menuCountLabel, menuCountTone, }) {
         throw new RangeError('AppShell menuCountLabel and menuCountTone come with a menuCount');
 }
 /**
- * Fails closed on the shell's words, the menu's count, its groups and
- * their items (ids unique across every group, each with an icon, which is
- * all the rail shows).
+ * Fails closed on the shell's words (a skip link's too), the menu's count,
+ * its groups and their items (ids unique across every group, each with an
+ * icon, which is all the rail shows).
  */
-export function assertAppShellProps({ groups, labels, menuCount, menuCountLabel, menuCountTone, navLabel, }) {
+export function assertAppShellProps({ groups, labels, menuCount, menuCountLabel, menuCountTone, navLabel, skipLink, }) {
     if (isBlank(navLabel))
         throw new RangeError('AppShell navLabel must be nonempty');
     if (isBlank(labels?.openMenu) || isBlank(labels?.closeMenu))
         throw new RangeError('AppShell labels openMenu and closeMenu are nonempty');
+    if (skipLink != null && isBlank(skipLink.label))
+        throw new RangeError('AppShell skipLink needs a nonempty label');
     assertMenuCount({ menuCount, menuCountLabel, menuCountTone });
     assertGroups(groups);
     const items = groups.flatMap((group) => group.items);

package/dist/css/css-app-shell-skip-link.d.ts

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

package/dist/css/css-app-shell-skip-link.js

@@ -0,0 +1,26 @@
+import { skipLinkRules } from './skip-link.js';
+import { zIndex } from './stacking.js';
+const link = '.sw-app-shell-skip-link';
+/*
+ * The shell's skip link, its first focusable element, in the shared skip
+ * link look: while it has focus it is fixed at the window's top start,
+ * over the sidebar, the compact bar and a page bar on its own layer, so it
+ * shows however far the page has scrolled. Once used, `main` holds focus
+ * (`tabindex="-1"`) without a ring: it is not a control, and the next Tab
+ * reaches the page's first one.
+ */
+export function cssAppShellSkipLinkRules() {
+    return `${skipLinkRules(link)}
+
+${link} {
+  inset-block-start: var(--sw-space-2);
+  inset-inline-start: var(--sw-space-2);
+  position: fixed;
+  ${zIndex('skipLink')}
+}
+
+.sw-app-shell-main:focus { outline: none; }`;
+}
+export function appShellSkipLinkClassCatalog() {
+    return ['sw-app-shell-skip-link'];
+}

package/dist/css/css-app-shell.js

@@ -2,6 +2,7 @@ import { breakpointQuery } from './breakpoints.js';
 import { appShellDrawerClassCatalog, cssAppShellDrawerClasses, } from './css-app-shell-drawer.js';
 import { appShellNavClassCatalog, cssAppShellNavClasses, cssAppShellRailNavRules, } from './css-app-shell-nav.js';
 import { appShellPageBarClassCatalog, cssAppShellPageBarClasses, } from './css-app-shell-page-bar.js';
+import { appShellSkipLinkClassCatalog, cssAppShellSkipLinkRules, } from './css-app-shell-skip-link.js';
 import { iconButtonRules } from './css-icon-button.js';
 /*
  * The width from which AppShell's sidebar is full rather than a rail: an
@@ -112,7 +113,8 @@ ${cssAppShellRailNavRules('    ')}
  * AppShell: a workspace frame with a pinned side navigation (see
  * components/AppShell.tsx). The links, groups and the rail's nav are
  * `css-app-shell-nav.ts`; the page bar and the menu's count are
- * `css-app-shell-page-bar.ts`; the menu drawer is `css-app-shell-drawer.ts`.
+ * `css-app-shell-page-bar.ts`; the menu drawer is `css-app-shell-drawer.ts`;
+ * the skip link is `css-app-shell-skip-link.ts`.
  */
 export function cssAppShellClasses() {
     return `${barRules()}
@@ -133,7 +135,9 @@ ${cssAppShellPageBarClasses()}
 
 ${sidebarRules()}
 
-${cssAppShellDrawerClasses()}`;
+${cssAppShellDrawerClasses()}
+
+${cssAppShellSkipLinkRules()}`;
 }
 export function appShellClassCatalog() {
     return [
@@ -151,5 +155,6 @@ export function appShellClassCatalog() {
         ...appShellNavClassCatalog(),
         ...appShellPageBarClassCatalog(),
         ...appShellDrawerClassCatalog(),
+        ...appShellSkipLinkClassCatalog(),
     ];
 }

package/dist/css/css-chrome.js

@@ -1,5 +1,6 @@
 import { typographyVariants } from '@scalewing/tokens';
 import { appHeaderBarClassCatalog, cssAppHeaderBarClasses, } from './css-app-header-bar.js';
+import { typedInputs } from './css-document.js';
 import { cssNavWordsClasses, navWordsClassCatalog } from './css-nav-words.js';
 import { zIndex } from './stacking.js';
 import { coarsePointerQuery, touchTarget } from './touch-target.js';
@@ -71,6 +72,26 @@ ${cssNavWordsClasses()}
   padding-inline-end: calc(
     var(--sw-control-xs-padding-inline) + var(--sw-space-5)
   );
+}
+
+/*
+ * The document canvas sizes every typed input under [data-theme] (0,2,1),
+ * which outranks the xs rule above, so an xs field's own text control
+ * matches it there. Adorned and search inputs sit one level deeper and keep
+ * their frames' rules. On a coarse pointer it is the 44 px touch target.
+ */
+[data-theme] .sw-field-xs > :is(${typedInputs}) {
+  font-size: ${caption.fontSize}px;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  min-height: var(--sw-control-xs-min-height);
+  padding-inline: var(--sw-control-xs-padding-inline);
+}
+
+@media ${coarsePointerQuery} {
+  [data-theme] .sw-field-xs > :is(${typedInputs}) {
+    min-height: ${touchTarget};
+  }
 }`;
 }
 export function chromeClassCatalog() {

package/dist/css/css-fixture-action.js

@@ -1,9 +1,10 @@
-import { quietFill } from './quiet-fill.js';
+import { mutedReadsAsText, quietFill } from './quiet-fill.js';
 /*
  * The action sits after the row in its own column, centred on the row's
  * height, outside the row's press area, keeping the row's end padding
  * after it. Where :has() is supported the hover fill spans the whole item,
- * so the row, its select and its action read as one line.
+ * so the row, its select and its action read as one line; a detail under
+ * the row is on that fill too, so its muted words take the text colour.
  */
 function actionRules() {
     return `.sw-fixture-action {
@@ -24,6 +25,8 @@ function actionRules() {
     :is(.sw-fixture-item-action, .sw-fixture-item-select) > .sw-fixture-row-pressable:hover {
       background: transparent;
     }
+
+    ${mutedReadsAsText([':is(.sw-fixture-item-action, .sw-fixture-item-select):has(> .sw-fixture-row-pressable:hover) > .sw-fixture-detail'])}
   }
 }`;
 }

package/dist/css/css-fixture.js

@@ -1,7 +1,7 @@
 import { typographyVariants } from '@scalewing/tokens';
 import { breakpointQuery } from './breakpoints.js';
 import { chevronStrokeIn } from './chevron.js';
-import { quietFill } from './quiet-fill.js';
+import { mutedReadsAsText, quietFill } from './quiet-fill.js';
 import { cssFixtureActionClasses, fixtureActionClassCatalog, } from './css-fixture-action.js';
 import { cssFixtureListRules } from './css-fixture-list.js';
 import { cssFixtureDetailClasses, fixtureDetailClassCatalog, } from './css-fixture-detail.js';
@@ -20,7 +20,8 @@ const belowMd = breakpointQuery('below', 'md');
  * colour, the quiet fill on hover and an inset accent ring, with the
  * shared chevron at the end. The sides' names are label type at weight 500
  * and wrap; the home side ends at the centre (its mark nearest it), the
- * away side starts from it, mirrored in right-to-left.
+ * away side starts from it, mirrored in right-to-left. On the hover fill
+ * its muted parts take the text colour (`mutedReadsAsText`).
  */
 function rowRules() {
     return `.sw-fixture-row {
@@ -47,6 +48,8 @@ function rowRules() {
 
 @media (hover: hover) {
   .sw-fixture-row-pressable:hover { background: ${quietFill}; }
+
+  ${mutedReadsAsText(['.sw-fixture-row-pressable:hover *'])}
 }
 
 .sw-fixture-row-pressable:focus { outline: none; }

package/dist/css/css-list-row.js

@@ -2,7 +2,7 @@ import { typographyVariants } from '@scalewing/tokens';
 import { checkStrokeIn, chevronStrokeIn } from './chevron.js';
 import { chartColorMix, chartInkMixes } from './chart-tones.js';
 import { tableCellTones } from './css-table-ledger.js';
-import { quietFill } from './quiet-fill.js';
+import { mutedReadsAsText, quietFill } from './quiet-fill.js';
 import { coarsePointerQuery, touchTarget } from './touch-target.js';
 const label = typographyVariants.label;
 const body = typographyVariants.body;
@@ -16,7 +16,8 @@ function onTitleLine(size) {
  * detail at the end, then the chevron or check, each lined up with the
  * title's first line. A pressable row is the whole button or link: a
  * quiet fill under the pointer, the focus ring inside its edge, 44 px on a
- * coarse pointer. Plain rows (inside a Card) have no inline padding.
+ * coarse pointer. Plain rows (inside a Card) have no inline padding. On
+ * the fill its muted parts take the text colour (`mutedReadsAsText`).
  */
 function rowRules() {
     return `.sw-list-row {
@@ -44,10 +45,14 @@ function rowRules() {
 
 @media (hover: hover) {
   .sw-list-row-pressable:hover:not(.sw-list-row-disabled) { background: ${quietFill}; }
+
+  ${mutedReadsAsText(['.sw-list-row-pressable:hover:not(.sw-list-row-disabled) *'])}
 }
 
 .sw-list-row-pressable:active:not(.sw-list-row-disabled) { background: ${quietFill}; }
 
+${mutedReadsAsText(['.sw-list-row-pressable:active:not(.sw-list-row-disabled) *'])}
+
 .sw-list-row-pressable:focus { outline: none; }
 
 .sw-list-row-pressable:focus-visible {

package/dist/css/css-select.js

@@ -125,6 +125,17 @@ export function cssSelectClasses() {
   .sw-select-invalid .sw-select-trigger { border-color: Mark; }
 }
 
+/* Off: faded as a disabled Button is; forced colours grey its frame, words and chevron. */
+.sw-select-trigger:disabled {
+  cursor: not-allowed;
+  opacity: var(--sw-disabled-opacity);
+}
+
+@media (forced-colors: active) {
+  .sw-select-trigger:disabled { border-color: GrayText; color: GrayText; }
+  .sw-select-trigger:disabled::after { border-color: GrayText; }
+}
+
 .sw-select-list {
   background: var(--sw-glass-fill);
   border: 1px solid var(--sw-glass-border);

package/dist/css/css-site-header-skip-link.js

@@ -1,49 +1,23 @@
-import { typographyVariants } from '@scalewing/tokens';
-import { visuallyHiddenDeclarations } from './css-utilities.js';
 import { siteHeaderContentStart, siteHeaderGutter, siteHeaderGutterQuery, } from './site-header-geometry.js';
-const label = typographyVariants.label;
+import { skipLinkRules } from './skip-link.js';
+const link = '.sw-site-header-skip-link';
 /*
- * The header's skip link, its first focusable element: visually hidden
- * until it has focus, then a pill on the surface in the text colour with
- * the accent ring, laid over the bar's start (centred in its height and
- * lined up with the brand), the control height tall only then. Positioned,
- * it paints over the bar's content, which is not, so it needs no layer of
- * its own.
+ * The header's skip link, its first focusable element, in the shared skip
+ * link look, laid over the bar's start (centred in its height and lined up
+ * with the brand) while it has focus. Positioned, it paints over the bar's
+ * content, which is not, so it needs no layer of its own.
  */
 export function cssSiteHeaderSkipLinkRules() {
-    return `.sw-site-header-skip-link {
-  align-items: center;
-  background: var(--sw-color-surface);
-  border-radius: var(--sw-radius-pill);
-  box-sizing: border-box;
-  display: inline-flex;
-  font-family: var(--sw-font-sans);
-  font-size: ${label.fontSize}px;
-  font-weight: ${label.fontWeight};
+    return `${skipLinkRules(link)}
+
+${link} {
   inset-block-start: 50%;
   inset-inline-start: ${siteHeaderContentStart(siteHeaderGutter.compact)};
-  letter-spacing: ${label.letterSpacing}px;
-  line-height: ${label.lineHeight}px;
-  padding-inline: var(--sw-space-4);
   position: absolute;
   transform: translateY(-50%);
-  white-space: nowrap;
-}
-
-[data-theme] .sw-site-header-skip-link {
-  color: var(--sw-color-text);
-  text-decoration: none;
 }
 
-[data-theme] .sw-site-header-skip-link:focus {
-  min-height: var(--sw-control-md-min-height);
-  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
-  outline-offset: calc(-1 * var(--sw-focus-ring-width));
-}
-
-.sw-site-header-skip-link:not(:focus) { ${visuallyHiddenDeclarations} }
-
 @media ${siteHeaderGutterQuery} {
-  .sw-site-header-skip-link { inset-inline-start: ${siteHeaderContentStart(siteHeaderGutter.wide)}; }
+  ${link} { inset-inline-start: ${siteHeaderContentStart(siteHeaderGutter.wide)}; }
 }`;
 }

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

@@ -1,17 +1,28 @@
 import { typographyVariants } from '@scalewing/tokens';
-import { quietFill } from './quiet-fill.js';
+import { mutedReadsAsText, quietFill } from './quiet-fill.js';
 const row = '.sw-table-row-press';
 const action = '.sw-table-action';
 /*
  * A pressable row: the pointer cursor over all of it, and the quiet fill
  * on its cells while it is hovered (on a pointer that hovers), pressed, or
  * while its action has keyboard focus, so a keyboard user sees the row the
- * focused name belongs to. The fill sits under the cells' text, so text,
- * muted text and toned figures keep their contrast as on any quiet-filled
- * row (an open menu's). Its action is underlined with it, so the row reads
- * as that one action. Forced colours drop fills, so the row is outlined in
- * the system highlight instead.
+ * focused name belongs to. Muted words fall under 4.5:1 on that fill, so
+ * a muted cell and the muted parts inside every cell take the text colour
+ * while it shows (`mutedReadsAsText`; the cell paints the fill, so its own
+ * colour is set, not the token). Its action is underlined with it, so the
+ * row reads as that one action. Forced colours drop fills, so the row is
+ * outlined in the system highlight instead.
  */
+const hovered = `${row}:hover`;
+const held = [`${row}:active`, `${row}:has(:focus-visible)`];
+/* A filled row's muted cells and the muted parts inside its cells read as text. */
+function mutedCellRules(rows) {
+    return `${mutedReadsAsText(rows.map((filled) => `${filled} > :is(td, th) *`))}
+
+${rows.map((filled) => `${filled} > .sw-table-tone-muted`).join(',\n')} {
+  color: var(--sw-color-text);
+}`;
+}
 function pressableRowRules() {
     return `${row} {
   cursor: pointer;
@@ -25,6 +36,8 @@ function pressableRowRules() {
   ${row}:hover ${action} {
     text-decoration-line: underline;
   }
+
+  ${mutedCellRules([hovered])}
 }
 
 ${row}:active > :is(td, th),
@@ -32,6 +45,8 @@ ${row}:has(:focus-visible) > :is(td, th) {
   background: ${quietFill};
 }
 
+${mutedCellRules(held)}
+
 @media (forced-colors: active) {
   ${row}:hover,
   ${row}:has(:focus-visible) {

package/dist/css/quiet-fill.d.ts

@@ -5,3 +5,14 @@
  * button all take it, so they read as one grey.
  */
 export declare const quietFill = "color-mix(in srgb, var(--sw-color-muted) 16%, transparent)";
+/**
+ * Muted words keep 4.5:1 on the surface but not on the quiet fill (4.14:1
+ * in most light palettes, 3.47:1 in harvest dark), while the text colour
+ * keeps it in every palette and scheme. So while a row shows the fill, its
+ * parts read the muted token as the text colour: the details, a consumer's
+ * `Text color="muted"`, the chevron. `scopes` are selectors for what sits
+ * on the fill (`<row>:hover *`), never the element that paints it, whose
+ * fill reads the muted token too. Toned words keep their tone. Forced
+ * colours replace both colours, so this changes nothing there.
+ */
+export declare function mutedReadsAsText(scopes: readonly string[]): string;

package/dist/css/quiet-fill.js

@@ -5,3 +5,18 @@
  * button all take it, so they read as one grey.
  */
 export const quietFill = 'color-mix(in srgb, var(--sw-color-muted) 16%, transparent)';
+/**
+ * Muted words keep 4.5:1 on the surface but not on the quiet fill (4.14:1
+ * in most light palettes, 3.47:1 in harvest dark), while the text colour
+ * keeps it in every palette and scheme. So while a row shows the fill, its
+ * parts read the muted token as the text colour: the details, a consumer's
+ * `Text color="muted"`, the chevron. `scopes` are selectors for what sits
+ * on the fill (`<row>:hover *`), never the element that paints it, whose
+ * fill reads the muted token too. Toned words keep their tone. Forced
+ * colours replace both colours, so this changes nothing there.
+ */
+export function mutedReadsAsText(scopes) {
+    return `${scopes.join(',\n')} {
+  --sw-color-muted: var(--sw-color-text);
+}`;
+}

package/dist/css/skip-link.d.ts

@@ -0,0 +1 @@
+export declare function skipLinkRules(selector: string): string;

package/dist/css/skip-link.js

@@ -0,0 +1,39 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { visuallyHiddenDeclarations } from './css-utilities.js';
+const label = typographyVariants.label;
+/*
+ * A skip link's look, shared by SiteHeader's and AppShell's: visually
+ * hidden until it has focus, then a pill on the surface in the text colour
+ * with the accent ring inside its edge, the control height tall. Each
+ * component positions its own; forced colours draw it as a link on the
+ * system canvas with the ring in the system colour.
+ */
+export function skipLinkRules(selector) {
+    return `${selector} {
+  align-items: center;
+  background: var(--sw-color-surface);
+  border-radius: var(--sw-radius-pill);
+  box-sizing: border-box;
+  display: inline-flex;
+  font-family: var(--sw-font-sans);
+  font-size: ${label.fontSize}px;
+  font-weight: ${label.fontWeight};
+  letter-spacing: ${label.letterSpacing}px;
+  line-height: ${label.lineHeight}px;
+  padding-inline: var(--sw-space-4);
+  white-space: nowrap;
+}
+
+[data-theme] ${selector} {
+  color: var(--sw-color-text);
+  text-decoration: none;
+}
+
+[data-theme] ${selector}:focus {
+  min-height: var(--sw-control-md-min-height);
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+${selector}:not(:focus) { ${visuallyHiddenDeclarations} }`;
+}

package/dist/css/stacking.d.ts

@@ -5,6 +5,7 @@ export declare const stackingOrder: {
     readonly popupHost: 4;
     readonly topChrome: 5;
     readonly sheetGrabber: 6;
+    readonly skipLink: 7;
     readonly popup: 10;
 };
 export type StackingLayer = keyof typeof stackingOrder;

package/dist/css/stacking.js

@@ -19,7 +19,9 @@
  *    strip its way between sections, and a popup opens downward).
  * 6. `sheetGrabber`: a bottom sheet's grabber, inside its dialog, over the
  *    banded title band that sticks under it.
- * 7. `popup`: a popup outside any lifted surface (Select list, ActionMenu
+ * 7. `skipLink`: AppShell's skip link while it has focus, fixed over the
+ *    top chrome and the sidebar (a popup is never open while it has focus).
+ * 8. `popup`: a popup outside any lifted surface (Select list, ActionMenu
  *    list, ContextSwitcher popup, MultiSelect panel, Combobox list, Tooltip,
  *    the DateField and CalendarButton calendar) over everything in the page.
  *
@@ -32,6 +34,7 @@ export const stackingOrder = {
     popupHost: 4,
     topChrome: 5,
     sheetGrabber: 6,
+    skipLink: 7,
     popup: 10,
 };
 /*

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { Checkbox, type CheckboxProps } from './components/Checkbox.js';
 export { PasteRows, type PasteRowsColumn, type PasteRowsProps, } from './components/PasteRows.js';
 export { parsePastedRows, type PastedRows, type PastedRowsDelimiter, pastedRowsDelimiters, } from './components/paste-rows/parse-pasted-rows.js';
 export { Spinner, type SpinnerProps, type SpinnerSize, } from './components/Spinner.js';
+export { LiveRegion, liveRegionPolitenesses, type LiveRegionPoliteness, type LiveRegionProps, } from './components/LiveRegion.js';
 export { Skeleton, skeletonVariants, type SkeletonProps, type SkeletonVariant, } from './components/Skeleton.js';
 export { EmptyState, emptyStateTitleElements, type EmptyStateProps, type EmptyStateTitleElement, } from './components/EmptyState.js';
 export { GlyphTile, glyphTileSizes, type GlyphTileHue, type GlyphTileProps, type GlyphTileSize, } from './components/GlyphTile.js';
@@ -65,7 +66,7 @@ export { DateToggleCalendar, type DateToggleCalendarProps, } from './components/
 export { CommandPalette, commandPaletteShortcuts, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteProps, type CommandPaletteShortcut, } from './components/CommandPalette.js';
 export { CommandPaletteTrigger, type CommandPaletteTriggerProps, } from './components/CommandPaletteTrigger.js';
 export { ContextSwitcher, contextSwitcherTriggerAppearances, contextSwitcherWidths, type ContextSwitcherAction, type ContextSwitcherBadge, type ContextSwitcherFilter, type ContextSwitcherGroup, type ContextSwitcherOption, type ContextSwitcherProps, type ContextSwitcherTriggerAppearance, type ContextSwitcherWidth, } from './components/ContextSwitcher.js';
-export { AppShell, type AppShellLabels, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, } from './components/AppShell.js';
+export { AppShell, type AppShellLabels, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, type AppShellSkipLink, } from './components/AppShell.js';
 export { SectionNav, sectionNavAppearances, type SectionNavAppearance, type SectionNavItem, type SectionNavProps, } from './components/SectionNav.js';
 export { SegmentedControl, type SegmentedControlProps, type SegmentedControlVariant, segmentedSizes, type SegmentedSize, type SegmentedItem, } from './components/SegmentedControl.js';
 export { Combobox, comboboxSizes, type ComboboxAction, type ComboboxBadge, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ComboboxSize, } from './components/Combobox.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { Checkbox } from './components/Checkbox.js';
 export { PasteRows, } from './components/PasteRows.js';
 export { parsePastedRows, pastedRowsDelimiters, } from './components/paste-rows/parse-pasted-rows.js';
 export { Spinner, } from './components/Spinner.js';
+export { LiveRegion, liveRegionPolitenesses, } from './components/LiveRegion.js';
 export { Skeleton, skeletonVariants, } from './components/Skeleton.js';
 export { EmptyState, emptyStateTitleElements, } from './components/EmptyState.js';
 export { GlyphTile, glyphTileSizes, } from './components/GlyphTile.js';

package/dist/styles.css

@@ -2194,6 +2194,14 @@ body {
   .sw-table-row-press:hover .sw-table-action {
     text-decoration-line: underline;
   }
+
+  .sw-table-row-press:hover > :is(td, th) * {
+  --sw-color-muted: var(--sw-color-text);
+}
+
+.sw-table-row-press:hover > .sw-table-tone-muted {
+  color: var(--sw-color-text);
+}
 }
 
 .sw-table-row-press:active > :is(td, th),
@@ -2201,6 +2209,16 @@ body {
   background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent);
 }
 
+.sw-table-row-press:active > :is(td, th) *,
+.sw-table-row-press:has(:focus-visible) > :is(td, th) * {
+  --sw-color-muted: var(--sw-color-text);
+}
+
+.sw-table-row-press:active > .sw-table-tone-muted,
+.sw-table-row-press:has(:focus-visible) > .sw-table-tone-muted {
+  color: var(--sw-color-text);
+}
+
 @media (forced-colors: active) {
   .sw-table-row-press:hover,
   .sw-table-row-press:has(:focus-visible) {
@@ -3077,10 +3095,18 @@ button.sw-date-toggle-day[aria-disabled='true'] {
 
 @media (hover: hover) {
   .sw-list-row-pressable:hover:not(.sw-list-row-disabled) { background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent); }
+
+  .sw-list-row-pressable:hover:not(.sw-list-row-disabled) * {
+  --sw-color-muted: var(--sw-color-text);
+}
 }
 
 .sw-list-row-pressable:active:not(.sw-list-row-disabled) { background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent); }
 
+.sw-list-row-pressable:active:not(.sw-list-row-disabled) * {
+  --sw-color-muted: var(--sw-color-text);
+}
+
 .sw-list-row-pressable:focus { outline: none; }
 
 .sw-list-row-pressable:focus-visible {
@@ -3355,6 +3381,10 @@ button.sw-date-toggle-day[aria-disabled='true'] {
 
 @media (hover: hover) {
   .sw-fixture-row-pressable:hover { background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent); }
+
+  .sw-fixture-row-pressable:hover * {
+  --sw-color-muted: var(--sw-color-text);
+}
 }
 
 .sw-fixture-row-pressable:focus { outline: none; }
@@ -3598,6 +3628,10 @@ button.sw-date-toggle-day[aria-disabled='true'] {
     :is(.sw-fixture-item-action, .sw-fixture-item-select) > .sw-fixture-row-pressable:hover {
       background: transparent;
     }
+
+    :is(.sw-fixture-item-action, .sw-fixture-item-select):has(> .sw-fixture-row-pressable:hover) > .sw-fixture-detail {
+  --sw-color-muted: var(--sw-color-text);
+}
   }
 }
 
@@ -5011,6 +5045,26 @@ button.sw-date-toggle-day[aria-disabled='true'] {
   );
 }
 
+/*
+ * The document canvas sizes every typed input under [data-theme] (0,2,1),
+ * which outranks the xs rule above, so an xs field's own text control
+ * matches it there. Adorned and search inputs sit one level deeper and keep
+ * their frames' rules. On a coarse pointer it is the 44 px touch target.
+ */
+[data-theme] .sw-field-xs > :is(input[type='text'], input[type='email'], input[type='number'], input[type='search'], input[type='url'], input[type='password'], input:not([type]), textarea) {
+  font-size: 13px;
+  letter-spacing: -0.08px;
+  line-height: 18px;
+  min-height: var(--sw-control-xs-min-height);
+  padding-inline: var(--sw-control-xs-padding-inline);
+}
+
+@media (pointer: coarse) {
+  [data-theme] .sw-field-xs > :is(input[type='text'], input[type='email'], input[type='number'], input[type='search'], input[type='url'], input[type='password'], input:not([type]), textarea) {
+    min-height: var(--sw-control-md-min-height);
+  }
+}
+
 .sw-section-nav-list {
   border-bottom: 1px solid var(--sw-color-border);
   display: flex;
@@ -5724,13 +5778,9 @@ button.sw-date-toggle-day[aria-disabled='true'] {
   font-family: var(--sw-font-sans);
   font-size: 15px;
   font-weight: 600;
-  inset-block-start: 50%;
-  inset-inline-start: calc(max(0px, (100% - calc(var(--sw-container-max) + 2 * var(--sw-space-5))) / 2) + var(--sw-space-4));
   letter-spacing: -0.2px;
   line-height: 20px;
   padding-inline: var(--sw-space-4);
-  position: absolute;
-  transform: translateY(-50%);
   white-space: nowrap;
 }
 
@@ -5747,6 +5797,13 @@ button.sw-date-toggle-day[aria-disabled='true'] {
 
 .sw-site-header-skip-link:not(:focus) { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 
+.sw-site-header-skip-link {
+  inset-block-start: 50%;
+  inset-inline-start: calc(max(0px, (100% - calc(var(--sw-container-max) + 2 * var(--sw-space-5))) / 2) + var(--sw-space-4));
+  position: absolute;
+  transform: translateY(-50%);
+}
+
 @media (min-width: 48rem) {
   .sw-site-header-skip-link { inset-inline-start: calc(max(0px, (100% - calc(var(--sw-container-max) + 2 * var(--sw-space-5))) / 2) + var(--sw-space-5)); }
 }
@@ -6132,6 +6189,43 @@ html:has(.sw-site-header-sticky) {
   .sw-app-shell-drawer { border-inline-end-color: CanvasText; }
 }
 
+.sw-app-shell-skip-link {
+  align-items: center;
+  background: var(--sw-color-surface);
+  border-radius: var(--sw-radius-pill);
+  box-sizing: border-box;
+  display: inline-flex;
+  font-family: var(--sw-font-sans);
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: -0.2px;
+  line-height: 20px;
+  padding-inline: var(--sw-space-4);
+  white-space: nowrap;
+}
+
+[data-theme] .sw-app-shell-skip-link {
+  color: var(--sw-color-text);
+  text-decoration: none;
+}
+
+[data-theme] .sw-app-shell-skip-link:focus {
+  min-height: var(--sw-control-md-min-height);
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+.sw-app-shell-skip-link:not(:focus) { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+
+.sw-app-shell-skip-link {
+  inset-block-start: var(--sw-space-2);
+  inset-inline-start: var(--sw-space-2);
+  position: fixed;
+  z-index: 7;
+}
+
+.sw-app-shell-main:focus { outline: none; }
+
 .sw-dialog {
   background: var(--sw-glass-fill);
   border: 1px solid var(--sw-glass-border);
@@ -6637,6 +6731,17 @@ html:has(.sw-site-header-sticky) {
   .sw-select-invalid .sw-select-trigger { border-color: Mark; }
 }
 
+/* Off: faded as a disabled Button is; forced colours grey its frame, words and chevron. */
+.sw-select-trigger:disabled {
+  cursor: not-allowed;
+  opacity: var(--sw-disabled-opacity);
+}
+
+@media (forced-colors: active) {
+  .sw-select-trigger:disabled { border-color: GrayText; color: GrayText; }
+  .sw-select-trigger:disabled::after { border-color: GrayText; }
+}
+
 .sw-select-list {
   background: var(--sw-glass-fill);
   border: 1px solid var(--sw-glass-border);

package/package.json

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