@scalewing/react 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @scalewing/react
 
+## 1.40.0
+
+### Minor Changes
+
+- 935ff2a: `DateRangeButton`: a button showing a range of days (`value` `{ start, end }`, `YYYY-MM-DD`) that opens a calendar to pick a first and a last day. From `md` up it is a popover with the `presets` (`DateRangePreset`: `id`, `label`, `range`; a press applies it at once) beside two months (above them below `lg`), the range being picked in a polite status, and Cancel and Apply; below `md` it is a Dialog bottom sheet with the presets in a row and one month. The first press sets the start and the second the end; days after `max` are disabled, and once a start is pressed so are the days past `maxDays`. Apply calls `onChange` with a changed range; Cancel, Escape, a press outside and the sheet's close keep the value. Its name is `label`, `labels.nameSeparator` and the range it shows. `labels` (`DateRangeButtonLabels`) holds every word, `dayCount` included; `min`, `today`, `weekStartsOn`, `locale`, `disabled`, `id`, `size` and `variant` (default `neutral`) as on CalendarButton. Input it cannot draw throws a `RangeError`. New exports `DateRangeButton`, `DateRangeButtonProps`, `DateRangeButtonValue`, `DateRangePreset`, `DateRangeButtonLabels`; new `sw-date-range-*` classes. It shares CalendarButton's private calendar grid, popover and month steps, whose public behaviour is unchanged. `ButtonGroup attached` now finds its buttons by type, so an open calendar beside one keeps the group's dividers and corners. No new tokens, no new dependency. Request: `docs/requests/teisoro-date-range-button.md`.
+- 3192e17: Web `ListGroup` and `ListRow`, the counterpart of react-native's. `ListGroup` is a list (`ul`, role kept) of rows with hairlines between them, a bordered `panel` or `plain` rows inside a surface, named by `aria-label` or `aria-labelledby`; `maxHeight` (`{ rows }`) bounds it to rows of a title and one detail line that scroll inside a named, focusable region shaded at an edge with more past it, and `footer` stays pinned under the rows, such as a total. `ListRow` has a `title` (`titleAppearance` `strong` or `plain`, `tone` `danger`), a muted `detail`, a `value` with `valueDetail` and `valueTone` (a table cell's tones) and a hidden `leading` mark; `onPress` or `href` makes the whole row a button or link with a chevron, named by its title and value and described by its details (`href` with `onPress` takes a plain press for a client router); `selected` makes it a choice with a check (`aria-pressed` or `aria-current`); `accessory="none"` hides the chevron; `disabled` blocks presses. Input it cannot draw throws a `RangeError`. New exports `ListGroup`, `ListGroupProps`, `ListRow`, `ListRowProps`, `listGroupVariants`, `listRowTones`, `listRowTitleAppearances`, `listRowValueTones`, `ListGroupMaxHeight`, `ListGroupVariant`, `ListRowTone`, `ListRowTitleAppearance`, `ListRowValueTone`; new `sw-list*` classes; no new tokens, no new dependency. Request: `docs/requests/teisoro-list-group.md`.
+- 1d3fafd: `NavCount`: a count after a Nav destination's words, placed inside its link or Button (`<a href="/tasks">Tasks<NavCount count={8} /></a>`), such as the tasks waiting in an area. It is SectionNav's count pill, now one shared rule, and it is read in the destination's name ("Tasks 8"); `countLabel` is read in place of the bare number ("Tasks 8 tasks to do") with the pill hidden from assistive technology; a `count` of 0 shows nothing. A count that is not a whole number from 0 or a blank `countLabel` throws a `RangeError`. New exports `NavCount`, `NavCountProps`; new class `sw-nav-count`; no new tokens, no new dependency. Request: `docs/requests/teisoro-nav-count.md`.
+- 62c33b1: `StatTile` `appearance="plain"` (`StatTileAppearance`, `statTileAppearances`; default `card`): the figure without the tile's surface, edge, radius or padding, top-aligned, for figures inside a card, such as four answers in a row divided by a composed `Separator`. A plain tile cannot be `emphasis="primary"`; that or an unknown appearance throws a `RangeError`. New class `sw-stat-tile-plain`; no new tokens, no new dependency. Request: `docs/requests/teisoro-stat-tile-plain.md`.
+
 ## 1.39.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,7 @@ import {
   Box,
   Button,
   CalendarButton,
+  DateRangeButton,
   Card,
   Checkbox,
   RadioGroup,
