@haruhimemoe/ui 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-04
+
+### Added
+
+- `PlayerCard`: osu!-web's user card from plain props (cover, avatar, country and team flags, supporter heart, username linking to the profile, an optional status row). It never fetches; apps pass a snapshot.
+
+## [0.9.0] - 2026-10-03
+
+### Added
+
+- `@haruhimemoe/ui/mdx`: `mdxComponents` (the `a`/`h2`/`h3`/`pre`/`table`/`blockquote` element overrides for `@next/mdx` and `react-markdown`), `CodeBlock` (a fenced code block, Shiki-highlighted when registered), `Callout` (a note/tip/warning aside, also reached through a GitHub-style `> [!NOTE]` blockquote), `parseCodeMeta` and `slugify`.
+- `@haruhimemoe/ui/remark`: `remarkHaruhime` (default export, for Turbopack's module-name-only `remarkPlugins`) plus the named `remarkCodeMeta`, `remarkCallouts` and `remarkHeadingIds`, and `createSlugger`.
+- `@haruhimemoe/ui/shiki`: an opt-in side-effect import (`shiki` is now an optional peer dependency) that registers Shiki's core highlighter for `CodeBlock`. An app that skips it, or doesn't install `shiki`, gets plain code blocks instead of a build failure.
+- `theme.css`: `--shiki-foreground`, `--shiki-background` and the `--shiki-token-*` variables Shiki's CSS-variables theme reads, derived from `--hue` like the rest of the palette.
+
+### Changed
+
+- `Prose` styles a `pre` at any depth, excluding `CodeBlock`'s own (`role="group"`), so a plain `pre` nested inside `li` or `blockquote` keeps its fence look while `CodeBlock` (as `mdxComponents`' `pre` override renders it) keeps its own. `Prose` also styles `blockquote`.
+- `CodeBlock` accepts every native `<div>` prop (`id`, `data-*`, `aria-*`, …) except `code`, `lang`, `title` and `highlight`, spread onto its wrapper.
+
 ## [0.8.0] - 2026-10-03
 
 ### Added
@@ -124,7 +144,9 @@ 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.8.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/haruhimemoe/ui/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/haruhimemoe/ui/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/haruhimemoe/ui/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/haruhimemoe/ui/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/haruhimemoe/ui/compare/v0.5.1...v0.6.0

package/README.md

@@ -2,11 +2,11 @@
 
 # @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, 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, a command palette (mod+k, with the defaults every tool shares) 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.
+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 player cards, a command palette (mod+k, with the defaults every tool shares) 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.8.0. Anything marked "since 0.8.0" is not in 0.7.0, anything marked "since 0.7.0" is not in 0.6.0, anything marked "since 0.6.0" is not in 0.5.0, anything marked "since 0.5.0" is not in 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.
+This README describes version 0.9.0. Anything marked "since 0.9.0" is not in 0.8.0, anything marked "since 0.8.0" is not in 0.7.0, anything marked "since 0.7.0" is not in 0.6.0, anything marked "since 0.6.0" is not in 0.5.0, anything marked "since 0.5.0" is not in 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
 
@@ -814,7 +814,7 @@ The page frame: a skip link, the header, `<main>` and the footer, with the foote
 
 ### osu!
 
-Since 0.4.0. Display pieces for beatmaps and mod pools. They take plain values (no osu! API types) and are Server Components.
+Since 0.4.0. Display pieces for beatmaps, mod pools and (since 0.10.0) players. They take plain values (no osu! API types) and are Server Components.
 
 #### `StarRating`
 
@@ -845,6 +845,174 @@ A mod pool slot's pill (`NM1`, `HD2`, `TB`), colored by the first two letters: N
 | --- | --- | --- | --- |
 | `mod` | `string` | required | The mod or slot label. |
 
