@haruhimemoe/ui 0.3.0 → 0.4.0

package/dist/components/basics/Badge.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+const BASE = "inline-flex items-center whitespace-nowrap rounded-full px-2 py-0.5 text-xs";
+// The looks the apps already use: pools' tags and warnings, and its header's beta pill.
+const TONES = {
+    neutral: "bg-b3 text-c2",
+    accent: "bg-h1 font-bold text-b6",
+    warning: "bg-amber-300/20 font-bold text-amber-200",
+    muted: "border border-b3 bg-b5 font-bold text-c4 uppercase tracking-wide",
+};
+/**
+ * @function Badge
+ * @param props {BadgeProps} native span props, plus a tone (default "neutral")
+ * @returns {JSX.Element} a rounded `<span>` pill in the tone's colors
+ */
+export function Badge({ tone = "neutral", className, ...props }) {
+    return _jsx("span", { className: cx(BASE, TONES[tone], className), ...props });
+}

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

@@ -1,16 +1,15 @@
 /**
  * @file src/components/basics/ButtonLink.tsx
  * @desc next/link styled as a pill button. Off-site hrefs (a scheme like https: or mailto:, or
- *       //host) render a plain <a>, with rel="noreferrer" when opened in a new tab.
+ *       //host) render a plain <a>, with rel="noreferrer" when opened in a new tab (AutoLink).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import Link from "next/link.js";
-import type { ComponentProps } from "react";
+import { type AutoLinkProps } from "./AutoLink.js";
 import { type ButtonSize, type ButtonVariant } from "./buttonStyles.js";
 /** Every next/link prop (including `ref`), plus a button variant and size. */