@@ -29,6 +30,8 @@ import {
   Separator,
   DescriptionList,
   DescriptionItem,
+  ListGroup,
+  ListRow,
   DenominationGrid,
   FilterChips,
   Grid,
@@ -375,6 +378,20 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 
 `appearance="words"` (opt-in; default `"default"`, `navAppearances`) draws every destination, a link or a `Button` of any variant, as plain words: no fill, border or underline, label type, the others in the muted color at medium weight and the current one (`aria-current`, not `"false"`) in the text color at label weight. A Button keeps its size, padding, touch target and focus ring; hover lifts a destination to the text color where the pointer can hover, never a disabled one. The current mark is color and weight, so each destination's words must be visible: a glyph-only destination has no weight to change (keep `default` for a glyph rail). Forced colors draw the current one's border in Highlight and underline its words. An unknown value throws a `RangeError`.
 
+`NavCount` puts a count after a destination's words, such as the tasks waiting in an area: place it inside the link or `Button`, after its words (`<a href="/tasks">Tasks<NavCount count={8} /></a>`). It is the pill `SectionNav`'s item `count` draws (the danger color with its on-color figures, an edge in forced colors), a space-2 after the words in a link or a Button, the link keeping its siblings' height, and it is read as part of the destination's name ("Tasks 8"). `count` is a whole number; 0 shows nothing. `countLabel` says what it means in your words ("8 tasks to do"): it is read in place of the bare number ("Tasks 8 tasks to do") and the pill is hidden from assistive technology. A count that is not a whole number from 0, or a blank `countLabel`, throws a `RangeError`.
+
+```tsx
+<Nav appearance="words" aria-label="Areas">
+  <Box as="a" href="/sightings">
+    Sightings
+  </Box>
+  <Box as="a" href="/tasks" aria-current="page">
+    Tasks
+    <NavCount count={8} countLabel="8 tasks to do" />
+  </Box>
+</Nav>
+```
+
 `SectionNav` is the navigation between the sections of one area, such as a portal's pages: a labelled `nav` (`aria-label` or `aria-labelledby`) of links from `items` (`{ id, label, href, current?, icon?, count? }`), quieter than a workspace's `Nav`. `current` is `'page'`, `'location'` (a page inside that section, such as a detail page under its list) or a boolean, written as `aria-current`; the current item is in the text color over an accent underline, or, from `verticalFrom` (a breakpoint) up, where the items stack as a side list, a bar at its start. `icon` is a decorative glyph before the label. `onNavigate` takes a plain press after preventing the browser's navigation, for a client router; a press with a modifier key or the middle button keeps the browser's behavior, and without `onNavigate` the links carry no handler, so a server component can render the nav. `count` (a whole number) is how many things wait in a section, such as tasks: a filled pill after the label, in the danger color with its on-color figures, read as part of the link's name ("Tasks 3"); 0 shows none, and there is no cap. `countLabel` says what the count means in your words ("3 tasks to do"): it is read in place of the bare number and the pill is hidden from assistive technology. `appearance="filled"` (default `"underline"`) is a quiet row of page buttons for an area's sub-navigation beside its name: no hairline and no underline or start bar, every link the `sm` control with the small radius at weight 500, the current one on a soft muted fill in the text color at 600 (a 2 px `Highlight` edge in forced colors), in the row or the side list. A coarse pointer gets 44 px targets. Empty or duplicate ids, empty labels, a `count` that is not a whole number from 0, a blank `countLabel` or one without a `count`, and an unknown `verticalFrom` or `appearance` throw a `RangeError`. Use `Tabs` for panels on one page.
 
 ```tsx
@@ -620,6 +637,65 @@ A bar in its own column reads as empty cells to assistive technology, which is f
 </DescriptionList>
 ```
 
+`StatTile` is one prominent figure with its label: a `label`, a consumer-formatted `value` (tabular figures; `tone` `accent`, `success`, `danger` or `warning` colours it), an optional `caption` under it and an optional `glyph` in a tinted circle. `emphasis="primary"` fills the one figure a page leads with in the accent. `appearance="plain"` (default `"card"`, `statTileAppearances`) drops the tile's surface, edge, radius and padding, top-aligned, for figures inside a card that already has them, such as four answers in a row divided by hairlines: compose a `Grid` and a vertical `Separator` before every tile but the first, hiding the one that would start a row below `md` (`Inline hideBelow="md"` around it). A plain tile cannot be `primary` (there is no surface to fill), and an unknown appearance throws a `RangeError`.
+
+```tsx
+<Card padding={5}>
+  <Grid columns={4} columnsBelow={{ md: 2 }} gap={4}>
+    {answers.map((answer, index) => (
+      <Inline align="stretch" gap={4} key={answer.label}>
+        {index > 0 ? (
+          // 2 is columnsBelow md: an answer that starts a row there has no hairline.
+          <Inline
+            align="stretch"
+            hideBelow={index % 2 === 0 ? 'md' : undefined}
+          >
+            <Separator orientation="vertical" decorative />
+          </Inline>
+        ) : null}
+        <StatTile appearance="plain" {...answer} />
+      </Inline>
+    ))}
+  </Grid>
+</Card>
+```
+
+`ListGroup` is rows in one list with a hairline between each pair, the web twin of react-native's: a `ul` (its list role kept) named by `aria-label` or `aria-labelledby`. `variant="panel"` (the default) is one bordered panel; `plain` draws no panel and a hairline above the first row too, for rows inside a `Card`. Each `ListRow` has a `title` (weight 600, or the body weight with `titleAppearance="plain"`; `tone="danger"` for a row that ends something), an optional muted `detail` line, an optional `value` at its end (weight 600, tabular figures; `valueTone` `success`, `danger`, `muted` or `accent`; `valueDetail` a muted line under it) and an optional `leading` mark such as a status dot, hidden from assistive technology, so the words say what it means. With `onPress` the whole row is a button, and with `href` a link (`onPress` then takes a plain press for a client router); either adds a chevron, a quiet fill under the pointer and 44 px on a coarse pointer, and the row is named by its title and value and described by its detail lines (`aria-label` replaces the name). `selected` makes a pressable row a choice: a check while true, `aria-pressed` on a button or `aria-current` on a link (on a row with neither `onPress` nor `href` it throws, since nothing could read the state). `accessory="none"` hides the chevron of a row that acts in place; `disabled` blocks presses. A row with neither `onPress` nor `href` only states something. `maxHeight={{ rows }}` bounds the list to that many rows of a title and one detail line, the rest scrolling inside its own named region, which shades an edge with more rows past it; a bounded list must be named. `footer` stays pinned under the rows, outside the scroll, such as a `ListRow` with the count and the total (a row there is not a list item). An empty title or value, an unknown variant or tone, a `valueDetail` without a value, or a bad row count throws a `RangeError`.
+
+```tsx
+<Card padding={4}>
+  <Text as="h3" id="look" variant="label">
+    Worth a look
+  </Text>
+  <ListGroup aria-labelledby="look" variant="plain">
+    <ListRow
+      leading={<Circle size={8} fill="currentColor" />}
+      title="Wed, Oct 7 · North marsh counted 6 fewer herons"
+      detail="Recounted Sat, Oct 10 by Field team A"
+      href="/nights/2026-10-07"
+      onPress={() => router.push('/nights/2026-10-07')}
+    />
+  </ListGroup>
+</Card>
+
+<ListGroup
+  aria-label="Night counts"
+  maxHeight={{ rows: 5 }}
+  footer={<ListRow title="8 nights" value="+0" />}
+>
+  {nights.map((night) => (
+    <ListRow
+      key={night.id}
+      title={night.name}
+      detail={night.detail}
+      value={night.change}
+      valueTone={night.tone}
+      onPress={() => openNight(night)}
+    />
+  ))}
+</ListGroup>
+```
+
 `Card` defaults to `glass`; `outlined` and `elevated` are solid surfaces, and `filled` is a quiet `--sw-color-subtle` fill with no border for plain information apart from pressable rows.
 
 `--sw-color-accentSubtle` is the accent tint from `@scalewing/tokens`: a quiet fill behind accent text or glyphs that keeps 4.5:1. The stylesheet and every palette file set it, and a palette that moves the accent or surface retints it.
@@ -736,6 +812,32 @@ People type the date into a text entry in the locale's numeric order (`MM/DD/YYY
 </Inline>
 ```
 
+`DateRangeButton` shows a range of days and opens a calendar to pick a first and a last day, such as a report's period between its own ‹ and › steps. Supply `label` (what pressing it does, such as "Choose survey period"), `value` (`{ start, end }`, both `YYYY-MM-DD` and included) and `onChange`; optional `min`, `max`, `today`, `disabled`, `locale`, `weekStartsOn`, `id` and a `ref` behave as on `CalendarButton`. The button shows a calendar glyph and the range in the locale, sharing what both ends have ("Oct 6 – 12, 2026"; one day as one date); its name is `label`, `labels.nameSeparator`, then that range. The first press on a day sets the start and the second the end; a press before the start starts over from it, and Apply with only a start applies that one day. Days after `max` are disabled, and once a start is pressed so are the days past `maxDays` (a whole number of days, both ends counted, such as 366). The range being picked and its length (`labels.dayCount`) are a polite status. **Apply** calls `onChange` when the range changed, closes and returns focus to the button; **Cancel**, Escape and a press outside close without a change. `presets` (`{ id, label, range }[]`) are ranges chosen in one press: a press applies its range at once and closes, and the one matching the range shown is pressed; a preset outside `min`/`max` or longer than `maxDays` throws, so compute presets from the same bounds and leave out one that does not fit (such as Last year for a station opened this spring). From `md` up the calendar is a popover with the presets beside two months (above them below `lg`, where both do not fit side by side), the range and the hint, and Cancel and Apply; below `md` it is a `Dialog` bottom sheet titled by `label` with the range under the title, the presets in a row that scrolls sideways, one month and the hint over Cancel and Apply. The keyboard is the calendar's: arrows, Home, End, PageUp and PageDown (with Shift by year) move one focus day across both months, and Enter or Space presses it. `labels` takes `previousMonth`, `nextMonth`, `nameSeparator`, `presets` (the presets group's name), `apply`, `cancel`, `close`, `hint` and `dayCount(days)`, in English by default. `size` (default `md`, at least 44 px tall on a coarse pointer) and `variant` (default `neutral`) follow `Button`. A value outside `min`/`max` or longer than `maxDays` is kept; an empty or malformed date, a start after its end, a `maxDays` under 1 or fractional, repeated preset ids, or an empty word throws a `RangeError`.
+
+```tsx
+<ButtonGroup aria-label="Survey period" attached>
+  <Button aria-label="The period before" variant="neutral" onPress={previous}>
+    ‹
+  </Button>
+  <DateRangeButton
+    label="Choose survey period"
+    value={period}
+    onChange={setPeriod}
+    presets={[
+      { id: 'week', label: 'Last 7 days', range: lastSevenDays },
+      { id: 'month', label: 'This month', range: thisMonth },
+    ]}
+    max={stationDay}
+    maxDays={366}
+    today={stationDay}
+    labels={{ apply: 'Show' }}
+  />
+  <Button aria-label="The period after" variant="neutral" onPress={next}>
+    ›
+  </Button>
+</ButtonGroup>
+```
+
 ```tsx
 <Switch
   label="Active habitats only"

package/dist/calendar-month.d.ts

@@ -17,8 +17,14 @@ export declare function weekdayOf(value: string): number;
 export declare function addDays(value: string, delta: number): string;
 /** Same day of the month `delta` months away, capped at that month's length. */
 export declare function addMonths(value: string, delta: number): string;
+/** Days from `start` to `end`: 0 for the same day, negative when `end` is earlier. */
+export declare function daysBetween(start: string, end: string): number;
 export declare function monthOf(value: string): CalendarMonth;
 export declare function shiftMonth(month: CalendarMonth, delta: number): CalendarMonth;
+/** Months from `from` to `to`: 0 for the same month, negative when `to` is earlier. */
+export declare function monthsBetween(from: CalendarMonth, to: CalendarMonth): number;
+/** `value`'s day of the month in `month`, capped at that month's length. */
+export declare function sameDayIn(month: CalendarMonth, value: string): string;
 export declare function firstOfMonth(month: CalendarMonth): string;
 export declare function lastOfMonth(month: CalendarMonth): string;
 /** Whether any day of the month falls inside `[min, max]`. */

package/dist/calendar-month.js

@@ -61,6 +61,10 @@ export function addMonths(value, delta) {
         day: Math.min(parts.day, daysInMonth(month.year, month.month)),
     });
 }
