@haruhimemoe/ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-24
+
+### Added
+
+- `Card` takes `headingLevel` (`2`, `3` or `4`, default `2`), like `FilterPanel`, for a card that sits under another heading.
+
+### Fixed
+
+- `SiteHeader` and `NavLinks` no longer send tailwind-merge to the browser on every page. `NavLinks` is now a Server Component: it merges its classes on the server and hands finished class strings to a small client list that only reads the path for `aria-current`. In a Next.js 16 build, the nav's client chunk drops from about 12 KB to 4 KB gzipped. When no link can be the current page (all external or text-only), the list renders on the server alone and nothing in the nav hydrates.
+- `Prose` no longer puts the `h2` or `h3` top margin above a heading that opens the block: its first child gets `mt-0`. The README shows the one-class pattern for content wrapped in `<section>`s.
+
 ## [0.1.0] - 2026-09-23
 
 ### Added
@@ -19,5 +30,6 @@ 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.1.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.2.0...HEAD
+[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

@@ -2,13 +2,17 @@
 
 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.
 
+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.2.0. Anything marked "since 0.2.0" is not in 0.1.0. [CHANGELOG.md](./CHANGELOG.md) lists what changed in each version.
+
 ## Requirements
 
 - Next.js 16 (app router)
 - React 19
-- Tailwind CSS 4.1 or later
+- Tailwind CSS 4.1 or later, below 5
 
-These are peer dependencies. The package is ESM only.
+These are peer dependencies. The package is ESM only, and its `engines` field asks for Node.js 22.12 or later.
 
 ## Install
 
@@ -147,16 +151,17 @@ export default function Home() {
 
 Import every component from `@haruhimemoe/ui`, in Server and Client Components alike.
 
-- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider`, `FilterPanel` and `NavLinks` (which `SiteHeader` renders for you). Each file starts with `"use client"`.
+- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider` and `FilterPanel`. Each file starts with `"use client"`.
+- **`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.
 
 ## Props, classes and refs
 
-- Every component takes its element's native props and passes them through (`id`, `aria-*`, `data-*`, event handlers). The tables below list only the extra props.
-- `ref` is a normal prop (React 19). Like the native props, it goes on the component's outer element (for `PageShell`, the wrapper `<div>`, not `<main>`).
-- `className` is added after the built-in classes and wins on conflict: a class that sets the same property as a built-in one replaces it (merged with [tailwind-merge](https://github.com/dcastil/tailwind-merge)). `<Select className="w-auto">` drops the built-in `w-full`.
+- Every component takes its element's native props and passes them through (`id`, `aria-*`, `data-*`, event handlers). Each section below names that element. The tables list only the extra props.
+- `ref` is a normal prop (React 19). It goes where the native props go: the outer element for most components, the control (`<input>`, `<select>`, `<textarea>`) for the form fields, and the `<button>` for `CopyButton`. On `PageShell` that is the wrapper `<div>`, not `<main>`.
+- `className` is added after the built-in classes and wins on conflict: a class that sets the same property as a built-in one replaces it (merged with [tailwind-merge](https://github.com/dcastil/tailwind-merge)). `<Select className="w-auto">` drops the built-in `w-full`. On `GitHubIcon` and `HaruhimeWordmark`, `className` replaces the default size instead.
 
 ## Components
 
@@ -176,8 +181,8 @@ 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`.
 
-- An `href` with a scheme (`https:`, `mailto:`) or starting with `//` renders a plain `<a>`, and `next/link`'s own props are dropped.
-- With `target="_blank"` and no `rel`, it adds `rel="noreferrer"`. A `rel` you pass always wins.
+- A string `href` with a scheme (`https:`, `mailto:`) or starting with `//` renders a plain `<a>`, and `next/link`'s own props are dropped.
+- 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`
 
@@ -193,7 +198,8 @@ The osu!-web panel: rounded, `b4` background, `p-5`. Every native `<section>` pr
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `title` | `ReactNode` | none | Rendered as an `<h2>` at the top. It also names the section (`aria-labelledby`), which makes the card a region landmark. |
+| `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. |
 
 #### `PageHeader`
 
@@ -228,6 +234,23 @@ An error notice (`role="alert"`) is announced either way.
 
 Long-form typography for MDX, docs and legal pages. A `max-w-3xl` `<div>` that styles the `h2`, `h3`, `p`, `a`, `strong`, `ul`, `ol`, `li`, `code`, `pre`, `hr` and `table` elements inside it. Every native `<div>` prop.
 
+The first element inside gets no top margin (`[&>:first-child]:mt-0`, since 0.2.0), so a heading that opens the block sits flush with what's above it instead of taking the `h2` or `h3` gap. The rule reaches direct children only. If you wrap the content in `<section>`s, the heading at the top of the first section keeps its margin. Reach one level deeper for that:
+
+```tsx
+<Prose className="[&>:first-child>:first-child]:mt-0">
+  <section>
+    <h2>What we store</h2>
+    <p>Your osu! id and your packs.</p>
+  </section>
+  <section>
+    <h2>How long we keep it</h2>
+    <p>Until you delete your account.</p>
+  </section>
+</Prose>
+```
+
+Later sections keep their heading margin, which spaces them apart.
+
 ### 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.
@@ -315,7 +338,7 @@ schema.org structured data in a `<script type="application/ld+json">`. Every `<`
 
 #### `GitHubIcon`
 
-The GitHub mark as an inline SVG in the current text color. Always hidden from screen readers, so put a label on the link around it. Every native `<svg>` prop.
+The GitHub mark as an inline SVG in the current text color. Hidden from screen readers by default (`aria-hidden="true"`), so put a label on the link around it. Every native `<svg>` prop except `children` and `viewBox`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -323,7 +346,7 @@ The GitHub mark as an inline SVG in the current text color. Always hidden from s
 
 #### `HaruhimeWordmark`
 
-The haruhime.moe wordmark as an inline SVG. It keeps the brand's own white and pink whatever `--hue` is. Every native `<svg>` prop.
+The haruhime.moe wordmark as an inline SVG. It keeps the brand's own white and pink whatever `--hue` is. Every native `<svg>` prop except `children` and `viewBox`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -476,7 +499,7 @@ 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 muted text with its `note` beside it in small uppercase letters (`{ label: "Pools", note: "soon" }`).
+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.
 
 #### `SiteHeader`
 
@@ -492,9 +515,15 @@ The dark top bar: brand on the left, the nav, and an actions slot on the right.
 
 The link for the current page gets `aria-current="page"` and lights up. A section link gets `aria-current="true"` on pages under it (`/packs` while on `/packs/123`). `/` only matches itself.
 
-#### `NavLinks` (client)
+Only a path inside the app can be the current page. External URLs, relative hrefs (`#main`, `?page=2`) and text-only entries never are. Since 0.2.0, when no link can be, the nav skips the client list. With only external and text-only entries, it renders on the server alone and nothing in it hydrates. A relative href still renders `next/link`, which hydrates. When a link can be the current page, a small client list marks it. In 0.1.0 the whole nav is a client component, so it always hydrates.
+
+Rendered from a Server Component, `SiteHeader` and `NavLinks` merge the nav's classes on the server, so tailwind-merge stays out of the browser (since 0.2.0; in 0.1.0 the nav always brings tailwind-merge to the browser). Rendered inside a Client Component, they merge them in the browser and bring tailwind-merge with them.
+
+Next bundles every client component a route imports, rendered or not. So a page with `SiteHeader` still downloads the client list's small chunk (mostly `next/link`), even when the nav rendered on the server alone.
+
+#### `NavLinks`
 
-The `<ul>` of links `SiteHeader` uses, for building your own header. Put it inside a `<nav>`. Every native `<ul>` prop. Type: `SiteNavAlign`.
+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.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -530,7 +559,7 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 
 ## Accessibility
 
-- Every component is checked with axe against the WCAG 2.2 A and AA rules in the test suite (all but color contrast, which needs a real browser). Interactive ones also have keyboard tests.
+- 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).
 - Focus is always visible: the theme draws an `h1` outline on `:focus-visible`. Fields show focus with an `h1` border instead (plus an `h1` ring when invalid), and `RangeSlider` thumbs with a solid `h1` ring. Those keep a transparent outline, so Windows high contrast mode (forced colors) still shows focus.
 - In forced colors mode, a pressed `Chip` takes the system highlight colors, so on and off still look different.
 - Form fields link their label, hint and error. An error sets `aria-invalid` and is announced.
@@ -539,7 +568,7 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 - `CopyButton` announces "Copied." (or the failure) through an `<output>`, on every press.
 - `Pagination` moves focus to its "Page X of Y" text when the link you pressed goes away on the first or last page.
 - `SiteHeader` marks the current page with `aria-current`. `PageShell` starts with a skip link to `<main>`.
-- `GitHubIcon` is always hidden from screen readers: give the link around it an `aria-label`, as `SiteFooter` does.
+- `GitHubIcon` is hidden from screen readers by default: give the link around it an `aria-label`, as `SiteFooter` does.
 - You supply the text, so you also supply labels: give icon-only buttons an `aria-label`, and keep `label` props meaningful.
 
 ## Compatibility
@@ -549,6 +578,7 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 | Next.js | 16 (app router). Components use `next/link` and `next/navigation`. |
 | React | 19 |
 | Tailwind CSS | 4.1 or later (4.x), through `@tailwindcss/postcss` |
+| Node.js | 22.12 or later (`engines`) |
 | Module format | ESM only. Plain Node and Vitest can import it (for component tests in your app). |
 | Theme | Dark only |
 

package/dist/components/basics/Card.d.ts

@@ -1,19 +1,22 @@
 /**
  * @file src/components/basics/Card.tsx
- * @desc osu!-web panel: rounded b4 surface, optional h2 title that labels the region. Server-safe
- *       (useId works in Server Components).
+ * @desc osu!-web panel: rounded b4 surface, optional title (an h2 by default) that labels the
+ *       region. Server-safe (useId works in Server Components).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import { type ComponentProps, type ReactNode } from "react";
-/** Every native `<section>` prop (including `ref`), with `title` rendered as the card's h2. */
+/** Every native `<section>` prop (including `ref`), with `title` rendered as the card's heading. */
 export type CardProps = Omit<ComponentProps<"section">, "title"> & {
     title?: ReactNode | undefined;
+    /** Heading level for the title (default 2). Use 3 or 4 for a card under another heading. */
+    headingLevel?: 2 | 3 | 4 | undefined;
 };
 /**
  * @function Card
- * @param props {CardProps} an optional title that labels the region, plus native section props
+ * @param props {CardProps} an optional title that labels the region, its heading level (default
+ *        2), plus native section props
  * @returns {JSX.Element} a rounded panel, labelled by its title when one is given
  */
-export declare function Card({ title, className, children, ...props }: CardProps): import("react").JSX.Element;
+export declare function Card({ title, headingLevel, className, children, ...props }: CardProps): import("react").JSX.Element;

package/dist/components/basics/Card.js

@@ -1,20 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * @file src/components/basics/Card.tsx
- * @desc osu!-web panel: rounded b4 surface, optional h2 title that labels the region. Server-safe
- *       (useId works in Server Components).
+ * @desc osu!-web panel: rounded b4 surface, optional title (an h2 by default) that labels the
+ *       region. Server-safe (useId works in Server Components).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import { useId } from "react";
 import { cx } from "../../utils/cx.js";
 /**
  * @function Card
- * @param props {CardProps} an optional title that labels the region, plus native section props
+ * @param props {CardProps} an optional title that labels the region, its heading level (default
+ *        2), plus native section props
  * @returns {JSX.Element} a rounded panel, labelled by its title when one is given
  */
-export function Card({ title, className, children, ...props }) {
+export function Card({ title, headingLevel = 2, className, children, ...props }) {
     const headingId = useId();
-    return (_jsxs("section", { "aria-labelledby": title ? headingId : undefined, className: cx("rounded-[10px] bg-b4 p-5 text-c2", className), ...props, children: [title ? (_jsx("h2", { id: headingId, className: "mb-2 font-bold text-c1 text-lg", children: title })) : null, children] }));
+    const Heading = `h${headingLevel}`;
+    return (_jsxs("section", { "aria-labelledby": title ? headingId : undefined, className: cx("rounded-[10px] bg-b4 p-5 text-c2", className), ...props, children: [title ? (_jsx(Heading, { id: headingId, className: "mb-2 font-bold text-c1 text-lg", children: title })) : null, children] }));
 }

package/dist/components/basics/Prose.d.ts

@@ -1,10 +1,11 @@
 /**
  * @file src/components/basics/Prose.tsx
  * @desc Long-form typography for MDX, docs and legal text, styled with the osu!-web tokens.
- *       Styles the plain elements inside it (headings, links, lists, code, tables).
+ *       Styles the plain elements inside it (headings, links, lists, code, tables). The element
+ *       that opens the block gets no top margin, so a leading heading sits flush.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import type { ComponentProps } from "react";
 /** Every native `<div>` prop (including `ref`). */
@@ -13,6 +14,7 @@ export type ProseProps = ComponentProps<"div">;
  * @function Prose
  * @param props {ProseProps} native div props; children are the rendered Markdown or MDX
  * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code and
- *          tables inside it
+ *          tables inside it. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
+ *          which outranks the h2 and h3 margins by specificity.
  */
 export declare function Prose({ className, ...props }: ProseProps): import("react").JSX.Element;

package/dist/components/basics/Prose.js

@@ -4,8 +4,9 @@ import { cx } from "../../utils/cx.js";
  * @function Prose
  * @param props {ProseProps} native div props; children are the rendered Markdown or MDX
  * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code and
- *          tables inside it
+ *          tables inside it. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
+ *          which outranks the h2 and h3 margins by specificity.
  */
 export function Prose({ className, ...props }) {
-    return (_jsx("div", { className: cx("max-w-3xl text-c2 leading-relaxed [&_a:hover]:text-c1 [&_a]:text-h1 [&_a]:underline [&_code]:rounded [&_code]:bg-b4 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:text-[0.9em] [&_h2]:mt-10 [&_h2]:mb-3 [&_h2]:font-bold [&_h2]:text-2xl [&_h2]:text-c1 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:font-bold [&_h3]:text-c1 [&_h3]:text-lg [&_hr]:my-8 [&_hr]:border-b3 [&_li]:mt-1 [&_ol]:list-decimal [&_ol]:pl-6 [&_p]:mt-3 [&_pre]:mt-3 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-b6 [&_pre]:p-3 [&_pre]:text-sm [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_strong]:text-c1 [&_table]:mt-4 [&_table]:w-full [&_table]:text-sm [&_td]:border-b3 [&_td]:border-b [&_td]:px-2 [&_td]:py-1.5 [&_th]:border-b3 [&_th]:border-b [&_th]:px-2 [&_th]:py-1.5 [&_th]:text-left [&_th]:text-c1 [&_ul]:mt-3 [&_ul]:list-disc [&_ul]:pl-6", className), ...props }));
+    return (_jsx("div", { className: cx("max-w-3xl text-c2 leading-relaxed [&>:first-child]:mt-0 [&_a:hover]:text-c1 [&_a]:text-h1 [&_a]:underline [&_code]:rounded [&_code]:bg-b4 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:text-[0.9em] [&_h2]:mt-10 [&_h2]:mb-3 [&_h2]:font-bold [&_h2]:text-2xl [&_h2]:text-c1 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:font-bold [&_h3]:text-c1 [&_h3]:text-lg [&_hr]:my-8 [&_hr]:border-b3 [&_li]:mt-1 [&_ol]:list-decimal [&_ol]:pl-6 [&_p]:mt-3 [&_pre]:mt-3 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-b6 [&_pre]:p-3 [&_pre]:text-sm [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_strong]:text-c1 [&_table]:mt-4 [&_table]:w-full [&_table]:text-sm [&_td]:border-b3 [&_td]:border-b [&_td]:px-2 [&_td]:py-1.5 [&_th]:border-b3 [&_th]:border-b [&_th]:px-2 [&_th]:py-1.5 [&_th]:text-left [&_th]:text-c1 [&_ul]:mt-3 [&_ul]:list-disc [&_ul]:pl-6", className), ...props }));
 }

package/dist/components/shell/NavItem.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file src/components/shell/NavItem.tsx
+ * @desc One entry of the header's nav list (internal): a link, or dimmed text with its note when
+ *       the entry has no href. NavLinks renders it on the server, and NavListClient in the
+ *       browser, so both lists print the same markup.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Thu Sep 24, 2026
+ * @modified Thu Sep 24, 2026
+ */
+import type { SiteLinkItem } from "./links.js";
+/** One nav entry, its aria-current and the finished classes for its link. */
+export type NavItemProps = {
+    item: SiteLinkItem;
+    /** The link's aria-current, from `ariaCurrentFor`. */
+    current?: "page" | "true" | undefined;
+    /** Classes for the link. Ignored for an entry without `href`. */
+    linkClassName: string;
+};
+/**
+ * @function navItemKey
+ * @param item {SiteLinkItem} a nav entry
+ * @returns {string} its React key: the href, or the label for a text-only entry
+ */
+export declare const navItemKey: (item: SiteLinkItem) => string;
+/**
+ * @function NavItem
+ * @param props {NavItemProps} the entry, its aria-current and its link classes
+ * @returns {JSX.Element} an `<li>` with the link, or with dimmed text and the note beside it
+ */
+export declare function NavItem({ item, current, linkClassName }: NavItemProps): import("react").JSX.Element;

package/dist/components/shell/NavItem.js

@@ -0,0 +1,28 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @file src/components/shell/NavItem.tsx
+ * @desc One entry of the header's nav list (internal): a link, or dimmed text with its note when
+ *       the entry has no href. NavLinks renders it on the server, and NavListClient in the
+ *       browser, so both lists print the same markup.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Thu Sep 24, 2026
+ * @modified Thu Sep 24, 2026
+ */
+import { AutoLink } from "./AutoLink.js";
+/**
+ * @function navItemKey
+ * @param item {SiteLinkItem} a nav entry
+ * @returns {string} its React key: the href, or the label for a text-only entry
+ */
+export const navItemKey = (item) => item.href || item.label;
+/**
+ * @function NavItem
+ * @param props {NavItemProps} the entry, its aria-current and its link classes
+ * @returns {JSX.Element} an `<li>` with the link, or with dimmed text and the note beside it
+ */
+export function NavItem({ item, current, linkClassName }) {
+    if (!item.href) {
+        return (_jsx("li", { children: _jsxs("span", { "aria-disabled": "true", className: "text-c4", children: [item.label, item.note ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { className: "text-xs uppercase tracking-wide", children: item.note })] })) : null] }) }));
+    }
+    return (_jsx("li", { children: _jsx(AutoLink, { href: item.href, "aria-current": current, className: linkClassName, children: item.label }) }));
+}

