@scalewing/react 1.42.0 → 1.44.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @scalewing/react
 
+## 1.44.0
+
+### Minor Changes
+
+- 2af39a5: `ActionMenu` `triggerAppearance="icon"`: the consumer's `trigger` glyph alone in a round quiet button as wide as it is tall (the sm control height, 44 px on a coarse pointer), muted with no fill, outline or chevron, the text colour on the quiet fill on hover and while open; named by `label`, for a row's own ••• menu. An icon trigger without a glyph throws a `RangeError`. New class `sw-action-menu-trigger-icon`; `actionMenuTriggerAppearances` gains `icon`. No new tokens, no new dependency. Request: `docs/requests/teisoro-action-menu-icon-trigger.md`.
+- 38a1715: `DescriptionList` `layout`: `columns` (the default, unchanged) or `spread`, each row's term at its start and its detail at its end, end-aligned, side by side at every width, for a short box of facts. New class `sw-description-list-spread`, new exports `descriptionListLayouts` and `DescriptionListLayout`; an unknown layout throws a `RangeError`. No new tokens, no new dependency. Request: `docs/requests/teisoro-description-list-spread.md`.
+- f426251: `FileField` `value.preview`: the address of a small image of a chosen photo, such as an object URL the consumer made from the `File`, drawn as a decorative 3:2 thumbnail (a space-8 by a space-6, cropped to fill, at the small radius) before the file's name in place of `icon`. A blank preview throws a `RangeError`. New class `sw-file-field-preview`. No new tokens, no new dependency. Request: `docs/requests/teisoro-file-field-preview.md`.
+- 76ae2b4: `FilterChips` option `tone`: `neutral` (the default, unchanged) or `warning`, which draws that chip, while it is not chosen, in the warning tint with its words and count in the warning ink (a warning `Notice`'s, 4.5:1 in every palette and scheme); chosen it is the accent and at a zero count quiet, like every chip. New class `sw-filter-chip-warning`, new exports `filterChipTones` and `FilterChipTone`; an unknown tone throws a `RangeError`. No new tokens, no new dependency. Request: `docs/requests/teisoro-filter-chip-tone.md`.
+- 49f90af: `FilterChipsRow`: several `FilterChips` groups on one row, each keeping its own name, choices and Tab stops, an optional `end` group at the row's end (at its own line's end when the row wraps), and `overflow` `wrap` (the default) or `scroll`, where every group's chips stay on one row that scrolls sideways together inside the row's own box, never the page, a group's own scroll giving way. New classes `sw-filter-chips-row`, `sw-filter-chips-row-end`, `sw-filter-chips-row-scroll`; new exports `FilterChipsRow` and `FilterChipsRowProps`; an unknown overflow throws a `RangeError`. The private slot check `hasSlot` moved from the list rows to `components/slot.ts`, shared by both. No new tokens, no new dependency. Request: `docs/requests/teisoro-filter-chips-row.md`.
+- a6c790c: `ListRow` `truncate`: opt-in, keeps the title and the detail line to one line each, cut with "…" where they do not fit; the unread dot follows the cut words, the whole words stay in the row's name, description and a `title` tooltip, and the value, tag and action keep their words whole. New classes `sw-list-row-truncate` and `sw-list-row-title-text`. Rows without it are unchanged. No new tokens, no new dependency. Request: `docs/requests/teisoro-list-row-truncate.md`.
+- d4647b8: `sw-container-reading`: a utility class that centres a column at the reading width (`--sw-reading-max`, 46rem, `Article`'s), as `sw-container` does at the container width, and full width below it; for a form or text that reads better narrower than the page. No new tokens, no new dependency. Request: `docs/requests/teisoro-container-reading.md`.
+- 7da3f25: `sw-font-mono`: a utility class that sets an element, or a native text control such as a `Field`'s `textarea`, in the platform's monospace face (`ui-monospace, monospace`, the generic CSS names only, so no face is chosen) at the size it already has, outranking the canvas's text control rules. For words read as typed code or marks, such as a Markdown source being written. No new tokens, no new dependency. Request: `docs/requests/teisoro-font-mono.md`.
+
+### Patch Changes
+
+- 68be1ea: `ListRow` `truncate`: the one-line rule for the title's words box (`sw-list-row-title-text`) is scoped to truncated rows (`.sw-list-row-truncate .sw-list-row-title-text`), as the detail's already was; a truncated row looks the same.
+
+## 1.43.0
+
+Not published: its release validation failed before publication (a gallery test timed out, fixed in #211). Its changes ship in 1.44.0, listed there.
+
 ## 1.42.0
 
 ### Minor Changes

package/README.md

@@ -144,6 +144,8 @@ A disabled native text control (`<input>`, `<select>` or `<textarea>` on the can
 
 `FileField` is one file chosen with the system picker or dropped on the field, with `Field`'s `label` (above it, or hidden with `labelVisuallyHidden`), `description` and `error` (a polite live region in place of the hint, the frame's edge in the danger color, `Mark` in forced colors). Empty, it is one wide zone on the subtle fill, a button named by the label and `chooseLabel` ("Field guide Choose a PDF"), with `dropLabel` ("or drop it here") muted after it where the pointer can drag (left out on a coarse pointer). Chosen (`value={{ name, detail? }}`), it shows the consumer's `icon` (hidden from assistive technology), the file's name over the muted `detail` and a neutral button named by the label and `changeLabel`, described by the name and detail. Either button opens the picker (the native input is hidden and out of the Tab order, its `accept` the list the picker offers); `onChange` receives the `File` chosen or dropped, the first of several, and when a choice or a drop swaps the zone and the chosen row while focus is in the field, focus moves to the button now there (focus the person moved elsewhere is never taken back). A file dragged over the field draws the accent edge and tint, its words in the text color. It never reads, checks or uploads the file, and a dropped file is not filtered by `accept`: check what you receive (type, size, its header) and say why in `error`, keeping the earlier `value` or none. `disabled` blocks the picker, refuses a dropped file and dashes the frame. `id` prefixes the ids of the field's parts. An empty `label`, `chooseLabel` or `changeLabel`, a blank `dropLabel`, or a `value` with no name or a blank detail throws a `RangeError`.
 
+A chosen photo can show itself: `value.preview` is the address of a small image of it, such as an object URL the consumer made from the `File` (and revokes when another is chosen), drawn as a 3:2 thumbnail (a space-8 wide, a space-6 tall, cropped to fill, at the small radius) before the name in place of `icon`. It is decorative (`alt=""`): the name beside it says which file it is. A blank `preview` throws a `RangeError`.
+
 ```tsx
 <FileField
   label="Field guide"
@@ -285,6 +287,8 @@ A `Button` that toggles something passes `aria-pressed`. The pressed button gets
 
 `ActionMenu` `triggerAppearance="text"` (opt-in; default `"framed"`, `actionMenuTriggerAppearances`) draws the trigger as its words (`trigger`, or `label`) in label type at medium weight in the text color, with the shared muted chevron pointing down after them and no fill or outline; the quiet grey fill shows on hover and while the menu is open. It is the sm control height (the 44 px target on a coarse pointer). Name the trigger with `label` as before, and include the words shown in it (WCAG 2.5.3, so voice control can say them): a person's name that opens their account menu takes a `label` such as "Account, Ada Okafor". The trigger's words are one flex item (mixed inline content keeps its spaces), then the chevron. Forced colors draw its border in the system's border color, the chevron in CanvasText, and an open trigger's border in Highlight. An unknown value throws a `RangeError`.
 
+`triggerAppearance="icon"` (opt-in) draws the `trigger` glyph alone in a round quiet button, as wide as it is tall (the sm control height, 44 px on a coarse pointer), in the muted colour with no fill, outline or chevron; it turns to the text colour on the quiet fill on hover and while the menu is open. Use it for a row's own ••• menu, named by `label` ("More for Heron calls"); the glyph says nothing on its own. An icon trigger without a `trigger` glyph throws a `RangeError`. Forced colors draw it in ButtonText with its kept border, Highlight while open.
+
 ```tsx
 <ActionMenu
   header={
@@ -790,6 +794,8 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 
 `DescriptionList` pairs terms with what each says, one `DescriptionItem` per row: a `dl` whose items each group a `dt` (`term`) with its `dd` (`children`). From `md` up the term sits in a start column as wide as the widest term, up to 40% of the list, and the detail beside it; every row aligns to its top, so a term and its detail's first line start level, and a hairline divides the rows, with no space above the first row or below the last. Below `md` each term sits over its detail. The list sets only the layout: pass your own `Text` for the term and the detail. Each child of a term or a detail is its own line with its own line height (a column), as wide as its content unless it sets its own width (a `Progress` fills the detail; a `Field` keeps its input's width): wrap inline content, such as words and a link on one line, in one element such as an `Inline`. Long unbreakable words wrap inside their column. A `dl` has no ARIA role, so name a list with a visible heading, and `aria-labelledby` on the `section` around it, rather than an `aria-label` on the list.
 
+`layout="spread"` (opt-in; the default is `columns`) sets each row on its own two columns at every width, for a short box of facts such as a side panel's details: the term at the row's start, as wide as its words up to half the row, and the detail at the row's end, its lines end-aligned. The hairlines, padding and top alignment are the same, and a phone keeps each term beside its detail. An unknown `layout` throws a `RangeError`; `descriptionListLayouts` lists the layouts.
+
 ```tsx
 <DescriptionList>
   <DescriptionItem
@@ -836,6 +842,8 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 
 A row can also carry three trailing parts. `unread` marks it new for the person, such as a document they have not opened: an accent dot after the title's last word (drawn as a border, so forced colors keep it in the text color), hidden from assistive technology, and `unreadLabel` (required while `unread`, such as "New") is read after the title, in a pressable row's name ("Heron calls New"). `tag` is a short status before the row's end, such as a `Badge` ("Only in English"), centred on the row and never wrapped; a pressable row is described by it after its detail lines. `action` is a control after the row and outside its press area, such as an `ActionMenu` of the row's own commands named by the consumer ("More for Heron calls"): it is the row's sibling in the list item, centred on the row, after it in the Tab order, and a press on it never opens the row; it keeps the row's end inset (a space-4 in a panel or outside a ListGroup, none in a plain list), and where `:has` is supported the hover fill spans the row and its control. An empty slot (`undefined`, `null`, `false` or `''`, as conditional JSX gives) draws nothing, for `leading` too. Pair `action` with `accessory="none"` when the row's own chevron would sit beside it. An unread row without `unreadLabel`, or a blank one, throws a `RangeError`. An `aria-label` replaces the whole name, unread words included.
 
+`truncate` (opt-in) keeps a row's title and its detail line to one line each, cut with "…" where they do not fit, for a long list read at a glance such as a shelf of documents. The title's words sit in their own box, so the unread dot follows the cut words and is never hidden; the whole words stay in the row's name and description and in a `title` tooltip on the words and the detail. The value, its detail, the tag and the action keep their words whole. A tooltip needs a pointer, so on a touch screen or from the keyboard the cut words are whole only in what the row opens and in what assistive technology reads; keep `truncate` for rows that open their whole content, or whose words a person does not need in full to choose.
+
 ```tsx
 <ListRow
   leading={
@@ -902,6 +910,10 @@ A row can also carry three trailing parts. `unread` marks it new for the person,
 
 `Text` steps `display` and `heading` down to the compact token sizes below the `md` breakpoint; consumers do not size type per viewport.
 
+`sw-container-reading` centres a column at the reading width (`--sw-reading-max`, 46rem, `Article`'s), as `sw-container` centres a page's column at the container width (72rem): `width: 100%`, the max width and auto inline margins, full width below it. Use it for a form or text that reads better narrower than the page, such as an open form of one column. As with `sw-container`, the width is the content box's, so put padding or a border on a child.
+
+`sw-font-mono` sets an element, or a native text control such as the `textarea` in a `Field`, in the platform's monospace face (`ui-monospace, monospace`, the generic names only) at the size it already has, for words read as typed code or marks, such as a Markdown source being written. It outranks the canvas's text control rules.
+
 `Text` has no margin of its own. Its default `p` and `h1`–`h4` elements drop the browser's block margins, so the `gap` of the `Stack` or `Inline` around it alone sets the spacing; put more space in that `gap`, not in a margin. The reset has zero specificity (`:where(.sw-text-*)`), so an authored margin, such as `sw-sr-only` or a consumer class, still applies.
 
 `Text` takes an optional `align` (`start`, `center`, `end`) mapped to generated `sw-text-align-*` classes, for a heading that must stay centered when it wraps.
@@ -993,6 +1005,8 @@ A strip row with `entry` makes its counts editable: each column holds a `Stepper
 
 `FilterChips` options for chips that sit above a list, all opt-in: `labelVisuallyHidden` keeps `label` as the group's name without drawing it, for chips whose words and place already say what they filter; `countAppearance="inline"` (`filterChipCountAppearances`, default `"figure"`) writes the count in the chip's own words after a middle dot ("Open · 3"), the dot hidden so the name reads "Open 3"; `overflow="scroll"` (`filterChipsOverflows`, default `"wrap"`) keeps the chips on one row that scrolls sideways inside its own box, never the page, each chip on one line, a focused chip scrolled into view and the focus ring unclipped. `multiple` turns several chips on at once, such as the days of a week: each chip is a native checkbox and its own Tab stop, `value` is a list of the chosen values (empty for none) and `onChange` receives every chosen value in the options' order. A multiple group cannot be `required` (nothing makes a checkbox group required); say what is needed in `error`. A value that is no option, a multiple `value` that is not a list, `required` with `multiple`, or an unknown count appearance or overflow throws a `RangeError`.
 
+An option's `tone` (`filterChipTones`, `FilterChipTone`; default `"neutral"`) set to `"warning"` draws that chip, while it is not chosen, in the warning tint with its words and count in the warning ink (a warning `Notice`'s fill and words, 4.5:1 in every palette and scheme), for a choice that shows what needs a look, such as documents missing a translation. Its words must say why; the tint only draws the eye. Chosen, it is the accent like every chip; with a zero count it is quiet like every chip; it keeps the chips' hairline, so an `error`'s danger edge still shows; forced colours draw it as every chip. An unknown tone throws a `RangeError`.
+
 ```tsx
 <FilterChips
   label="Nocturnal surveys"
@@ -1017,6 +1031,52 @@ A strip row with `entry` makes its counts editable: each column holds a `Stepper
     { value: 'sat', label: 'Sat' },
   ]}
 />
+
+<FilterChips
+  label="Camera traps to check"
+  labelVisuallyHidden
+  multiple
+  value={unchecked}
+  onChange={setUnchecked}
+  options={[
+    { value: 'unchecked', label: 'Not checked this week', count: 2, tone: 'warning' },
+  ]}
+/>
+```
+
+`FilterChipsRow` lays several `FilterChips` groups on one row, for filters that need more than one kind of choice, such as kinds (one choice) and a toggle that narrows them (a checkbox). Each group keeps its own name, choices and Tab stops; the row is a plain `div` that lays them out a space-2 apart, their chips level along the bottom (an error under one group lifts its chips above the others'). `end` sets a group apart at the row's end, and at its own line's end when the row wraps. `overflow` (`"wrap"` by default, or `"scroll"`) wraps the groups onto more lines, or keeps every group's chips on one row that scrolls sideways together inside the row's own box, never the page, the focus ring unclipped and a focused chip scrolled into view; inside a scrolling row a group's own `overflow` gives way, and a group is as wide as its chips, so a drawn label or an `error` wraps under them. An empty `end` draws nothing; an unknown `overflow` throws a `RangeError`.
+
+```tsx
+<FilterChipsRow
+  overflow="scroll"
+  end={
+    <FilterChips
+      label="Not translated"
+      labelVisuallyHidden
+      multiple
+      countAppearance="inline"
+      value={untranslated}
+      onChange={setUntranslated}
+      options={[
+        {
+          value: 'untranslated',
+          label: 'Not translated',
+          count: 2,
+          tone: 'warning',
+        },
+      ]}
+    />
+  }
+>
+  <FilterChips
+    label="Kinds"
+    labelVisuallyHidden
+    countAppearance="inline"
+    value={kind}
+    onChange={setKind}
+    options={kinds}
+  />
+</FilterChipsRow>
 ```
 
 `DateField` is a controlled date-only field that draws its own calendar. Supply `value`, `min`, and `max` as valid `YYYY-MM-DD` dates; use an empty `value` for a blank field. Its callback returns a date-only string or an empty string, without timezone conversion. Invalid serialized dates and inverted bounds throw; a value outside the bounds remains visible with invalid styling. `required` marks the label with the same `aria-hidden` asterisk as `Field` and sets the entry's native `required`. Its label is drawn as `Field`'s (the same label words and mark inside a `<label>` that keeps the canvas type), so its label row and its gap to the entry match a `Field` beside it. For a blank required field, supply `error` when form validation runs to show the message and invalid styling.

package/dist/components/ActionMenu.d.ts

@@ -51,8 +51,10 @@ export type ActionMenuProps = {
     /**
      * `text` draws the trigger as its words with a chevron after them, no
      * fill or outline until hovered or open, such as a person's name opening
-     * their account menu; `framed` (the default) is the small outlined
-     * control.
+     * their account menu; `icon` draws the `trigger` glyph alone in a round
+     * quiet button with no chevron, such as a row's ••• menu, named by
+     * `label` (an icon trigger needs a `trigger`); `framed` (the default) is
+     * the small outlined control.
      */
     triggerAppearance?: ActionMenuTriggerAppearance;
 };

package/dist/components/ActionMenu.js

@@ -2,8 +2,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useLayoutEffect, useRef, useState, } from 'react';
 import { cx } from '../class-names.js';
-import { actionMenuTriggerAppearances, actionMenuTriggerTextClass, } from '../css/css-action-menu-trigger.js';
+import { actionMenuTriggerAppearances, actionMenuTriggerIconClass, actionMenuTriggerTextClass, } from '../css/css-action-menu-trigger.js';
 import { ActionMenuList } from './action-menu/ActionMenuList.js';
+import { assertActionMenu } from './action-menu/assert-action-menu.js';
 import { tabStop } from '../tab-stop.js';
 export { actionMenuTriggerAppearances };
 function nextEnabled(items, current, direction) {
@@ -22,12 +23,7 @@ export function ActionMenu({ label, items, header, trigger, disabled = false, al
     const openRef = useRef(false);
     const [open, setOpen] = useState(false);
     const [focusIndex, setFocusIndex] = useState(-1);
-    if (items.some((item) => (item.detail !== undefined && !item.detail.trim()) ||
-        (item.detailLang !== undefined &&
-            (!item.detailLang.trim() || item.detail === undefined))))
-        throw new RangeError('ActionMenu item detail and detailLang must not be blank; detailLang needs a detail');
-    if (!actionMenuTriggerAppearances.includes(triggerAppearance))
-        throw new RangeError(`Unknown ActionMenu triggerAppearance: ${String(triggerAppearance)}`);
+    assertActionMenu({ items, trigger, triggerAppearance });
     const enabled = !disabled && items.some((item) => !item.disabled);
     useLayoutEffect(() => {
         if (!enabled && open)
@@ -94,5 +90,5 @@ export function ActionMenu({ label, items, header, trigger, disabled = false, al
         close(true);
         item.onSelect();
     }
-    return (_jsxs("div", { className: "sw-action-menu", children: [_jsx("button", { "aria-controls": open ? menuId : undefined, "aria-expanded": open, "aria-haspopup": "menu", "aria-label": label, className: cx('sw-action-menu-trigger', triggerAppearance === 'text' && actionMenuTriggerTextClass), disabled: !enabled, onClick: () => (open ? close(true) : openMenu()), onKeyDown: onTriggerKeyDown, ref: triggerRef, tabIndex: tabStop, type: "button", children: triggerAppearance === 'text' ? (_jsx("span", { children: trigger ?? label })) : ((trigger ?? label)) }), open ? (_jsx(ActionMenuList, { align: align, focusIndex: focusIndex, header: header, id: menuId, items: items, label: label, onDismiss: () => close(), onFocusIndex: setFocusIndex, onKeyDown: onMenuKeyDown, onSelect: select, triggerRef: triggerRef })) : null] }));
+    return (_jsxs("div", { className: "sw-action-menu", children: [_jsx("button", { "aria-controls": open ? menuId : undefined, "aria-expanded": open, "aria-haspopup": "menu", "aria-label": label, className: cx('sw-action-menu-trigger', triggerAppearance === 'text' && actionMenuTriggerTextClass, triggerAppearance === 'icon' && actionMenuTriggerIconClass), disabled: !enabled, onClick: () => (open ? close(true) : openMenu()), onKeyDown: onTriggerKeyDown, ref: triggerRef, tabIndex: tabStop, type: "button", children: triggerAppearance === 'text' ? (_jsx("span", { children: trigger ?? label })) : ((trigger ?? label)) }), open ? (_jsx(ActionMenuList, { align: align, focusIndex: focusIndex, header: header, id: menuId, items: items, label: label, onDismiss: () => close(), onFocusIndex: setFocusIndex, onKeyDown: onMenuKeyDown, onSelect: select, triggerRef: triggerRef })) : null] }));
 }

package/dist/components/DescriptionList.d.ts

@@ -1,15 +1,25 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+import { type DescriptionListLayout } from './description-list-layout.js';
+export { descriptionListLayouts, type DescriptionListLayout, } from './description-list-layout.js';
 export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'children'> & {
     /** The list's `DescriptionItem`s. */
     children: ReactNode;
+    /**
+     * `columns` (the default): the terms in a start column and the details
+     * beside them, each term over its detail below `md`. `spread`: each
+     * row's term at its start and its detail at its end, end-aligned, side
+     * by side at every width, for a short box of facts.
+     */
+    layout?: DescriptionListLayout;
 };
 /**
  * Terms and what each one says, one item per row: the term in a start
  * column as wide as the widest term (up to 40% of the list), the detail
  * beside it, a hairline between rows, every row aligned to its top. Below
- * the layout breakpoint (`md`) each term sits over its detail.
+ * the layout breakpoint (`md`) each term sits over its detail. `spread`
+ * sets each detail at its row's end instead, beside its term at every width.
  */
-export declare function DescriptionList({ children, className, ...rest }: DescriptionListProps): import("react").JSX.Element;
+export declare function DescriptionList({ children, className, layout, ...rest }: DescriptionListProps): import("react").JSX.Element;
 export type DescriptionItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
     /**
      * What the row describes, such as a name; the consumer's own `Text`. Each

package/dist/components/DescriptionList.js

@@ -1,13 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
+import { assertDescriptionListLayout, } from './description-list-layout.js';
+export { descriptionListLayouts, } from './description-list-layout.js';
 /**
  * Terms and what each one says, one item per row: the term in a start
  * column as wide as the widest term (up to 40% of the list), the detail
  * beside it, a hairline between rows, every row aligned to its top. Below
- * the layout breakpoint (`md`) each term sits over its detail.
+ * the layout breakpoint (`md`) each term sits over its detail. `spread`
+ * sets each detail at its row's end instead, beside its term at every width.
  */
-export function DescriptionList({ children, className, ...rest }) {
-    return (_jsx("dl", { className: cx('sw-description-list', className), ...rest, children: children }));
+export function DescriptionList({ children, className, layout = 'columns', ...rest }) {
+    assertDescriptionListLayout(layout);
+    return (_jsx("dl", { className: cx('sw-description-list', layout === 'spread' && 'sw-description-list-spread', className), ...rest, children: children }));
 }
 /** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
 export function DescriptionItem({ term, children, className, ...rest }) {

package/dist/components/FileField.d.ts

@@ -4,6 +4,13 @@ export type FileFieldValue = {
     name: string;
     /** A muted line under the name, such as "4 pages · 1.6 MB". */
     detail?: string;
+    /**
+     * The address of a small image of a chosen photo, such as an object URL
+     * the consumer made from the `File` (and revokes): drawn as a thumbnail
+     * before the name in place of `icon`, hidden from assistive technology,
+     * so the name says which file it is.
+     */
+    preview?: string;
 };
 export type FileFieldProps = {
     /** The field's label, drawn above it as Field's, and part of its button's name. */
@@ -29,7 +36,10 @@ export type FileFieldProps = {
     changeLabel: string;
     /** Muted words after `chooseLabel` for a fine pointer, such as "or drop it here". */
     dropLabel?: string;
-    /** A consumer mark before the chosen file's name (Lucide), hidden from assistive technology. */
+    /**
+     * A consumer mark before the chosen file's name (Lucide), hidden from
+     * assistive technology; not drawn when `value.preview` is set.
+     */
     icon?: ReactNode;
     disabled?: boolean;
     /** Prefixes the ids the field gives its parts (its button is `${id}-button`). */
@@ -37,8 +47,9 @@ export type FileFieldProps = {
 };
 /**
  * One file chosen by a press or dropped on the field: empty, a wide zone
- * that opens the system picker; chosen, the file's name and detail with a
- * button to choose another. It hands the `File` to the consumer and shows
- * what the consumer passes back as `value`; it never reads or uploads it.
+ * that opens the system picker; chosen, the file's name and detail (after
+ * a thumbnail for a photo with a `preview`) with a button to choose
+ * another. It hands the `File` to the consumer and shows what the
+ * consumer passes back as `value`; it never reads or uploads it.
  */
 export declare function FileField({ label, labelVisuallyHidden, description, error, accept, value, onChange, chooseLabel, changeLabel, dropLabel, icon, disabled, id, }: FileFieldProps): import("react").JSX.Element;

package/dist/components/FileField.js

@@ -17,11 +17,20 @@ function hasMark(icon) {
         icon !== '' &&
         typeof icon !== 'boolean');
 }
+/** Before a chosen file's name: its photo's thumbnail, else the consumer's mark. */
+function ChosenMark({ icon, preview }) {
+    if (preview !== undefined)
+        return _jsx("img", { alt: "", className: "sw-file-field-preview", src: preview });
+    if (!hasMark(icon))
+        return null;
+    return (_jsx("span", { "aria-hidden": "true", className: "sw-file-field-icon", children: icon }));
+}
 /**
  * One file chosen by a press or dropped on the field: empty, a wide zone
- * that opens the system picker; chosen, the file's name and detail with a
- * button to choose another. It hands the `File` to the consumer and shows
- * what the consumer passes back as `value`; it never reads or uploads it.
+ * that opens the system picker; chosen, the file's name and detail (after
+ * a thumbnail for a photo with a `preview`) with a button to choose
+ * another. It hands the `File` to the consumer and shows what the
+ * consumer passes back as `value`; it never reads or uploads it.
  */
 export function FileField({ label, labelVisuallyHidden = false, description, error, accept, value = null, onChange, chooseLabel, changeLabel, dropLabel, icon, disabled = false, id, }) {
     assertFileField({ label, chooseLabel, changeLabel, dropLabel, value });
@@ -62,5 +71,5 @@ export function FileField({ label, labelVisuallyHidden = false, description, err
         id: ids.button,
     };
     const open = () => inputRef.current?.click();
-    return (_jsxs(Stack, { className: cx('sw-field', 'sw-file-field', error && 'sw-field-invalid'), gap: labelVisuallyHidden ? 0 : 1, children: [_jsx("span", { id: ids.label, children: _jsx(FieldLabelText, { label: label, visuallyHidden: labelVisuallyHidden }) }), _jsxs("div", { className: cx('sw-file-field-frame', chosen ? 'sw-file-field-chosen' : 'sw-file-field-empty', drop.dragging && 'sw-file-field-dragging', disabled && 'sw-file-field-disabled'), ...drop.handlers, ...focusHandlers, children: [_jsx("input", { accept: accept, "aria-label": label, disabled: disabled, hidden: true, onChange: onInput, ref: inputRef, tabIndex: -1, type: "file" }), chosen ? (_jsxs(_Fragment, { children: [!hasMark(icon) ? null : (_jsx("span", { "aria-hidden": "true", className: "sw-file-field-icon", children: icon })), _jsxs("span", { className: "sw-file-field-file", children: [_jsx("span", { className: "sw-file-field-name", id: ids.name, children: value.name }), value.detail ? (_jsx("span", { className: "sw-file-field-detail", id: ids.detail, children: value.detail })) : null] }), _jsx(Button, { ...naming, disabled: disabled, disabledAppearance: "neutral", onPress: open, ref: buttonRef, variant: "neutral", children: changeLabel })] })) : (_jsxs("button", { ...naming, className: "sw-file-field-zone", disabled: disabled, onClick: open, ref: buttonRef, tabIndex: tabStop, type: "button", children: [_jsx("span", { className: "sw-file-field-choose", children: chooseLabel }), dropLabel ? ' ' : null, dropLabel ? (_jsx("span", { className: "sw-file-field-drop", children: dropLabel })) : null] }))] }), description && !error ? (_jsx("span", { className: "sw-field-description", id: ids.hint, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: ids.error, message: error })] }));
+    return (_jsxs(Stack, { className: cx('sw-field', 'sw-file-field', error && 'sw-field-invalid'), gap: labelVisuallyHidden ? 0 : 1, children: [_jsx("span", { id: ids.label, children: _jsx(FieldLabelText, { label: label, visuallyHidden: labelVisuallyHidden }) }), _jsxs("div", { className: cx('sw-file-field-frame', chosen ? 'sw-file-field-chosen' : 'sw-file-field-empty', drop.dragging && 'sw-file-field-dragging', disabled && 'sw-file-field-disabled'), ...drop.handlers, ...focusHandlers, children: [_jsx("input", { accept: accept, "aria-label": label, disabled: disabled, hidden: true, onChange: onInput, ref: inputRef, tabIndex: -1, type: "file" }), chosen ? (_jsxs(_Fragment, { children: [_jsx(ChosenMark, { icon: icon, preview: value.preview }), _jsxs("span", { className: "sw-file-field-file", children: [_jsx("span", { className: "sw-file-field-name", id: ids.name, children: value.name }), value.detail ? (_jsx("span", { className: "sw-file-field-detail", id: ids.detail, children: value.detail })) : null] }), _jsx(Button, { ...naming, disabled: disabled, disabledAppearance: "neutral", onPress: open, ref: buttonRef, variant: "neutral", children: changeLabel })] })) : (_jsxs("button", { ...naming, className: "sw-file-field-zone", disabled: disabled, onClick: open, ref: buttonRef, tabIndex: tabStop, type: "button", children: [_jsx("span", { className: "sw-file-field-choose", children: chooseLabel }), dropLabel ? ' ' : null, dropLabel ? (_jsx("span", { className: "sw-file-field-drop", children: dropLabel })) : null] }))] }), description && !error ? (_jsx("span", { className: "sw-field-description", id: ids.hint, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: ids.error, message: error })] }));
 }

package/dist/components/FilterChips.d.ts

@@ -1,5 +1,5 @@
 import { type FilterChipsProps } from './filter-chips/options.js';
-export { filterChipCountAppearances, filterChipsOverflows, type FilterChipCountAppearance, type FilterChipOption, type FilterChipsOverflow, type FilterChipsProps, } from './filter-chips/options.js';
+export { filterChipCountAppearances, filterChipsOverflows, filterChipTones, type FilterChipCountAppearance, type FilterChipOption, type FilterChipsOverflow, type FilterChipsProps, type FilterChipTone, } from './filter-chips/options.js';
 /**
  * A labelled row of chips: one choice (radios), or several at once
  * (`multiple`, checkboxes), each chip optionally counted.

package/dist/components/FilterChips.js

@@ -7,7 +7,7 @@ import { FieldErrorRegion } from './FieldErrorRegion.js';
 import { showsRequiredMark } from './FieldLabelText.js';
 import { FilterChip } from './filter-chips/FilterChip.js';
 import { assertFilterChips } from './filter-chips/validate.js';
-export { filterChipCountAppearances, filterChipsOverflows, } from './filter-chips/options.js';
+export { filterChipCountAppearances, filterChipsOverflows, filterChipTones, } from './filter-chips/options.js';
 /** The values a change leaves on, in the options' order. */
 function toggled(options, chosen, value, checked) {
     return options

package/dist/components/FilterChipsRow.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import { type FilterChipsOverflow } from './filter-chips/options.js';
+export type FilterChipsRowProps = {
+    /** The row's chip groups, each a `FilterChips` with its own name. */
+    children: ReactNode;
+    /**
+     * A group set apart at the row's end, such as one toggle of another kind
+     * after the filters ("Missing a translation"); on its own line's end when
+     * the row wraps.
+     */
+    end?: ReactNode;
+    /**
+     * `wrap` (the default): the groups wrap onto more lines. `scroll`: every
+     * group's chips stay on one row that scrolls sideways together inside
+     * the row's own box, never the page; a group's own `overflow` gives way.
+     */
+    overflow?: FilterChipsOverflow;
+};
+/**
+ * Several chip groups on one row: the groups keep their own names and
+ * choices (a radio group and a checkbox, say), and the row lays them out
+ * together, wrapping or scrolling as one, with an optional group at its end.
+ */
+export declare function FilterChipsRow({ children, end, overflow, }: FilterChipsRowProps): import("react").JSX.Element;

package/dist/components/FilterChipsRow.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
+import { hasSlot } from './slot.js';
+import { filterChipsOverflows, } from './filter-chips/options.js';
+/**
+ * Several chip groups on one row: the groups keep their own names and
+ * choices (a radio group and a checkbox, say), and the row lays them out
+ * together, wrapping or scrolling as one, with an optional group at its end.
+ */
+export function FilterChipsRow({ children, end, overflow = 'wrap', }) {
+    if (!filterChipsOverflows.includes(overflow))
+        throw new RangeError(`Unknown FilterChipsRow overflow: ${String(overflow)}`);
+    return (_jsxs("div", { className: cx('sw-filter-chips-row', overflow === 'scroll' && 'sw-filter-chips-row-scroll'), children: [children, hasSlot(end) ? (_jsx("div", { className: "sw-filter-chips-row-end", children: end })) : null] }));
+}

package/dist/components/ListRow.d.ts

@@ -64,6 +64,13 @@ export type ListRowProps = {
      * `ActionMenu` of the row's own actions. It needs its own name.
      */
     action?: ReactNode;
+    /**
+     * Keeps the title and the detail on one line each, cut with "…" where
+     * they do not fit, for a long list read at a glance; the full words stay
+     * in the row's name and description, and in a `title` tooltip. The
+     * value, its detail and the tag keep their words whole.
+     */
+    truncate?: boolean;
     /** `none` hides the chevron of a pressable row that acts in place. */
     accessory?: 'chevron' | 'none';
     /**
@@ -76,6 +83,7 @@ export type ListRowProps = {
  * 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). `unread` marks it new,
- * `tag` adds a status before its end, and `action` a control beside it.
+ * `tag` adds a status before its end, `action` a control beside it, and
+ * `truncate` keeps its title and detail to one line each.
  */
-export declare function ListRow({ title, detail, value, valueDetail, valueTone, valueBadge, leading, onPress, href, selected, disabled, tone, titleAppearance, accessory, unread, unreadLabel, tag, action, 'aria-label': ariaLabel, }: ListRowProps): import("react").JSX.Element;
+export declare function ListRow({ title, detail, value, valueDetail, valueTone, valueBadge, leading, onPress, href, selected, disabled, tone, titleAppearance, accessory, unread, unreadLabel, tag, action, truncate, 'aria-label': ariaLabel, }: ListRowProps): import("react").JSX.Element;

package/dist/components/ListRow.js

@@ -12,9 +12,10 @@ import { rowNaming } from './list/row-naming.js';
  * 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). `unread` marks it new,
- * `tag` adds a status before its end, and `action` a control beside it.
+ * `tag` adds a status before its end, `action` a control beside it, and
+ * `truncate` keeps its title and detail to one line each.
  */
-export function ListRow({ title, detail, value, valueDetail, valueTone, valueBadge, leading, onPress, href, selected, disabled = false, tone = 'default', titleAppearance = 'strong', accessory = 'chevron', unread = false, unreadLabel, tag, action, 'aria-label': ariaLabel, }) {
+export function ListRow({ title, detail, value, valueDetail, valueTone, valueBadge, leading, onPress, href, selected, disabled = false, tone = 'default', titleAppearance = 'strong', accessory = 'chevron', unread = false, unreadLabel, tag, action, truncate = false, 'aria-label': ariaLabel, }) {
     const pressable = onPress !== undefined || href !== undefined;
     assertListRow({
         title,
@@ -32,8 +33,8 @@ export function ListRow({ title, detail, value, valueDetail, valueTone, valueBad
     });
     const id = useId();
     const kind = listRowAccessory({ pressable, selected, accessory });
-    const content = (_jsx(ListRowContent, { accessory: kind, detail: detail, id: id, leading: leading, tag: tag, title: title, titleAppearance: titleAppearance, tone: tone, unreadLabel: unread ? unreadLabel : undefined, value: value, valueBadge: valueBadge, valueDetail: valueDetail, valueTone: valueTone }));
-    const className = cx('sw-list-row', pressable && 'sw-list-row-pressable', disabled && 'sw-list-row-disabled');
+    const content = (_jsx(ListRowContent, { accessory: kind, detail: detail, id: id, leading: leading, tag: tag, title: title, titleAppearance: titleAppearance, tone: tone, truncate: truncate, unreadLabel: unread ? unreadLabel : undefined, value: value, valueBadge: valueBadge, valueDetail: valueDetail, valueTone: valueTone }));
+    const className = cx('sw-list-row', pressable && 'sw-list-row-pressable', disabled && 'sw-list-row-disabled', truncate && 'sw-list-row-truncate');
     const naming = rowNaming(id, {
         'aria-label': ariaLabel,
         value,

package/dist/components/action-menu/assert-action-menu.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import { type ActionMenuTriggerAppearance } from '../../css/css-action-menu-trigger.js';
+import { type ActionMenuItem } from '../ActionMenu.js';
+/**
+ * Fails closed on a menu it cannot draw: an item's blank detail or
+ * detailLang (or a detailLang with no detail), an unknown trigger
+ * appearance, or an icon trigger with no glyph.
+ */
+export declare function assertActionMenu({ items, trigger, triggerAppearance, }: {
+    items: readonly ActionMenuItem[];
+    trigger: ReactNode;
+    triggerAppearance: ActionMenuTriggerAppearance;
+}): void;

package/dist/components/action-menu/assert-action-menu.js

@@ -0,0 +1,21 @@
+import { actionMenuTriggerAppearances, } from '../../css/css-action-menu-trigger.js';
+import { hasSlot } from '../slot.js';
+/** Whether an icon trigger has a glyph to draw (blank words are none). */
+function hasGlyph(trigger) {
+    return (hasSlot(trigger) && !(typeof trigger === 'string' && trigger.trim() === ''));
+}
+/**
+ * Fails closed on a menu it cannot draw: an item's blank detail or
+ * detailLang (or a detailLang with no detail), an unknown trigger
+ * appearance, or an icon trigger with no glyph.
+ */
+export function assertActionMenu({ items, trigger, triggerAppearance, }) {
+    if (items.some((item) => (item.detail !== undefined && !item.detail.trim()) ||
+        (item.detailLang !== undefined &&
+            (!item.detailLang.trim() || item.detail === undefined))))
+        throw new RangeError('ActionMenu item detail and detailLang must not be blank; detailLang needs a detail');
+    if (!actionMenuTriggerAppearances.includes(triggerAppearance))
+        throw new RangeError(`Unknown ActionMenu triggerAppearance: ${String(triggerAppearance)}`);
+    if (triggerAppearance === 'icon' && !hasGlyph(trigger))
+        throw new RangeError('An icon ActionMenu trigger needs its glyph');
+}

package/dist/components/description-list-layout.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How a DescriptionList lays out its rows: `columns` (the default), the
+ * terms in a start column and the details beside them, each term over its
+ * detail below `md`; `spread`, each row's term at its start and its detail
+ * at its end, side by side at every width.
+ */
+export declare const descriptionListLayouts: readonly ["columns", "spread"];
+export type DescriptionListLayout = (typeof descriptionListLayouts)[number];
+/** Fails closed on a layout the list cannot draw. */
+export declare function assertDescriptionListLayout(layout: unknown): void;

package/dist/components/description-list-layout.js

@@ -0,0 +1,13 @@
+import { isOneOf } from '../is-one-of.js';
+/**
+ * How a DescriptionList lays out its rows: `columns` (the default), the
+ * terms in a start column and the details beside them, each term over its
+ * detail below `md`; `spread`, each row's term at its start and its detail
+ * at its end, side by side at every width.
+ */
+export const descriptionListLayouts = ['columns', 'spread'];
+/** Fails closed on a layout the list cannot draw. */
+export function assertDescriptionListLayout(layout) {
+    if (!isOneOf(descriptionListLayouts, layout))
+        throw new RangeError(`Unknown DescriptionList layout: ${String(layout)}`);
+}

package/dist/components/file-field/file-field-checks.d.ts

@@ -1,8 +1,8 @@
 import type { FileFieldValue } from '../FileField.js';
 /**
  * Fails closed on a FileField it cannot name or show: an empty label,
- * choose or change words, a blank drop hint, or a chosen file with no name
- * or a blank detail.
+ * choose or change words, a blank drop hint, or a chosen file with no name,
+ * a blank detail or a blank preview address.
  */
 export declare function assertFileField(props: {
     label: string;

package/dist/components/file-field/file-field-checks.js

@@ -3,8 +3,8 @@ function isBlank(text) {
 }
 /**
  * Fails closed on a FileField it cannot name or show: an empty label,
- * choose or change words, a blank drop hint, or a chosen file with no name
- * or a blank detail.
+ * choose or change words, a blank drop hint, or a chosen file with no name,
+ * a blank detail or a blank preview address.
  */
 export function assertFileField(props) {
     for (const key of ['label', 'chooseLabel', 'changeLabel'])
@@ -18,4 +18,6 @@ export function assertFileField(props) {
         throw new RangeError('FileField value name must be non-empty text');
     if (props.value.detail !== undefined && isBlank(props.value.detail))
         throw new RangeError('FileField value detail must be non-empty text');
+    if (props.value.preview !== undefined && isBlank(props.value.preview))
+        throw new RangeError('FileField value preview must be an image address');
 }

package/dist/components/filter-chips/FilterChip.js

@@ -13,7 +13,7 @@ function ChipCount({ count, appearance, }) {
 }
 /** One chip: a native radio or checkbox under its face. */
 export function FilterChip({ option, name, type, checked, required, tabStopHere, countAppearance, onCheckedChange, }) {
-    return (_jsxs("label", { className: cx('sw-filter-chip', option.count === 0 && 'sw-filter-chip-quiet'), children: [_jsx("input", { checked: checked, className: "sw-filter-chip-input", disabled: option.disabled, name: name, onChange: (event) => {
+    return (_jsxs("label", { className: cx('sw-filter-chip', option.count === 0 && 'sw-filter-chip-quiet', option.tone === 'warning' && 'sw-filter-chip-warning'), children: [_jsx("input", { checked: checked, className: "sw-filter-chip-input", disabled: option.disabled, name: name, onChange: (event) => {
                     if (!option.disabled)
                         onCheckedChange(event.currentTarget.checked);
                 }, required: required, tabIndex: tabStopHere ? tabStop : undefined, type: type, value: option.value }), _jsxs("span", { className: "sw-filter-chip-face", children: [option.label, option.count === undefined ? null : (_jsx(ChipCount, { appearance: countAppearance, count: option.count }))] })] }));

package/dist/components/filter-chips/options.d.ts

@@ -1,9 +1,19 @@
 import { type RequiredMark } from '../FieldLabelText.js';
+/**
+ * A chip's colour while it is not chosen: `neutral` (the default), the
+ * glass chip; `warning`, the warning tint with its words in the warning
+ * ink, for a choice that shows what needs a look ("Missing a
+ * translation"). Its words must say so; the tint only draws the eye. A
+ * chosen chip is the accent, whatever its tone.
+ */
+export declare const filterChipTones: readonly ["neutral", "warning"];
+export type FilterChipTone = (typeof filterChipTones)[number];
 export type FilterChipOption = {
     value: string;
     label: string;
     count?: number;
     disabled?: boolean;
+    tone?: FilterChipTone;
 };
 /**
  * How a chip's count is drawn: `figure` (the default), a muted tabular

package/dist/components/filter-chips/options.js

@@ -1,3 +1,11 @@
+/**
+ * A chip's colour while it is not chosen: `neutral` (the default), the
+ * glass chip; `warning`, the warning tint with its words in the warning
+ * ink, for a choice that shows what needs a look ("Missing a
+ * translation"). Its words must say so; the tint only draws the eye. A
+ * chosen chip is the accent, whatever its tone.
+ */
+export const filterChipTones = ['neutral', 'warning'];
 /**
  * How a chip's count is drawn: `figure` (the default), a muted tabular
  * figure after a space; `inline`, the label's own words and type, after a

package/dist/components/filter-chips/validate.d.ts

@@ -2,8 +2,8 @@ import { type FilterChipsProps } from './options.js';
 /**
  * Fails closed on chips it cannot draw: an empty label, no options, blank
  * or repeated values, a chosen value that is no option, a count that is
- * not a whole number from 0, an unknown count appearance or overflow, and
- * a multiple choice asked to be required or given a value that is not a
- * list.
+ * not a whole number from 0, an unknown chip tone, count appearance or
+ * overflow, and a multiple choice asked to be required or given a value
+ * that is not a list.
  */
 export declare function assertFilterChips(props: FilterChipsProps): void;