+/** Days from `start` to `end`: 0 for the same day, negative when `end` is earlier. */
+export function daysBetween(start, end) {
+    return toDayNumber(requireDate(end)) - toDayNumber(requireDate(start));
+}
 export function monthOf(value) {
     const parts = requireDate(value);
     return { year: parts.year, month: parts.month };
@@ -69,6 +73,17 @@ export function shiftMonth(month, delta) {
     const index = month.year * 12 + (month.month - 1) + delta;
     return { year: Math.floor(index / 12), month: (index % 12) + 1 };
 }
+/** Months from `from` to `to`: 0 for the same month, negative when `to` is earlier. */
+export function monthsBetween(from, to) {
+    return to.year * 12 + to.month - (from.year * 12 + from.month);
+}
+/** `value`'s day of the month in `month`, capped at that month's length. */
+export function sameDayIn(month, value) {
+    return formatDateOnly({
+        ...month,
+        day: Math.min(requireDate(value).day, daysInMonth(month.year, month.month)),
+    });
+}
 export function firstOfMonth(month) {
     return formatDateOnly({ ...month, day: 1 });
 }

package/dist/components/DateRangeButton.d.ts

@@ -0,0 +1,65 @@
+import { type WeekStart } from '../calendar-month.js';
+import { type DateRangePreset } from '../date-range-input.js';
+import { type DateRangeButtonLabels } from '../date-range-labels.js';
+import { type DateOnlyRange } from '../date-only.js';
+import { type ButtonSize, type ButtonVariant } from './Button.js';
+export type { DateRangeButtonLabels, DateRangePreset };
+/** A span of calendar days `YYYY-MM-DD`, both ends included. */
+export type DateRangeButtonValue = DateOnlyRange;
+export type DateRangeButtonProps = {
+    /**
+     * What pressing it does, such as "Choose a period". The button's name is
+     * this label, `labels.nameSeparator`, then the range it shows; the
+     * popover and the sheet are named by it.
+     */
+    label: string;
+    /**
+     * The range shown, `{ start, end }` as `YYYY-MM-DD`, start not after end.
+     * A range outside `min`/`max` or longer than `maxDays` stays the value.
+     */
+    value: DateRangeButtonValue;
+    /** Receives a new range on Apply or a preset, never converted through UTC. */
+    onChange: (value: DateRangeButtonValue) => void;
+    /**
+     * Ranges chosen in one press, such as "Last 7 days": a list beside the
+     * months (a row above the month on a phone). A press applies its range
+     * and closes. Each must lie inside `min`/`max` and `maxDays`.
+     */
+    presets?: readonly DateRangePreset[];
+    min?: string;
+    /** The last day that can be picked, such as today. */
+    max?: string;
+    /**
+     * The longest range, in days with both ends counted: once a first day is
+     * pressed, the days after this many are disabled.
+     */
+    maxDays?: number;
+    /**
+     * The calendar's today `YYYY-MM-DD`, the day it marks. Defaults to the
+     * device's local date; pass the business's day when it keeps its own.
+     */
+    today?: string;
+    disabled?: boolean;
+    /** The `<button>` element's id. */
+    id?: string;
+    /**
+     * BCP 47 tag for the dates and the calendar's month and weekday names.
+     * Defaults to the nearest `lang` attribute, then en-US.
+     */
+    locale?: string;
+    /** First column of the calendar: 0 Sunday (default) or 1 Monday. */
+    weekStartsOn?: WeekStart;
+    /** The calendar's words; English by default. */
+    labels?: Partial<DateRangeButtonLabels>;
+    /** A Button size; a coarse pointer gets a 44 px target. */
+    size?: ButtonSize;
+    /** Default `neutral`, the quiet grey of a page's period controls. */
+    variant?: ButtonVariant;
+};
+/**
+ * A button showing a range of days that opens a calendar to pick a first
+ * and a last day: from `md` up a popover with the presets and two months,
+ * below it a bottom sheet with one month. Apply gives the range; Cancel,
+ * Escape and a press outside keep the value. The ref reaches the `<button>`.
+ */
+export declare const DateRangeButton: import("react").ForwardRefExoticComponent<DateRangeButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/DateRangeButton.js

@@ -0,0 +1,54 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef, useCallback } from 'react';
+import { breakpointQuery } from '../css/breakpoints.js';
+import { latestPick, rangeDayCount, sameRange } from '../date-range-draft.js';
+import { assertDateRangeInput, } from '../date-range-input.js';
+import { resolveDateRangeButtonLabels, } from '../date-range-labels.js';
+import { formatRangeLong, formatRangeShort } from '../date-range-words.js';
+import { todayDateOnly } from '../date-only.js';
+import { Button } from './Button.js';
+import { DateFieldGlyph } from './date-field/DateFieldGlyph.js';
+import { useLangLocale } from './date-field/use-lang-locale.js';
+import { DateRangePopover } from './date-range/DateRangePopover.js';
+import { DateRangeSheet } from './date-range/DateRangeSheet.js';
+import { useRangePopup } from './date-range/use-range-popup.js';
+import { useMediaQuery } from './use-media-query.js';
+/** Sets a forwarded ref, callback or object, to the same node. */
+function setForwardedRef(ref, node) {
+    if (typeof ref === 'function')
+        ref(node);
+    else if (ref)
+        ref.current = node;
+}
+/**
+ * A button showing a range of days that opens a calendar to pick a first
+ * and a last day: from `md` up a popover with the presets and two months,
+ * below it a bottom sheet with one month. Apply gives the range; Cancel,
+ * Escape and a press outside keep the value. The ref reaches the `<button>`.
+ */
+export const DateRangeButton = forwardRef(function DateRangeButton({ label, value, onChange, presets = [], min, max, maxDays, today, disabled = false, id, locale, weekStartsOn = 0, labels, size = 'md', variant = 'neutral', }, ref) {
+    assertDateRangeInput({
+        label,
+        value,
+        presets,
+        min,
+        max,
+        maxDays,
+        today,
+        weekStartsOn,
+    });
+    const words = resolveDateRangeButtonLabels(labels);
+    const popup = useRangePopup(value, disabled, onChange);
+    const resolvedLocale = useLangLocale(locale, popup.buttonRef);
+    const wide = useMediaQuery(breakpointQuery('from', 'md'), true);
+    const { buttonRef } = popup;
+    const setButton = useCallback((node) => {
+        buttonRef.current = node;
+        setForwardedRef(ref, node);
+    }, [buttonRef, ref]);
+    const { range } = popup.draft;
+    const shown = formatRangeShort(value, resolvedLocale);
+    const Panel = wide ? DateRangePopover : DateRangeSheet;
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { "aria-controls": popup.shown ? popup.id : undefined, "aria-expanded": popup.shown, "aria-haspopup": "dialog", className: "sw-date-range-button", disabled: disabled, id: id, onPress: popup.toggle, ref: setButton, size: size, variant: variant, children: [_jsx("span", { className: "sw-sr-only", children: `${label}${words.nameSeparator}${shown}` }), _jsx(DateFieldGlyph, { name: "calendar" }), _jsx("span", { "aria-hidden": "true", children: shown })] }), popup.shown ? (_jsx(Panel, { buttonRef: buttonRef, count: words.dayCount(rangeDayCount(range)), draft: popup.draft, id: popup.id, label: label, labels: words, latest: latestPick(popup.draft, max, maxDays), line: formatRangeLong(range, resolvedLocale), locale: resolvedLocale, max: max, min: min, onApply: () => popup.apply(range), onCancel: popup.cancel, onChoosePreset: (preset) => popup.apply(preset.range), onPress: popup.press, presets: presets, pressedPresetId: presets.find((preset) => sameRange(preset.range, range))?.id, today: today ?? todayDateOnly(), weekStartsOn: weekStartsOn })) : null] }));
+});