package/dist/components/shell/NavLinks.d.ts

@@ -1,10 +1,11 @@
 /**
  * @file src/components/shell/NavLinks.tsx
- * @desc The header's nav list. A client component only so it can read the current path and set
- *       aria-current on the matching link; SiteHeader around it stays a server component.
+ * @desc The header's nav list. Server-safe: it merges the classes here, then renders the list
+ *       itself when no link can be the current page (external, relative or text-only), or hands
+ *       it to the small NavListClient, which reads the path to set aria-current.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import type { ComponentProps } from "react";
 import { type SiteLinkItem } from "./links.js";
@@ -19,6 +20,9 @@ export type NavLinksProps = Omit<ComponentProps<"ul">, "children"> & {
  * @function NavLinks
  * @param props {NavLinksProps} the links (items without `href` show as dimmed text with their
  *        `note`), the alignment (default "start") and native list props
- * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current
+ * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current.
+ *          When no link can be current, it skips the client list and nothing reads the path.
+ *          From a Server Component with only external and text-only links, nothing hydrates; a
+ *          relative href still renders next/link, which does.
  */
 export declare function NavLinks({ links, align, className, ...props }: NavLinksProps): import("react").JSX.Element;

package/dist/components/shell/NavLinks.js

@@ -1,17 +1,8 @@
-/**
- * @file src/components/shell/NavLinks.tsx
- * @desc The header's nav list. A client component only so it can read the current path and set
- *       aria-current on the matching link; SiteHeader around it stays a server component.
- * @author David @dvhsh (https://dvh.sh)
- * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
- */
-"use client";
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { usePathname } from "next/navigation.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from "../../utils/cx.js";
-import { AutoLink } from "./AutoLink.js";
-import { ariaCurrentFor } from "./links.js";
+import { canBeCurrent } from "./links.js";
+import { NavItem, navItemKey } from "./NavItem.js";
+import { NavListClient } from "./NavListClient.js";
 const LISTS = {
     start: "flex flex-wrap gap-x-5 gap-y-1 font-bold text-sm",
     center: "flex flex-wrap items-center justify-center gap-x-6 gap-y-1 font-bold",
@@ -26,15 +17,15 @@ const CURRENT = "text-c1 transition-colors";
  * @function NavLinks
  * @param props {NavLinksProps} the links (items without `href` show as dimmed text with their
  *        `note`), the alignment (default "start") and native list props
- * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current
+ * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current.
+ *          When no link can be current, it skips the client list and nothing reads the path.
+ *          From a Server Component with only external and text-only links, nothing hydrates; a
+ *          relative href still renders next/link, which does.
  */
 export function NavLinks({ links, align = "start", className, ...props }) {
-    const pathname = usePathname();
-    return (_jsx("ul", { className: cx(LISTS[align], className), ...props, children: links.map((item) => {
-            if (!item.href) {
-                return (_jsx("li", { children: _jsxs("span", { "aria-disabled": "true", className: "text-c4", children: [item.label, item.note ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { className: "text-xs uppercase tracking-wide", children: item.note })] })) : null] }) }, item.label));
-            }
-            const current = ariaCurrentFor(pathname, item.href);
-            return (_jsx("li", { children: _jsx(AutoLink, { href: item.href, "aria-current": current, className: current ? CURRENT : LINKS[align], children: item.label }) }, item.href));
-        }) }));
+    const listClassName = cx(LISTS[align], className);
+    if (!links.some((item) => item.href && canBeCurrent(item.href))) {
+        return (_jsx("ul", { className: listClassName, ...props, children: links.map((item) => (_jsx(NavItem, { item: item, linkClassName: LINKS[align] }, navItemKey(item)))) }));
+    }
+    return (_jsx(NavListClient, { links: links, linkClassName: LINKS[align], currentClassName: CURRENT, className: listClassName, ...props }));
 }