+#### `PlayerCard`
+
+Since 0.10.0. osu!-web's user card (the 120px card from the friends list and user tooltips): the profile cover under a dark overlay, the 60px avatar, the country flag, the team flag and the supporter heart, the username, and an optional status row. The whole card links to the osu! profile. Every native `<div>` prop except `children`.
+
+It never fetches. Pass a snapshot you keep yourself (from one osu! API lookup, or typed by hand), so a page of cards costs no API calls and hits no rate limits. Leave `status` out for static data: the card draws no online or offline ring unless told to. Images are plain `<img>` tags (lazy; the avatar and flags are sized), so the app needs no `images.remotePatterns` for osu!'s hosts. A cover ending in `.gif` is hidden when the visitor asks for reduced motion.
+
+```tsx
+<PlayerCard
+  username="peppy"
+  userId={2}
+  countryCode="AU"
+  coverUrl="https://assets.ppy.sh/user-profile-covers/2/….jpeg"
+  team={{ name: "mom?", flagUrl: "https://assets.ppy.sh/teams/flag/1/….png" }}
+  supporter
+  statusText="osu!"
+/>
+```
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `username` | `string` | required | The name on the card. |
+| `userId` | `number` | none | The osu! id: the avatar comes from `https://a.ppy.sh/<id>` and the card links to `https://osu.ppy.sh/users/<id>`. |
+| `href` | `string \| null` | the profile | Replaces the link; `null` draws none. Without a link the name is plain text. A linked card outlines on hover and on keyboard focus. |
+| `avatarUrl` | `string` | from `userId` | Replaces the avatar. With neither, the name's first letter stands in. |
+| `coverUrl` | `string` | none | The cover behind the card. None leaves it plain `b4`. |
+| `countryCode` | `string` | none | ISO 3166-1 alpha-2. Draws osu!'s own flag (`osu.ppy.sh/assets/images/flags/<code points>.svg`); anything but two letters draws none. |
+| `countryName` | `string` | English name from `Intl` | The flag's alt text. |
+| `team` | `{ name, flagUrl }` | none | The team flag beside the country's, its alt text the team's name. |
+| `supporter` | `boolean` | `false` | Draws the supporter heart. |
+| `supporterLabel` | `string` | `"osu! supporter"` | What screen readers hear for the heart. |
+| `status` | `"online" \| "offline"` | none | Draws the status ring (lime online, dark offline). |
+| `statusText` | `ReactNode` | `"Online"`/`"Offline"` with a status | The bottom row's main line: a status, or anything short (a role). |
+| `statusNote` | `ReactNode` | none | A small line above it ("Last seen 29 days ago", "formerly RMarc"). |
+
+The bottom row is left out when there is no status, text or note; the card keeps its 120px height so cards line up in a grid. A card with a cover gets a `b5` overlay at 80%, enough for `c2` text at 12px to keep 4.5:1 over a white cover (axe can't check text over an image).
+
+### MDX (server)
+
+Since 0.9.0. Three subpaths, so an app that never renders Markdown loads none of this: `@haruhimemoe/ui/mdx` (the React pieces: `mdxComponents`, `CodeBlock`, `Callout`), `@haruhimemoe/ui/remark` (plain functions, no React, for `@next/mdx` and `react-markdown`'s `remarkPlugins`), and `@haruhimemoe/ui/shiki` (opt-in code highlighting). The root `@haruhimemoe/ui` export is unchanged.
+
+**With `@next/mdx`:**
+
+```ts
+// next.config.ts
+import createMDX from "@next/mdx";
+
+const withMDX = createMDX({
+  extension: /\.mdx?$/,
+  // Turbopack only takes MDX plugins as module names, not imported functions.
+  options: { remarkPlugins: ["remark-gfm", "@haruhimemoe/ui/remark"] },
+});
+
+export default withMDX({ pageExtensions: ["ts", "tsx", "md", "mdx"] });
+```
+
+```tsx
+// mdx-components.tsx
+import { mdxComponents } from "@haruhimemoe/ui/mdx";
+import "@haruhimemoe/ui/shiki"; // optional: see "Code highlighting" below
+
+export function useMDXComponents(components) {
+  return { ...mdxComponents, ...components };
+}
+```
+
+`remark-gfm` isn't ui's dependency (pin it yourself); without it `@next/mdx` has no pipe tables, and a table with no GFM stays a paragraph.
+
+**With `react-markdown`:**
+
+```tsx
+import { mdxComponents } from "@haruhimemoe/ui/mdx";
+import remarkHaruhime from "@haruhimemoe/ui/remark";
+import remarkGfm from "remark-gfm";
+import Markdown from "react-markdown";
+
+<Markdown components={mdxComponents} remarkPlugins={[remarkGfm, remarkHaruhime]}>
+  {body}
+</Markdown>;
+```
+
+`mdxComponents` must render in a Server Component: `CodeBlock` (its `pre` override hands off to) is async, and a client component can't render an async one. A client-side renderer, like a live editor preview, can't use `pre` from this map; pass your own synchronous override for that case.
+
+If you sanitize the output (`rehype-sanitize` or your own schema), allow `className` on `code` matching `/^language-/`, `dataMeta` on `code`, `dataCallout` on `blockquote`, and `id` on `h2`/`h3`: the remark plugin writes these, and `mdxComponents` reads them back. rehype-sanitize's default `clobberPrefix` renames those heading ids to `user-content-…`; pass `clobberPrefix: ""` (what haruhime.moe uses) to keep the plain id, or live with the prefix and update any hand-written anchor links to match.
+
+#### `mdxComponents`
+
+The element overrides apps pass to `@next/mdx`'s `useMDXComponents` or `react-markdown`'s `components`: `{ a, blockquote, h2, h3, pre, table }`. Spread it and add your own (`{ ...mdxComponents, Example: LiveExample }`).
+
+| Element | Renders |
+| --- | --- |
+| `a` | `https://` opens in a new tab (`rel="noopener noreferrer"`); a same-page `#hash` is a plain anchor; everything else goes through `AutoLink` (`next/link`, or a plain `<a>` off-site). |
+| `h2`, `h3` | The heading with its id (from the remark plugin, or a `slugify` of its own text) and, beside it, a `#` anchor link (`aria-label="Link to section: …"`, always visible in `c4`, turning `h1` on hover, never only on hover). |
+| `pre` | Reads its single `code` child (text, `language-x` class, the fence's meta) and renders `CodeBlock`. Anything else (a `pre` with no single `code` child) renders as a plain, focusable `<pre>`. |
+| `table` | The table wrapped in a focusable, named scroll region: `<div role="group" tabIndex={0} aria-label="…">`, labelled by the table's `<caption>` text, or `"Table"` without one. |
+| `blockquote` | A blockquote the remark plugin marked `data-callout` renders as `Callout` of that type; any other blockquote renders plainly. |
+
+#### `CodeBlock`
+
+An async Server Component: a header bar (the fence's `title`, or the language name, or `"Code"`) with a copy button, over a `<pre role="group" tabIndex={0}>` of lines. Every native `<div>` prop goes on the wrapper except `code`, `lang`, `title` and `highlight`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `code` | `string` | required | The text. Any line endings (`\r\n`, a trailing newline) are normalized; a lone trailing newline doesn't add a phantom last line. |
+| `lang` | `string` | none | A Shiki language id or alias (`ts`, `tsx`, `js`, `json`, `bash`/`sh`/`shell`, `css`, `html`, `md`/`markdown`, `diff`, `yaml`/`yml`). Unknown languages render plain. |
+| `title` | `string` | none | Shown in the header instead of the language; also names the `<pre>` and the copy button ("Copy x.ts"). |
+| `highlight` | `readonly number[]` | `[]` | 1-based line numbers to mark: an `h1` left border and a `b4` tint (`forced-colors:border-[Highlight]` keeps the mark visible under Windows high contrast). |
+
+In MDX, pass these through the fence's meta string instead of writing `CodeBlock` by hand: ` ```ts title="pool.ts" {2,4-5}`. `parseCodeMeta` reads `title="…"` or `title='…'` and `{1,3-5}` ranges (anything else is ignored, and it never throws); the language comes from the fence's own tag.
+
+#### Code highlighting
+
+`shiki` is an optional peer dependency: apps that never render code don't install it, and ui's only runtime dependency stays `tailwind-merge`. An app that renders code:
+
+```sh
+bun add shiki
+```
+
+```ts
+// in the module that renders code: mdx-components.tsx, or next to your react-markdown call
+import "@haruhimemoe/ui/shiki";
+```
+
+That import is a side effect: it registers a Shiki core highlighter (`shiki/core` with the no-WASM JS regex engine, loaded through dynamic `import()`) under `@haruhimemoe/ui/mdx`'s `CodeBlock`. The registration lives on `globalThis` for the whole process, not per module graph, but it only exists once the import has actually run: put it in the module that renders code (`mdx-components.tsx`, which reaches every MDX page, or directly beside your `react-markdown` renderer) so it runs before `CodeBlock` does. `package.json`'s `sideEffects` lists `./dist/shiki.js`, so bundlers don't drop the bare import; Turbopack resolves even a dynamic `import("shiki/core")` at build time, which is why highlighting is a separate subpath instead of `CodeBlock` importing it unconditionally.
+
+Without the import, `CodeBlock` renders plain, unstyled lines, and in development it logs one `console.warn` per process ("code blocks aren't highlighted…"). A highlighter that fails to load (a missing package, a broken build) falls back the same way, warned once.
+
+Tokens render as `<span style={{ color: "var(--shiki-token-…)" }}>`, no injected Shiki HTML, through `--shiki-*` custom properties in `theme.css` (see "Setup" above for loading it). They follow `--hue` like the rest of the palette: `--shiki-foreground` and `--shiki-background` are `c2`/`b6`; `-punctuation` is `c3` and `-comment` is `c4`, the palette tokens as-is; `-keyword` and `-link` are `hsl(var(--hue) 100% 78%)`, the palette's own hue with no offset; `-string`, `-string-expression`, `-constant`, `-function` and `-parameter` are each `calc(var(--hue) + N)`, a hue-offset HSL value. Every one stays at or above 4.5:1 against both `b6` (the block's background) and `b4` (a highlighted line's tint) at every integer hue. `keyword` and `link` get their own fixed lightness instead of reusing `h1`: `h1`'s default (76%) drops to 4.33:1 against `b4` at hue 240, and a `--h1-l` override written for other text shouldn't silently recolor code too.
+
+#### `Callout`
+
+A labelled aside: a left-border panel (`role="note"`) with an icon and a bold label, usable directly in MDX or rendered by `mdxComponents`' `blockquote` override.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `type` | `"note" \| "tip" \| "warning"` | `"note"` | The border color, icon and default label (`h1` / `c2` / `h2` border; "Note" / "Tip" / "Warning"). The type is in the text, never color alone. |
+| `title` | `ReactNode` | the type's label | Replaces the default label. |
+| `children` | `ReactNode` | required | The body. |
+
+GitHub-style callout syntax works through the remark plugin: a blockquote whose first paragraph starts with `[!NOTE]`, `[!TIP]`, `[!WARNING]` (case-insensitive; GitHub's `[!IMPORTANT]` maps to `tip`, `[!CAUTION]` to `warning`) becomes a `Callout` of that type, the marker stripped:
+
+```md
+> [!NOTE]
+> Packs are deleted after 90 days of no edits.
+```
+
+Or write `<Callout type="tip">` directly in an `.mdx` file.
+
+#### `@haruhimemoe/ui/remark`
+
+Plain functions (no React), for `remarkPlugins`. Default export `remarkHaruhime(options?)` runs all three transforms below in order and is what Turbopack needs by module name: `remarkPlugins: ["@haruhimemoe/ui/remark"]`. Named exports `remarkCodeMeta`, `remarkCallouts` and `remarkHeadingIds` run one each, for `react-markdown`'s array form or a custom pipeline.
+
+| Option (all default `true`) | Turns off |
+| --- | --- |
+| `codeMeta` | Copying a fenced code block's meta string onto `data-meta`, which `CodeBlock`'s fence syntax (`title=`, `{…}`) reads. |
+| `callouts` | The `[!NOTE]` / `[!TIP]` / `[!WARNING]` blockquote markers. |
+| `headingIds` | Slugged, deduplicated ids on `h2`/`h3` (a heading that already has one keeps it). |
+
+`slugify(text)` and `createSlugger()` are also exported: lowercase, Unicode-aware (letters, marks, digits and underscores from any script survive; everything else but whitespace and hyphens is dropped), spaces to hyphens, repeats suffixed `-1`, `-2` like GitHub's own heading anchors. `@haruhimemoe/ui/mdx` re-exports `slugify` for apps that build their own heading links.
+
+#### Accessibility
+
+- The `<pre>` `CodeBlock` renders and the `<div>` `mdxComponents`' `table` wraps a table in are both `role="group"` with `tabIndex={0}` and an `aria-label` (`pre` may not be named on its own): keyboard users can reach a sideways scroll that a mouse would otherwise require. Do the same for any `pre` you render yourself inside `Prose`.
+- Heading anchor links are always visible (`c4`, turning `h1` on hover), never hover-only, and at least 24px; their `aria-label` ("Link to section: …") keeps the heading's own accessible name as its own text.
+- `CodeCopyButton` reports "Copied" or "Copy failed" through a live region mounted before use, like `CopyButton`.
+- `Callout` is `role="note"` with the type in text, not color alone; highlighted code lines keep a `forced-colors` border so Windows high contrast mode still shows them.
+
+`Prose` (in "Basics" above) styles a direct-child `pre` with its own fence look, so `CodeBlock` (which isn't a direct child; `mdxComponents`' `pre` override renders it) is untouched when both are in play. `Prose` also styles `blockquote`.
+
 ### Palette (client)
 
 Since 0.8.0. A command palette: press Ctrl K (⌘K on a Mac) anywhere on the page and a dialog opens with a search box over everything the app can do. It is one component for every haruhime tool: `CommandPalette` is the engine, `siteCommands` the defaults every site shares, and each app plugs in its own commands, pages and search providers through the same `Command` and `Provider` types. No new dependency.

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

@@ -1,11 +1,14 @@
 /**
  * @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). The element
- *       that opens the block gets no top margin, so a leading heading sits flush.
+ *       Styles the plain elements inside it (headings, links, lists, code, tables, blockquotes).
+ *       The element that opens the block gets no top margin, so a leading heading sits flush. Any
+ *       `pre` at any depth (including one nested inside `li` or `blockquote`) gets Prose's fence
+ *       styles, except CodeBlock's own `pre` (`role="group"`, the `./mdx` subpath's fenced code
+ *       renderer), which keeps its own look untouched.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Thu Sep 24, 2026
+ * @modified Sat Oct 3, 2026
  */
 import type { ComponentProps } from "react";
 /** Every native `<div>` prop (including `ref`). */
@@ -13,8 +16,8 @@ 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. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
- *          which outranks the h2 and h3 margins by specificity.
+ * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code,
+ *          tables and blockquotes 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

@@ -3,10 +3,10 @@ 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. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
- *          which outranks the h2 and h3 margins by specificity.
+ * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code,
+ *          tables and blockquotes 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 [&>: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 }));
+    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 [&_blockquote]:mt-3 [&_blockquote]:border-b2 [&_blockquote]:border-l-2 [&_blockquote]:pl-4 [&_blockquote]:text-c3 [&_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:not([role=group])]:mt-3 [&_pre:not([role=group])]:overflow-x-auto [&_pre:not([role=group])]:rounded-md [&_pre:not([role=group])]:bg-b6 [&_pre:not([role=group])]:p-3 [&_pre:not([role=group])]: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/mdx/Callout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file src/components/mdx/Callout.tsx
+ * @desc A labelled aside for MDX prose (note, tip, warning): a left-border panel with an icon and
+ *       a bold label, rendered by MdxBlockquote for a GitHub-style `> [!NOTE]` blockquote, or
+ *       usable directly in hand-written MDX.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps, ReactNode } from "react";
+import type { CalloutType } from "../../remark/callouts.js";
+export type { CalloutType };
+/** Every native `<div>` prop except `title` (replaced by the callout's own label slot). */
+export type CalloutProps = Omit<ComponentProps<"div">, "title"> & {
+    type?: CalloutType | undefined;
+    title?: ReactNode;
+};
+/**
+ * @function Callout
+ * @param props {CalloutProps} the callout type (default "note"), an optional title replacing
+ *        the type's default label, native div props and children
+ * @returns {JSX.Element} a bordered, labelled panel announced as a note
+ */
+export declare function Callout({ type, title, className, children, ...props }: CalloutProps): import("react").JSX.Element;

package/dist/components/mdx/Callout.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+const LABEL = { note: "Note", tip: "Tip", warning: "Warning" };
+const BORDER = {
+    note: "border-h1",
+    tip: "border-c2",
+    warning: "border-h2",
+};
+const ICON = {
+    note: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm1 15h-2v-6h2Zm0-8h-2V7h2Z",
+    tip: "M9 21h6v-2H9Zm3-19a7 7 0 0 0-4 12.7V17h8v-2.3A7 7 0 0 0 12 2Z",
+    warning: "M1 21h22L12 2Zm12-3h-2v-2h2Zm0-4h-2v-4h2Z",
+};
+/**
+ * @function Callout
+ * @param props {CalloutProps} the callout type (default "note"), an optional title replacing
+ *        the type's default label, native div props and children
+ * @returns {JSX.Element} a bordered, labelled panel announced as a note
+ */
+export function Callout({ type = "note", title, className, children, ...props }) {
+    return (_jsxs("div", { role: "note", className: cx("mt-4 rounded-md border-l-4 bg-b5 px-4 py-3 text-c2", BORDER[type], className), ...props, children: [_jsxs("p", { className: "mt-0! flex items-center gap-2 font-bold text-c1", children: [_jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", className: "size-4 shrink-0 fill-current", children: _jsx("path", { d: ICON[type] }) }), title ?? LABEL[type]] }), _jsx("div", { className: "[&>:first-child]:mt-1", children: children })] }));
+}

package/dist/components/mdx/CodeBlock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/mdx/CodeBlock.tsx
+ * @desc A fenced code block rendered with Shiki highlighting when the app registered it (by
+ *       importing `@haruhimemoe/ui/shiki`) and the language is one of the bundled set, plain text
+ *       otherwise. Async so it can await the lazily-loaded highlighter from highlighter.ts.
+ *       Server-safe: the only client piece is the copy button (CodeCopyButton).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** The code (any line endings, trailing newline optional), language, title, highlighted lines
+ *  and every other native `<div>` prop (spread onto the wrapper). */
+export type CodeBlockProps = Omit<ComponentProps<"div">, "title" | "children"> & {
+    code: string;
+    lang?: string | undefined;
+    title?: string | undefined;
+    highlight?: readonly number[] | undefined;
+};
+/**
+ * @function CodeBlock
+ * @param props {CodeBlockProps} the code, optional language, title, highlighted line numbers and
+ *        wrapper class
+ * @returns {Promise<JSX.Element>} a header (name and copy button) over a highlighted `<pre>`
+ */
+export declare function CodeBlock({ code, lang, title, highlight, className, ...rest }: CodeBlockProps): Promise<import("react").JSX.Element>;

package/dist/components/mdx/CodeBlock.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+import { CodeCopyButton } from "./CodeCopyButton.js";
+import { getHighlighter, THEME } from "./highlighter.js";
+const BASE = "block min-h-6 border-l-2 px-3";
+const LINE = `${BASE} border-transparent`;
+// Never both border colors on one element: Tailwind emits border-h1 before border-transparent.
+const MARKED = `${BASE} border-h1 bg-b4 forced-colors:border-[Highlight]`;
+/** Shiki's tokens per line, or null to render plain text. */
+const tokenize = async (code, lang) => {
+    if (!lang)
+        return null;
+    const highlighter = await getHighlighter();
+    if (!highlighter?.getLoadedLanguages().includes(lang.toLowerCase()))
+        return null;
+    try {
+        return highlighter.codeToTokens(code, { lang: lang.toLowerCase(), theme: THEME }).tokens;
+    }
+    catch {
+        return null;
+    }
+};
+const tokenStyle = (token) => ({
+    color: token.color,
+    fontStyle: (token.fontStyle ?? 0) & 1 ? "italic" : undefined,
+    fontWeight: (token.fontStyle ?? 0) & 2 ? "bold" : undefined,
+});
+/**
+ * @function CodeBlock
+ * @param props {CodeBlockProps} the code, optional language, title, highlighted line numbers and
+ *        wrapper class
+ * @returns {Promise<JSX.Element>} a header (name and copy button) over a highlighted `<pre>`
+ */
+export async function CodeBlock({ code, lang, title, highlight = [], className, ...rest }) {
+    const text = code.replace(/\r\n?/g, "\n").replace(/\n$/, "");
+    const tokens = await tokenize(text, lang);
+    const lines = tokens ?? text.split("\n").map((content) => [{ content, offset: 0 }]);
+    const marked = new Set(highlight);
+    const name = title ?? lang;
+    return (_jsxs("div", { className: cx("mt-3 overflow-hidden rounded-md border border-b3 bg-b6", className), ...rest, children: [_jsxs("div", { className: "flex min-h-9 items-center justify-between gap-3 border-b3 border-b px-3 py-1 text-c3 text-sm", children: [_jsx("span", { className: "truncate", children: name ?? "Code" }), _jsx(CodeCopyButton, { code: text, label: title ? `Copy ${title}` : "Copy code" })] }), _jsx("pre", { role: "group", 
+                // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+                tabIndex: 0, "aria-label": name ? `Code: ${name}` : "Code", className: "overflow-x-auto py-3 text-c2 text-sm leading-6", children: _jsx("code", { children: lines.flatMap((line, index) => {
+                        const span = (_jsx("span", { className: marked.has(index + 1) ? MARKED : LINE, "data-highlighted": marked.has(index + 1) ? "" : undefined, children: line.map((token, i) => tokens ? (_jsx("span", { style: tokenStyle(token), children: token.content }, i)) : (token.content)) }, index));
+                        // A plain "\n" text node between line spans (no key needed on a bare string): kept
+                        // out of the last line so there's no trailing phantom newline.
+                        return index < lines.length - 1 ? [span, "\n"] : [span];
+                    }) }) })] }));
+}

package/dist/components/mdx/CodeCopyButton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/CodeCopyButton.tsx
+ * @desc The copy button CodeBlock renders beside a code fence's header: copies the plain code
+ *       text and reports "Copied" or "Copy failed" in a polite live region, like CopyButton. A
+ *       server component (CodeBlock) renders this client file, so it takes a finished class
+ *       string and never imports cx, keeping tailwind-merge out of the client bundle.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The code to copy, and the button's accessible name (e.g. "Copy x.ts" or "Copy code"). */
+export type CodeCopyButtonProps = {
+    code: string;
+    label: string;
+};
+/**
+ * @function CodeCopyButton
+ * @param props {CodeCopyButtonProps} the code to copy and the button's accessible name
+ * @returns {JSX.Element} the copy button and an `<output>` announcing "Copied" or "Copy failed"
+ */
+export declare function CodeCopyButton({ code, label }: CodeCopyButtonProps): import("react").JSX.Element;

package/dist/components/mdx/CodeCopyButton.js

@@ -0,0 +1,34 @@
+/**
+ * @file src/components/mdx/CodeCopyButton.tsx
+ * @desc The copy button CodeBlock renders beside a code fence's header: copies the plain code
+ *       text and reports "Copied" or "Copy failed" in a polite live region, like CopyButton. A
+ *       server component (CodeBlock) renders this client file, so it takes a finished class
+ *       string and never imports cx, keeping tailwind-merge out of the client bundle.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StatusOutput } from "../actions/StatusOutput.js";
+import { useLatestStatus } from "../actions/useLatestStatus.js";
+const BUTTON = "inline-flex min-h-6 min-w-6 items-center justify-center rounded px-2 py-0.5 text-c2 text-sm hover:bg-b4 hover:text-c1";
+/**
+ * @function CodeCopyButton
+ * @param props {CodeCopyButtonProps} the code to copy and the button's accessible name
+ * @returns {JSX.Element} the copy button and an `<output>` announcing "Copied" or "Copy failed"
+ */
+export function CodeCopyButton({ code, label }) {
+    const { status, start, settle } = useLatestStatus();
+    const copy = async () => {
+        const run = start();
+        try {
+            await navigator.clipboard.writeText(code);
+            settle(run, "copied");
+        }
+        catch {
+            settle(run, "failed");
+        }
+    };
+    return (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(StatusOutput, { run: status?.run ?? null, children: status?.result === "copied" ? "Copied" : "Copy failed" }), _jsx("button", { type: "button", "aria-label": label, className: BUTTON, onClick: copy, children: "Copy" })] }));
+}

package/dist/components/mdx/MdxBlockquote.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/mdx/MdxBlockquote.tsx
+ * @desc react-markdown/MDX's `blockquote` override: a blockquote carrying `data-callout` (set by
+ *       the `remarkCallouts` plugin on a GitHub-style `> [!NOTE]` blockquote) renders as a
+ *       Callout of that type, with every other prop (className, id, …) forwarded to it; any other
+ *       blockquote renders plainly. Drops the `node` prop react-markdown passes to every
+ *       component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native `<blockquote>` prop, plus `node` (dropped) and the callout plugin's marker. */
+export type MdxBlockquoteProps = ComponentProps<"blockquote"> & {
+    node?: unknown;
+    "data-callout"?: string;
+};
+/**
+ * @function MdxBlockquote
+ * @param props {MdxBlockquoteProps} native blockquote props and an optional `data-callout` type
+ * @returns {JSX.Element} a Callout for a known `data-callout` type, otherwise a plain blockquote
+ */
+export declare function MdxBlockquote({ node: _node, "data-callout": callout, children, ...props }: MdxBlockquoteProps): import("react").JSX.Element;

package/dist/components/mdx/MdxBlockquote.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Callout } from "./Callout.js";
+const TYPES = ["note", "tip", "warning"];
+/**
+ * @function MdxBlockquote
+ * @param props {MdxBlockquoteProps} native blockquote props and an optional `data-callout` type
+ * @returns {JSX.Element} a Callout for a known `data-callout` type, otherwise a plain blockquote
+ */
+export function MdxBlockquote({ node: _node, "data-callout": callout, children, ...props }) {
+    if (callout && TYPES.includes(callout)) {
+        // Callout's props are a div's (ComponentProps<"blockquote"> isn't literally
+        // ComponentProps<"div">, e.g. `ref`), but every field react-markdown passes here (className,
+        // id, aria-*, data-*) is one Callout already forwards straight onto its own div.
+        return (_jsx(Callout, { type: callout, ...props, children: children }));
+    }
+    return _jsx("blockquote", { ...props, children: children });
+}