package/dist/components/ListGroup.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from 'react';
+import { type ListGroupMaxHeight, type ListGroupVariant } from '../list-options.js';
+export type ListGroupProps = {
+    /** `ListRow` elements; the group draws a hairline between each pair. */
+    children: ReactNode;
+    /** Names the list, such as its card's heading. Required with `maxHeight`. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /**
+     * `panel` (the default) is one bordered panel; `plain` draws no panel
+     * and a hairline above the first row too, for rows inside a Card.
+     */
+    variant?: ListGroupVariant;
+    /**
+     * Bounds the list to a row count of its own region, `{ rows }` rows of a
+     * title and one detail line, where the rest scroll; the region is a named
+     * keyboard stop and shades an edge with more rows past it.
+     */
+    maxHeight?: ListGroupMaxHeight;
+    /**
+     * Pinned under the rows, outside the scroll, under a hairline: a total
+     * the rows add up to, such as a `ListRow` with the count and the sum.
+     */
+    footer?: ReactNode;
+    className?: string;
+    id?: string;
+};
+/**
+ * Rows in one list (`ul`, its list role kept) with hairlines between them:
+ * a panel of its own, or plain rows inside a surface. The ref reaches the
+ * outer box.
+ */
+export declare const ListGroup: import("react").ForwardRefExoticComponent<ListGroupProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ListGroup.js

