@haruhimemoe/ui 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,46 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-28
+
+### Added
+
+- `SiteFooter` takes `discordLabel` (default "Discord"), the Discord link's accessible name, as `githubLabel` does for GitHub.
+- `HeadingLevel` (`2 | 3 | 4 | 5 | 6`), the type of `headingLevel` on `Card` and `FilterPanel`.
+- `TextLink` and `linkClasses`: a text link in two looks, `accent` (`h1`, underlined, for running text) and `plain` (bold `c1`, underlined on hover, for names in lists). Like `ButtonLink`, it is `next/link` inside the app and a plain `<a>` off-site.
+- `Badge`: a small pill for a status or tag, in `neutral`, `accent`, `warning` or `muted` (an outlined "beta" tag).
+- Table primitives: `Table` (a sideways-scrolling wrapper, and a caption that can be for screen readers only), `THead`, `TBody`, `Th` (`scope="col"` by default, bold for `scope="row"`) and `Td`, with `numeric` for `tabular-nums` cells. They carry the look the apps' tables share.
+- `cx`, the class merger the components use (tailwind-merge), and its `ClassValue` type.
+- `InlineConfirm`: a two-step confirm in the page. Opening moves focus to cancel; cancel, Escape or a confirm that resolves puts it back on the trigger, so focus never falls to the page body. The open confirm is a group named by its question. A pending confirm keeps focus and ignores presses; a failed one stays open.
+- `AsyncButton`: runs an async action and announces its result (or a failure, in rose) in an `<output>`, one run at a time, with an optional pending label.
+- `Disclosure`: a button with `aria-expanded` and `aria-controls` that shows and hides a panel, which stays in the page while hidden. Uncontrolled, or controlled with `open` and `onOpenChange`.
+- `RadioGroup`: a native radio fieldset on the `Checkbox` look, with a legend, per-option hints, and a group hint and error. Controlled or uncontrolled.
+- `TypeToConfirm`: a form whose submit stays off until a name is typed exactly, for actions that can't be undone.
+- `ChoiceChips`: single-select chips as native radios (arrow keys move and pick), with `Chip`'s look and `ChipGroup`'s `label` and `hideLabel`.
+- `Chip` and `ChipOption` take `unavailableReason`: the chip is blocked but stays focusable (`aria-disabled`), with the reason as its description and title.
+- `LinkTabs`: a named nav of pill links with `aria-current="page"` on the current one.
+- `HeaderMenu`: the header's account disclosure (button, links, extra controls), closed by Escape (focus back on the button), a click outside, a link, or focus leaving it.
+- osu! display pieces: `StarRating` (a pill on osu!'s star-rating spectrum that reads "5.23 stars"), `BeatmapStats` (CS, AR, OD, HP, BPM and length from plain numbers) and `ModBadge` (a slot pill colored by its mod bucket).
+- `Pagination` button mode: `onPageChange` instead of `hrefFor`, for results fetched in place. `pageCount` can be `null` (the status reads "Page X", and `hasNext` says whether Next works). The ends stay in place with `aria-disabled`, and the status is a polite live region.
+
+### Changed
+
+- `Card` takes `headingLevel` `5` and `6` too, like `FilterPanel`.
+
+### Fixed
+
+- Hrefs that browsers read as off-site now count as external: `/\host`, `\\host`, and a URL behind leading spaces or control characters. Before, `ButtonLink` sent them through `next/link` without its `rel="noreferrer"` default, and a nav hydrated its client list for them.
+- `Pagination` normalizes `page` and `pageCount`: `NaN` reads as page 1 (a `NaN` count as one page), a page past either end is pulled back inside, and fractions are dropped. Before, `page={NaN}` showed "Page NaN of 5" with no links, and page 99 of 5 linked to page 98.
+- `CopyButton` reports only the latest press. A slow earlier copy that failed after a later one worked no longer replaces "Copied." with the failure.
+- `SiteHeader` and `NavLinks` key entries by label and href, as `SiteFooter` does, so two entries with the same href no longer share a React key.
+- `Checkbox` keeps an `aria-labelledby` you pass, after its own label. Before, it was dropped.
+- `RangeSlider` counts a `step` of `0`, below `0` or not finite as `1`, and swaps `min` and `max` given the wrong way round. Before, `step={0}` sent `NaN` to `onChange` on every key press or drag.
+
+### Security
+
+- The release workflow pins every GitHub Action to a full commit SHA and npm to an exact version, since that job holds the npm publish token. It also runs the coverage floor and the consumer check before publishing, as CI does. Dependabot (the `bun` and `github-actions` ecosystems) keeps the pins and the exact dependency versions current.
+- Report vulnerabilities through GitHub's private vulnerability reporting first, or by email (SECURITY.md).
+
 ## [0.3.0] - 2026-09-25
 
 ### Added
@@ -37,7 +77,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `className` on every component, and the extras passed to `buttonClasses` and `fieldClasses`, merge with tailwind-merge: a caller's class replaces a built-in one that sets the same property (`fieldClasses("w-auto")` drops `w-full`).
 - Shell: `SiteHeader` (brand slot, nav links as data with `aria-current`, actions slot), `NavLinks`, `SiteFooter` (link columns as data, fine print, the haruhime.moe wordmark and a GitHub link) and `PageShell` (skip link, header, main, footer).
 
-[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.3.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/haruhimemoe/ui/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/haruhimemoe/ui/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/haruhimemoe/ui/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/haruhimemoe/ui/releases/tag/v0.1.0

package/README.md

@@ -1,10 +1,12 @@
+<p align="center"><a href="https://github.com/haruhimemoe/ui"><picture><source media="(prefers-color-scheme: light)" srcset="https://www.haruhime.moe/brand/repos/ui-banner-on-light.svg"><img alt="@haruhimemoe/ui" src="https://www.haruhime.moe/brand/repos/ui-banner.svg" width="640"></picture></a></p>
+
 # @haruhimemoe/ui
 
-React components for the haruhime.moe osu! tools on Next.js. It ships the osu!-web-style palette as a Tailwind 4 theme, plus buttons, cards, form fields, filter controls (toggle chips, a two-thumb range slider, a filter panel) and the site header, footer and page frame. Most components are Server Components. The few that need the browser carry `"use client"` in their own files, so you import everything from one place.
+React components for the haruhime.moe osu! tools on Next.js. It ships the osu!-web-style palette as a Tailwind 4 theme, plus buttons, links, badges, form fields and confirms, filter controls (toggle and choice chips, a two-thumb range slider, a filter panel), tables, osu! beatmap display pieces and the site header, footer, tabs, account menu and page frame. Most components are Server Components. The few that need the browser carry `"use client"` in their own files, so you import everything from one place.
 
 See every component in its states at [haruhime.moe/ui](https://www.haruhime.moe/ui). The page names the version it runs.
 
-This README describes version 0.3.0. Anything marked "since 0.3.0" is not in 0.2.0, and anything marked "since 0.2.0" is not in 0.1.0. [CHANGELOG.md](./CHANGELOG.md) lists what changed in each version.
+This README describes version 0.4.0. Anything marked "since 0.4.0" is not in 0.3.0, anything marked "since 0.3.0" is not in 0.2.0, and anything marked "since 0.2.0" is not in 0.1.0. [CHANGELOG.md](./CHANGELOG.md) lists what changed in each version.
 
 ## Requirements
 
@@ -151,11 +153,11 @@ export default function Home() {
 
 Import every component from `@haruhimemoe/ui`, in Server and Client Components alike.
 
-- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider` and `FilterPanel`. Each file starts with `"use client"`.
+- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider` and `FilterPanel`, and since 0.4.0 `AsyncButton`, `InlineConfirm`, `Disclosure`, `ChoiceChips`, `RadioGroup`, `TypeToConfirm` and `HeaderMenu`. Each file starts with `"use client"`. They merge their classes with tailwind-merge in the browser, so a page that renders any of them loads tailwind-merge (about 9 KB gzipped), however its header renders.
 - **`SiteHeader` and `NavLinks`** are Server Components with a small client part (since 0.2.0; in 0.1.0 `NavLinks` is a client component). When a nav link can be the current page (a path such as `/packs`), a client list reads the path to set `aria-current`. With only external or text-only links, the nav renders on the server alone and nothing in it hydrates. Relative hrefs (`#main`) skip the client list too, but they render `next/link`, which hydrates.
 - **Everything else is server-safe:** no state, no effects, no browser APIs.
 
-A Server Component can't pass a function to a Client Component. So callback props (`onChange`, `onPressedChange`, `onClear`) have to come from your own `"use client"` file, like the filters example below. Props that are plain data (`CopyButton`'s `text`, `Chip`'s `pressed`) work from a Server Component. `Pagination` takes a function (`hrefFor`), but it is a Server Component itself, so that is fine anywhere.
+A Server Component can't pass a function to a Client Component. So callback props (`onChange`, `onPressedChange`, `onClear`) have to come from your own `"use client"` file, like the filters example below. Props that are plain data (`CopyButton`'s `text`, `Chip`'s `pressed`) work from a Server Component. `Pagination` takes a function (`hrefFor`), but it is a Server Component itself, so that is fine anywhere. Its button mode (`onPageChange`) is a callback, so render that from a `"use client"` file.
 
 ## Props, classes and refs
 
@@ -181,7 +183,7 @@ A pill button. Every native `<button>` prop.
 
 A link that looks like `Button`. Every `next/link` prop (`href`, `prefetch`, `replace`, `scroll`, `target`, `rel`...), plus `variant` and `size` as on `Button`.
 
-- A string `href` with a scheme (`https:`, `mailto:`) or starting with `//` renders a plain `<a>`, and `next/link`'s own props are dropped.
+- A string `href` with a scheme (`https:`, `mailto:`) or starting with `//` renders a plain `<a>`, and `next/link`'s own props are dropped. The href is read the way the browser reads it: leading spaces don't count and a backslash counts as a slash, so `/\host` and `\\host` are off-site too (since 0.4.0).
 - That plain `<a>` with `target="_blank"` and no `rel` gets `rel="noreferrer"`. A `rel` you pass always wins. Internal links get only the `rel` you pass.
 
 #### `buttonClasses`
@@ -199,7 +201,7 @@ The osu!-web panel: rounded, `b4` background, `p-5`. Every native `<section>` pr
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `title` | `ReactNode` | none | Rendered as a heading at the top (`<h2>` by default). It also names the section (`aria-labelledby`), which makes the card a region landmark. |
-| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's heading level. Use `3` or `4` for a card that sits under another heading, such as a card inside a titled card. Since 0.2.0. |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | The title's heading level (type `HeadingLevel`). Use `3` or lower for a card that sits under another heading, such as a card inside a titled card. Since 0.2.0; `5` and `6` since 0.4.0. |
 
 #### `PageHeader`
 
@@ -251,6 +253,45 @@ The first element inside gets no top margin (`[&>:first-child]:mt-0`, since 0.2.
 
 Later sections keep their heading margin, which spaces them apart.
 
+#### `Disclosure` (client)
+
+Since 0.4.0. A button that shows and hides a panel below it, with `aria-expanded` and `aria-controls` and a ▾ / ▴ arrow. The closed panel stays in the page, hidden, so fields inside keep their values. Every native `<div>` prop except `children`, for the wrapper.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `summary` | `ReactNode` | required | The button's text. It can change with the state. |
+| `children` | `ReactNode` | required | The panel. |
+| `defaultOpen` | `boolean` | `false` | Whether it starts open. |
+| `open`, `onOpenChange` | `boolean`, `(open: boolean) => void` | none | Control the state from outside. |
+| `buttonClassName`, `panelClassName` | `string` | none | Classes for the button and the panel, merged last. |
+
+#### `TextLink`
+
+Since 0.4.0. A text link: `next/link` inside the app, a plain `<a>` off-site (with `rel="noreferrer"` in a new tab), like `ButtonLink`. Every `next/link` prop. Type: `TextLinkVariant`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `variant` | `"accent" \| "plain"` | `"accent"` | `accent` is `h1` and underlined, for links in running text (it doesn't rely on color alone). `plain` is bold `c1`, underlined on hover, for a name or title in a list or table. |
+
+```tsx
+<p>
+  Scripts can read public packs. <TextLink href="/docs/api">Read the API docs</TextLink>.
+</p>
+<TextLink href={`/packs/${pack.id}`} variant="plain">{pack.name}</TextLink>
+```
+
+#### `linkClasses`
+
+Since 0.4.0. `linkClasses({ variant?, className? }): string` returns the `TextLink` classes, for an element that should look like one (a `<button>` that reads as a link, say). Type: `LinkClassOptions`.
+
+#### `Badge`
+
+Since 0.4.0. A small pill for a status or tag ("Unranked", "beta", a count). A `<span>` with no role, so screen readers read it in line with the text around it. Every native `<span>` prop. Type: `BadgeTone`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `tone` | `"neutral" \| "accent" \| "warning" \| "muted"` | `"neutral"` | `neutral` is `b3` with `c2` text, `accent` is `h1` with dark bold text, `warning` is a faint amber with bold amber text, `muted` is an outlined pill in small bold capitals (a "beta" tag). |
+
 ### Forms
 
 The fields render a label, the control, an optional hint and an optional error, wired together for screen readers. They are Server Components: you pass the `id`, so they need no generated ids.
@@ -285,7 +326,42 @@ Every native `<select>` prop, plus the field props. Pass `<option>` elements as
 
 #### `Checkbox`
 
-Every native `<input>` prop except `type` (`checked`, `defaultChecked`, `onChange`, `name`, `disabled`...), plus the field props. The label is bold `text-c1` and the hint follows it inline after a dot. Clicking anywhere on the row toggles it. The label alone is the accessible name; the hint is the description.
+Every native `<input>` prop except `type` (`checked`, `defaultChecked`, `onChange`, `name`, `disabled`...), plus the field props. The label is bold `text-c1` and the hint follows it inline after a dot. Clicking anywhere on the row toggles it. The label alone is the accessible name; the hint is the description. An `aria-labelledby` you pass is added after the label (since 0.4.0; 0.3.0 dropped it).
+
+#### `RadioGroup` (client)
+
+Since 0.4.0. A native radio group on the `Checkbox` look: a `<fieldset>` named by its `<legend>`, one radio per option with a bold label and an inline hint, then the group's hint and error. Each option's label is its accessible name and its hint its description. Arrow keys move and pick, as native radios do. Every native `<fieldset>` prop except `onChange`, `children` and `defaultValue`; `disabled` turns off every radio. Types: `RadioOption`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | required | The legend. |
+| `options` | `readonly RadioOption[]` | required | `{ value: string; label: ReactNode; hint?: ReactNode; disabled?: boolean }` for each radio. |
+| `value` / `defaultValue` | `string` | none | The picked value, held by you (`value`, with `onChange`) or by the group (`defaultValue`). |
+| `onChange` | `(value: string) => void` | none | Gets the picked option's value. |
+| `name` | `string` | generated | The radios' name, for a form. |
+| `hint`, `error` | `ReactNode` | none | Under the options, linked to the group with `aria-describedby`. An error is a `role="alert"` and marks the radios `aria-invalid`. |
+| `required` | `boolean` | `false` | Every radio gets `required`. |
+
+#### `TypeToConfirm` (client)
+
+Since 0.4.0. A confirm for something that can't be undone: a `<form>` whose submit button stays off until the expected text is typed exactly (spaces around it don't count). The field has no autocomplete, autocapitalize or spellcheck. Enter submits once it matches. Children show above the field, to say what the action does. Every native `<form>` prop except `onSubmit`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `id` | `string` | required | The text field's id, as on `TextInput`. |
+| `expected` | `string` | required | What has to be typed. |
+| `label` | `ReactNode` | `"Type <expected> to confirm"` | The field's label. |
+| `hint`, `error` | `ReactNode` | none | As on `TextInput`. Pass `error` when the action fails. |
+| `submitLabel` | `ReactNode` | required | The button's text. |
+| `pendingLabel` | `ReactNode` | `submitLabel` | The button's text while `onConfirm` runs. It runs once at a time. |
+| `onConfirm` | `() => void \| Promise<void>` | required | Runs on submit once the text matches. If it throws or rejects, the form stays as typed. |
+| `variant` | `"primary" \| "secondary" \| "ghost"` | `"secondary"` | The button's look. |
+
+```tsx
+<TypeToConfirm id="delete-pool" expected={pool.name} submitLabel="Delete this pool" onConfirm={remove} error={error}>
+  <p>This deletes the pool for everyone who edits it. It can't be undone.</p>
+</TypeToConfirm>
+```
 
 #### `fieldClasses`
 
@@ -299,7 +375,7 @@ Every native `<input>` prop except `type` (`checked`, `defaultChecked`, `onChang
 
 #### `CopyButton` (client)
 
-A button that copies text, with the result in an `<output>` beside it that screen readers announce. Each press clears the message first, so a second copy is announced too. If the clipboard is missing or refuses (an insecure page, say), it shows the failure message. Every `Button` prop except `onClick` and `children`; `className` and the native props go on the button.
+A button that copies text, with the result in an `<output>` beside it that screen readers announce. Each press clears the message first, so a second copy is announced too. Only the latest press reports: an earlier copy that settles later (behind a permission prompt, say) doesn't overwrite it (since 0.4.0). If the clipboard is missing or refuses (an insecure page, say), it shows the failure message. Every `Button` prop except `onClick` and `children`; `className` and the native props go on the button.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -313,26 +389,56 @@ A button that copies text, with the result in an `<output>` beside it that scree
 
 #### `Pagination`
 
-Previous and next pill links around "Page X of Y". Renders nothing when there is one page or none. Every native `<nav>` prop; `aria-label` defaults to `"Pages"`.
+Previous and next pills around "Page X of Y": links (`hrefFor`), or since 0.4.0 buttons (`onPageChange`). Renders nothing when there is one page or none. Every native `<nav>` prop except `children`; `aria-label` defaults to `"Pages"`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `page` | `number` | required | The current page, starting at 1. |
 | `pageCount` | `number` | required | How many pages there are. |
-| `hrefFor` | `(page: number) => string` | required | Builds a page's URL, e.g. `` (p) => `/packs?page=${p}` ``. |
+| `hrefFor` | `(page: number) => string` | one of the two | Link mode: builds a page's URL, e.g. `` (p) => `/packs?page=${p}` ``. |
+| `onPageChange` | `(page: number) => void` | one of the two | Button mode (since 0.4.0): called with the page to show, for results fetched in place. `pageCount` may be `null` there. |
+| `hasNext` | `boolean` | `false` | Button mode with `pageCount={null}`: whether a page comes after this one. |
 | `previousLabel` | `ReactNode` | `"Previous"` | Text of the link to the page before. |
 | `nextLabel` | `ReactNode` | `"Next"` | Text of the link to the page after. |
-| `formatStatus` | `(page: number, pageCount: number) => ReactNode` | `"Page X of Y"` | The text in the middle. |
+| `formatStatus` | `(page: number, pageCount: number) => ReactNode` | `"Page X of Y"` | The text in the middle. In button mode `pageCount` can be `null`, and the default reads "Page X". |
+
+A `page` or `pageCount` straight from a URL is safe to pass (since 0.4.0): `NaN` reads as page 1 (and a `NaN` count as one page), a page past either end is pulled back inside, and fractions are dropped. `Number("abc")` shows page 1 with a Next link, and page 99 of 5 shows page 5.
 
 The links use `next/link` with `rel="prev"` and `rel="next"`. On the first and last page one link goes away. If it had keyboard focus (Next pressed on page 4 of 5), focus moves to the "Page X of Y" text instead of falling back to the top of the page. `Pagination` stays a Server Component; that text is a small client component inside it.
 
-#### `JsonLd`
+In button mode, Previous and Next are `<button>`s. At the first or last page they stay in place, dimmed, with `aria-disabled="true"`: they keep focus and ignore presses. The status is a polite live region there, so each new page is announced.
 
-schema.org structured data in a `<script type="application/ld+json">`. Every `<` in the output is escaped, so a string in the data can't close the tag. Native `<script>` props such as `id` and `nonce` pass through.
+```tsx
+<Pagination page={page} pageCount={null} hasNext={data.hasMore} onPageChange={setPage} />
+```
+
+#### `AsyncButton` (client)
+
+Since 0.4.0. A button that runs an async action and reports how it went in an `<output>` beside it that screen readers announce, like `CopyButton`. While it runs, the button keeps focus but ignores presses (`aria-disabled`). Every `Button` prop except `onClick`; the children are its text.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `data` | `Record<string, unknown>` | required | The schema.org object. `@context` defaults to `https://schema.org`; set it in `data` to change it. |
+| `action` | `() => ReactNode \| Promise<ReactNode>` | required | Runs on press. What it returns is the message ("Done."). |
+| `pendingLabel` | `ReactNode` | the children | The button's text while the action runs. |
+| `failedMessage` | `ReactNode \| ((error: unknown) => ReactNode)` | `"Something went wrong. Try again."` | Shown in `text-rose-300` when the action throws or rejects. |
+| `wrapperClassName` | `string` | none | Classes for the wrapper around the button and the message. |
+
+#### `InlineConfirm` (client)
+
+Since 0.4.0. A two-step confirm in the page, no dialog: a trigger button, then the question with a cancel and a confirm button in its place. Opening moves focus to cancel, the safe choice. Cancel or Escape closes it and puts focus back on the trigger, and so does a confirm that resolves. The open confirm is a `<fieldset>` (a group) named by the question, so screen readers hear the question when focus arrives. Every native `<div>` prop except `children`, for the wrapper.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `trigger` | `ReactNode` | required | The first button's text. |
+| `question` | `ReactNode` | required | Shown once the trigger is pressed. |
+| `onConfirm` | `() => void \| Promise<void>` | required | Runs on confirm. While it runs, both buttons keep focus but ignore presses. If it throws or rejects, the confirm stays open: show the error yourself. |
+| `confirmLabel`, `cancelLabel` | `ReactNode` | `"Confirm"`, `"Cancel"` | The two buttons' text. |
+| `pendingLabel` | `ReactNode` | `confirmLabel` | The confirm button's text while `onConfirm` runs. |
+| `onCancel` | `() => void` | none | Called when it closes without confirming. |
+| `triggerProps` | `ButtonProps` | none | Props for the trigger (`aria-label`, `variant`, `disabled`). It is `secondary` by default. |
+| `confirmVariant` | `"primary" \| "secondary" \| "ghost"` | `"secondary"` | The confirm button's look. Cancel is always `ghost`. |
+
+If a confirm removes the item (and the `InlineConfirm` with it), move focus somewhere sensible yourself, such as the list's heading.
 
 ### Icons
 
@@ -366,7 +472,7 @@ The haruhime.moe wordmark as an inline SVG. It keeps the brand's own white and p
 
 #### `HaruhimeWordmarkLink`
 
-A plain `<a>` around a decorative `HaruhimeWordmark`, dimmed until hovered. Every native `<a>` prop.
+A plain `<a>` around a decorative `HaruhimeWordmark`, dimmed until hovered. Every native `<a>` prop except `children`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -436,13 +542,14 @@ Give the `ChipGroup` or `RangeSlider` inside a `FilterRow` `hideLabel`. The row'
 
 #### `Chip` (client)
 
-A toggle pill: a `<button>` with `aria-pressed`, `h1` when on. Every native `<button>` prop.
+A toggle pill: a `<button>` with `aria-pressed`, `h1` when on. Every native `<button>` prop except `aria-pressed`, which `pressed` sets.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `pressed` | `boolean` | required | Whether it is on. |
 | `onPressedChange` | `(pressed: boolean) => void` | none | Called with the new state on click, Enter or Space. |
 | `type` | `"button" \| "submit" \| "reset"` | `"button"` | Never submits a form by default. |
+| `unavailableReason` | `ReactNode` | none | Since 0.4.0. Why the chip can't be pressed right now (EZ with HR picked). The chip is dimmed and never toggles, but stays in the tab order (`aria-disabled="true"`, not `disabled`), so keyboard and screen reader users find it and hear the reason as its description. A string reason is also its `title`. |
 
 Your own `onClick` runs first. Call `event.preventDefault()` in it to skip the toggle.
 
@@ -454,20 +561,33 @@ A labelled row of chips for picking several values (mods, game modes). A `<field
 | --- | --- | --- | --- |
 | `label` | `ReactNode` | required | Names the group. |
 | `hideLabel` | `boolean` | `false` | For use inside a `FilterRow`, which names the row: the label doesn't render and the fieldset isn't a group of its own (`role="none"`). `disabled` still reaches every chip. |
-| `options` | `readonly ChipOption[]` | required | `{ value: string; label: ReactNode; disabled?: boolean }` for each chip. |
+| `options` | `readonly ChipOption[]` | required | `{ value: string; label: ReactNode; disabled?: boolean; unavailableReason?: ReactNode }` for each chip (`unavailableReason` since 0.4.0, as on `Chip`). |
 | `value` | `readonly string[]` | required | The picked values. |
 | `onChange` | `(value: string[]) => void` | required | Gets the new picked values, in the options' order, without duplicates. |
 
+#### `ChoiceChips` (client)
+
+Since 0.4.0. One choice from a few, as a real radio group drawn as chips (a status or type filter): native radios under one name, so Tab reaches the checked chip and the arrow keys move and pick. Same look as `Chip`, with the focus ring on the chip. A `<fieldset>` like `ChipGroup`, with the same `label` and `hideLabel`; every native `<fieldset>` prop except `onChange`, `children` and `defaultValue`. Type: `ChoiceChipOption`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | required | Names the group. |
+| `hideLabel` | `boolean` | `false` | As on `ChipGroup`, inside a `FilterRow`. |
+| `options` | `readonly ChoiceChipOption<T>[]` | required | `{ value: T; label: ReactNode; disabled?: boolean }` for each chip. |
+| `value` | `T` | required | The picked value. |
+| `onChange` | `(value: T) => void` | required | Gets the picked value. |
+| `name` | `string` | generated | The radios' name, for a form. |
+
 #### `RangeSlider` (client)
 
-Two thumbs on one track with an editable box at each end, for star rating, length or BPM. A `<fieldset>`; every native `<fieldset>` prop except `onChange` and `children`. Type: `RangeSliderValue` (`[number, number | null]`), so `useState<RangeSliderValue>` can pass its setter straight in.
+Two thumbs on one track with an editable box at each end, for star rating, length or BPM. A `<fieldset>`; every native `<fieldset>` prop except `onChange`, `children` and `inputMode`. Type: `RangeSliderValue` (`[number, number | null]`), so `useState<RangeSliderValue>` can pass its setter straight in.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `label` | `string` | required | Names the group, and the ends as "Minimum *label*" and "Maximum *label*". |
 | `hideLabel` | `boolean` | `false` | For use inside a `FilterRow`, which names the row: the label doesn't show and the fieldset isn't a group of its own (`role="none"`). The ends keep their "Minimum *label*" and "Maximum *label*" names. |
-| `min`, `max` | `number` | required | The bounds. |
-| `step` | `number` | `1` | Step between values. Typed values snap to it. |
+| `min`, `max` | `number` | required | The bounds. Given the wrong way round (`max` below `min`), they swap (since 0.4.0). |
+| `step` | `number` | `1` | Step between values. Typed values snap to it. A step of `0`, below `0` or not finite counts as `1` (since 0.4.0), so `onChange` never gets `NaN`. |
 | `value` | `readonly [number, number \| null]` | required | The range. A `null` top means no upper limit. |
 | `onChange` | `(value: [number, number \| null]) => void` | required | Gets the new range. |
 | `openEnded` | `boolean` | `false` | The top end at `max` means "no upper limit": it shows `max+` (like `10+`) and reports `null`. |
@@ -494,13 +614,23 @@ A titled panel of `FilterRow`s with a live result count and a "Clear filters" bu
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `title` | `ReactNode` | required | The heading. It also names the panel and the phone toggle. |
-| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | The heading's level. |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | The heading's level (type `HeadingLevel`). |
 | `resultCount` | `ReactNode` | none | Shown in a polite live region, so each new count is announced. |
 | `active` | `boolean` | `false` | Whether any filter is set. |
 | `onClear` | `() => void` | none | The clear button's action. The button shows only when `active` is true and this is set. |
 | `clearLabel` | `ReactNode` | `"Clear filters"` | The clear button's text. |
 | `defaultOpen` | `boolean` | `false` | Whether the rows start open on phones. |
 
+### Meta
+
+#### `JsonLd`
+
+schema.org structured data in a `<script type="application/ld+json">`. Every `<` in the output is escaped, so a string in the data can't close the tag. Every native `<script>` prop except `children`, `dangerouslySetInnerHTML`, `type` and `src` (`id` and `nonce` pass through).
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>` | required | The schema.org object. `@context` defaults to `https://schema.org`; set it in `data` to change it. |
+
 ### Shell
 
 Links in the header and footer are data (type `SiteLinkItem`):
@@ -509,11 +639,11 @@ Links in the header and footer are data (type `SiteLinkItem`):
 type SiteLinkItem = { label: string; href?: string; note?: string };
 ```
 
-Paths use `next/link`; anything with a scheme (`https:`, `mailto:`) or starting with `//` is a plain `<a>`. An item without `href` shows as plain text. `note` adds a word beside it in small uppercase letters (`{ label: "Pools", note: "soon" }`). The header dims text-only items and shows the note only on them. The footer shows a note beside a link too.
+Paths use `next/link`; anything with a scheme (`https:`, `mailto:`) or starting with `//` is a plain `<a>` (and, since 0.4.0, `/\host`, `\\host` or a URL behind leading spaces, which browsers also read as off-site). An item without `href` shows as plain text. `note` adds a word beside it in small uppercase letters (`{ label: "Sheets", note: "soon" }`). The header dims text-only items and shows the note only on them. The footer shows a note beside a link too.
 
 #### `SiteHeader`
 
-The dark top bar: brand on the left, the nav, and an actions slot on the right. Every native `<header>` prop. A Server Component; the nav list inside is `NavLinks`.
+The dark top bar: brand on the left, the nav, and an actions slot on the right. Every native `<header>` prop except `children`. A Server Component; the nav list inside is `NavLinks`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -533,7 +663,7 @@ Next bundles every client component a route imports, rendered or not. So a page
 
 #### `NavLinks`
 
-The `<ul>` of links `SiteHeader` uses, for building your own header. Put it inside a `<nav>`. Every native `<ul>` prop. Type: `SiteNavAlign`. It works in Server and Client Components. Since 0.2.0 it is a Server Component with a small client part (in 0.1.0 it is a client component). From a Server Component it behaves like `SiteHeader`'s nav. Inside a Client Component (a header with a menu toggle, say), it renders in the browser with the rest of that component: it merges its classes there, so tailwind-merge ships in that page's bundle.
+The `<ul>` of links `SiteHeader` uses, for building your own header. Put it inside a `<nav>`. Every native `<ul>` prop except `children`. Type: `SiteNavAlign`. It works in Server and Client Components. Since 0.2.0 it is a Server Component with a small client part (in 0.1.0 it is a client component). From a Server Component it behaves like `SiteHeader`'s nav. Inside a Client Component (a header with a menu toggle, say), it renders in the browser with the rest of that component: it merges its classes there, so tailwind-merge ships in that page's bundle.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -542,7 +672,7 @@ The `<ul>` of links `SiteHeader` uses, for building your own header. Put it insi
 
 #### `SiteFooter`
 
-Link columns, an extra slot, fine print, the haruhime.moe wordmark, a GitHub icon link and an optional Discord icon link. Every native `<footer>` prop. Type: `SiteFooterColumn` (`{ title: string; items: readonly SiteLinkItem[] }`).
+Link columns, an extra slot, fine print, the haruhime.moe wordmark, a GitHub icon link and an optional Discord icon link. Every native `<footer>` prop except `children`. Type: `SiteFooterColumn` (`{ title: string; items: readonly SiteLinkItem[] }`).
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -553,7 +683,30 @@ Link columns, an extra slot, fine print, the haruhime.moe wordmark, a GitHub ico
 | `parentHref` | `string` | `"https://www.haruhime.moe"` | Where the wordmark links. |
 | `githubHref` | `string \| false` | `"https://github.com/haruhimemoe"` | Where the GitHub icon links. `false` leaves it out. |
 | `githubLabel` | `string` | `"haruhimemoe on GitHub"` | The GitHub link's accessible name. |
-| `discordHref` | `string` | none | Where the Discord icon links, such as your server's invite (`https://discord.gg/...`). Without it there is no Discord icon. The icon sits before the GitHub icon at the same size. It stays white (`text-c1`) and dims on hover instead of changing color, since Discord's brand guidelines ask that the logo not be recolored. The link's accessible name is "Discord". Since 0.3.0. |
+| `discordHref` | `string` | none | Where the Discord icon links, such as your server's invite (`https://discord.gg/...`). Without it there is no Discord icon. The icon sits before the GitHub icon at the same size. It stays white (`text-c1`) and dims on hover instead of changing color, since Discord's brand guidelines ask that the logo not be recolored. Since 0.3.0. |
+| `discordLabel` | `string` | `"Discord"` | The Discord link's accessible name. Since 0.4.0. |
+
+#### `LinkTabs`
+
+Since 0.4.0. A row of link tabs (Pools / Maps, All / Hidden): a named `<nav>` with a list of pill links. The current one gets `aria-current="page"` and a `b3` pill (underlined in forced colors mode). These are links, not ARIA tabs, since each loads its own URL. A Server Component: you say which is current. Every native `<nav>` prop except `children`. Type: `LinkTabItem`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `label` | `string` | required | The nav landmark's accessible name. |
+| `items` | `readonly LinkTabItem[]` | required | `{ href: string; label: ReactNode; current?: boolean }` for each tab, each with its own href. |
+
+#### `HeaderMenu` (client)
+
+Since 0.4.0. The header's account menu: a button (an avatar and a name, say) that shows a small panel of links and extra controls such as a sign-out button. It is a disclosure, not an ARIA menu: the button has `aria-expanded` and `aria-controls`, and Tab moves through the panel. Escape closes it and puts focus back on the button; a click outside it, a click on one of its links, or focus leaving it closes it too. Every native `<div>` prop except `children`, for the wrapper. Type: `HeaderMenuItem`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | required | The button's content. |
+| `items` | `readonly HeaderMenuItem[]` | `[]` | `{ href: string; label: ReactNode }` links, top to bottom. |
+| `children` | `ReactNode` | none | Shown after the links, such as a sign-out button. |
+| `align` | `"start" \| "end"` | `"end"` | Which edge of the button the panel lines up with. |
+| `buttonLabel` | `string` | none | The button's accessible name, when its content is only an image. |
+| `buttonClassName` | `string` | none | Classes for the button, merged last. |
 
 #### `PageShell`
 
@@ -568,6 +721,78 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 | `mainId` | `string` | `"main"` | `<main>`'s id, which the skip link targets. |
 | `mainClassName` | `string` | none | Extra classes for `<main>`, e.g. `"max-w-7xl"`. |
 
+### osu!
+
+Since 0.4.0. Display pieces for beatmaps and mod pools. They take plain values (no osu! API types) and are Server Components.
+
+#### `StarRating`
+
+A star-rating pill colored on osu!'s difficulty spectrum: "★ 5.23" on the rating's color, dark text up to 6.5 and pale yellow above. The spectrum is osu!'s own, the same at every `--hue`, so the pill sets its colors inline. Screen readers hear "5.23 stars" and the `label` after it. Every native `<span>` prop except `children`; a `style` you pass merges over the colors.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `value` | `number` | required | The rating, shown with two decimals. `NaN` shows as "–" on grey. |
+| `label` | `ReactNode` | none | Read after the rating by screen readers, e.g. "with HR" (what a `title` tells mouse users). |
+| `unit` | `string` | `"stars"` | The word read after the number. |
+
+#### `BeatmapStats`
+
+A beatmap's CS, AR, OD, HP, BPM and length as a compact `<dl>`, in that order. Stats you leave out (or that aren't finite) don't show. CS, AR, OD, HP and BPM are `<abbr>`s titled with their full names. Every native `<dl>` prop except `children`. Type: `BeatmapStatKey`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `cs`, `ar`, `od`, `hp` | `number \| null` | none | Shown with at most one decimal. |
+| `bpm` | `number \| null` | none | Shown whole. |
+| `lengthSeconds` | `number \| null` | none | Shown as `m:ss`, or `h:mm:ss` from an hour. |
+| `labels` | `Partial<Record<BeatmapStatKey, ReactNode>>` | none | Replaces a label (`{ length: "Länge" }`). |
+
+#### `ModBadge`
+
+A mod pool slot's pill (`NM1`, `HD2`, `TB`), colored by the first two letters: NM sky, HD amber, HR rose, DT and NC violet, FM emerald, TB orange, with dark text. Anything else is a `b3` pill. Every native `<span>` prop; `children` replace the text, and `className` recolors it (`bg-pink-300` for a custom bucket).
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `mod` | `string` | required | The mod or slot label. |
+
+### Tables
+
+Since 0.4.0. `Table`, `THead`, `TBody`, `Th` and `Td` give a data table the apps' look: full width, small left-aligned text, muted capitals in the head and a rule above each body row. They are Server Components, and each takes its element's native props, `className` (merged last) and `ref`. Use plain `<tr>` for rows.
+
+```tsx
+<Table caption="The pool's maps" hideCaption>
+  <THead>
+    <tr>
+      <Th>Slot</Th>
+      <Th numeric>Stars</Th>
+    </tr>
+  </THead>
+  <TBody>
+    {slots.map((slot) => (
+      <tr key={slot.label}>
+        <Th scope="row">{slot.label}</Th>
+        <Td numeric>{slot.stars}</Td>
+      </tr>
+    ))}
+  </TBody>
+</Table>
+```
+
+| Component | Extra props | What it renders |
+| --- | --- | --- |
+| `Table` | `caption?: ReactNode`, `hideCaption?: boolean` (default `false`), `wrapperClassName?: string` | A `<div>` that scrolls sideways on phones, around the `<table>`. `className` and `ref` go on the `<table>`. The caption names the table; `hideCaption` keeps it for screen readers only, when a heading already shows. |
+| `THead` | none | A `<thead>` in `c3`, `text-xs`, uppercase. |
+| `TBody` | none | A `<tbody>` whose rows get a `b4` top border. Add `[&>tr]:align-top` for rows of mixed height. |
+| `Th` | `numeric?: boolean` | A `<th>` with `scope="col"` by default. With `scope="row"` it is a row's heading, in bold `c1`. |
+| `Td` | `numeric?: boolean` | A `<td>`. `numeric` lines up digits (`tabular-nums`). |
+
+Cells get `py-2 pr-3`, and the last cell of a row no right padding.
+
+### Utilities
+
+#### `cx`
+
+Since 0.4.0. `cx(...classes: ClassValue[]): string` is the class merger every component uses: it skips falsy values and resolves Tailwind conflicts with tailwind-merge, so a later class wins (`cx("w-full", cond && "w-auto")`). Type: `ClassValue` (`string | false | null | undefined | 0`). It imports tailwind-merge, so a client file that uses it sends tailwind-merge to the browser.
+
 ## Accessibility
 
 - Every component is checked in the test suite with axe-core's WCAG 2.0, 2.1 and 2.2 A and AA rules (all but color contrast, which needs a real browser). Interactive ones also have keyboard tests. The tests also calculate the contrast figures under Setup (`c1` on `h2`, `h1` on `b4`, and the `--h1-l` and `--h2-l` values).
@@ -595,7 +820,7 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 
 ## Changelog and contributing
 
-See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version and [CONTRIBUTING.md](./CONTRIBUTING.md) to work on the package. Report security issues as described in [SECURITY.md](./SECURITY.md).
+See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version and [CONTRIBUTING.md](./CONTRIBUTING.md) to work on the package. Report security issues as described in [SECURITY.md](./SECURITY.md). Bring questions and feedback to the haruhime.moe [Discord server](https://discord.gg/bKy9kjMV4y).
 
 ## License
 

package/dist/components/actions/AsyncButton.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file src/components/actions/AsyncButton.tsx
+ * @desc A button that runs an async action and says how it went in an <output> beside it (a
+ *       polite live region), like the apps' refresh and retry buttons. While the action runs the
+ *       button stays focusable but ignores presses (aria-disabled), and can show a pending label.
+ *       A rejected action shows the failure message in rose.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ReactNode } from "react";
+import { type ButtonProps } from "../basics/Button.js";
+/** Every Button prop except onClick, plus the action and what to say while and after it runs. */
+export type AsyncButtonProps = Omit<ButtonProps, "onClick"> & {
+    /** Runs on press. What it returns (or resolves to) is shown as the result, e.g. "Done.". */
+    action: () => ReactNode | Promise<ReactNode>;
+    /** The button's text while the action runs. Defaults to the button's children. */
+    pendingLabel?: ReactNode;
+    /** Shown when the action throws or rejects: a message, or a function of the error. */
+    failedMessage?: ReactNode | ((error: unknown) => ReactNode);
+    /** Classes for the wrapper around the button and its status. */
+    wrapperClassName?: string | undefined;
+};
+/**
+ * @function AsyncButton
+ * @param props {AsyncButtonProps} the action, an optional pending label and failure message, plus
+ *        Button props (`className` and `ref` go on the button)
+ * @returns {JSX.Element} the button and an `<output>` that announces the action's result
+ */
+export declare function AsyncButton({ action, pendingLabel, failedMessage, wrapperClassName, className, children, ...props }: AsyncButtonProps): import("react").JSX.Element;

package/dist/components/actions/AsyncButton.js

@@ -0,0 +1,48 @@
+/**
+ * @file src/components/actions/AsyncButton.tsx
+ * @desc A button that runs an async action and says how it went in an <output> beside it (a
+ *       polite live region), like the apps' refresh and retry buttons. While the action runs the
+ *       button stays focusable but ignores presses (aria-disabled), and can show a pending label.
+ *       A rejected action shows the failure message in rose.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { cx } from "../../utils/cx.js";
+import { Button } from "../basics/Button.js";
+import { StatusOutput } from "./StatusOutput.js";
+import { useLatestStatus } from "./useLatestStatus.js";
+/**
+ * @function AsyncButton
+ * @param props {AsyncButtonProps} the action, an optional pending label and failure message, plus
+ *        Button props (`className` and `ref` go on the button)
+ * @returns {JSX.Element} the button and an `<output>` that announces the action's result
+ */
+export function AsyncButton({ action, pendingLabel, failedMessage = "Something went wrong. Try again.", wrapperClassName, className, children, ...props }) {
+    const [pending, setPending] = useState(false);
+    // `pending` reaches the button only after a render; two presses in one frame must not both run.
+    const running = useRef(false);
+    const { status, start, settle } = useLatestStatus();
+    const run = async () => {
+        if (running.current)
+            return;
+        running.current = true;
+        setPending(true);
+        const id = start();
+        try {
+            settle(id, { message: await action(), failed: false });
+        }
+        catch (error) {
+            const message = typeof failedMessage === "function" ? failedMessage(error) : failedMessage;
+            settle(id, { message, failed: true });
+        }
+        finally {
+            running.current = false;
+            setPending(false);
+        }
+    };
+    return (_jsxs("div", { className: cx("flex flex-wrap items-center gap-3", wrapperClassName), children: [_jsx(Button, { "aria-disabled": pending || undefined, onClick: run, className: cx("aria-disabled:cursor-wait aria-disabled:opacity-70", className), ...props, children: pending && pendingLabel !== undefined ? pendingLabel : children }), _jsx(StatusOutput, { run: status?.run ?? null, children: status?.result.failed ? (_jsx("span", { className: "text-rose-300", children: status.result.message })) : (status?.result.message) })] }));
+}

package/dist/components/actions/CopyButton.d.ts

@@ -4,12 +4,12 @@
  *       it (a polite live region), like the packs export and doc pages. If the clipboard is
  *       missing or refuses, it says so and tells the reader to copy by hand. Each press empties
  *       the status first and then writes the result as a new node, so a second copy is announced
- *       too.
+ *       too. Only the latest press reports: a slow earlier copy that settles later is ignored.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type ButtonProps } from "../basics/Button.js";
 /** Every Button prop (native button props, variant, size) except children and onClick. */
 export type CopyButtonProps = Omit<ButtonProps, "children" | "onClick"> & {