@eifi1/ui-kit 0.10.0 → 0.11.0

package/src/components/alert-banner.tsx

@@ -140,6 +140,31 @@ interface AlertBannerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "on
   variant?: "box" | "inline" | "strip";
   /** See {@link AlertSize}. Default `md`. */
   size?: AlertSize;
+  /**
+   * `inline` only (0.11.0): lay the message out as a BLOCK — a full-width `flex` row,
+   * the glyph on the text's FIRST line when it wraps — instead of the `inline-flex`,
+   * centred line it is by default. keksdose writes `className="flex"` on nearly every
+   * inline banner it has (accounts-page:564, holdings-panel:631, import-map-step:66/314,
+   * guest-key-control:84) to get a line of its own under a total or a field, and a
+   * two-line hint there then centres its glyph between the lines.
+   *
+   * An option rather than the new default, because the inline-flex is load-bearing for
+   * the callers the variant was made for: lenkbank's corner-motion toolbar
+   * (corner-motion.tsx:178) sets it as a `shrink-0` item beside the controls, kastlan's
+   * import page and keksdose's rules page place it in a run of content — a block would
+   * take the whole row in the second kind, and top-align the first against a taller
+   * control. Ignored by `box` and `strip`, which are blocks already.
+   */
+  block?: boolean;
+  /**
+   * `false` opts an inline banner out of its live region (no `role="alert"` /
+   * `role="status"`), for a message that is static page content rather than the answer
+   * to something the user just did: keksdose's CAMT review step (camt-review-step:214)
+   * renders "unresolved rows block the import" as part of the step, and as
+   * `role="alert"` a screen reader interrupted with it on every mount. A `role` you pass
+   * still wins. Default `true`; the box and the strip are role-less either way.
+   */
+  live?: boolean;
   /**
    * An opaque, raised surface (a shadow, and no translucency in dark mode) for a
    * notice that floats over the page — see {@link TONE_ELEVATED}. `box` and `strip`
@@ -200,6 +225,8 @@ export function AlertBanner({
   tone = "danger",
   variant = "box",
   size = "md",
+  block = false,
+  live = true,
   elevated = false,
   action,
   icon,
@@ -217,11 +244,13 @@ export function AlertBanner({
   const strip = variant === "strip";
   const sm = size === "sm";
   const interactive = href !== undefined || onClick !== undefined;
-  const resolvedRole = role ?? (inline ? (tone === "danger" ? "alert" : "status") : undefined);
+  // A block-laid inline banner behaves like a box for layout: a row that may wrap.
+  const inlineRow = inline && !block;
+  const resolvedRole = role ?? (inline && live ? (tone === "danger" ? "alert" : "status") : undefined);
 
   const Glyph = TONE_GLYPH[tone];
   // Onto the first line of a box's text: 2px at 14px/20px, 1px at 12px/16px.
-  const nudge = inline || strip ? undefined : sm ? "mt-px" : "mt-0.5";
+  const nudge = inlineRow || strip ? undefined : sm ? "mt-px" : "mt-0.5";
   const glyph =
     icon === null ? null : icon !== undefined ? (
       <span
@@ -239,7 +268,7 @@ export function AlertBanner({
   // column, so the action drops under it instead. A box may wrap its text, so it
   // top-aligns and nudges the glyph onto the first line.
   const row = cn(
-    inline ? "inline-flex items-center" : strip ? "flex flex-wrap items-center gap-y-1" : "flex items-start",
+    inlineRow ? "inline-flex items-center" : strip ? "flex flex-wrap items-center gap-y-1" : "flex items-start",
     sm ? "gap-1.5 text-xs" : inline ? "gap-1.5 text-sm" : "gap-2 text-sm",
   );
   const frame = inline
@@ -254,7 +283,7 @@ export function AlertBanner({
   const content = (
     <>
       {glyph}
-      <span className={cn(!inline && "flex-1", "min-w-0 text-start")}>{children}</span>
+      <span className={cn(!inlineRow && "flex-1", "min-w-0 text-start")}>{children}</span>
       {interactive && (
         <ChevronRight
           aria-hidden
@@ -288,7 +317,7 @@ export function AlertBanner({
   // `relative z-10` so it stays clickable over a whole-row banner's stretched target.
   const trailing =
     action !== undefined && action !== null ? (
-      <div className={cn("relative z-10 flex shrink-0 items-center gap-2", !strip && !inline && "self-center", strip && "ms-auto")}>
+      <div className={cn("relative z-10 flex shrink-0 items-center gap-2", !strip && !inlineRow && "self-center", strip && "ms-auto")}>
         {action}
       </div>
     ) : null;
@@ -319,12 +348,12 @@ export function AlertBanner({
     ? cn(
         "flex min-w-0 flex-1 text-start",
         sm ? "gap-1.5" : "gap-2",
-        inline || strip ? "items-center" : "items-start",
+        inlineRow || strip ? "items-center" : "items-start",
         "outline-none after:absolute after:inset-0 after:content-['']",
         strip ? "after:rounded-none" : "after:rounded-md",
         "focus-visible:after:ring-2 focus-visible:after:ring-[var(--brand)]",
       )
-    : cn(row, !inline && "w-full", frame, TONE_TEXT[tone], hover, focusRing, className);
+    : cn(row, !inlineRow && "w-full", frame, TONE_TEXT[tone], hover, focusRing, className);
   // The div's attributes are the row element's: an `id`, a test id or an
   // `aria-describedby` belongs on the thing that takes focus. The live-region role is
   // NOT carried over — a button or a link that is also a `status` is neither.

package/src/components/bulk-action-bar.tsx

@@ -6,6 +6,7 @@ import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
 import { useKitLabels } from "../i18n/kit-labels";
 import { useAnnounce } from "../hooks/use-announce";
+import { useMediaQuery } from "../hooks/use-media-query";
 import { OVERLAY_EXIT_MS, prefersReducedMotion } from "../hooks/use-close-transition";
 import { Button, IconButton } from "./ui";
 
@@ -34,16 +35,89 @@ export const DEFAULT_BULK_ACTION_BAR_LABELS: BulkActionBarLabels = {
  */
 export type BulkActionBarVariant = "floating" | "sticky" | "inline";
 