@@ -0,0 +1,19 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from '../class-names.js';
+import { assertListGroup, listMaxHeightStyle, } from '../list-options.js';
+import { ListRowContainer } from './list/list-row-container.js';
+import { ScrollRegion } from './ScrollRegion.js';
+/**
+ * Rows in one list (`ul`, its list role kept) with hairlines between them:
+ * a panel of its own, or plain rows inside a surface. The ref reaches the
+ * outer box.
+ */
+export const ListGroup = forwardRef(function ListGroup({ children, 'aria-label': label, 'aria-labelledby': labelledBy, variant = 'panel', maxHeight, footer, className, id, }, ref) {
+    assertListGroup({ label, labelledBy, variant, maxHeight });
+    const list = (_jsx("ul", { "aria-label": label, "aria-labelledby": labelledBy, className: "sw-list", 
+        // A list styled without bullets loses its role in Safari.
+        role: "list", children: _jsx(ListRowContainer.Provider, { value: "li", children: children }) }));
+    return (_jsxs("div", { className: cx('sw-list-group', `sw-list-group-${variant}`, className), id: id, ref: ref, children: [maxHeight === undefined ? (list) : (_jsx(ScrollRegion, { "aria-label": label, "aria-labelledby": labelledBy, className: "sw-list-group-scroll", style: listMaxHeightStyle(maxHeight), children: list })), footer === undefined ? null : (_jsx("div", { className: "sw-list-group-footer", children: _jsx(ListRowContainer.Provider, { value: "div", children: footer }) }))] }));
+});