package/dist/components/shell/NavListClient.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/shell/NavListClient.tsx
+ * @desc The nav list that marks the current page (internal). The only client part of the header:
+ *       it reads the pathname to set aria-current. Its classes arrive finished from NavLinks on
+ *       the server, so it imports no class merging and ships no tailwind-merge to the browser.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Thu Sep 24, 2026
+ * @modified Thu Sep 24, 2026
+ */
+import type { ComponentProps } from "react";
+import { type SiteLinkItem } from "./links.js";
+/** Every native `<ul>` prop (including `ref`), plus the links and their finished classes. */
+export type NavListClientProps = Omit<ComponentProps<"ul">, "children"> & {
+    links: readonly SiteLinkItem[];
+    /** Classes for a link that is not the current page. */
+    linkClassName: string;
+    /** Classes for the current page's link. */
+    currentClassName: string;
+};
+/**
+ * @function NavListClient
+ * @param props {NavListClientProps} the links, the classes for current and other links, and
+ *        native list props (`className` already merged)
+ * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current
+ */
+export declare function NavListClient({ links, linkClassName, currentClassName, ...props }: NavListClientProps): import("react").JSX.Element;

package/dist/components/shell/NavListClient.js

@@ -0,0 +1,27 @@
+/**
+ * @file src/components/shell/NavListClient.tsx
+ * @desc The nav list that marks the current page (internal). The only client part of the header:
+ *       it reads the pathname to set aria-current. Its classes arrive finished from NavLinks on
+ *       the server, so it imports no class merging and ships no tailwind-merge to the browser.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Thu Sep 24, 2026
+ * @modified Thu Sep 24, 2026
+ */
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePathname } from "next/navigation.js";
+import { ariaCurrentFor } from "./links.js";
+import { NavItem, navItemKey } from "./NavItem.js";
+/**
+ * @function NavListClient
+ * @param props {NavListClientProps} the links, the classes for current and other links, and
+ *        native list props (`className` already merged)
+ * @returns {JSX.Element} a `<ul>` of links, the one for the current path marked aria-current
+ */
+export function NavListClient({ links, linkClassName, currentClassName, ...props }) {
+    const pathname = usePathname();
+    return (_jsx("ul", { ...props, children: links.map((item) => {
+            const current = item.href ? ariaCurrentFor(pathname, item.href) : undefined;
+            return (_jsx(NavItem, { item: item, current: current, linkClassName: current ? currentClassName : linkClassName }, navItemKey(item)));
+        }) }));
+}