package/dist/components/mdx/MdxHeading.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/mdx/MdxHeading.tsx
+ * @desc react-markdown/MDX's `h2`/`h3` override: gives the heading a stable id (the given `id`,
+ *       from remark's heading-id plugin, or a slug of its own text) and a hover-revealed anchor
+ *       link beside it. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native heading prop, plus the `node` react-markdown passes (dropped). */
+export type MdxHeadingProps = ComponentProps<"h2"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxH2
+ * @param props {MdxHeadingProps} native h2 props and an optional id
+ * @returns {JSX.Element} an `<h2>` with a slug id and an anchor link
+ */
+export declare const MdxH2: ({ node: _node, id, children, ...props }: MdxHeadingProps) => import("react").JSX.Element;
+/**
+ * @function MdxH3
+ * @param props {MdxHeadingProps} native h3 props and an optional id
+ * @returns {JSX.Element} an `<h3>` with a slug id and an anchor link
+ */
+export declare const MdxH3: ({ node: _node, id, children, ...props }: MdxHeadingProps) => import("react").JSX.Element;

package/dist/components/mdx/MdxHeading.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { slugify } from "../../remark/slugify.js";
+import { textOf } from "./textOf.js";
+const WRAP = "group flex items-baseline gap-2 [&:first-child>:first-child]:mt-0";
+// The ! wins over Prose's [&_a]:text-h1 and [&_a]:underline, which outrank plain utilities.
+const ANCHOR = "inline-flex min-h-6 min-w-6 items-center justify-center rounded text-c4! no-underline! hover:text-h1!";
+const heading = (Tag) => function MdxHeading({ node: _node, id, children, ...props }) {
+    const text = textOf(children);
+    const slug = id ?? slugify(text);
+    return (_jsxs("div", { className: WRAP, children: [_jsx(Tag, { id: slug || undefined, ...props, children: children }), slug ? (_jsx("a", { href: `#${slug}`, "aria-label": `Link to section: ${text}`, className: ANCHOR, children: "#" })) : null] }));
+};
+/**
+ * @function MdxH2
+ * @param props {MdxHeadingProps} native h2 props and an optional id
+ * @returns {JSX.Element} an `<h2>` with a slug id and an anchor link
+ */
+export const MdxH2 = heading("h2");
+/**
+ * @function MdxH3
+ * @param props {MdxHeadingProps} native h3 props and an optional id
+ * @returns {JSX.Element} an `<h3>` with a slug id and an anchor link
+ */
+export const MdxH3 = heading("h3");