package/dist/components/ListRow.d.ts

@@ -0,0 +1,51 @@
+import { type ReactNode } from 'react';
+import { type ListRowTitleAppearance, type ListRowTone, type ListRowValueTone } from '../list-options.js';
+export type ListRowProps = {
+    title: string;
+    /** A muted line under the title. */
+    detail?: string;
+    /** A figure or word at the row's end, such as "+$1.48". */
+    value?: string;
+    /** A muted line under the value, such as "checks $3,427". */
+    valueDetail?: string;
+    /** Colours the value only, as a table cell's tone; the words say why. */
+    valueTone?: ListRowValueTone;
+    /**
+     * A consumer mark at the row's start, such as a status dot or a Lucide
+     * glyph (ADR 0008). It is hidden from assistive technology, so the words
+     * must say what it means.
+     */
+    leading?: ReactNode;
+    /**
+     * Makes the whole row a button (or, with `href`, a link's plain press
+     * for a client router) and adds the chevron.
+     */
+    onPress?: () => void;
+    /** Makes the whole row a link to `href`, with the chevron. */
+    href?: string;
+    /**
+     * Makes the row a choice: a check while true, nothing while false, and
+     * the state (`aria-pressed` on a button, `aria-current` on a link). Only
+     * on a row with `onPress` or `href`.
+     */
+    selected?: boolean;
+    /** Dims the row and blocks presses; a link row drops its `href`. */
+    disabled?: boolean;
+    /** `danger` draws the title in the danger colour, for a row that ends something. */
+    tone?: ListRowTone;
+    /** `plain` sets the title at the body weight, for a list of plain statements. */
+    titleAppearance?: ListRowTitleAppearance;
+    /** `none` hides the chevron of a pressable row that acts in place. */
+    accessory?: 'chevron' | 'none';
+    /**
+     * Replaces a pressable row's name, which is its title and value; its
+     * detail lines are its description.
+     */
+    'aria-label'?: string;
+};
+/**
+ * One row of a `ListGroup`: it opens something (`onPress` or `href`, with
+ * a chevron, the whole row pressing), picks one option in place
+ * (`selected`), or only states something (neither).
+ */
+export declare function ListRow({ title, detail, value, valueDetail, valueTone, leading, onPress, href, selected, disabled, tone, titleAppearance, accessory, 'aria-label': ariaLabel, }: ListRowProps): import("react").JSX.Element;

package/dist/components/ListRow.js