+/**
+ * A variant per breakpoint, mobile first — `{ base: "floating", md: "sticky" }` is the
+ * phone's floating card below 768px and the desktop's sticky bar from there up. The
+ * breakpoints are Tailwind's (sm 640, md 768, lg 1024, xl 1280px), the ones the kit's
+ * classes already use. keksdose's payees selection bar (payees-selection-bar.tsx)
+ * computes exactly this with its own `useMediaQuery("(min-width: 768px)")`; every bar
+ * that is a card on a phone and a strip on a desktop would repeat it.
+ *
+ * Resolved in JS rather than with `md:` classes because the variants differ in more
+ * than classes: the floating bar's clear is an icon at the start, the others' a text
+ * button at the end, and the floating bar is positioned by inline style.
+ */
+export interface ResponsiveBulkActionBarVariant {
+  base: BulkActionBarVariant;
+  sm?: BulkActionBarVariant;
+  md?: BulkActionBarVariant;
+  lg?: BulkActionBarVariant;
+  xl?: BulkActionBarVariant;
+}
+
+const BREAKPOINTS = [
+  ["xl", "(min-width: 1280px)"],
+  ["lg", "(min-width: 1024px)"],
+  ["md", "(min-width: 768px)"],
+  ["sm", "(min-width: 640px)"],
+] as const;
+
+/** The variant in force: the widest breakpoint that matches AND names one, else
+ *  `base`. The four queries are subscribed unconditionally — hooks cannot be skipped —
+ *  and a plain string variant simply ignores them. Without `matchMedia` (SSR, tests)
+ *  every query is false, so the bar renders its `base`, the phone's, first. */
+function useResolvedVariant(variant: BulkActionBarVariant | ResponsiveBulkActionBarVariant): BulkActionBarVariant {
+  const matches = {
+    xl: useMediaQuery(BREAKPOINTS[0][1], false),
+    lg: useMediaQuery(BREAKPOINTS[1][1], false),
+    md: useMediaQuery(BREAKPOINTS[2][1], false),
+    sm: useMediaQuery(BREAKPOINTS[3][1], false),
+  };
+  if (typeof variant === "string") return variant;
+  for (const [key] of BREAKPOINTS) {
+    const v = variant[key];
+    if (matches[key] && v !== undefined) return v;
+  }
+  return variant.base;
+}
+
 export interface BulkActionBarProps extends Omit<ComponentPropsWithoutRef<"div">, "role" | "children"> {
-  /** How many items are selected. The bar shows only while this is above zero. */
+  /** How many items are selected. The bar shows only while this is above zero —
+   *  unless {@link open} says otherwise. */
   count: number;
+  /**
+   * Show the bar regardless of `count` — `true` for SELECTION MODE with nothing picked
+   * yet, `false` to hide it with rows still selected. Left out, `count > 0` decides, as
+   * before.
+   *
+   * keksdose's invoice lines (invoice-lines-bulk-bar.tsx) enter selection with a
+   * "Select" button, and the bar must be there at "0 selected" to hold the way out and
+   * a "Select all" (pass it as a child); gated on the count, the bar appeared only at
+   * the first tick, and the user who pressed "Select" saw nothing happen. The exit plays
+   * when it closes either way, and the count is still announced on every change.
+   */
+  open?: boolean;
   /** Clear the selection / leave selection mode. */
   onClear: () => void;
   /** The actions: buttons (`IconButton size="lg"` on a phone, `Button` from md up),
    *  in the caller's order. They are the toolbar's arrow-key stops, after the clear. */
   children?: ReactNode;
-  /** Default `floating`. See {@link BulkActionBarVariant}. */
-  variant?: BulkActionBarVariant;
+  /** Default `floating`. See {@link BulkActionBarVariant}; an object picks one per
+   *  breakpoint, see {@link ResponsiveBulkActionBarVariant}. */
+  variant?: BulkActionBarVariant | ResponsiveBulkActionBarVariant;
+  /**
+   * Content BELOW the toolbar row, inside the same surface — the same floating card or
+   * sticky tinted strip — but OUTSIDE the toolbar: its fields keep their own Tab stops
+   * and arrow keys, and the toolbar's roving focus never walks into it. keksdose's
+   * desktop receipt-line bar (invoice-lines-bulk-bar.tsx) shows its `BulkFields` form —
+   * a category picker, an exclude checkbox, Apply — under the count and the clear; a
+   * form is not a toolbar's content (`role="toolbar"` promises one arrow-key widget),
+   * and set beside the bar it lost the sticky tint and scrolled away from it.
+   *
+   * On the floating variant the panel scrolls within 60% of the viewport's height, so a
+   * long form on a phone cannot push the bar off the top of the screen.
+   */
+  panel?: ReactNode;
   /** Default: `bulkActionBar` from the {@link UiKitProvider}, else English. */
   labels?: Partial<BulkActionBarLabels>;
 }
