@haruhimemoe/ui 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ 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
@@ -138,7 +144,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.9.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

package/README.md

@@ -2,7 +2,7 @@
 
 # @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.
 
@@ -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,42 @@ 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.

package/dist/components/osu/PlayerCard.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file src/components/osu/PlayerCard.tsx
+ * @desc osu!-web's user card (the 120px card from the friends list and user tooltips) from plain
+ *       props: cover under a b5 overlay, 60px avatar, country flag, team flag and supporter heart,
+ *       the username (the whole card links to the profile), and an optional status row. It never
+ *       fetches: the app passes a snapshot, so nothing here claims live data unless told to. The
+ *       online ring's lime is osu!'s own green-light, hue-independent like StarRating's spectrum.
+ *       Keyboard focus outlines the whole card in h1 as well as the username's own ring.
+ *       Plain `<img>`s, not next/image, so apps need no `images.remotePatterns` for osu!'s hosts.
+ *       Server-safe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import type { ComponentProps, ReactNode } from "react";
+/** An osu! team: its name (the flag's alt text and tooltip) and its flag image. */
+export type PlayerTeam = {
+    /** The team's name. */
+    name: string;
+    /** The team flag's URL (osu! serves them from assets.ppy.sh). */
+    flagUrl: string;
+};
+/** Every native `<div>` prop except children, plus the player's snapshot. */
+export type PlayerCardProps = Omit<ComponentProps<"div">, "children"> & {
+    /** The name shown on the card, as-is. */
+    username: string;
+    /** The osu! user id: the avatar comes from a.ppy.sh and the card links to the profile. */
+    userId?: number | undefined;
+    /** Replaces the profile link; `null` draws no link even with a `userId`. */
+    href?: string | null | undefined;
+    /** Replaces the a.ppy.sh avatar. Without it and a `userId`, a letter stands in. */
+    avatarUrl?: string | undefined;
+    /** The profile cover, drawn behind everything. None leaves the card plain b4. */
+    coverUrl?: string | undefined;
+    /** ISO 3166-1 alpha-2 code; draws osu!'s flag. Anything else draws none. */
+    countryCode?: string | undefined;
+    /** The flag's alt text (default: the English name from Intl, else the code). */
+    countryName?: string | undefined;
+    /** The player's osu! team, drawn as its flag beside the country's. */
+    team?: PlayerTeam | undefined;
+    /** Draws the supporter heart. */
+    supporter?: boolean | undefined;
+    /** What screen readers hear for the heart (default "osu! supporter"). */
+    supporterLabel?: string | undefined;
+    /** Draws the status ring. Leave it out for static data: the card never guesses a status. */
+    status?: "online" | "offline" | undefined;
+    /** The bottom row's main line (default "Online" or "Offline" when `status` is set). */
+    statusText?: ReactNode;
+    /** A small line above it ("Last seen 29 days ago", "formerly RMarc"). */
+    statusNote?: ReactNode;
+};
+/**
+ * @function PlayerCard
+ * @param props {PlayerCardProps} the player's snapshot (name, id, cover, flags, supporter,
+ *        status) and native div props
+ * @returns {JSX.Element} a 120px osu!-web user card; the whole card links to the profile when it
+ *          has a link
+ */
+export declare function PlayerCard({ username, userId, href, avatarUrl, coverUrl, countryCode, countryName, team, supporter, supporterLabel, status, statusText, statusNote, className, ...props }: PlayerCardProps): import("react").JSX.Element;