package/dist/components/mdx/MdxLink.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/components/mdx/MdxLink.tsx
+ * @desc react-markdown/MDX's `a` override: an external `http(s)` href opens in a new tab with a
+ *       safe rel (full props spread, like the `<a>` AutoLink itself renders for an off-app href);
+ *       a same-page hash link is a plain anchor, since AutoLink's own `isExternalHref` check
+ *       doesn't treat `#usage` as external and would otherwise send it through next/link, which
+ *       has no reason to handle a same-page jump; everything else (internal paths, `mailto:` and
+ *       other schemes) goes through AutoLink, which already picks `next/link` or a plain `<a>` by
+ *       href and spreads every other prop onto whichever element it renders. No `href` at all (a
+ *       README `<a name>`/`<a id>` anchor via rehype-raw) renders a plain `<a>` with no `href`
+ *       attribute, not a focusable empty link. Drops the `node` prop react-markdown passes to
+ *       every component, so it never reaches the DOM.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native `<a>` prop, plus the `node` react-markdown passes (dropped, never rendered). */
+export type MdxLinkProps = ComponentProps<"a"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxLink
+ * @param props {MdxLinkProps} the link's href and native anchor props
+ * @returns {JSX.Element} an external link (new tab, `rel="noopener noreferrer"`), a plain anchor
+ *          for a same-page hash, or an AutoLink (next/link or a plain anchor, by href) otherwise,
+ *          every other prop forwarded in full
+ */
+export declare function MdxLink({ node: _node, href, children, ...props }: MdxLinkProps): import("react").JSX.Element;