package/dist/components/shell/SiteHeader.d.ts

@@ -1,11 +1,12 @@
 /**
  * @file src/components/shell/SiteHeader.tsx
  * @desc Site header, the osu!-web dark bar: a brand slot on the left, nav links from data, and an
- *       actions slot on the right (an account menu, say). A server component; only the nav list
- *       inside is a client component, to mark the current page.
+ *       actions slot on the right (an account menu, say). A server component. The nav list is a
+ *       small client component only when a link can be the current page; with only external or
+ *       text-only links the whole header renders on the server.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import type { ComponentProps, ReactNode } from "react";
 import type { SiteLinkItem } from "./links.js";

package/dist/components/shell/links.d.ts

@@ -1,10 +1,11 @@
 /**
  * @file src/components/shell/links.ts
- * @desc Link data shared by SiteHeader and SiteFooter, plus the two rules they apply to it: which
- *       hrefs leave the app (plain `<a>`) and which link marks the current page.
+ * @desc Link data shared by SiteHeader and SiteFooter, plus the rules they apply to it: which
+ *       hrefs leave the app (plain `<a>`), which link marks the current page, and which hrefs can
+ *       ever be the current page.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import { isExternalHref } from "../../utils/href.js";
 export { isExternalHref };
@@ -14,6 +15,14 @@ export type SiteLinkItem = {
     href?: string | undefined;
     note?: string | undefined;
 };
+/**
+ * @function canBeCurrent
+ * @param href {string} a nav link target
+ * @returns {boolean} true when some pathname makes `ariaCurrentFor` mark the link, which is only
+ *          for a path in the app ("/packs"). False for external, relative, fragment-only and
+ *          query-only hrefs.
+ */
+export declare const canBeCurrent: (href: string) => boolean;
 /**
  * @function ariaCurrentFor
  * @param pathname {string | null} the current pathname (`usePathname()`), null outside the router

package/dist/components/shell/links.js

@@ -1,14 +1,31 @@
 /**
  * @file src/components/shell/links.ts
- * @desc Link data shared by SiteHeader and SiteFooter, plus the two rules they apply to it: which
- *       hrefs leave the app (plain `<a>`) and which link marks the current page.
+ * @desc Link data shared by SiteHeader and SiteFooter, plus the rules they apply to it: which
+ *       hrefs leave the app (plain `<a>`), which link marks the current page, and which hrefs can
+ *       ever be the current page.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Thu Sep 24, 2026
  */
 import { isExternalHref } from "../../utils/href.js";
 export { isExternalHref };
 const trimSlash = (path) => path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+// The app path an href points at, without query, fragment or trailing slash. Undefined for an
