@hackcove/ui-react 0.10.2 → 0.10.3

package/README.md

@@ -81,7 +81,7 @@ takes the size of the text around it. Upgrading: `MIGRATING.md`, shipped in the
   text colours as a `TableCell` tone, winning over `color`; pair the colour with a word, as in "Saved."),
   `numeric` (tabular figures), `mono` (the monospace face) and `truncate` (one line, cut with an
   ellipsis, the full text in a `title`, so its content is text).
-- Controls: `Button` (`variant` is `primary` (default), `outline`, `ghost`, `link` or `dashed`, the link having no box: text with an underline on hover, for an in-line action, and the dashed one a dashed outline in muted text that fills its container, like `Card dashed`, for an "add another" row, with a leading icon as a child, ignoring `tone`; `size="sm"` is compact, `text-xs`, for table rows and toolbars, `size="lg"` is `text-base` with more padding; `tone="danger"` is red, for delete and clear, and `tone="positive"` green, for accept and approve; `disabledReason` disables it, greys it flat and makes the reason its `title`; `busy` disables it with `aria-busy` and keeps its colour, showing `busyLabel` in place of the children; `pressed` makes it a toggle with `aria-pressed`, on `outline` and `ghost` neutral when off and filled in the tone's primary colour when on, so an `outline` `size="sm"` Button with `pressed` is a filter chip; `count` puts a small number chip after the label, part of the button's name ("Splits, 3"), and a button that opens something also takes `aria-expanded`; with `href`, or `render` to draw the app's own router `<Link>`, it is a link with the same look, `external` opening a new tab), `ButtonGroup` (a wrapping row of buttons; `end` is one item pushed to the far side, `label` makes it a named `role="group"`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`; `variant` is `outline` (default) or `ghost`, `tone` is `default` or `danger`, `size` matches a `Button`'s height; `badge` puts a red count on its corner, not shown at 0; with `href` or `render` it is a link, `external` opening a new tab), `Icon` (one bare `<svg>` sized to fill a box, or `name` for one of the set's own icons (`diff`, `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`, `speed`, `search`, `chevron-right`, `chevron-down`, `close`, `external-link`, `settings`, `bell`, `check`, `plus`: feature ideas and UI glyphs on one 24 grid, a 1.5 stroke, round caps and joins, each the idea or action, not a product): `size` `sm` 14px, `md` 16px (default), `lg` 20px or `feature` 32px; `tone` is a text tone or `inherit` (default, the text colour around it); `aria-hidden` unless `label` names it as `role="img"`), `ColourSchemeToggle` (a light/dark switch on `<html>`; `id`, `data-*` and other button props go on the button, `store={false}` skips `localStorage`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field; `prefix` is short text inside the border before the value, a currency symbol, on a plain field only; `type="search"` drops the browser's search look and shows a "Clear search" button while the field has a value), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Input`, `Select` and `Textarea` take `size` (`md` default, `sm`: `text-xs`, less padding, for dense forms and table rows, or `lg`: `text-base`, more padding) and `width` (`full` default, the fixed `xs` 5rem, `sm` 7rem, `md` 9rem, `lg` 12rem, `fill`: grows to the room left in a flex row and can shrink to nothing, so the buttons beside it stay on the line, or `auto`: no width class, as wide as the browser makes it); a fixed width replaces `w-full`, so there is no class to collide with. `Input` also takes `align` (`start` default, or `end` to right-align a numeric value). `size` replaces the native `size` attribute, so a multi-row `<select size={4}>` is not reachable through `Select`. `Checkbox` (a native checkbox with its label; other props go on the input; `size="sm"` is `text-xs` with a smaller box and `size="lg"` `text-base` with a larger one, `align="start"` puts the box on the first line of a label that wraps, where the default `center` centres it on all of them, and with no `label` it is a bare box for a table cell, named by `aria-label`; `description` is a muted line under the label, the box's `aria-describedby`). `Switch` (an on/off setting that acts at once, usually by saving to a server: a native `<button role="switch" aria-checked>`, controlled only, with `checked` and `onChange(next)`; give it a `label` (the whole label is the click target) or, with none, an `aria-label`: one is required; `description` is a muted line under the label and its `aria-describedby`; `size` is `sm`, `md` (default) or `lg`; `busy` is the save in flight: `aria-busy`, a click or key does nothing, it keeps its colour and its focus; `disabled` is the native one, washed out; a value sent with a form stays a `Checkbox`). `RadioGroup` and `Radio` (one choice from a few options: the group has a `label`, `value`/`onChange` or `defaultValue`, `name`, `isDisabled`, `isRequired`, `size` (`sm`, `md` default, `lg`, as `Checkbox`) and an `error` shown like `Field`'s with `role="alert"`; each `Radio` has a `value`, a `label`, an optional `description` and `isDisabled`; one tab stop, the arrow keys move and choose). `Disclosure` (a summary button with a chevron and `aria-expanded` over a body that opens and closes; `summary`, `children`, `defaultOpen`; it keeps its own state and replaces `<details>`). `FileDrop` (a dashed drop zone, a `<label>` around a file input that covers it, so a click opens the dialog and a dropped file lands on the input; `children` is the prompt, `accept`, `multiple`, `name`, `disabled` and `onChange` on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; `disabled` disables the button; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; `hideLabel` keeps the label for assistive tech and draws no text, for a control whose purpose is plain from what surrounds it, and makes `layout="row"` a column; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line; `span="full"` runs it across both columns of a `FormGrid`). `FormGrid` (two columns of `Field`s from `md`, one below it), `FormRow` (an inline-edit row: `FormRowField`s side by side, an `action` after them, and one `hint` or `error` under the whole row; see Layout) and `FormRowField` (a compact label over one control, `span` 1 to 4). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body; `actions` puts a button or link at the end of the row; `banner` makes it a flat strip, bottom border only and no radius, for the top of a `Card flush`). `ListRow` (a full-width row that is a `<button>`, or a link with `href` or `render`, with a hover fill, a left-aligned label and `trailing` content; `divided` draws a hairline above the row, to separate rows in a `Card flush`; `expanded` makes it the header of a collapsible section: `aria-expanded` and a chevron, the caller owning the state and the section; `leading` is content before the label (an `Avatar`), and `leadingWidth="thumbnail"` gives it a fixed width so rows with and without a picture line up; `size` sets the padding (`sm` dense, `md` default, `lg`); `focused` draws the focus ring on the row the keyboard cursor is on, for a list moved with the arrow keys while focus stays on the list; `selected` marks the row in view with a violet fill and `aria-current="true"`; a link row (`href` or `render`) can hold its own link, button or control in `trailing`, which sits above the row's link and takes its own click; `static` makes it a plain `<div>`, for a row that holds its own buttons where the row would otherwise be a `<button>`, and adds `actions`, buttons after `trailing`, and `revealOnHover`, which shows them only on hover or focus inside the row and always on a touch screen; a compact bordered list is `Card flush` around `static` rows at `size="sm"`, `divided` after the first (no separate part); `active` marks the row the pointer or the keyboard is on, with the hover fill and the `revealOnHover` actions shown, for a list that follows both through the row's `onPointerEnter`, `onPointerLeave` and `onFocus`, which every row passes through). `Tabs` (underline tabs for switching a view in place: a row over a bottom rule, the current tab underlined in the accent; `items` are `{ value, label }` buttons, with `value` the current one's `value` and `onChange(value)` the caller's state, one tab stop and the arrow keys, Home and End moving between enabled tabs, or `{ label, href | render, active?, external? }` links in a `<nav>` with `aria-current="page"` on the current one (`active`, or the item whose `value` is `value`); `label` names the group; a button tab takes `disabled` and `controls`, the id of its `role="tabpanel"`, which is the caller's; `variant="pill"` fills the current tab, with no rule, for `PageHeader`'s `tabs` slot, an `AppShell` `nav` or a rail; only a pill row takes `size` and `orientation`, and `orientation="vertical"` stacks it in one column, the content of a `SidebarLayout` rail; `disabled` on the row disables every tab, e.g. until hydration). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange`, `disabled` and `label` as `Tabs`, as a `radiogroup` with `aria-checked` on each `radio`). On both an item takes `data-*` attributes (typed `data-${string}`) onto its button or link; on `Tabs` and `SegmentedControl` an item takes `count` (a small muted number after the label, part of its name: "Shots 12") and `title`; a `disabled` button option stays in the page as `aria-disabled`, so its `title` is still the hover tooltip and is announced as the reason, it is out of the tab order and the arrow keys, Home and End skip it. `Dialog` (a modal on the browser's `<dialog>`, opened on mount, so render it only while open: `title` is its name, `description` a line under it, `footer` the right-aligned actions; Esc, the backdrop or a `<form method="dialog">` call `onClose`; `size` is `sm` (320px, a list), `md` (440px, default, a form), `lg` (640px, a wider form or a table) or `full` (the whole screen, for media or a player: the body fills the height between the title and the footer and scrolls if taller; there is no backdrop to click, so put a close button on a `<form method="dialog">` in the `footer`)). `FieldDialog` (a `Dialog` with one text field and Cancel and submit buttons, every string passed in: `title`, `description`, `label`, `inputLabel`, `placeholder`, `hint`, `emptyReason`, `submit` and `busyLabel`; `onSubmit` gets the trimmed value and a resolved promise closes it, a rejection shows its message). `Drawer` (a modal slide-over on the right edge, on a native `<dialog>` opened on mount like `Dialog`, so render it only while open: `title` is its name, a close button sits beside it, `children` scroll between the header and an optional pinned `footer`; Esc, the scrim and the close button call `onClose`; `size` is `sm`, `md` (default) or `lg`; `closeLabel` names the close button). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, or `{ label, href | render, external? }` for one that links; the last is the current page and is never a link and gets `aria-current="page"`, and each crumb truncates). `Table` (a list of records in a rounded, bordered card around a full-width `<table>` that scrolls sideways on a narrow screen; `caption` names it for assistive tech and is not drawn; compose it from `TableHead`, `TableBody`, `TableFoot`, `TableRow`, `TableHeaderCell` (`align` `start`, `center` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `indent` of 1 to 3 to set a start-aligned cell in, for a line under a parent row, `tone` `default`, `strong` or `muted`, or the Callout tones `neutral`, `info`, `positive`, `warn` or `danger` for an amount that means something, in the tone's text colour and with no fill, so pair the colour with a sign or a word; `numeric` for tabular figures, `mono` for a small mono face, `truncate` to cap a long value's width, cut it with an ellipsis and put the full text in a `title`, so its content is text (strings and numbers); `secondary` for a second, muted line under the content; `colSpan` passes through, so a `TableCell` with `colSpan` in a row of its own is a full-width panel, an empty state or a note, centred with `align="center"`); `TableEditCell` (a `TableCell` whose value opens an editor in place: `children` is the value, drawn as a button; a click, Enter or Space swaps it for `renderEditor(close)`, a plain control in the cell and not a popover of its own, and moves the focus into it; `close` and Esc put the focus back on the value, and a press outside or Tab out of it closes it too, so the control saves on its own change or submit; `label` names the button and the editor; it takes the `TableCell` props except `truncate`); `InlineEdit` (the same edit trigger without the cell, for a `TableCell` that holds other content too: `label`, `renderEditor(close)` and `children`, with the same keyboard and focus behaviour); `TableFoot` (the `<tfoot>` for totals: its cells are strong by default and each row has a firmer line above it, in a card and in a `plain` table alike); `TableGroupRow` (a full-width group header in the body: `label` spans `colSpan` columns, the table's column count, which is required; optional `trailing` content sits at the far end, and the group's rows follow it); `tone` on a `TableRow` in the body marks the row with a stripe on its leading edge over a soft fill: `neutral`, `info`, `positive`, `warn` or `danger`, as `Callout`, or `muted`, which only fades the row (a transfer, a row that is not the point); a bold subtotal is not a tone: `emphasis` on a `TableRow` in the body gives it a `TableFoot` row's look among the other rows; `stripe` (a text tone) draws the leading stripe alone, with no fill; a row takes one of `tone`, `stripe` and `emphasis`; `variant="plain"` on `Table` drops the card border, fill and shadow, the head strip and the row hover and keeps the row dividers, for a table inside a card of its own; every table element passes `id`, `data-*` and `aria-*` through, and none takes a `className` or `style`). `Timeline` (a named `<ol>` of events; `label` is its `aria-label`, `empty` is drawn instead when there are no items) with `TimelineItem` (a `title`, an already-formatted `time`, the `children` as a note, and `tone`, a Callout tone for the marker dot, `neutral` by default). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures; `total` makes it the sum row, a firm rule above and strong text, and `tone` (`muted`, `positive`, `warn`, `danger`, `info`) colours the value on any row, so `total tone="warn"` is a total that does not reconcile; `align="start"` puts the values left-aligned in one column beside the labels instead, using CSS subgrid: in Chrome before 117 a row stacks its label over its value). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; with `src` (the app's own local image path, never a remote one) it is a round, cropped `<img alt={name}>` instead, and if that image fails to load it shows the initials; `size` is `xs` (16px, for an inline mention), `sm`, `md` (default), `lg`, `xl` (56px), `2xl` (64px) or `3xl` (96px); `onClick` makes it one button named by `name`; `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `TextLink` (an inline text link in the accent colour; `href` is required unless `render` draws the app's own router `<Link>`, `external` adds `target="_blank"` and `rel="noreferrer"`, `stretch` covers the nearest `relative` ancestor so a whole row or card is the click target, `size` (`sm`, `md` or `lg`) pins the type size where it would otherwise follow the text around it, `mono` sets the monospace face, `tone` (`warn`, `danger`, `positive`, `info` or `muted`) gives it a meaning's colour in place of the accent, every other anchor prop passes through). `MetaList` (a wrapping row of facts or links in muted small text, joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; branch · SHA · date, or a footer's Privacy · Terms; an item is text, a `Code` or a `TextLink`; `nowrap` keeps each item on one line, for links; `mono` sets the row in the monospace face, for ids and paths). `PageFade` (the page's content area, named for the View Transitions API so a route change cross-fades it while the frame around it stays put; wrap what changes between pages, once per page, or give each a `name` (a CSS identifier) when there are two; it fades when the navigation runs in a view transition, through `startPageTransition(update)` (flushes a synchronous state change inside `document.startViewTransition`) or a router's own option such as TanStack Router `viewTransition`, and otherwise, in a browser without View Transitions, or under `prefers-reduced-motion: reduce`, it swaps with no fade; it renders a small `<style>`, with no colour in it, and the div is a stacking context, so portal an overlay that must rise above the frame). `EmptyState` (what a page or list shows when it has nothing yet: a centred `title`, the `children` as the explanation under it, and `actions` in a centred row; a named `<section>`; `level` is the title's heading level, 2 (default) to 6, and does not change its look; for one muted line inside a card, `Text as="p" color="muted"`). `Steps` (a numbered `<ol>` of `Step`s, each a `title` and the `children` as a detail line, the numbers counted by CSS in a violet disc; for a "get started" list, not for progress). `Divider` (a hairline `<hr>` in the theme's line colour; spacing comes from the layout around it). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `CodeBlock` (a block of code, no client JS: the text is `children` (a string) or `lines` (one entry per line), `language` (`text` (default, one colour), `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`) colours it, `console` being a shell session where a `$ ` line is a command and the rest is output, and `copy` then copies only the commands; `label` is a caption naming the language or file; long lines wrap by default, so nothing is cut off and a command copies as one line, and `overflow="scroll"` keeps lines whole and scrolls them under a thin scrollbar in the theme's muted ink; `copy` adds a copy button beside the code, which copies it exactly as given and needs the page hydrated; other props go on the root `<figure>`). `CodeExample` (one framed example: the rendered `children` over the `code` that makes them, coloured as TSX, in one bordered box, with an optional `caption` as its last band; a wide preview or long code scrolls inside the frame under the same thin scrollbar; `copy` adds a button that copies the code; no client JS without `copy`). `Video` (a full-width, rounded `<video>` with controls that loads metadata only; `src` is required, `poster` and a WebVTT `captions` track are optional, children are the fallback). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `outline` `sm` `Button`s with `pressed`). `DateField` (see Dates).
+- Controls: `Button` (`variant` is `primary` (default), `outline`, `ghost`, `link` or `dashed`, the link having no box: text with an underline on hover, for an in-line action, and the dashed one a dashed outline in muted text that fills its container, like `Card dashed`, for an "add another" row, with a leading icon as a child, ignoring `tone`; `size="sm"` is compact, `text-xs`, for table rows and toolbars, `size="lg"` is `text-base` with more padding; `tone="danger"` is red, for delete and clear, and `tone="positive"` green, for accept and approve; `disabledReason` disables it, greys it flat and makes the reason its `title`; `busy` disables it with `aria-busy` and keeps its colour, showing `busyLabel` in place of the children; `pressed` makes it a toggle with `aria-pressed`, on `outline` and `ghost` neutral when off and filled in the tone's primary colour when on, so an `outline` `size="sm"` Button with `pressed` is a filter chip; `count` puts a small number chip after the label, part of the button's name ("Splits, 3"), and a button that opens something also takes `aria-expanded`; with `href`, or `render` to draw the app's own router `<Link>`, it is a link with the same look, `external` opening a new tab), `ButtonGroup` (a wrapping row of buttons; `end` is one item pushed to the far side, `label` makes it a named `role="group"`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`; `variant` is `outline` (default) or `ghost`, `tone` is `default` or `danger`, `size` matches a `Button`'s height; `badge` puts a red count on its corner, not shown at 0; with `href` or `render` it is a link, `external` opening a new tab), `Icon` (one bare `<svg>` sized to fill a box, or `name` for one of the set's own icons (`diff`, `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`, `speed`, `search`, `chevron-right`, `chevron-down`, `close`, `external-link`, `settings`, `bell`, `check`, `plus`: feature ideas and UI glyphs on one 24 grid, a 1.5 stroke, round caps and joins, each the idea or action, not a product): `size` `sm` 14px, `md` 16px (default), `lg` 20px or `feature` 32px; `tone` is a text tone or `inherit` (default, the text colour around it); `aria-hidden` unless `label` names it as `role="img"`), `ColourSchemeToggle` (a light/dark switch on `<html>`; `id`, `data-*` and other button props go on the button, `store={false}` skips `localStorage`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field; `prefix` is short text inside the border before the value, a currency symbol, on a plain field only; `type="search"` drops the browser's search look and shows a "Clear search" button while the field has a value), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Input`, `Select` and `Textarea` take `size` (`md` default, `sm`: `text-xs`, less padding, for dense forms and table rows, or `lg`: `text-base`, more padding) and `width` (`full` default, the fixed `xs` 5rem, `sm` 7rem, `md` 9rem, `lg` 12rem, `fill`: grows to the room left in a flex row and can shrink to nothing, so the buttons beside it stay on the line, or `auto`: no width class, as wide as the browser makes it); a fixed width replaces `w-full`, so there is no class to collide with. `Input` also takes `align` (`start` default, or `end` to right-align a numeric value). `size` replaces the native `size` attribute, so a multi-row `<select size={4}>` is not reachable through `Select`. `Checkbox` (a real `<input type="checkbox">` with its label, drawn by the library as an empty outlined box and a filled violet one with a check mark, so it reads the same in every theme and browser; other props go on the input; `size="sm"` is `text-xs` with a smaller box and `size="lg"` `text-base` with a larger one, `align="start"` puts the box on the first line of a label that wraps, where the default `center` centres it on all of them, and with no `label` it is a bare box for a table cell, named by `aria-label`; `description` is a muted line under the label, the box's `aria-describedby`). `Switch` (an on/off setting that acts at once, usually by saving to a server: a native `<button role="switch" aria-checked>`, controlled only, with `checked` and `onChange(next)`; give it a `label` (the whole label is the click target) or, with none, an `aria-label`: one is required; `description` is a muted line under the label and its `aria-describedby`; `size` is `sm`, `md` (default) or `lg`; `busy` is the save in flight: `aria-busy`, a click or key does nothing, it keeps its colour and its focus; `disabled` is the native one, washed out; a value sent with a form stays a `Checkbox`). `RadioGroup` and `Radio` (one choice from a few options: the group has a `label`, `value`/`onChange` or `defaultValue`, `name`, `isDisabled`, `isRequired`, `size` (`sm`, `md` default, `lg`, as `Checkbox`) and an `error` shown like `Field`'s with `role="alert"`; each `Radio` has a `value`, a `label`, an optional `description` and `isDisabled`; one tab stop, the arrow keys move and choose). `Disclosure` (a summary button with a chevron and `aria-expanded` over a body that opens and closes; `summary`, `children`, `defaultOpen`; it keeps its own state and replaces `<details>`). `FileDrop` (a dashed drop zone, a `<label>` around a file input that covers it, so a click opens the dialog and a dropped file lands on the input; `children` is the prompt, `accept`, `multiple`, `name`, `disabled` and `onChange` on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; `disabled` disables the button; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; `hideLabel` keeps the label for assistive tech and draws no text, for a control whose purpose is plain from what surrounds it, and makes `layout="row"` a column; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line; `span="full"` runs it across both columns of a `FormGrid`). `FormGrid` (two columns of `Field`s from `md`, one below it), `FormRow` (an inline-edit row: `FormRowField`s side by side, an `action` after them, and one `hint` or `error` under the whole row; see Layout) and `FormRowField` (a compact label over one control, `span` 1 to 4). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body; `actions` puts a button or link at the end of the row; `banner` makes it a flat strip, bottom border only and no radius, for the top of a `Card flush`). `ListRow` (a full-width row that is a `<button>`, or a link with `href` or `render`, with a hover fill, a left-aligned label and `trailing` content; `divided` draws a hairline above the row, to separate rows in a `Card flush`; `expanded` makes it the header of a collapsible section: `aria-expanded` and a chevron, the caller owning the state and the section; `leading` is content before the label (an `Avatar`), and `leadingWidth="thumbnail"` gives it a fixed width so rows with and without a picture line up; `size` sets the padding (`sm` dense, `md` default, `lg`); `focused` draws the focus ring on the row the keyboard cursor is on, for a list moved with the arrow keys while focus stays on the list; `selected` marks the row in view with a violet fill and `aria-current="true"`; a link row (`href` or `render`) can hold its own link, button or control in `trailing`, which sits above the row's link and takes its own click; `static` makes it a plain `<div>`, for a row that holds its own buttons where the row would otherwise be a `<button>`, and adds `actions`, buttons after `trailing`, and `revealOnHover`, which shows them only on hover or focus inside the row and always on a touch screen; a compact bordered list is `Card flush` around `static` rows at `size="sm"`, `divided` after the first (no separate part); `active` marks the row the pointer or the keyboard is on, with the hover fill and the `revealOnHover` actions shown, for a list that follows both through the row's `onPointerEnter`, `onPointerLeave` and `onFocus`, which every row passes through). `Tabs` (underline tabs for switching a view in place: a row over a bottom rule, the current tab underlined in the accent; `items` are `{ value, label }` buttons, with `value` the current one's `value` and `onChange(value)` the caller's state, one tab stop and the arrow keys, Home and End moving between enabled tabs, or `{ label, href | render, active?, external? }` links in a `<nav>` with `aria-current="page"` on the current one (`active`, or the item whose `value` is `value`); `label` names the group; a button tab takes `disabled` and `controls`, the id of its `role="tabpanel"`, which is the caller's; `variant="pill"` fills the current tab, with no rule, for `PageHeader`'s `tabs` slot, an `AppShell` `nav` or a rail; only a pill row takes `size` and `orientation`, and `orientation="vertical"` stacks it in one column, the content of a `SidebarLayout` rail; `disabled` on the row disables every tab, e.g. until hydration). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange`, `disabled` and `label` as `Tabs`, as a `radiogroup` with `aria-checked` on each `radio`). On both an item takes `data-*` attributes (typed `data-${string}`) onto its button or link; on `Tabs` and `SegmentedControl` an item takes `count` (a small muted number after the label, part of its name: "Shots 12") and `title`; a `disabled` button option stays in the page as `aria-disabled`, so its `title` is still the hover tooltip and is announced as the reason, it is out of the tab order and the arrow keys, Home and End skip it. `Dialog` (a modal on the browser's `<dialog>`, opened on mount, so render it only while open: `title` is its name, `description` a line under it, `footer` the right-aligned actions; Esc, the backdrop or a `<form method="dialog">` call `onClose`; `size` is `sm` (320px, a list), `md` (440px, default, a form), `lg` (640px, a wider form or a table) or `full` (the whole screen, for media or a player: the body fills the height between the title and the footer and scrolls if taller; there is no backdrop to click, so put a close button on a `<form method="dialog">` in the `footer`)). `FieldDialog` (a `Dialog` with one text field and Cancel and submit buttons, every string passed in: `title`, `description`, `label`, `inputLabel`, `placeholder`, `hint`, `emptyReason`, `submit` and `busyLabel`; `onSubmit` gets the trimmed value and a resolved promise closes it, a rejection shows its message). `Drawer` (a modal slide-over on the right edge, on a native `<dialog>` opened on mount like `Dialog`, so render it only while open: `title` is its name, a close button sits beside it, `children` scroll between the header and an optional pinned `footer`; Esc, the scrim and the close button call `onClose`; `size` is `sm`, `md` (default) or `lg`; `closeLabel` names the close button). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, or `{ label, href | render, external? }` for one that links; the last is the current page and is never a link and gets `aria-current="page"`, and each crumb truncates). `Table` (a list of records in a rounded, bordered card around a full-width `<table>` that scrolls sideways on a narrow screen; `caption` names it for assistive tech and is not drawn; compose it from `TableHead`, `TableBody`, `TableFoot`, `TableRow`, `TableHeaderCell` (`align` `start`, `center` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `indent` of 1 to 3 to set a start-aligned cell in, for a line under a parent row, `tone` `default`, `strong` or `muted`, or the Callout tones `neutral`, `info`, `positive`, `warn` or `danger` for an amount that means something, in the tone's text colour and with no fill, so pair the colour with a sign or a word; `numeric` for tabular figures, `mono` for a small mono face, `truncate` to cap a long value's width, cut it with an ellipsis and put the full text in a `title`, so its content is text (strings and numbers); `secondary` for a second, muted line under the content; `colSpan` passes through, so a `TableCell` with `colSpan` in a row of its own is a full-width panel, an empty state or a note, centred with `align="center"`); `TableEditCell` (a `TableCell` whose value opens an editor in place: `children` is the value, drawn as a button; a click, Enter or Space swaps it for `renderEditor(close)`, a plain control in the cell and not a popover of its own, and moves the focus into it; `close` and Esc put the focus back on the value, and a press outside or Tab out of it closes it too, so the control saves on its own change or submit; `label` names the button and the editor; it takes the `TableCell` props except `truncate`); `InlineEdit` (the same edit trigger without the cell, for a `TableCell` that holds other content too: `label`, `renderEditor(close)` and `children`, with the same keyboard and focus behaviour); `TableFoot` (the `<tfoot>` for totals: its cells are strong by default and each row has a firmer line above it, in a card and in a `plain` table alike); `TableGroupRow` (a full-width group header in the body: `label` spans `colSpan` columns, the table's column count, which is required; optional `trailing` content sits at the far end, and the group's rows follow it); `tone` on a `TableRow` in the body marks the row with a stripe on its leading edge over a soft fill: `neutral`, `info`, `positive`, `warn` or `danger`, as `Callout`, or `muted`, which only fades the row (a transfer, a row that is not the point); a bold subtotal is not a tone: `emphasis` on a `TableRow` in the body gives it a `TableFoot` row's look among the other rows; `stripe` (a text tone) draws the leading stripe alone, with no fill; a row takes one of `tone`, `stripe` and `emphasis`; `variant="plain"` on `Table` drops the card border, fill and shadow, the head strip and the row hover and keeps the row dividers, for a table inside a card of its own; every table element passes `id`, `data-*` and `aria-*` through, and none takes a `className` or `style`). `Timeline` (a named `<ol>` of events; `label` is its `aria-label`, `empty` is drawn instead when there are no items) with `TimelineItem` (a `title`, an already-formatted `time`, the `children` as a note, and `tone`, a Callout tone for the marker dot, `neutral` by default). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures; `total` makes it the sum row, a firm rule above and strong text, and `tone` (`muted`, `positive`, `warn`, `danger`, `info`) colours the value on any row, so `total tone="warn"` is a total that does not reconcile; `align="start"` puts the values left-aligned in one column beside the labels instead, using CSS subgrid: in Chrome before 117 a row stacks its label over its value). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; with `src` (the app's own local image path, never a remote one) it is a round, cropped `<img alt={name}>` instead, and if that image fails to load it shows the initials; `size` is `xs` (16px, for an inline mention), `sm`, `md` (default), `lg`, `xl` (56px), `2xl` (64px) or `3xl` (96px); `onClick` makes it one button named by `name`; `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `TextLink` (an inline text link in the accent colour; `href` is required unless `render` draws the app's own router `<Link>`, `external` adds `target="_blank"` and `rel="noreferrer"`, `stretch` covers the nearest `relative` ancestor so a whole row or card is the click target, `size` (`sm`, `md` or `lg`) pins the type size where it would otherwise follow the text around it, `mono` sets the monospace face, `tone` (`warn`, `danger`, `positive`, `info` or `muted`) gives it a meaning's colour in place of the accent, every other anchor prop passes through). `MetaList` (a wrapping row of facts or links in muted small text, joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; branch · SHA · date, or a footer's Privacy · Terms; an item is text, a `Code` or a `TextLink`; `nowrap` keeps each item on one line, for links; `mono` sets the row in the monospace face, for ids and paths). `PageFade` (the page's content area, named for the View Transitions API so a route change cross-fades it while the frame around it stays put; wrap what changes between pages, once per page, or give each a `name` (a CSS identifier) when there are two; it fades when the navigation runs in a view transition, through `startPageTransition(update)` (flushes a synchronous state change inside `document.startViewTransition`) or a router's own option such as TanStack Router `viewTransition`, and otherwise, in a browser without View Transitions, or under `prefers-reduced-motion: reduce`, it swaps with no fade; it renders a small `<style>`, with no colour in it, and the div is a stacking context, so portal an overlay that must rise above the frame). `EmptyState` (what a page or list shows when it has nothing yet: a centred `title`, the `children` as the explanation under it, and `actions` in a centred row; a named `<section>`; `level` is the title's heading level, 2 (default) to 6, and does not change its look; for one muted line inside a card, `Text as="p" color="muted"`). `Steps` (a numbered `<ol>` of `Step`s, each a `title` and the `children` as a detail line, the numbers counted by CSS in a violet disc; for a "get started" list, not for progress). `Divider` (a hairline `<hr>` in the theme's line colour; spacing comes from the layout around it). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `CodeBlock` (a block of code, no client JS: the text is `children` (a string) or `lines` (one entry per line), `language` (`text` (default, one colour), `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`) colours it, `console` being a shell session where a `$ ` line is a command and the rest is output, and `copy` then copies only the commands; `label` is a caption naming the language or file; long lines wrap by default, so nothing is cut off and a command copies as one line, and `overflow="scroll"` keeps lines whole and scrolls them under a thin scrollbar in the theme's muted ink; `copy` adds a copy button beside the code, which copies it exactly as given and needs the page hydrated; other props go on the root `<figure>`). `CodeExample` (one framed example: the rendered `children` over the `code` that makes them, coloured as TSX, in one bordered box, with an optional `caption` as its last band; a wide preview or long code scrolls inside the frame under the same thin scrollbar; `copy` adds a button that copies the code; no client JS without `copy`). `Video` (a full-width, rounded `<video>` with controls that loads metadata only; `src` is required, `poster` and a WebVTT `captions` track are optional, children are the fallback). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `outline` `sm` `Button`s with `pressed`). `DateField` (see Dates).
 - Dates: `toISODate`, `fromISODate`, and the `CalendarDate` type.
 
 ## Dates

package/dist/AppShell.js

@@ -1,10 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
+import { useState } from "react";
 import { AppShellMenu } from "./AppShellMenu.js";
 import { ContainerFrame } from "./Container.js";
 import { schemeClass } from "./colourScheme.js";
 import { cx, focusRing } from "./cx.js";
 import { renderLink } from "./link.js";
+import { useScrollEdges } from "./scrollEdges.js";
 /**
  * The class an app puts on its own `<html>`: it always reserves the scrollbar, so centred content
  * does not shift between a short page and a long one. AppShell never touches `<html>` itself.
@@ -56,32 +57,9 @@ const ROW = "items-center gap-4 overflow-x-clip whitespace-nowrap md:overflow-x-
 const FADE = "md:data-more-start:[--fade-start:2rem] md:data-more-end:[--fade-end:2rem] md:data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
 /** A row in a Container, with the fade on whichever side still has content to scroll to. */
 function ScrollRow({ className, children }) {
-    const row = useRef(null);
-    // Every render: the children may have changed, and each needs observing.
-    useEffect(() => {
-        const el = row.current;
-        if (!el)
-            return undefined;
-        const update = () => {
-            const start = el.scrollLeft > 1;
-            const end = el.scrollWidth - el.clientWidth - el.scrollLeft > 1;
-            el.toggleAttribute("data-more-start", start);
-            el.toggleAttribute("data-more-end", end);
-            el.toggleAttribute("data-more", start || end);
-        };
-        update();
-        el.addEventListener("scroll", update, { passive: true });
-        // jsdom (a consumer's own tests) has no ResizeObserver.
-        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
-        resize?.observe(el);
-        for (const child of el.children)
-            resize?.observe(child);
-        return () => {
-            el.removeEventListener("scroll", update);
-            resize?.disconnect();
-        };
-    });
-    return (_jsx(ContainerFrame, { elementRef: (el) => void (row.current = el), className: cx(ROW, FADE, className), children: children }));
+    const [row, setRow] = useState(null);
+    useScrollEdges(row, "x");
+    return (_jsx(ContainerFrame, { elementRef: setRow, className: cx(ROW, FADE, className), children: children }));
 }
 /**
  * The header row's slots in order: brand, nav (from `md`), the free `children`, then controls and,

package/dist/Avatar.d.ts

@@ -1,4 +1,4 @@
-import { type HTMLAttributes, type ReactElement } from "react";
+import type { HTMLAttributes, ReactElement } from "react";
 import type { Unstyled } from "./props.js";
 declare const SIZE_CLASSES: {
     readonly xs: "size-4 text-[0.5rem]";

package/dist/Avatar.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from "react";
 import { cx, focusRing } from "./cx.js";
+import { useImageFailed } from "./useImageFailed.js";
 /** The identity colours, in hash order. Each is a stock background utility; a theme remaps them. */
 const COLOUR_CLASSES = [
     "bg-violet-600",
@@ -63,14 +63,13 @@ export function Avatar(props) {
 }
 /** Avatar plus the stack's ring: internal, so the ring only ever comes from `AvatarStack`. */
 export function AvatarMark({ name, src, size = "md", shape = "round", ring = false, onError, onClick, ...rest }) {
-    // The `src` that failed to load: a new `src` gets its own try, so a broken one never sticks.
-    const [failedSrc, setFailedSrc] = useState();
+    const { ref, failed, markFailed } = useImageFailed(src);
     const corners = avatarShapeClass(shape, size);
     // As a button, the button takes the consumer's props and the mark inside keeps only its look.
     const markProps = onClick ? {} : rest;
-    const mark = src && src !== failedSrc ? (_jsx("img", { src: src, alt: name, title: name, className: cx("shrink-0 object-cover", corners, SIZE_CLASSES[size], ring), onError: (event) => {
+    const mark = src && !failed ? (_jsx("img", { ref: ref, src: src, alt: name, title: name, className: cx("shrink-0 object-cover", corners, SIZE_CLASSES[size], ring), onError: (event) => {
             onError?.(event);
-            setFailedSrc(src);
+            markFailed();
         }, ...markProps })) : (_jsx("span", { "aria-hidden": "true", title: name, className: cx("inline-grid shrink-0 place-items-center font-semibold text-violet-50", corners, SIZE_CLASSES[size], avatarColourClass(name), ring), ...markProps, children: initialsOf(name) }));
     if (!onClick)
         return mark;

package/dist/Checkbox.d.ts

@@ -2,7 +2,9 @@ import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import type { Unstyled } from "./props.js";
 import type { Size } from "./size.js";
 /**
- * A native checkbox with its label. Every prop but the label goes on the input.
+ * A checkbox with its label. It is a real `<input type="checkbox">`, drawn by the library (an
+ * empty outlined box, then a filled violet one with a check mark) so it reads the same in every
+ * theme and browser. Every prop but the label goes on the input.
  * `size="sm"` is `text-xs` and a smaller box, for a dense row; `size="lg"` is `text-base` and a
  * larger box. Leave `label` out for a bare box in
  * a table cell, and name it with `aria-label`. `align="start"` puts the box on the label's first

package/dist/Checkbox.js

@@ -8,7 +8,9 @@ const SIZE = {
     lg: { label: "gap-2.5 text-base", box: "h-5 w-5", start: "mt-0.5" },
 };
 /**
- * A native checkbox with its label. Every prop but the label goes on the input.
+ * A checkbox with its label. It is a real `<input type="checkbox">`, drawn by the library (an
+ * empty outlined box, then a filled violet one with a check mark) so it reads the same in every
+ * theme and browser. Every prop but the label goes on the input.
  * `size="sm"` is `text-xs` and a smaller box, for a dense row; `size="lg"` is `text-base` and a
  * larger box. Leave `label` out for a bare box in
  * a table cell, and name it with `aria-label`. `align="start"` puts the box on the label's first
@@ -20,5 +22,8 @@ const SIZE = {
 export function Checkbox({ label, description, size = "md", align = "center", "aria-describedby": describedBy, ...rest }) {
     const { descriptionId, describedIds } = useDescription(description, describedBy);
     const start = align === "start" || descriptionId !== undefined;
-    return (_jsxs("label", { className: cx("inline-flex cursor-pointer text-slate-700", start ? "items-start" : "items-center", SIZE[size].label), children: [_jsx("input", { type: "checkbox", className: cx(SIZE[size].box, "shrink-0", start && SIZE[size].start, "accent-violet-600", focusRing), ...(describedIds ? { "aria-describedby": describedIds } : {}), ...rest }), _jsx(Words, { label: label, description: description, id: descriptionId })] }));
+    return (_jsxs("label", { className: cx(
+        // Faded and default-cursor unless the box is enabled. Written as `has-enabled` so the
+        // label carries no `disabled` class text: the disabled state belongs on the input.
+        "group/checkbox inline-flex cursor-default text-slate-700 opacity-50 has-enabled:cursor-pointer has-enabled:opacity-100", start ? "items-start" : "items-center", SIZE[size].label), children: [_jsx("span", { "aria-hidden": "true", className: cx(SIZE[size].box, start && SIZE[size].start, "pointer-events-none invisible absolute z-10 block rounded border border-violet-600 bg-violet-600 text-violet-50 group-has-checked/checkbox:visible"), children: _jsx("svg", { viewBox: "0 0 16 16", fill: "none", className: "h-full w-full", children: _jsx("path", { d: "M4 8.5l2.5 2.5L12 5.5", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }) }) }), _jsx("input", { type: "checkbox", className: cx(SIZE[size].box, "shrink-0", start && SIZE[size].start, "appearance-none rounded border border-slate-300 bg-white hover:border-violet-400", focusRing), ...(describedIds ? { "aria-describedby": describedIds } : {}), ...rest }), _jsx(Words, { label: label, description: description, id: descriptionId })] }));
 }

package/dist/Image.d.ts

@@ -1,4 +1,4 @@
-import { type ReactElement } from "react";
+import type { ReactElement } from "react";
 import type { Passthrough } from "./props.js";
 import type { Size } from "./size.js";
 /**

package/dist/Image.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from "react";
 import { cx } from "./cx.js";
 import { Icon } from "./Icon.js";
+import { useImageFailed } from "./useImageFailed.js";
 const ASPECT = {
     square: "aspect-square",
     "4:3": "aspect-[4/3]",
@@ -48,11 +48,10 @@ function pictureLook(fit, framed) {
  * thumbnail with a label is a `MediaTile`.
  */
 export function Image({ src, alt, aspect = "4:3", fit = "cover", width = "full", framed = false, ...rest }) {
-    // The `src` that failed to load: a new `src` gets its own try, so a broken one never sticks.
-    const [failedSrc, setFailedSrc] = useState();
+    const { ref, failed, markFailed } = useImageFailed(src);
     const box = cx(FRAME, IMAGE_WIDTH[width]);
-    if (src && src !== failedSrc) {
-        return (_jsx("img", { ...rest, src: src, alt: alt, className: cx(box, ASPECT[aspect], pictureLook(fit, framed)), onError: () => setFailedSrc(src) }));
+    if (src && !failed) {
+        return (_jsx("img", { ...rest, ref: ref, src: src, alt: alt, className: cx(box, ASPECT[aspect], pictureLook(fit, framed)), onError: markFailed }));
     }
     return (_jsx("span", { ...rest, ...(alt ? { role: "img", "aria-label": alt } : { "aria-hidden": true }), className: cx(box, aspect === "natural" ? PLACEHOLDER_ASPECT : ASPECT[aspect], INSET, "grid place-items-center text-slate-400"), children: _jsx(Icon, { size: "lg", children: _jsx("svg", { viewBox: "0 0 20 20", fill: "currentColor", children: _jsx("path", { d: PICTURE }) }) }) }));
 }

package/dist/PageLayouts.js

@@ -4,8 +4,9 @@ import { Card } from "./Card.js";
 import { cx } from "./cx.js";
 import { PageHeader, PageHeaderContent } from "./PageHeader.js";
 import { STACK_WIDTH, Stack } from "./Stack.js";
+import { useScrollEdges } from "./scrollEdges.js";
 import { scrollStopProps, useScrollStop } from "./scrollStop.js";
-import { STICKY_ASIDE_LG, STICKY_SCROLL_LG } from "./stickyColumn.js";
+import { STICKY_ASIDE_LG, STICKY_FADE_LG, STICKY_SCROLL_LG } from "./stickyColumn.js";
 import { StickyBar } from "./StickyBar.js";
 // Compositions of the layout foundation. None sets a page width or outer padding of its own; the
 // ones that narrow their content do it inside the Container they are rendered in.
@@ -20,9 +21,10 @@ export function ListLayout({ filters, empty, isEmpty = false, children, breadcru
  * itself so its end stays reachable.
  */
 export function DetailLayout({ aside, asideLabel, stickyAside = false, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }) {
-    const { attach, stop } = useScrollStop();
+    const { element, attach, stop } = useScrollStop();
+    useScrollEdges(element, "y");
     const { props, ring } = scrollStopProps(stickyAside && stop, { label: asideLabel });
-    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: cx("min-w-0", stickyAside && STICKY_ASIDE_LG), "aria-label": asideLabel, children: _jsx("div", { ref: stickyAside ? attach : undefined, ...props, className: stickyAside ? cx(STICKY_SCROLL_LG, ring) : undefined, children: _jsx(Stack, { children: aside }) }) })] })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: cx("min-w-0", stickyAside && STICKY_ASIDE_LG), "aria-label": asideLabel, children: _jsx("div", { ref: stickyAside ? attach : undefined, ...props, className: stickyAside ? cx(STICKY_SCROLL_LG, STICKY_FADE_LG, ring) : undefined, children: _jsx(Stack, { children: aside }) }) })] })] }));
 }
 /** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
 export function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, ...form }) {

package/dist/SidebarLayout.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
 import { FoldedColumn } from "./foldedColumn.js";
+import { useScrollEdges } from "./scrollEdges.js";
 import { scrollStopProps, useScrollStop } from "./scrollStop.js";
-import { STICKY_ASIDE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
+import { STICKY_ASIDE_MD, STICKY_FADE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
 /**
  * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
  * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
@@ -16,7 +17,8 @@ import { STICKY_ASIDE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
  * border or a fixed height, and it no longer sits beside the canvas on a phone.
  */
 export function SidebarLayout({ rail, railLabel, children, ...rest }) {
-    const { attach, stop } = useScrollStop();
+    const { element, attach, stop } = useScrollStop();
+    useScrollEdges(element, "y");
     const { props, ring } = scrollStopProps(stop, { label: railLabel });
-    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, ring), children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: railLabel, children: rail })) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
+    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, STICKY_FADE_MD, ring), children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: railLabel, children: rail })) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
 }