package/dist/components/mdx/MdxLink.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AutoLink } from "../basics/AutoLink.js";
+/**
+ * @function MdxLink
+ * @param props {MdxLinkProps} the link's href and native anchor props
+ * @returns {JSX.Element} an external link (new tab, `rel="noopener noreferrer"`), a plain anchor
+ *          for a same-page hash, or an AutoLink (next/link or a plain anchor, by href) otherwise,
+ *          every other prop forwarded in full
+ */
+export function MdxLink({ node: _node, href, children, ...props }) {
+    if (href === undefined) {
+        return _jsx("a", { ...props, children: children });
+    }
+    if (/^https?:\/\//i.test(href)) {
+        return (_jsx("a", { href: href, target: "_blank", rel: "noopener noreferrer", ...props, children: children }));
+    }
+    if (href.startsWith("#")) {
+        return (_jsx("a", { href: href, ...props, children: children }));
+    }
+    // AutoLink's props are next/link's (anchor attributes plus next/link-only props like
+    // `prefetch`); every prop MdxLink accepts from react-markdown is a native anchor attribute,
+    // which AutoLink spreads straight onto whichever element it renders. Narrow cast, like
+    // AutoLink's own `href` handling: ComponentProps<"a"> isn't literally ComponentProps<Link>,
+    // but every field here is one AutoLink already knows how to forward.
+    return (_jsx(AutoLink, { href: href, ...props, children: children }));
+}