@@ -0,0 +1,59 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useId } from 'react';
+import { cx } from '../class-names.js';
+import { assertListRow, listRowAccessory, } from '../list-options.js';
+import { tabStop } from '../tab-stop.js';
+import { plainPress } from './link-press.js';
+import { ListRowContent } from './list/ListRowContent.js';
+import { ListRowContainer } from './list/list-row-container.js';
+function ids(...parts) {
+    const joined = parts.filter(Boolean).join(' ');
+    return joined === '' ? undefined : joined;
+}
+/**
+ * One row of a `ListGroup`: it opens something (`onPress` or `href`, with
+ * a chevron, the whole row pressing), picks one option in place
+ * (`selected`), or only states something (neither).
+ */
+export function ListRow({ title, detail, value, valueDetail, valueTone, leading, onPress, href, selected, disabled = false, tone = 'default', titleAppearance = 'strong', accessory = 'chevron', 'aria-label': ariaLabel, }) {
+    const pressable = onPress !== undefined || href !== undefined;
+    assertListRow({
+        title,
+        tone,
+        titleAppearance,
+        valueTone,
+        accessory,
+        value,
+        valueDetail,
+        selected,
+        pressable,
+    });
+    const container = useContext(ListRowContainer);
+    const id = useId();
+    const kind = listRowAccessory({ pressable, selected, accessory });
+    const content = (_jsx(ListRowContent, { accessory: kind, detail: detail, id: id, leading: leading, title: title, titleAppearance: titleAppearance, tone: tone, value: value, valueDetail: valueDetail, valueTone: valueTone }));
+    const className = cx('sw-list-row', pressable && 'sw-list-row-pressable', disabled && 'sw-list-row-disabled');
+    const naming = {
+        'aria-label': ariaLabel,
+        'aria-labelledby': ariaLabel
+            ? undefined
+            : ids(`${id}-title`, value !== undefined && `${id}-value`),
+        'aria-describedby': ids(Boolean(detail) && `${id}-detail`, Boolean(valueDetail) && `${id}-value-detail`),
+    };
+    let row;
+    if (href !== undefined)
+        row = (_jsx("a", { ...naming, "aria-current": selected ? 'true' : undefined, "aria-disabled": disabled || undefined, className: className, href: disabled ? undefined : href, onClick: onPress && !disabled
+                ? (event) => {
+                    if (!plainPress(event))
+                        return;
+                    event.preventDefault();
+                    onPress();
+                }
+                : undefined, role: disabled ? 'link' : undefined, tabIndex: disabled ? undefined : tabStop, children: content }));
+    else if (onPress !== undefined)
+        row = (_jsx("button", { ...naming, "aria-pressed": selected, className: className, disabled: disabled, onClick: onPress, tabIndex: tabStop, type: "button", children: content }));
+    else
+        row = (_jsx("div", { "aria-label": ariaLabel, className: className, role: ariaLabel ? 'group' : undefined, children: content }));
+    return container === 'li' ? (_jsx("li", { className: "sw-list-item", children: row })) : (_jsx("div", { className: "sw-list-item", children: row }));
+}

package/dist/components/NavCount.d.ts

@@ -0,0 +1,21 @@
+export type NavCountProps = {
+    /**
+     * How many things wait behind the destination, such as tasks to do: a
+     * filled pill after its words, read in the link's name ("Tasks 8"). A
+     * whole number; 0 shows nothing.
+     */
+    count: number;
+    /**
+     * What the count means, in the consumer's words ("8 tasks to do"): read
+     * in the name in place of the bare number ("Tasks 8 tasks to do"), the
+     * pill then hidden from assistive technology.
+     */
+    countLabel?: string;
+};
+/**
+ * A count after a Nav destination's words, placed inside its link or
+ * Button: `<a href="/tasks">Tasks<NavCount count={8} /></a>`. It is the
+ * pill SectionNav's item count draws, and it is part of the destination's
+ * accessible name, as there.
+ */
+export declare function NavCount({ count, countLabel }: NavCountProps): import("react").JSX.Element | null;

package/dist/components/NavCount.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/** Fails closed on a count that is not a whole number or an empty label. */
+function assertNavCount({ count, countLabel }) {
+    if (!Number.isInteger(count) || count < 0)
+        throw new RangeError(`NavCount count must be a whole number from 0: ${String(count)}`);
+    if (countLabel !== undefined &&
+        (typeof countLabel !== 'string' || !countLabel.trim()))
+        throw new RangeError('NavCount countLabel must be non-empty text');
+}
+/**
+ * A count after a Nav destination's words, placed inside its link or
+ * Button: `<a href="/tasks">Tasks<NavCount count={8} /></a>`. It is the
+ * pill SectionNav's item count draws, and it is part of the destination's
+ * accessible name, as there.
+ */
+export function NavCount({ count, countLabel }) {
+    assertNavCount({ count, countLabel });
+    if (count === 0)
+        return null;
+    // The space is its own text node, so every browser and the name's
+    // computation keep it between the words and the count.
+    return (_jsxs(_Fragment, { children: [' ', countLabel ? _jsx("span", { className: "sw-sr-only", children: countLabel }) : null, _jsx("span", { "aria-hidden": countLabel ? true : undefined, className: "sw-nav-count", children: count })] }));
+}

package/dist/components/SectionNav.js