-export type ButtonLinkProps = ComponentProps<typeof Link> & {
+export type ButtonLinkProps = AutoLinkProps & {
     variant?: ButtonVariant | undefined;
     size?: ButtonSize | undefined;
 };
@@ -20,4 +19,4 @@ export type ButtonLinkProps = ComponentProps<typeof Link> & {
  * @returns {JSX.Element} a next/link styled as a pill button, or a plain `<a>` for an external
  *          href (next/link's own props are dropped there)
  */
-export declare function ButtonLink({ variant, size, className, href, target, rel, ...props }: ButtonLinkProps): import("react").JSX.Element;
+export declare function ButtonLink({ variant, size, className, ...props }: ButtonLinkProps): import("react").JSX.Element;

package/dist/components/basics/ButtonLink.js

@@ -2,13 +2,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * @file src/components/basics/ButtonLink.tsx
  * @desc next/link styled as a pill button. Off-site hrefs (a scheme like https: or mailto:, or
- *       //host) render a plain <a>, with rel="noreferrer" when opened in a new tab.
+ *       //host) render a plain <a>, with rel="noreferrer" when opened in a new tab (AutoLink).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import Link from "next/link.js";
-import { isExternalHref } from "../../utils/href.js";
+import { AutoLink } from "./AutoLink.js";
 import { buttonClasses } from "./buttonStyles.js";
 /**
  * @function ButtonLink
@@ -16,11 +15,6 @@ import { buttonClasses } from "./buttonStyles.js";
  * @returns {JSX.Element} a next/link styled as a pill button, or a plain `<a>` for an external
  *          href (next/link's own props are dropped there)
  */
-export function ButtonLink({ variant, size, className, href, target, rel, ...props }) {
-    const classes = buttonClasses({ variant, size, className });
-    if (typeof href === "string" && isExternalHref(href)) {
-        const { as: _as, replace: _replace, scroll: _scroll, shallow: _shallow, passHref: _passHref, prefetch: _prefetch, locale: _locale, legacyBehavior: _legacyBehavior, onNavigate: _onNavigate, transitionTypes: _transitionTypes, ...anchorProps } = props;
-        return (_jsx("a", { href: href, target: target, rel: rel ?? (target === "_blank" ? "noreferrer" : undefined), className: classes, ...anchorProps }));
-    }
-    return _jsx(Link, { href: href, target: target, rel: rel, className: classes, ...props });
+export function ButtonLink({ variant, size, className, ...props }) {
+    return _jsx(AutoLink, { className: buttonClasses({ variant, size, className }), ...props });
 }

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

@@ -4,14 +4,15 @@
  *       region. Server-safe (useId works in Server Components).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Thu Sep 24, 2026
+ * @modified Mon Sep 28, 2026
  */
 import { type ComponentProps, type ReactNode } from "react";
+import { type HeadingLevel } from "./cardStyles.js";
 /** 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;
+    /** Heading level for the title (default 2). Use 3 or lower for a card under another heading. */
+    headingLevel?: HeadingLevel | undefined;
 };
 /**
  * @function Card

package/dist/components/basics/Card.js

@@ -5,10 +5,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *       region. Server-safe (useId works in Server Components).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Thu Sep 24, 2026
+ * @modified Mon Sep 28, 2026
  */
 import { useId } from "react";
 import { cx } from "../../utils/cx.js";
+import { CARD, CARD_HEADING } from "./cardStyles.js";
 /**
  * @function Card
  * @param props {CardProps} an optional title that labels the region, its heading level (default
@@ -18,5 +19,5 @@ import { cx } from "../../utils/cx.js";
 export function Card({ title, headingLevel = 2, className, children, ...props }) {
     const headingId = useId();
     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] }));
+    return (_jsxs("section", { "aria-labelledby": title ? headingId : undefined, className: cx(CARD, className), ...props, children: [title ? (_jsx(Heading, { id: headingId, className: cx("mb-2", CARD_HEADING), children: title })) : null, children] }));
 }

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

@@ -0,0 +1,34 @@
+/**
+ * @file src/components/basics/Disclosure.tsx
+ * @desc A button that shows and hides a panel below it (the packs download options): the button
+ *       carries aria-expanded and aria-controls, and the closed panel stays in the page, hidden,
+ *       so its form fields keep their values. Uncontrolled by default, or controlled with `open`.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ComponentProps, type ReactNode } from "react";
+/** Every native `<div>` prop for the wrapper, plus the button's text and the panel. */
+export type DisclosureProps = Omit<ComponentProps<"div">, "children"> & {
+    /** The button's text. It can change with `open` ("Download options" / a summary). */
+    summary: ReactNode;
+    /** The panel, shown while open. */
+    children: ReactNode;
+    /** Whether it starts open (default false). Ignored when `open` is set. */
+    defaultOpen?: boolean | undefined;
+    /** Controls the state from outside; pair it with `onOpenChange`. */
+    open?: boolean | undefined;
+    /** Called with the new state when the button is pressed. */
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Classes for the button, merged last. */
+    buttonClassName?: string | undefined;
+    /** Classes for the panel, merged last. */
+    panelClassName?: string | undefined;
+};
+/**
+ * @function Disclosure
+ * @param props {DisclosureProps} the summary, the panel as children, the open state, and native
+ *        div props for the wrapper
+ * @returns {JSX.Element} the toggle button (with a ▾ / ▴ arrow) and the panel it controls
+ */
+export declare function Disclosure({ summary, children, defaultOpen, open, onOpenChange, buttonClassName, panelClassName, className, ...props }: DisclosureProps): import("react").JSX.Element;

package/dist/components/basics/Disclosure.js

@@ -0,0 +1,30 @@
+/**
+ * @file src/components/basics/Disclosure.tsx
+ * @desc A button that shows and hides a panel below it (the packs download options): the button
+ *       carries aria-expanded and aria-controls, and the closed panel stays in the page, hidden,
+ *       so its form fields keep their values. Uncontrolled by default, or controlled with `open`.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from "react";
+import { cx } from "../../utils/cx.js";
+/**
+ * @function Disclosure
+ * @param props {DisclosureProps} the summary, the panel as children, the open state, and native
+ *        div props for the wrapper
+ * @returns {JSX.Element} the toggle button (with a ▾ / ▴ arrow) and the panel it controls
+ */
+export function Disclosure({ summary, children, defaultOpen = false, open, onOpenChange, buttonClassName, panelClassName, className, ...props }) {
+    const panelId = useId();
+    const [inner, setInner] = useState(defaultOpen);
+    const isOpen = open ?? inner;
+    const toggle = () => {
+        if (open === undefined)
+            setInner(!isOpen);
+        onOpenChange?.(!isOpen);
+    };
+    return (_jsxs("div", { className: cx("flex flex-col gap-2", className), ...props, children: [_jsxs("button", { type: "button", "aria-expanded": isOpen, "aria-controls": panelId, onClick: toggle, className: cx("inline-flex items-center gap-1 self-start font-bold text-c2 text-sm transition-colors hover:text-c1", buttonClassName), children: [summary, _jsx("span", { "aria-hidden": "true", children: isOpen ? "▴" : "▾" })] }), _jsx("div", { id: panelId, hidden: !isOpen, className: panelClassName, children: children })] }));
+}

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

@@ -6,9 +6,10 @@
  *       status region that mounts with its text already inside may not be announced.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import type { ComponentProps } from "react";
+/** The notice's color, and its live role: `info` is c3, `warning` amber, `error` rose. */
 export type NoticeTone = "info" | "warning" | "error";
 /** Every native `<p>` prop (including `ref`), plus a tone, a live flag and the element to render. */
 export type NoticeProps = ComponentProps<"p"> & {

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

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/basics/TextLink.tsx
+ * @desc A text link: next/link inside the app, a plain <a> off-site (with rel="noreferrer" in a
+ *       new tab), in the `accent` look for running text or the `plain` one for names in lists.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type AutoLinkProps } from "./AutoLink.js";
+import { type TextLinkVariant } from "./linkStyles.js";
+/** Every next/link prop (including `ref`), plus the link's look. */
+export type TextLinkProps = AutoLinkProps & {
+    /** "accent" (default) for running text, "plain" for a name or title in a list or table. */
+    variant?: TextLinkVariant | undefined;
+};
+/**
+ * @function TextLink
+ * @param props {TextLinkProps} next/link props, plus an optional variant
+ * @returns {JSX.Element} a next/link, or a plain `<a>` for an external href, styled as a text link
+ */
+export declare function TextLink({ variant, className, ...props }: TextLinkProps): import("react").JSX.Element;

package/dist/components/basics/TextLink.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @file src/components/basics/TextLink.tsx
+ * @desc A text link: next/link inside the app, a plain <a> off-site (with rel="noreferrer" in a
+ *       new tab), in the `accent` look for running text or the `plain` one for names in lists.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { AutoLink } from "./AutoLink.js";
+import { linkClasses } from "./linkStyles.js";
+/**
+ * @function TextLink
+ * @param props {TextLinkProps} next/link props, plus an optional variant
+ * @returns {JSX.Element} a next/link, or a plain `<a>` for an external href, styled as a text link
+ */
+export function TextLink({ variant, className, ...props }) {
+    return _jsx(AutoLink, { className: linkClasses({ variant, className }), ...props });
+}

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

@@ -3,9 +3,11 @@
  * @desc Shared class builder for Button and ButtonLink (osu!-web pill buttons).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
+/** The pill's colors: `primary` is h2 (h1 on hover), `secondary` b3, `ghost` transparent. */
 export type ButtonVariant = "primary" | "secondary" | "ghost";
+/** The pill's height, padding and text size: `md` is h-9 and text-sm, `lg` h-11 and text-base. */
 export type ButtonSize = "md" | "lg";
 /** Options for {@link buttonClasses}. */
 export type ButtonClassOptions = {

package/dist/components/basics/buttonStyles.js

@@ -3,7 +3,7 @@
  * @desc Shared class builder for Button and ButtonLink (osu!-web pill buttons).
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import { cx } from "../../utils/cx.js";
 const BASE = "inline-flex items-center justify-center gap-2 rounded-full font-bold transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-h1 disabled:cursor-not-allowed disabled:opacity-50";

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

@@ -0,0 +1,14 @@
+/**
+ * @file src/components/basics/cardStyles.ts
+ * @desc The osu!-web panel look that Card and FilterPanel share: the rounded b4 surface and its
+ *       title, plus the heading levels either one takes for that title.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A heading level for a component's title: `h2` to `h6` (a page has one `h1`). */
+export type HeadingLevel = 2 | 3 | 4 | 5 | 6;
+/** The panel: rounded, b4 background, p-5, c2 text. */
+export declare const CARD = "rounded-[10px] bg-b4 p-5 text-c2";
+/** The panel's title: bold c1 at text-lg. */
+export declare const CARD_HEADING = "font-bold text-c1 text-lg";

package/dist/components/basics/cardStyles.js

@@ -0,0 +1,12 @@
+/**
+ * @file src/components/basics/cardStyles.ts
+ * @desc The osu!-web panel look that Card and FilterPanel share: the rounded b4 surface and its
+ *       title, plus the heading levels either one takes for that title.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The panel: rounded, b4 background, p-5, c2 text. */
+export const CARD = "rounded-[10px] bg-b4 p-5 text-c2";
+/** The panel's title: bold c1 at text-lg. */
+export const CARD_HEADING = "font-bold text-c1 text-lg";

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

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/basics/linkStyles.ts
+ * @desc Class builder for text links, shared by TextLink and any element that should look like
+ *       one: `accent` for links in running text (h1, underlined, like Prose), `plain` for names
+ *       and titles in lists and tables (bold c1, underlined on hover).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A text link's look: `accent` in running text, `plain` for a name or title in a list. */
+export type TextLinkVariant = "accent" | "plain";
+/** Options for {@link linkClasses}. */
+export type LinkClassOptions = {
+    variant?: TextLinkVariant | undefined;
+    className?: string | undefined;
+};
+/**
+ * @function linkClasses
+ * @param opts {LinkClassOptions} variant (default "accent") and extra classes
+ * @returns {string} the text link classes, with the caller's className appended last (it
+ *          replaces a built-in class that sets the same property)
+ */
+export declare const linkClasses: ({ variant, className }?: LinkClassOptions) => string;

package/dist/components/basics/linkStyles.js

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/basics/linkStyles.ts
+ * @desc Class builder for text links, shared by TextLink and any element that should look like
+ *       one: `accent` for links in running text (h1, underlined, like Prose), `plain` for names
+ *       and titles in lists and tables (bold c1, underlined on hover).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { cx } from "../../utils/cx.js";
+// The accent link is underlined at rest, so it doesn't rely on color alone (WCAG 1.4.1). A plain
+// link sits where the context says it's a link (a list of names), and underlines on hover.
+const VARIANTS = {
+    accent: "text-h1 underline underline-offset-2 transition-colors hover:text-c1",
+    plain: "font-bold text-c1 underline-offset-2 hover:underline",
+};
+/**
+ * @function linkClasses
+ * @param opts {LinkClassOptions} variant (default "accent") and extra classes
+ * @returns {string} the text link classes, with the caller's className appended last (it
+ *          replaces a built-in class that sets the same property)
+ */
+export const linkClasses = ({ variant = "accent", className } = {}) => cx(VARIANTS[variant], className);

package/dist/components/filters/Chip.d.ts

@@ -2,24 +2,32 @@
  * @file src/components/filters/Chip.tsx
  * @desc Toggle pill (osu! beatmap listing style): a `<button>` with `aria-pressed`, pink when on.
  *       Same look as the mod chips on packs.haruhime.moe. In forced-colors mode a pressed chip
- *       takes the system highlight colors, so on and off still look different.
+ *       takes the system highlight colors, so on and off still look different. With
+ *       `unavailableReason` it is blocked but stays focusable (aria-disabled), and screen readers
+ *       hear the reason as its description.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import type { ComponentProps } from "react";
+import { type ComponentProps, type ReactNode } from "react";
 /** Every native `<button>` prop (including `ref`), plus the pressed state and its handler. */
 export type ChipProps = Omit<ComponentProps<"button">, "aria-pressed"> & {
     /** Whether the chip is on. */
     pressed: boolean;
     /** Called with the new state when the chip is clicked (or toggled with Enter or Space). */
     onPressedChange?: ((pressed: boolean) => void) | undefined;
+    /**
+     * Why the chip can't be pressed right now (EZ with HR picked). The chip is blocked but stays
+     * in the tab order (aria-disabled), and the reason is its description (and its title).
+     */
+    unavailableReason?: ReactNode;
 };
 /**
  * @function Chip
  * @param props {ChipProps} native button props, plus `pressed` and an optional `onPressedChange`.
  *        A caller's `onClick` runs first; calling `event.preventDefault()` in it skips the toggle.
  *        Callbacks can only be passed from client code.
- * @returns {JSX.Element} a `<button type="button" aria-pressed>` styled as a pill
+ * @returns {JSX.Element} a `<button type="button" aria-pressed>` styled as a pill, and the
+ *          screen-reader-only reason beside it when it is unavailable
  */
-export declare function Chip({ pressed, onPressedChange, onClick, className, type, ...props }: ChipProps): import("react").JSX.Element;
+export declare function Chip({ pressed, onPressedChange, unavailableReason, onClick, className, type, title, "aria-describedby": describedBy, ...props }: ChipProps): import("react").JSX.Element;

package/dist/components/filters/Chip.js

@@ -2,28 +2,37 @@
  * @file src/components/filters/Chip.tsx
  * @desc Toggle pill (osu! beatmap listing style): a `<button>` with `aria-pressed`, pink when on.
  *       Same look as the mod chips on packs.haruhime.moe. In forced-colors mode a pressed chip
- *       takes the system highlight colors, so on and off still look different.
+ *       takes the system highlight colors, so on and off still look different. With
+ *       `unavailableReason` it is blocked but stays focusable (aria-disabled), and screen readers
+ *       hear the reason as its description.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { cx } from "../../utils/cx.js";
-const BASE = "rounded-full px-2.5 py-0.5 font-bold text-xs transition-colors disabled:cursor-not-allowed disabled:opacity-40";
-const PRESSED = "bg-h1 text-b6 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]";
-const UNPRESSED = "bg-b3 text-c2 not-disabled:hover:bg-b2";
+import { CHIP, CHIP_OFF, CHIP_ON, CHIP_UNAVAILABLE } from "./chipStyles.js";
 /**
  * @function Chip
  * @param props {ChipProps} native button props, plus `pressed` and an optional `onPressedChange`.
  *        A caller's `onClick` runs first; calling `event.preventDefault()` in it skips the toggle.
  *        Callbacks can only be passed from client code.
- * @returns {JSX.Element} a `<button type="button" aria-pressed>` styled as a pill
+ * @returns {JSX.Element} a `<button type="button" aria-pressed>` styled as a pill, and the
+ *          screen-reader-only reason beside it when it is unavailable
  */
-export function Chip({ pressed, onPressedChange, onClick, className, type = "button", ...props }) {
-    return (_jsx("button", { type: type, "aria-pressed": pressed, onClick: (event) => {
+export function Chip({ pressed, onPressedChange, unavailableReason, onClick, className, type = "button", title, "aria-describedby": describedBy, ...props }) {
+    const reasonId = useId();
+    const blocked = unavailableReason !== undefined && unavailableReason !== null;
+    const reasonTitle = blocked && typeof unavailableReason === "string" ? unavailableReason : undefined;
+    const chip = (_jsx("button", { type: type, "aria-pressed": pressed, "aria-disabled": blocked || undefined, "aria-describedby": blocked ? [reasonId, describedBy].filter(Boolean).join(" ") : describedBy, title: title ?? reasonTitle, onClick: (event) => {
             onClick?.(event);
-            if (!event.defaultPrevented)
+            if (!event.defaultPrevented && !blocked)
                 onPressedChange?.(!pressed);
-        }, className: cx(BASE, pressed ? PRESSED : UNPRESSED, className), ...props }));
+        }, className: cx(CHIP, "disabled:cursor-not-allowed disabled:opacity-40", pressed ? CHIP_ON : CHIP_OFF, blocked ? CHIP_UNAVAILABLE : !pressed && "not-disabled:hover:bg-b2", className), ...props }));
+    if (!blocked)
+        return chip;
+    // The reason sits beside the button, not inside it, where it would join the button's name.
+    return (_jsxs(_Fragment, { children: [chip, _jsx("span", { id: reasonId, className: "sr-only", children: unavailableReason })] }));
 }

package/dist/components/filters/ChipGroup.d.ts

@@ -4,24 +4,23 @@
  *       in the tab order; the group reports the picked values in the options' order.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
-import { type ComponentProps, type ReactNode } from "react";
+import type { ReactNode } from "react";
+import { type GroupFrameProps } from "./GroupFrame.js";
 /** One chip: the value it stands for, what it shows, and whether it can be toggled. */
 export type ChipOption = {
     value: string;
     label: ReactNode;
     disabled?: boolean | undefined;
+    /** Why the chip can't be picked right now; it stays focusable. See Chip. */
+    unavailableReason?: ReactNode;
 };
-/** Every native `<fieldset>` prop except `onChange` and `children`, plus label, options, value. */
-export type ChipGroupProps = Omit<ComponentProps<"fieldset">, "onChange" | "children"> & {
-    /** Names the group (`role="group"` + `aria-labelledby`). */
-    label: ReactNode;
-    /**
-     * Leave the name to a surrounding FilterRow: no label shows, and the fieldset is not a group
-     * of its own (role none), so screen readers hear the row's name once.
-     */
-    hideLabel?: boolean | undefined;
+/**
+ * Every native `<fieldset>` prop except `onChange` and `children`, plus `label` (names the group)
+ * and `hideLabel` (leave the name to a surrounding FilterRow), the options and the picked values.
+ */
+export type ChipGroupProps = Omit<GroupFrameProps, "onChange" | "children"> & {
     options: readonly ChipOption[];
     /** The picked values. */
     value: readonly string[];
@@ -36,4 +35,4 @@ export type ChipGroupProps = Omit<ComponentProps<"fieldset">, "onChange" | "chil
  * @returns {JSX.Element} a `<fieldset>` (role group) labeled by its label, one Chip per option.
  *          With `hideLabel`, the fieldset has role none and no label.
  */
-export declare function ChipGroup({ label, hideLabel, options, value, onChange, className, ...props }: ChipGroupProps): import("react").JSX.Element;
+export declare function ChipGroup({ options, value, onChange, ...props }: ChipGroupProps): import("react").JSX.Element;

package/dist/components/filters/ChipGroup.js

@@ -4,13 +4,12 @@
  *       in the tab order; the group reports the picked values in the options' order.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId } from "react";
-import { cx } from "../../utils/cx.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { Chip } from "./Chip.js";
+import { GroupFrame } from "./GroupFrame.js";
 /**
  * @function toggleValue
  * @param value {readonly string[]} the picked values
@@ -35,10 +34,6 @@ const toggleValue = (value, option, on, options) => {
  * @returns {JSX.Element} a `<fieldset>` (role group) labeled by its label, one Chip per option.
  *          With `hideLabel`, the fieldset has role none and no label.
  */
-export function ChipGroup({ label, hideLabel = false, options, value, onChange, className, ...props }) {
-    const labelId = useId();
-    return (_jsxs("fieldset", { 
-        // Inside a FilterRow (hideLabel), the row's fieldset is the group. A second group with the
-        // same name would be read twice. The fieldset stays, so `disabled` still reaches every chip.
-        role: hideLabel ? "none" : undefined, "aria-labelledby": hideLabel ? undefined : labelId, className: cx("flex flex-col gap-2", className), ...props, children: [hideLabel ? null : (_jsx("span", { id: labelId, className: "font-bold text-c3 text-sm", children: label })), _jsx("div", { className: "flex flex-wrap items-center gap-1", children: options.map((option) => (_jsx(Chip, { pressed: value.includes(option.value), disabled: option.disabled, onPressedChange: (on) => onChange(toggleValue(value, option.value, on, options)), children: option.label }, option.value))) })] }));
+export function ChipGroup({ options, value, onChange, ...props }) {
+    return (_jsx(GroupFrame, { ...props, children: _jsx("div", { className: "flex flex-wrap items-center gap-1", children: options.map((option) => (_jsx(Chip, { pressed: value.includes(option.value), disabled: option.disabled, unavailableReason: option.unavailableReason, onPressedChange: (on) => onChange(toggleValue(value, option.value, on, options)), children: option.label }, option.value))) }) }));
 }

package/dist/components/filters/ChoiceChips.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file src/components/filters/ChoiceChips.tsx
+ * @desc One choice from a few, as a real radio group drawn as chips (the pools status and type
+ *       filters): native radio inputs under one name, so Tab reaches the checked chip, the arrow
+ *       keys move and pick, and screen readers hear "radio, 1 of 3, checked". Same look as Chip,
+ *       with the focus ring on the chip, not the hidden input. A labelled fieldset like ChipGroup.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ReactNode } from "react";
+import { type GroupFrameProps } from "./GroupFrame.js";
+/** One choice: the value it stands for, what it shows, and whether it can be picked. */
+export type ChoiceChipOption<T extends string = string> = {
+    value: T;
+    label: ReactNode;
+    disabled?: boolean | undefined;
+};
+/**
+ * Every native `<fieldset>` prop except `onChange`, `children` and `defaultValue`, plus `label`
+ * and `hideLabel` (as on ChipGroup), the options, the picked value and the radios' name.
+ */
+export type ChoiceChipsProps<T extends string = string> = Omit<GroupFrameProps, "onChange" | "children" | "defaultValue"> & {
+    options: readonly ChoiceChipOption<T>[];
+    /** The picked value. */
+    value: T;
+    /** Called with the value of the chip that was picked. */
+    onChange: (value: T) => void;
+    /** The radios' name, for a form (default: a generated one). */
+    name?: string | undefined;
+};
+/**
+ * @function ChoiceChips
+ * @param props {ChoiceChipsProps} label, options, the picked value and a change handler, plus
+ *        native fieldset props (`disabled` turns off every chip). Render it from client code.
+ * @returns {JSX.Element} a `<fieldset>` named by its label, with one radio chip per option
+ */
+export declare function ChoiceChips<T extends string = string>({ options, value, onChange, name, ...props }: ChoiceChipsProps<T>): import("react").JSX.Element;

package/dist/components/filters/ChoiceChips.js

@@ -0,0 +1,31 @@
+/**
+ * @file src/components/filters/ChoiceChips.tsx
+ * @desc One choice from a few, as a real radio group drawn as chips (the pools status and type
+ *       filters): native radio inputs under one name, so Tab reaches the checked chip, the arrow
+ *       keys move and pick, and screen readers hear "radio, 1 of 3, checked". Same look as Chip,
+ *       with the focus ring on the chip, not the hidden input. A labelled fieldset like ChipGroup.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { cx } from "../../utils/cx.js";
+import { CHIP, CHIP_OFF, CHIP_ON, CHIP_UNAVAILABLE } from "./chipStyles.js";
+import { GroupFrame } from "./GroupFrame.js";
+// A label around a hidden radio: it shows the input's focus and disabled state itself.
+const LABEL = "cursor-pointer has-focus-visible:outline-2 has-focus-visible:outline-h1 has-focus-visible:outline-offset-2 has-disabled:cursor-not-allowed has-disabled:opacity-40";
+/**
+ * @function ChoiceChips
+ * @param props {ChoiceChipsProps} label, options, the picked value and a change handler, plus
+ *        native fieldset props (`disabled` turns off every chip). Render it from client code.
+ * @returns {JSX.Element} a `<fieldset>` named by its label, with one radio chip per option
+ */
+export function ChoiceChips({ options, value, onChange, name, ...props }) {
+    const generated = useId();
+    return (_jsx(GroupFrame, { ...props, children: _jsx("div", { className: "flex flex-wrap items-center gap-1", children: options.map((option) => {
+                const on = option.value === value;
+                return (_jsxs("label", { className: cx(CHIP, LABEL, on ? CHIP_ON : CHIP_OFF, !on && !option.disabled && "hover:bg-b2", option.disabled && CHIP_UNAVAILABLE), children: [_jsx("input", { type: "radio", name: name ?? generated, value: option.value, checked: on, disabled: option.disabled, onChange: () => onChange(option.value), className: "sr-only" }), option.label] }, option.value));
+            }) }) }));
+}

package/dist/components/filters/FilterPanel.d.ts

@@ -1,19 +1,20 @@
 /**
  * @file src/components/filters/FilterPanel.tsx
  * @desc Filter panel (osu! beatmap listing style): a titled card of FilterRows with a live result
- *       count and a "Clear filters" link. On phones the rows fold away behind a disclosure button;
- *       from `sm` up they are always shown.
+ *       count and a "Clear filters" button. On phones the rows fold away behind a disclosure
+ *       button; from `sm` up they are always shown.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Wed Sep 23, 2026
+ * @modified Mon Sep 28, 2026
  */
 import { type ComponentProps, type ReactNode } from "react";
+import { type HeadingLevel } from "../basics/cardStyles.js";
 /** Every native `<section>` prop except `title`, plus the panel's title, count and clear action. */
 export type FilterPanelProps = Omit<ComponentProps<"section">, "title"> & {
     /** The panel heading; it also names the panel and its phone disclosure button. */
     title: ReactNode;
     /** Heading level for the title (default 2). */
-    headingLevel?: 2 | 3 | 4 | 5 | 6 | undefined;
+    headingLevel?: HeadingLevel | undefined;
     /** Shown in an `<output aria-live="polite">`, so screen readers hear each new count. */
     resultCount?: ReactNode;
     /** True while any filter is set; shows the clear button. */