package/dist/components/osu/PlayerCard.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+import { AutoLink } from "../basics/AutoLink.js";
+import { avatarUrl as defaultAvatarUrl, countryName as defaultCountryName, flagUrl, isAnimatedImage, normalizeCountryCode, profileUrl, } from "./playerLinks.js";
+/** The first letter or digit of a name, for the stand-in avatar. */
+function initialOf(name) {
+    return name.match(/[\p{L}\p{N}]/u)?.[0]?.toUpperCase() ?? "?";
+}
+/** Whether a status line has something to show: not null, undefined, a boolean or "". */
+function shown(node) {
+    return node != null && typeof node !== "boolean" && node !== "";
+}
+/** The supporter heart: osu!'s pink-circle badge with a white heart. */
+function SupporterHeart({ label }) {
+    return (_jsx("span", { role: "img", "aria-label": label, className: "inline-flex size-[26px] shrink-0 items-center justify-center rounded-full bg-h2 text-c1", children: _jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", className: "size-3.5", fill: "currentColor", children: _jsx("path", { d: "M12 21s-7.5-4.6-10-9.3C.3 8.4 2.2 4.5 6 4.5c2.2 0 3.6 1.2 4.5 2.5l1.5 2 1.5-2c.9-1.3 2.3-2.5 4.5-2.5 3.8 0 5.7 3.9 4 7.2C19.5 16.4 12 21 12 21z" }) }) }));
+}
+/**
+ * @function PlayerCard
+ * @param props {PlayerCardProps} the player's snapshot (name, id, cover, flags, supporter,
+ *        status) and native div props
+ * @returns {JSX.Element} a 120px osu!-web user card; the whole card links to the profile when it
+ *          has a link
+ */
+export function PlayerCard({ username, userId, href, avatarUrl, coverUrl, countryCode, countryName, team, supporter = false, supporterLabel = "osu! supporter", status, statusText, statusNote, className, ...props }) {
+    const link = href === null ? null : (href ?? (userId === undefined ? null : profileUrl(userId)));
+    const avatar = avatarUrl ?? (userId === undefined ? null : defaultAvatarUrl(userId));
+    const code = normalizeCountryCode(countryCode);
+    const flag = flagUrl(countryCode);
+    const mainLine = shown(statusText)
+        ? statusText
+        : status === "online"
+            ? "Online"
+            : status
+                ? "Offline"
+                : null;
+    const note = shown(statusNote) ? statusNote : null;
+    const hasStatusRow = status !== undefined || mainLine !== null || note !== null;
+    return (_jsxs("div", { className: cx("relative isolate flex h-[120px] flex-col justify-between overflow-hidden rounded-[10px] bg-b4 text-c1", link &&
+            "hover:outline-2 hover:outline-c3 has-[a:focus-visible]:outline-2 has-[a:focus-visible]:outline-h1", className), ...props, children: [coverUrl ? (_jsx("img", { src: coverUrl, alt: "", loading: "lazy", decoding: "async", className: cx("absolute inset-0 -z-10 size-full object-cover", isAnimatedImage(coverUrl) && "motion-reduce:hidden") })) : null, coverUrl ? _jsx("div", { "aria-hidden": "true", className: "absolute inset-0 -z-10 bg-b5/80" }) : null, _jsxs("div", { className: "flex gap-2.5 p-2.5", children: [avatar ? (_jsx("img", { src: avatar, alt: "", width: 60, height: 60, loading: "lazy", decoding: "async", className: "size-[60px] shrink-0 rounded-md bg-b4 object-cover" })) : (_jsx("span", { "aria-hidden": "true", className: "flex size-[60px] shrink-0 items-center justify-center rounded-md bg-b3 font-bold text-2xl text-c3", children: initialOf(username) })), _jsxs("div", { className: "grid min-w-0 flex-1 grid-rows-[26px_1fr]", children: [_jsxs("div", { className: "flex h-[26px] items-center gap-1.5", children: [flag && code ? (_jsx("img", { src: flag, alt: countryName ?? defaultCountryName(code), width: 36, height: 26, loading: "lazy", decoding: "async", className: "h-[26px] w-auto shrink-0" })) : null, team ? (_jsx("img", { src: team.flagUrl, alt: team.name, width: 52, height: 26, loading: "lazy", decoding: "async", className: "h-[26px] w-[52px] shrink-0 rounded-sm object-cover" })) : null, supporter ? _jsx(SupporterHeart, { label: supporterLabel }) : null] }), _jsx("div", { className: "flex min-w-0 items-center", children: link ? (_jsx(AutoLink, { href: link, className: "truncate font-semibold text-base text-c1 after:absolute after:inset-0", children: username })) : (_jsx("span", { className: "truncate font-semibold text-base", children: username })) })] })] }), hasStatusRow ? (_jsxs("div", { className: "flex items-center gap-2.5 px-2.5 pb-2.5", children: [_jsx("div", { className: "flex w-[60px] shrink-0 justify-center", children: status ? (_jsx("span", { "aria-hidden": "true", className: cx("size-[25px] rounded-full border-4", status === "online" ? "border-lime-400" : "border-b6") })) : null }), _jsxs("div", { className: "flex min-w-0 flex-col", children: [note !== null ? _jsx("span", { className: "truncate text-c2 text-xs", children: note }) : null, mainLine !== null ? _jsx("span", { className: "truncate text-sm", children: mainLine }) : null] })] })) : null] }));
+}

package/dist/components/osu/playerLinks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file src/components/osu/playerLinks.ts
+ * @desc The osu! URLs and names PlayerCard builds from plain props: profile and avatar from a
+ *       user id, osu-web's own country flag SVG from a two-letter code, the country's English
+ *       name for the flag's alt text, and whether a cover is an animated GIF. Pure, server-safe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+/**
+ * @function profileUrl
+ * @param id {number} the osu! user id
+ * @returns {string} the user's osu! profile page
+ */
+export declare const profileUrl: (id: number) => string;
+/**
+ * @function avatarUrl
+ * @param id {number} the osu! user id
+ * @returns {string} the user's current avatar on a.ppy.sh (osu! serves the default for none)
+ */
+export declare const avatarUrl: (id: number) => string;
+/**
+ * @function normalizeCountryCode
+ * @param code {string | undefined} an ISO 3166-1 alpha-2 code, any case, maybe padded
+ * @returns {string | null} the code in capitals, or null when it isn't two ASCII letters
+ */
+export declare function normalizeCountryCode(code: string | undefined): string | null;
+/**
+ * @function flagUrl
+ * @param code {string | undefined} an ISO 3166-1 alpha-2 code
+ * @returns {string | null} osu-web's flag SVG (named by the flag emoji's regional-indicator code
+ *          points, lowercase hex joined by "-"), or null for anything but two ASCII letters
+ */
+export declare function flagUrl(code: string | undefined): string | null;
+/**
+ * @function countryName
+ * @param code {string} an ISO 3166-1 alpha-2 code
+ * @returns {string} the region's English name from Intl, or the code in capitals when Intl
+ *          doesn't know it
+ */
+export declare function countryName(code: string): string;
+/**
+ * @function isAnimatedImage
+ * @param url {string} an image URL
+ * @returns {boolean} true when the path ends in .gif (before any query or hash)
+ */
+export declare const isAnimatedImage: (url: string) => boolean;

package/dist/components/osu/playerLinks.js

@@ -0,0 +1,65 @@
+/**
+ * @file src/components/osu/playerLinks.ts
+ * @desc The osu! URLs and names PlayerCard builds from plain props: profile and avatar from a
+ *       user id, osu-web's own country flag SVG from a two-letter code, the country's English
+ *       name for the flag's alt text, and whether a cover is an animated GIF. Pure, server-safe.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+const REGIONAL_INDICATOR_A = 0x1f1e6;
+/**
+ * @function profileUrl
+ * @param id {number} the osu! user id
+ * @returns {string} the user's osu! profile page
+ */
+export const profileUrl = (id) => `https://osu.ppy.sh/users/${id}`;
+/**
+ * @function avatarUrl
+ * @param id {number} the osu! user id
+ * @returns {string} the user's current avatar on a.ppy.sh (osu! serves the default for none)
+ */
+export const avatarUrl = (id) => `https://a.ppy.sh/${id}`;
+/**
+ * @function normalizeCountryCode
+ * @param code {string | undefined} an ISO 3166-1 alpha-2 code, any case, maybe padded
+ * @returns {string | null} the code in capitals, or null when it isn't two ASCII letters
+ */
+export function normalizeCountryCode(code) {
+    const upper = code?.trim().toUpperCase() ?? "";
+    return /^[A-Z]{2}$/.test(upper) ? upper : null;
+}
+/**
+ * @function flagUrl
+ * @param code {string | undefined} an ISO 3166-1 alpha-2 code
+ * @returns {string | null} osu-web's flag SVG (named by the flag emoji's regional-indicator code
+ *          points, lowercase hex joined by "-"), or null for anything but two ASCII letters
+ */
+export function flagUrl(code) {
+    const upper = normalizeCountryCode(code);
+    if (!upper)
+        return null;
+    const points = [...upper].map((letter) => (REGIONAL_INDICATOR_A + letter.charCodeAt(0) - 65).toString(16));
+    return `https://osu.ppy.sh/assets/images/flags/${points.join("-")}.svg`;
+}
+/**
+ * @function countryName
+ * @param code {string} an ISO 3166-1 alpha-2 code
+ * @returns {string} the region's English name from Intl, or the code in capitals when Intl
+ *          doesn't know it
+ */
+export function countryName(code) {
+    const upper = code.trim().toUpperCase();
+    try {
+        return new Intl.DisplayNames(["en"], { type: "region" }).of(upper) ?? upper;
+    }
+    catch {
+        return upper;
+    }
+}
+/**
+ * @function isAnimatedImage
+ * @param url {string} an image URL
+ * @returns {boolean} true when the path ends in .gif (before any query or hash)
+ */
+export const isAnimatedImage = (url) => /\.gif(?:[?#]|$)/i.test(url);

package/dist/index.d.ts

@@ -49,6 +49,7 @@ export { HaruhimeWordmarkLink, type HaruhimeWordmarkLinkProps, } from "./compone
 export { JsonLd, type JsonLdProps } from "./components/meta/JsonLd.js";
 export { type BeatmapStatKey, BeatmapStats, type BeatmapStatsProps, } from "./components/osu/BeatmapStats.js";
 export { ModBadge, type ModBadgeProps } from "./components/osu/ModBadge.js";
+export { PlayerCard, type PlayerCardProps, type PlayerTeam, } from "./components/osu/PlayerCard.js";
 export { StarRating, type StarRatingProps } from "./components/osu/StarRating.js";
 export { CommandPalette } from "./components/palette/CommandPalette.js";
 export { CommandPaletteButton, type CommandPaletteButtonProps, } from "./components/palette/CommandPaletteButton.js";

package/dist/index.js

@@ -54,6 +54,7 @@ export { JsonLd } from "./components/meta/JsonLd.js";
 // osu!
 export { BeatmapStats, } from "./components/osu/BeatmapStats.js";
 export { ModBadge } from "./components/osu/ModBadge.js";
+export { PlayerCard, } from "./components/osu/PlayerCard.js";
 export { StarRating } from "./components/osu/StarRating.js";
 // Palette
 export { CommandPalette } from "./components/palette/CommandPalette.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haruhimemoe/ui",
-  "version": "0.9.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 and confirms, filter controls, tables, osu! beatmap display pieces, a command palette and the site header and footer.",
+  "version": "0.10.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 and confirms, filter controls, tables, osu! beatmap display pieces and player cards, a command palette and the site header and footer.",
   "keywords": [
     "osu",
     "osu!",