@@ -4,15 +4,8 @@ import { breakpoints } from '../css/breakpoints.js';
 import { sectionNavVerticalClass } from '../css/css-section-nav.js';
 import { assertSectionNavAppearance, } from '../css/css-section-nav-filled.js';
 import { tabStop } from '../tab-stop.js';
+import { plainPress } from './link-press.js';
 export { sectionNavAppearances } from '../css/css-section-nav-filled.js';
-function plainPress(event) {
-    return (event.button === 0 &&
-        !event.defaultPrevented &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        !event.altKey);
-}
 function ariaCurrent(current) {
     if (current === true)
         return 'true';

package/dist/components/StatTile.d.ts

@@ -1,7 +1,7 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
-import { type StatTileTone, statTileTones } from '../css/css-stat-tile.js';
-export type { StatTileTone };
-export { statTileTones };
+import { type StatTileAppearance, statTileAppearances, type StatTileTone, statTileTones } from '../css/css-stat-tile.js';
+export type { StatTileAppearance, StatTileTone };
+export { statTileAppearances, statTileTones };
 export type StatTileEmphasis = 'default' | 'primary';
 export type StatTileProps = Omit<HTMLAttributes<HTMLElement>, 'children'> & {
     /** A short name for the figure, set in the label variant. */
@@ -16,10 +16,17 @@ export type StatTileProps = Omit<HTMLAttributes<HTMLElement>, 'children'> & {
     caption?: ReactNode;
     /** `primary` fills the tile in the accent for the one figure a page leads with. */
     emphasis?: StatTileEmphasis;
+    /**
+     * `plain` drops the tile's surface, edge and padding, so the figure sits
+     * inside a card that already has them, such as four answers in a row
+     * with hairlines between them. A plain tile cannot be `primary`, which
+     * is a fill. Default `card`.
+     */
+    appearance?: StatTileAppearance;
 };
 /**
  * One prominent figure with its label: the tiles a report or a list opens
  * with. Presentation only; the consumer formats the number and picks the
  * glyph.
  */
-export declare function StatTile({ caption, className, emphasis, glyph, label, tone, value, ...rest }: StatTileProps): import("react").JSX.Element;
+export declare function StatTile({ appearance, caption, className, emphasis, glyph, label, tone, value, ...rest }: StatTileProps): import("react").JSX.Element;

package/dist/components/StatTile.js

@@ -1,14 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
-import { statTileTones } from '../css/css-stat-tile.js';
+import { statTileAppearances, statTileTones, } from '../css/css-stat-tile.js';
 import { Text } from './Text.js';
-export { statTileTones };
+export { statTileAppearances, statTileTones };
+function assertStatTile(appearance, emphasis) {
+    if (!statTileAppearances.includes(appearance))
+        throw new RangeError(`Unknown StatTile appearance: ${String(appearance)}`);
+    if (appearance === 'plain' && emphasis === 'primary')
+        throw new RangeError('A plain StatTile has no surface to fill; emphasis primary needs appearance card');
+}
 /**
  * One prominent figure with its label: the tiles a report or a list opens
  * with. Presentation only; the consumer formats the number and picks the
  * glyph.
  */
-export function StatTile({ caption, className, emphasis = 'default', glyph, label, tone = 'default', value, ...rest }) {
+export function StatTile({ appearance = 'card', caption, className, emphasis = 'default', glyph, label, tone = 'default', value, ...rest }) {
+    assertStatTile(appearance, emphasis);
     const primary = emphasis === 'primary';
-    return (_jsxs("section", { className: cx('sw-stat-tile', primary && 'sw-stat-tile-primary', className), ...rest, children: [glyph ? (_jsx("span", { "aria-hidden": "true", className: "sw-stat-tile-glyph", children: glyph })) : null, _jsxs("span", { className: "sw-stat-tile-body", children: [_jsx(Text, { as: "span", className: "sw-stat-tile-label", color: primary ? 'onAccent' : 'muted', variant: "label", children: label }), _jsx(Text, { as: "strong", className: "sw-stat-tile-value", color: primary ? 'onAccent' : tone === 'default' ? 'text' : tone, variant: "heading", children: value }), caption ? (_jsx(Text, { as: "span", className: "sw-stat-tile-caption", color: primary ? 'onAccent' : 'muted', variant: "caption", children: caption })) : null] })] }));
+    return (_jsxs("section", { className: cx('sw-stat-tile', appearance === 'plain' && 'sw-stat-tile-plain', primary && 'sw-stat-tile-primary', className), ...rest, children: [glyph ? (_jsx("span", { "aria-hidden": "true", className: "sw-stat-tile-glyph", children: glyph })) : null, _jsxs("span", { className: "sw-stat-tile-body", children: [_jsx(Text, { as: "span", className: "sw-stat-tile-label", color: primary ? 'onAccent' : 'muted', variant: "label", children: label }), _jsx(Text, { as: "strong", className: "sw-stat-tile-value", color: primary ? 'onAccent' : tone === 'default' ? 'text' : tone, variant: "heading", children: value }), caption ? (_jsx(Text, { as: "span", className: "sw-stat-tile-caption", color: primary ? 'onAccent' : 'muted', variant: "caption", children: caption })) : null] })] }));
 }