package/dist/scrollEdges.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export declare function useScrollEdges(element: HTMLElement | null, axis: "x" | "y"): void;

package/dist/scrollEdges.js

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export function useScrollEdges(element, axis) {
+    useEffect(() => {
+        if (!element)
+            return undefined;
+        const el = element;
+        const update = () => {
+            const [position, scrollSize, clientSize] = axis === "x"
+                ? [el.scrollLeft, el.scrollWidth, el.clientWidth]
+                : [el.scrollTop, el.scrollHeight, el.clientHeight];
+            const start = position > 1;
+            const end = scrollSize - clientSize - position > 1;
+            el.toggleAttribute("data-more-start", start);
+            el.toggleAttribute("data-more-end", end);
+            el.toggleAttribute("data-more", start || end);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
+        resize?.observe(el);
+        for (const child of el.children)
+            resize?.observe(child);
+        return () => {
+            el.removeEventListener("scroll", update);
+            resize?.disconnect();
+        };
+    });
+}

package/dist/stickyColumn.d.ts

@@ -15,3 +15,13 @@ export declare const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)]
 export declare const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
 export declare const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
 export declare const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";
+/**
+ * While a sticky column's scroller has more to scroll to on a side, that edge fades out (a mask, so
+ * it follows any theme), the way AppShell's header row does. `useScrollEdges` sets `data-more-start`
+ * / `data-more-end` (and `data-more` for either); a column that fits has none and is untouched.
+ * Each is prefixed with its breakpoint, below which the column neither sticks nor scrolls and gets
+ * no mask. While the scroller itself holds the keyboard's tab stop (`focus-visible`) the mask is
+ * off, since it would hide the focus ring (an outline) at the faded edges.
+ */
+export declare const STICKY_FADE_MD = "md:data-more-start:[--fade-start:1.5rem] md:data-more-end:[--fade-end:1.5rem] md:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] md:data-more:focus-visible:[mask-image:none]";
+export declare const STICKY_FADE_LG = "lg:data-more-start:[--fade-start:1.5rem] lg:data-more-end:[--fade-end:1.5rem] lg:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] lg:data-more:focus-visible:[mask-image:none]";