@@ -105,7 +179,9 @@ export function BulkActionBar({
   count,
   onClear,
   children,
-  variant = "floating",
+  variant: variantProp = "floating",
+  open,
+  panel,
   labels: labelsProp,
   className,
   style,
@@ -116,21 +192,22 @@ export function BulkActionBar({
   const labels = useKitLabels("bulkActionBar", DEFAULT_BULK_ACTION_BAR_LABELS, labelsProp);
   const { announce, regionProps } = useAnnounce();
   const barRef = useRef<HTMLDivElement>(null);
-  const shown = count > 0;
+  const variant = useResolvedVariant(variantProp);
+  const shown = open ?? count > 0;
 
   // The count the bar last SHOWED, so a bar lowering itself after "clear" still reads
   // "3 selected" on its way out rather than "0 selected". Adjusted during render
   // (`Collapse`'s pattern), as is the exit below.
   const [shownCount, setShownCount] = useState(count);
   const [leaving, setLeaving] = useState(false);
-  const [prevCount, setPrevCount] = useState(count);
-  if (count !== prevCount) {
-    setPrevCount(count);
+  const [prev, setPrev] = useState({ count, shown });
+  if (count !== prev.count || shown !== prev.shown) {
+    setPrev({ count, shown });
     if (shown) {
       setShownCount(count);
       setLeaving(false);
-    } else {
-      setLeaving(prevCount > 0 && !prefersReducedMotion());
+    } else if (prev.shown) {
+      setLeaving(!prefersReducedMotion());
     }
   }
   useEffect(() => {
@@ -145,8 +222,9 @@ export function BulkActionBar({
   useEffect(() => {
     if (spoken.current === count) return;
     spoken.current = count;
-    announce(count > 0 ? labels.selected(count) : labels.cleared);
-  }, [count, labels, announce]);
+    // In selection mode the bar stays at zero, so zero is a count like any other.
+    announce(count > 0 || shown ? labels.selected(count) : labels.cleared);
+  }, [count, shown, labels, announce]);
 
   // Roving tab stop. The controls are the caller's, so the stop is kept on the DOM
   // rather than through props: after every render the remembered control (or the
@@ -191,54 +269,82 @@ export function BulkActionBar({
     </Button>
   );
 
+  const hasPanel = panel !== undefined && panel !== null && panel !== false;
+  // The surface — where the bar sits and what it looks like — and the toolbar row's
+  // own layout. Without a panel they are one element, exactly as before 0.11.0; with
+  // one the surface wraps the row and the panel, so both share its tint and position.
+  const surfaceClass = floating
+    ? cn(
+        "fixed z-30 rounded-2xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+        shown ? "animate-sheet" : "animate-sheet-out",
+      )
+    : cn(
+        variant === "sticky" &&
+          "sticky top-0 z-20 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur",
+        shown ? "animate-overlay" : "animate-overlay-out",
+      );
+  const rowClass = cn("flex items-center", floating ? "gap-1 px-2 py-1" : "gap-2 px-3 py-2");
+  const surfaceStyle = floating ? { ...FLOATING_STYLE, ...style } : style;
+
+  const toolbar = (
+    <div
+      {...(hasPanel ? null : rest)}
+      ref={barRef}
+      role="toolbar"
+      aria-label={labels.selected(shownCount)}
+      aria-orientation="horizontal"
+      data-bulk-action-bar={hasPanel ? undefined : variant}
+      // Leaving: out of the tab order and the accessibility tree at once, while the
+      // bar still animates. The selection it acted on is already gone.
+      inert={(!hasPanel && !shown) || undefined}
+      onKeyDown={handleKeyDown}
+      onFocus={(e) => {
+        onFocus?.(e);
+        // Clicking a control is using it: the stop follows the pointer too.
+        const hit = itemsOf(barRef.current).find((el) => el === e.target);
+        if (hit) {
+          active.current = hit;
+          rove(barRef.current, active);
+        }
+      }}
+      style={hasPanel ? undefined : surfaceStyle}
+      className={hasPanel ? rowClass : cn(rowClass, surfaceClass, className)}
+    >
+      {floating && clear}
+      <span className="min-w-0 flex-1 truncate text-sm font-medium text-[var(--text-primary)]">
+        {labels.selected(shownCount)}
+      </span>
+      {/* `contents`, so the caller's controls are flex items of the bar itself. */}
+      <div className="contents">{children}</div>
+      {!floating && clear}
+    </div>
+  );
+
   return (
     <>
       <span {...regionProps} />
-      <div
-        {...rest}
-        ref={barRef}
-        role="toolbar"
-        aria-label={labels.selected(shownCount)}
-        aria-orientation="horizontal"
-        data-bulk-action-bar={variant}
-        // Leaving: out of the tab order and the accessibility tree at once, while the
-        // bar still animates. The selection it acted on is already gone.
-        inert={!shown || undefined}
-        onKeyDown={handleKeyDown}
-        onFocus={(e) => {
-          onFocus?.(e);
-          // Clicking a control is using it: the stop follows the pointer too.
-          const hit = itemsOf(barRef.current).find((el) => el === e.target);
-          if (hit) {
-            active.current = hit;
-            rove(barRef.current, active);
-          }
-        }}
-        style={floating ? { ...FLOATING_STYLE, ...style } : style}
-        className={cn(
-          "flex items-center",
-          floating
-            ? cn(
-                "fixed z-30 gap-1 rounded-2xl border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 shadow-lg",
-                shown ? "animate-sheet" : "animate-sheet-out",
-              )
-            : cn(
-                "gap-2 px-3 py-2",
-                variant === "sticky" &&
-                  "sticky top-0 z-20 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur",
-                shown ? "animate-overlay" : "animate-overlay-out",
-              ),
-          className,
-        )}
-      >
-        {floating && clear}
-        <span className="min-w-0 flex-1 truncate text-sm font-medium text-[var(--text-primary)]">
-          {labels.selected(shownCount)}
-        </span>
-        {/* `contents`, so the caller's controls are flex items of the bar itself. */}
-        <div className="contents">{children}</div>
-        {!floating && clear}
-      </div>
+      {hasPanel ? (
+        <div
+          {...rest}
+          data-bulk-action-bar={variant}
+          inert={!shown || undefined}
+          style={surfaceStyle}
+          className={cn("flex flex-col", surfaceClass, className)}
+        >
+          {toolbar}
+          <div
+            data-bulk-action-bar-panel=""
+            className={cn(
+              "border-t border-[var(--border)] px-3 py-3",
+              floating && "max-h-[60dvh] overflow-y-auto",
+            )}
+          >
+            {panel}
+          </div>
+        </div>
+      ) : (
+        toolbar
+      )}
     </>
   );
 }

package/src/components/button-group.tsx

@@ -1,5 +1,6 @@
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
+import { buttonClasses, type ButtonSize, type ButtonVariant } from "./ui";
 
 // Every class below is spelled out in full rather than assembled from parts: the
 // consumer's Tailwind build finds classes by scanning this package's source as text,
@@ -8,12 +9,15 @@ import { cn } from "../lib/cn";
 // Each rule is written twice, once for a direct child and once for a `<button>` one
 // level down. The second is for a Tooltip-wrapped IconButton — the map zoom's + and −
 // both carry a tooltip — where the direct child is the tooltip's wrapper span and the
-// button that draws the border and the corners sits inside it.
+// button that draws the border and the corners sits inside it. The same again for an
+// `<a>` one level down: a router link member (see {@link ButtonGroupLink}) under a
+// tooltip. A bare link is a direct child and needs nothing extra.
 const JOINED_COMMON = cn(
   "inline-flex rounded-md border border-[var(--border)]",
   // The group draws the frame; each member gives up its own border, radius and shadow.
   "[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none",
   "[&>*>button]:rounded-none [&>*>button]:border-0 [&>*>button]:shadow-none",
+  "[&>*>a]:rounded-none [&>*>a]:border-0 [&>*>a]:shadow-none",
   "[&>*]:border-[var(--border)]",
   // A focused member rises above its neighbours so its ring is not painted over by
   // the next one's background.
@@ -30,6 +34,7 @@ const JOINED: Record<"horizontal" | "vertical", string> = {
     "[&>*:not(:first-child)]:border-s",
     "[&>:first-child]:rounded-s-md [&>:last-child]:rounded-e-md",
     "[&>:first-child>button]:rounded-s-md [&>:last-child>button]:rounded-e-md",
+    "[&>:first-child>a]:rounded-s-md [&>:last-child>a]:rounded-e-md",
   ),
   // The block axis is top-to-bottom in both reading directions, so top/bottom are
   // already the logical edges here.
@@ -39,13 +44,47 @@ const JOINED: Record<"horizontal" | "vertical", string> = {
     "[&>*:not(:first-child)]:border-t",
     "[&>:first-child]:rounded-t-md [&>:last-child]:rounded-b-md",
     "[&>:first-child>button]:rounded-t-md [&>:last-child>button]:rounded-b-md",
+    "[&>:first-child>a]:rounded-t-md [&>:last-child>a]:rounded-b-md",
   ),
 };
 
+// `gapped`: the members keep their own shape — round overlay discs, each its own
+// border and radius — and sit apart. Nothing is stripped, so there is nothing to
+// restore per edge, and the gap is logical by nature.
+const GAPPED: Record<"horizontal" | "vertical", string> = {
+  horizontal: "inline-flex flex-row items-center gap-1",
+  vertical: "inline-flex flex-col items-center gap-1",
+};
+
+// `elevated`, joined: the frame itself floats — a filled surface under the members (a
+// ghost member would otherwise show the content through it) and the shadow of a
+// control lifted over the page.
+const ELEVATED_JOINED = "bg-[var(--bg-surface)] shadow-lg";
+// `elevated`, gapped: there is no frame, so each disc carries the shadow. Aimed at the
+// control, not the tooltip's square wrapper span, whose shadow would be a box round a
+// round disc.
+const ELEVATED_GAPPED =
+  "[&>button]:shadow-md [&>a]:shadow-md [&>*>button]:shadow-md [&>*>a]:shadow-md";
+
 export interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
   /** `horizontal` (default): side by side, in reading order. `vertical`: stacked —
    *  the map's zoom + over −. */
   orientation?: "horizontal" | "vertical";
+  /**
+   * `joined` (default): one frame, hairline dividers, outer corners rounded. `gapped`:
+   * separate controls with a small gap, each keeping its own shape — the overlay
+   * discs of keksdose's receipt preview zoom (scan-file-preview.tsx:362, the − and +
+   * `IconButton variant="overlay"` in a hand-made `flex gap-1`), where a joined frame
+   * would be a box drawn over the photo.
+   */
+  variant?: "joined" | "gapped";
+  /**
+   * Float it: a surface with a shadow, for a toolbar that sits OVER content (a map's
+   * zoom, a photo's controls) rather than in the page's flow — keksdose adds
+   * `shadow-sm` to each disc on the receipt preview by hand. On a joined group the
+   * frame is filled and shadowed; on a gapped one, each member.
+   */
+  elevated?: boolean;
 }
 
 /**
@@ -63,13 +102,94 @@ export interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<"div">,
  * roving, and every member keeps its own tab stop, as plain adjacent buttons do.
  * For one-of-many selection use `ToggleGroup`, which has the radio semantics.
  */
-export function ButtonGroup({ orientation = "horizontal", className, ...rest }: ButtonGroupProps) {
+export function ButtonGroup({
+  orientation = "horizontal",
+  variant = "joined",
+  elevated = false,
+  className,
+  ...rest
+}: ButtonGroupProps) {
+  const joined = variant === "joined";
   return (
     <div
       {...rest}
       role="group"
       data-orientation={orientation}
-      className={cn(JOINED[orientation], className)}
+      data-variant={variant}
+      className={cn(
+        joined ? JOINED[orientation] : GAPPED[orientation],
+        elevated && (joined ? ELEVATED_JOINED : ELEVATED_GAPPED),
+        className,
+      )}
     />
   );
 }
+
+/** What {@link ButtonGroupLinkProps.renderLink} is handed. Spread it onto your router's
+ *  link, mapping `href` — `renderLink={({ href, ...p }) => <Link to={href} {...p} />}`. */
+export interface ButtonGroupLinkRenderProps {
+  href: string;
+  /** The button look — keep it, or the member is a bare link in the frame. */
+  className: string;
+  children: ReactNode;
+  ref?: Ref<HTMLAnchorElement>;
+  "aria-current"?: "page";
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+  [key: `aria-${string}`]: string | boolean | number | undefined;
+  [key: `data-${string}`]: unknown;
+}
+
+export interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<"a">, "href" | "className" | "children"> {
+  href: string;
+  /** The {@link Button} variant it looks like. Default `secondary`, the usual member. */
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  /** The member for the page you are on: `aria-current="page"` and the "on" look of a
+   *  pressed member, so a link row reads as a segmented switch between pages. */
+  current?: boolean;
+  /** Render through your router's `Link` — see {@link ButtonGroupLinkRenderProps}. */
+  renderLink?: (props: ButtonGroupLinkRenderProps) => ReactElement;
+  className?: string;
+  children: ReactNode;
+  ref?: Ref<HTMLAnchorElement>;
+}
+
+const LINK_CURRENT = "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]";
+
+/**
+ * A {@link ButtonGroup} member that navigates: a link drawn as a {@link Button}, so it
+ * joins the frame like one. A group mixing actions and pages — "Export" beside "Open
+ * report" — had to either make the page a button with an `onClick` navigate (no
+ * middle-click, no "open in new tab", no link semantics) or style an `<a>` whose
+ * corners the group did not know about. Plain `<a>` by default; `renderLink` for the
+ * router's `Link`, the kit's usual shape (`Chip`, `MenuItem`, `StatTile`).
+ */
+export function ButtonGroupLink({
+  href,
+  variant = "secondary",
+  size,
+  current = false,
+  renderLink,
+  className,
+  children,
+  ...rest
+}: ButtonGroupLinkProps) {
+  const props: ButtonGroupLinkRenderProps = {
+    ...rest,
+    href,
+    "aria-current": current ? "page" : undefined,
+    className: buttonClasses(variant, { size, className: cn(current && LINK_CURRENT, className) }),
+    children,
+  };
+  if (renderLink) return <RenderedGroupLink render={renderLink} {...props} />;
+  const { children: content, ...anchor } = props;
+  return <a {...anchor}>{content}</a>;
+}
+
+/** Calls `renderLink` as a component, so the router link's hooks are its own. */
+function RenderedGroupLink({
+  render,
+  ...props
+}: ButtonGroupLinkRenderProps & { render: (props: ButtonGroupLinkRenderProps) => ReactElement }) {
+  return render(props);
+}