+// href that leaves the app or is relative ("packs", "#main", "?page=2").
+const appPath = (href) => {
+    if (isExternalHref(href))
+        return undefined;
+    const target = trimSlash(href.replace(/[?#].*$/s, ""));
+    return target.startsWith("/") ? target : undefined;
+};
+/**
+ * @function canBeCurrent
+ * @param href {string} a nav link target
+ * @returns {boolean} true when some pathname makes `ariaCurrentFor` mark the link, which is only
+ *          for a path in the app ("/packs"). False for external, relative, fragment-only and
+ *          query-only hrefs.
+ */
+export const canBeCurrent = (href) => appPath(href) !== undefined;
 /**
  * @function ariaCurrentFor
  * @param pathname {string | null} the current pathname (`usePathname()`), null outside the router
@@ -18,10 +35,8 @@ const trimSlash = (path) => path.length > 1 && path.endsWith("/") ? path.slice(0
  *          External and relative hrefs never match, and "/" only matches itself.
  */
 export function ariaCurrentFor(pathname, href) {
-    if (!pathname || isExternalHref(href))
-        return undefined;
-    const target = trimSlash(href.replace(/[?#].*$/s, ""));
-    if (!target.startsWith("/"))
+    const target = appPath(href);
+    if (!pathname || target === undefined)
         return undefined;
     const here = trimSlash(pathname);
     if (here === target)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haruhimemoe/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React components for the haruhime.moe osu! tools on Next.js: the osu!-web-style palette as a Tailwind theme, buttons, cards, form fields, filter controls and the site header and footer.",
   "keywords": [
     "osu",