package/dist/stickyColumn.js

@@ -15,3 +15,13 @@ export const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)] md:self
 export const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
 export const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
 export const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";
+/**
+ * While a sticky column's scroller has more to scroll to on a side, that edge fades out (a mask, so
+ * it follows any theme), the way AppShell's header row does. `useScrollEdges` sets `data-more-start`
+ * / `data-more-end` (and `data-more` for either); a column that fits has none and is untouched.
+ * Each is prefixed with its breakpoint, below which the column neither sticks nor scrolls and gets
+ * no mask. While the scroller itself holds the keyboard's tab stop (`focus-visible`) the mask is
+ * off, since it would hide the focus ring (an outline) at the faded edges.
+ */
+export const STICKY_FADE_MD = "md:data-more-start:[--fade-start:1.5rem] md:data-more-end:[--fade-end:1.5rem] md:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] md:data-more:focus-visible:[mask-image:none]";
+export const STICKY_FADE_LG = "lg:data-more-start:[--fade-start:1.5rem] lg:data-more-end:[--fade-end:1.5rem] lg:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] lg:data-more:focus-visible:[mask-image:none]";

package/dist/useImageFailed.d.ts

@@ -0,0 +1,19 @@
+import { type RefObject } from "react";
+/**
+ * Whether the picture at `src` has failed to load, for `Avatar` and `Image`, which swap a failed
+ * picture for a fallback. A new `src` gets its own try, so a broken one never sticks.
+ *
+ * A failure is caught two ways. `markFailed` is the img's `onError`, for a picture that fails
+ * after React has attached. On a server-rendered page the browser can fail the picture before
+ * hydration, when the `error` event is already gone, so once the img mounts it is checked as well:
+ * finished (`complete`) with no width (`naturalWidth` 0) means it failed. A picture still loading
+ * or already loaded is left alone.
+ */
+export declare function useImageFailed(src: string | undefined): {
+    /** Pass to the <img>. */
+    ref: RefObject<HTMLImageElement | null>;
+    /** True when there is no `src`, or this `src` has failed. */
+    failed: boolean;
+    /** Pass to the <img>'s `onError`. */
+    markFailed: () => void;
+};

package/dist/useImageFailed.js

@@ -0,0 +1,21 @@
+import { useEffect, useRef, useState } from "react";
+/**
+ * Whether the picture at `src` has failed to load, for `Avatar` and `Image`, which swap a failed
+ * picture for a fallback. A new `src` gets its own try, so a broken one never sticks.
+ *
+ * A failure is caught two ways. `markFailed` is the img's `onError`, for a picture that fails
+ * after React has attached. On a server-rendered page the browser can fail the picture before
+ * hydration, when the `error` event is already gone, so once the img mounts it is checked as well:
+ * finished (`complete`) with no width (`naturalWidth` 0) means it failed. A picture still loading
+ * or already loaded is left alone.
+ */
+export function useImageFailed(src) {
+    const [failedSrc, setFailedSrc] = useState();
+    const ref = useRef(null);
+    useEffect(() => {
+        const img = ref.current;
+        if (src && img?.complete && img.naturalWidth === 0)
+            setFailedSrc(src);
+    }, [src]);
+    return { ref, failed: !src || src === failedSrc, markFailed: () => setFailedSrc(src) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a theme from @hackcove/themes.",
   "keywords": [
     "components",