@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/components/breadcrumbs.tsx

@@ -2,7 +2,8 @@ import { Fragment, useEffect, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import { ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 
 export interface BreadcrumbsLabels {
   /** The `nav` landmark's name — what a screen reader lists it as. */
@@ -35,7 +36,8 @@ export interface BreadcrumbLinkProps {
 
 export interface BreadcrumbsProps extends Omit<ComponentPropsWithoutRef<"nav">, "children"> {
   items: BreadcrumbItem[];
-  /** Your router's link. Default `<a>`. The API `Chip`, `StatTile` and `ListItem` share. */
+  /** Your router's link. Default: the `<UiKitProvider linkComponent>` (for an in-app
+   *  `href`), then `<a>`. The API `Chip`, `StatTile` and `ListItem` share. */
   renderLink?: (props: BreadcrumbLinkProps) => ReactElement;
   /**
    * The mark between crumbs. Default a chevron, mirrored in RTL — a chevron pointing
@@ -78,6 +80,7 @@ export function Breadcrumbs({
   ...rest
 }: BreadcrumbsProps) {
   const labels = useKitLabels("breadcrumbs", DEFAULT_BREADCRUMBS_LABELS, labelsProp);
+  const kitLink = useKitLink();
   const [expanded, setExpanded] = useState(false);
   // The "…" button vanishes when pressed; focus goes to the first crumb it revealed,
   // not back to the top of the document.
@@ -121,8 +124,11 @@ export function Breadcrumbs({
             );
           } else if (item.href !== undefined) {
             const props: BreadcrumbLinkProps = { href: item.href, className: linkClass, children: item.label };
+            const kit = pickLinkRenderer<BreadcrumbLinkProps>(undefined, kitLink, item.href);
             content = renderLink ? (
               renderLink(props)
+            ) : kit ? (
+              <RenderedKitLink render={kit} props={props} />
             ) : (
               <a href={props.href} className={props.className}>
                 {props.children}

package/src/components/button-group.tsx

@@ -1,6 +1,8 @@
 import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
 import { buttonClasses, type ButtonSize, type ButtonVariant } from "./ui";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 
 // 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,
@@ -147,7 +149,8 @@ export interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<"a">
   /** 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}. */
+  /** Render through your router's `Link` — see {@link ButtonGroupLinkRenderProps}.
+   *  Default: the `<UiKitProvider linkComponent>`, then `<a>`. */
   renderLink?: (props: ButtonGroupLinkRenderProps) => ReactElement;
   className?: string;
   children: ReactNode;
@@ -174,6 +177,7 @@ export function ButtonGroupLink({
   children,
   ...rest
 }: ButtonGroupLinkProps) {
+  const kitLink = useKitLink();
   const props: ButtonGroupLinkRenderProps = {
     ...rest,
     href,
@@ -181,7 +185,8 @@ export function ButtonGroupLink({
     className: buttonClasses(variant, { size, className: cn(current && LINK_CURRENT, className) }),
     children,
   };
-  if (renderLink) return <RenderedGroupLink render={renderLink} {...props} />;
+  const render = pickLinkRenderer(renderLink, kitLink, href);
+  if (render) return <RenderedGroupLink render={render} {...props} />;
   const { children: content, ...anchor } = props;
   return <a {...anchor}>{content}</a>;
 }

package/src/components/calendar-heatmap.tsx

@@ -4,6 +4,8 @@ import { cn } from "../lib/cn";
 import { dirOf, horizontalStep } from "../lib/direction";
 import { addMonthsClamped, localeWeekStart, parseIsoDate, toLocalIso } from "../lib/dates";
 import { useKitLabels, useKitLocale, useKitWeekStart } from "../i18n/kit-labels";
+import { lerpHex, textOn } from "../theme/chart-palette";
+import { parseHex } from "../theme/color";
 import { Tooltip } from "./tooltip";
 import type { WeekDay } from "./mini-calendar";
 
@@ -103,6 +105,39 @@ export interface CalendarHeatmapProps extends Omit<ComponentPropsWithoutRef<"div
   /** The scale's colour, as any CSS colour. Default `var(--brand)`; each step is this
    *  mixed into `--bg-surface`, so the ramp follows the theme. */
   color?: string;
+  /**
+   * A CONTINUOUS scale from `colorFrom` (the smallest value) to `colorTo` (the busiest
+   * day), instead of `levels` steps of `color` — keksdose's palette-store ramp,
+   * `seqLow` → `seqHigh`. Both are needed; `color` is then unused. Two `#rrggbb`
+   * colours are interpolated in JS, so the fill is a concrete hex and the day number's
+   * ink (in `"month"`) is MEASURED against it; anything else (a `var()`) is mixed with
+   * `color-mix()`. `levels` still sets `data-level` and the legend's swatch count.
+   */
+  colorFrom?: string;
+  colorTo?: string;
+  /**
+   * A fill of the caller's own for a day with a value: handed the value and the
+   * scale's `max`, returns any CSS colour. Wins over `color` and `colorFrom`/`colorTo`.
+   * Also paints the legend, at `max × level / levels`.
+   */
+  fill?: (value: number, max: number) => string;
+  /** The fill of a day with no value (or a value of 0). Default: a wash of the text
+   *  colour over the surface, which reads as a cell on both themes. */
+  emptyColor?: string;
+  /**
+   * Where the window ENDS — the day `maxDays` counts back from, and the last one drawn:
+   *
+   * - `"to"` (default): on `to`.
+   * - `"today"`: on today.
+   * - `"latest"`: on the last day that can carry a figure — today, or a later day that
+   *   actually has a value. A window running into the future (a report's "all" preset
+   *   ends a year ahead) then spends its cells on the days a person is looking for,
+   *   not on a year of empty ones.
+   * - a `"YYYY-MM-DD"`: on that day.
+   *
+   * Always kept inside `from`…`to`.
+   */
+  anchor?: "to" | "today" | "latest" | (string & {});
   /**
    * The most days to draw. A longer window keeps its LATEST `maxDays` and says how many
    * it left out (`labels.truncated`) rather than silently ending. Default: no cap.
@@ -131,6 +166,26 @@ const EMPTY_FILL = "color-mix(in oklab, var(--text-primary) 8%, var(--bg-surface
 
 const weekdayIndex = (d: Date, weekStart: WeekDay) => (d.getDay() - weekStart + 7) % 7;
 
+/** Where the window ends for an {@link CalendarHeatmapProps.anchor}, kept in `[from, to]`.
+ *  `latestData` is the latest ISO date carrying a value, or `""`. */
+export function heatmapWindowEnd(
+  from: string,
+  to: string,
+  anchor: string,
+  latestData: string,
+  today: string = toLocalIso(new Date()),
+): string {
+  let end: string;
+  if (anchor === "today") end = today;
+  else if (anchor === "latest") end = latestData > today ? latestData : today;
+  else if (anchor === "to" || !parseIsoDate(anchor)) end = to;
+  else end = anchor;
+  // ISO dates sort as strings, so the clamp is plain comparison.
+  if (end > to) end = to;
+  if (end < from) end = from;
+  return end;
+}
+
 /** The step a value falls on: 0 for nothing, else 1…levels by its share of `max`. */
 export function heatmapLevel(value: number, max: number, levels: number): number {
   if (!(value > 0) || !(max > 0) || levels < 1) return 0;
@@ -159,7 +214,9 @@ function levelFill(level: number, levels: number, color: string): string {
  * the other way round, mirrored in RTL — PageUp/PageDown move a month and Home/End go
  * to the window's first/last day. Each cell is named with its whole date AND its value,
  * because the colour is not something a screen reader can say, and carries
- * `data-day="YYYY-MM-DD"` as its identity for tests and for the host.
+ * `data-day="YYYY-MM-DD"` as its identity for tests and for the host. Note that in
+ * `"weeks"` the cells are in DOM order by WEEKDAY ROW (all Mondays, then all
+ * Tuesdays…), not by date — query by `data-day`, not by position.
  *
  * The tooltip is portalled (a year of squares always sits in a sideways scroller) and
  * `data-private` unless `sensitive={false}`. Cell size in `"weeks"` is the CSS variable
@@ -178,6 +235,11 @@ export function CalendarHeatmap({
   max: maxProp,
   levels = 4,
   color = "var(--brand)",
+  colorFrom,
+  colorTo,
+  fill: fillProp,
+  emptyColor,
+  anchor = "to",
   maxDays,
   legend = true,
   locale: localeProp,
@@ -202,9 +264,16 @@ export function CalendarHeatmap({
 
   // The window, trimmed from the FRONT: the days a person looks for are the recent
   // ones, and a cap that kept the oldest would end the calendar before today.
+  const latestData = useMemo(() => {
+    let latest = "";
+    for (const [iso, v] of values) if (v !== 0 && iso > latest) latest = iso;
+    return latest;
+  }, [values]);
+  const windowEnd = heatmapWindowEnd(from, to, anchor, latestData);
+
   const { days, dropped } = useMemo(() => {
     const start = parseIsoDate(from);
-    const end = parseIsoDate(to);
+    const end = parseIsoDate(windowEnd);
     const list: Date[] = [];
     if (!start || !end || end < start) return { days: list, dropped: 0 };
     const cursor = new Date(end);
@@ -216,7 +285,7 @@ export function CalendarHeatmap({
     const first = list[0];
     const trimmed = first ? Math.round((first.getTime() - start.getTime()) / 86_400_000) : 0;
     return { days: list, dropped: Math.max(0, trimmed) };
-  }, [from, to, maxDays]);
+  }, [from, windowEnd, maxDays]);
 
   const firstIso = days.length ? toLocalIso(days[0]) : "";
   const lastIso = days.length ? toLocalIso(days[days.length - 1]) : "";
@@ -341,13 +410,43 @@ export function CalendarHeatmap({
   };
 
   const legendLevels = Array.from({ length: levels + 1 }, (_, l) => l);
+  const empty = emptyColor ?? EMPTY_FILL;
+  const continuous = colorFrom !== undefined && colorTo !== undefined;
+  const hexRamp = continuous && parseHex(colorFrom) != null && parseHex(colorTo) != null;
+
+  /** A day's fill, and the ink its number is set in (`"month"`). */
+  const paint = (value: number, level: number): { fill: string; ink: string } => {
+    if (level === 0) return { fill: empty, ink: "var(--text-primary)" };
+    if (fillProp || continuous) {
+      const t = max > 0 ? Math.min(1, Math.max(0, value / max)) : 1;
+      const fill = fillProp
+        ? fillProp(value, max)
+        : hexRamp
+          ? lerpHex(colorFrom!, colorTo!, t)
+          : `color-mix(in oklab, ${colorTo} ${Math.round(t * 100)}%, ${colorFrom})`;
+      // Measured where the fill is a colour; a mix of references cannot be measured,
+      // and the page's own text colour is the safe answer there.
+      const measured = textOn(fill);
+      return { fill, ink: measured === "currentColor" ? "var(--text-primary)" : measured };
+    }
+    // Light text once the fill is the stronger half of the mix — `--bg-surface` is the
+    // colour the scale is mixed INTO, so it is the one that contrasts with its far end
+    // on either theme.
+    const strong = levelPercent(level, levels) >= 45;
+    return {
+      fill: levelFill(level, levels, color),
+      ink: strong ? "var(--bg-surface)" : "var(--text-primary)",
+    };
+  };
+  // The legend's swatches: a value that lands on each step (the top one on `max`).
+  const legendFill = (l: number) => paint(((max > 0 ? max : 1) * l) / levels, l).fill;
 
   const cell = (d: Date, wrapClass: string, cellClass: string, withNumber: boolean) => {
     const iso = toLocalIso(d);
     const raw = values.get(iso);
     const value = raw ?? 0;
     const level = heatmapLevel(value, max, levels);
-    const fill = levelFill(level, levels, color);
+    const { fill, ink } = paint(value, level);
     const formattedDate = formatDay(d);
     const formattedValue = formatValue(value);
     const name = labels.day(formattedDate, formattedValue);
@@ -355,10 +454,6 @@ export function CalendarHeatmap({
       ? tooltip({ iso, date: d, value, hasData: raw !== undefined, level, formattedDate, formattedValue })
       : name;
     const isSelected = selected === iso;
-    // Light text once the fill is the stronger half of the mix — `--bg-surface` is the
-    // colour the scale is mixed INTO, so it is the one that contrasts with its far end
-    // on either theme.
-    const strong = level > 0 && levelPercent(level, levels) >= 45;
     const shared = {
       role: "gridcell",
       "data-day": iso,
@@ -370,7 +465,7 @@ export function CalendarHeatmap({
       onFocus: () => {
         if (iso !== activeIso) setActiveIso(iso);
       },
-      style: { background: fill, color: strong ? "var(--bg-surface)" : "var(--text-primary)" },
+      style: { background: fill, color: ink },
       className: cn(
         cellClass,
         isSelected && "ring-2 ring-[var(--text-primary)]",
@@ -493,7 +588,7 @@ export function CalendarHeatmap({
               key={l}
               data-legend-level={l}
               className="size-2.5 rounded-sm"
-              style={{ background: levelFill(l, levels, color) }}
+              style={{ background: legendFill(l) }}
             />
           ))}
           <span className="ms-0.5">{labels.more}</span>

package/src/components/chip.tsx

@@ -5,7 +5,8 @@ import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
 import { FIELD_INVALID } from "./ui";
-import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLink, useKitLocale } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 
 /**
  * A chip: a compact pill carrying one value.
@@ -384,7 +385,8 @@ export type ChipProps = ChipBaseProps &
         /**
          * Renders the link for `href` — pass your router's `<Link>` here, since a
          * plain `<a>` reloads a single-page app (keksdose's account-menu admin pill).
-         * Default: `<a>`. Ignored without `href`.
+         * Default: the `<UiKitProvider linkComponent>`, then `<a>`. Ignored without
+         * `href`.
          *
          * A render function rather than an `as={Link}`, for three reasons. It is the
          * API `StatTile` already has (`renderLink`), so a consumer learns it once.
@@ -455,6 +457,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
   ref,
 ) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS, { remove: removeLabel });
+  const kitLink = useKitLink();
   const s = SIZE[size];
   const interactive = !!href || !!onClick;
   // One radius for every rounded piece — the pill, the body inside a split pill, the ×
@@ -570,10 +573,11 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
       className: remove ? inner : look,
       children: body,
     };
-    const link = renderLink ? (
+    const render = pickLinkRenderer(renderLink, kitLink, href);
+    const link = render ? (
       // Through a component rather than called here, so the forwarded ref arrives as
       // an ordinary prop of an element and is never handed to a function mid-render.
-      <RenderedLink render={renderLink} {...linkProps} />
+      <RenderedLink render={render} {...linkProps} />
     ) : (
       <a
         ref={ref as React.Ref<HTMLAnchorElement>}

package/src/components/choice-card.tsx

@@ -1,8 +1,19 @@
 import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useRef } from "react";
-import type { ButtonHTMLAttributes, ChangeEvent, ComponentType, InputHTMLAttributes, ReactNode } from "react";
+import type {
+  ButtonHTMLAttributes,
+  ChangeEvent,
+  ComponentType,
+  InputHTMLAttributes,
+  MouseEvent,
+  ReactElement,
+  ReactNode,
+  Ref,
+} from "react";
 import { Check, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
 import { assignRef, hasMessage, mergeDescribedBy } from "./choice-parts";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 
 /**
  * A checkbox or a radio, presented as a bordered card: a title, a line of description,
@@ -231,6 +242,30 @@ const META_TONE: Record<ActionCardMetaTone, string> = {
   success: "text-[var(--success)]",
 };
 
+/** The colour of {@link ActionCardProps.icon}. `default` is the secondary text colour
+ *  the icon has always had; `brand` tints it (keksdose's privacy enrolment). */
+export type ActionCardIconTone = "default" | "muted" | "brand" | "warning" | "danger" | "info" | "success";
+
+const ICON_TONE: Record<ActionCardIconTone, string> = {
+  default: "text-[var(--text-secondary)]",
+  ...META_TONE,
+  brand: "text-[var(--brand)]",
+};
+
+/** What {@link ActionCardProps.renderLink} (and the provider's `linkComponent`) is
+ *  handed. Spread it onto your router's link — `({ href, ...p }) => <Link to={href} {...p} />`. */
+export interface ActionCardLinkProps {
+  href: string;
+  /** The card's whole look — keep it. */
+  className: string;
+  children: ReactNode;
+  ref?: Ref<HTMLAnchorElement>;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+  id?: string;
+  [key: `aria-${string}`]: string | boolean | number | undefined;
+  [key: `data-${string}`]: unknown;
+}
+
 export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> {
   /** What the card does — the button's accessible name. */
   title: ReactNode;
@@ -247,6 +282,21 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
   metaTone?: ActionCardMetaTone;
   /** A Lucide icon (or any component taking a `className`), shown at the card's start. */
   icon?: ChoiceCardProps["icon"];
+  /** The icon's colour. Default `default` (the secondary text colour). */
+  iconTone?: ActionCardIconTone;
+  /** Classes on the icon, after {@link iconTone} — a size, a tinted tile behind it. */
+  iconClassName?: string;
+  /**
+   * Makes the card a LINK to another page rather than a button that acts: kastlan's
+   * section tiles on the group overview (group-overview-page), each an icon, a name and
+   * a line on what is there. A real `<a href>`, so a middle click opens it in a new
+   * tab. A `disabled` card renders the inert button instead — a link cannot be
+   * disabled. The ref then reaches the `<a>`.
+   */
+  href?: string;
+  /** Your router's link for an in-app `href`. Default: the `<UiKitProvider
+   *  linkComponent>`, then a plain `<a>`. Ignored without `href`. */
+  renderLink?: (props: ActionCardLinkProps) => ReactElement;
 }
 
 /**
@@ -254,7 +304,8 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
  * card's icon, title and description, plus a `meta` line, that runs `onClick` the
  * moment it is pressed. keksdose's privacy enrolment (privacy-enroll-dialog:345,
  * `CustodyOption`) offers two custody modes this way — picking one IS the next step,
- * so there is no checked state to show and no "Continue" to press after it.
+ * so there is no checked state to show and no "Continue" to press after it. With
+ * `href` it is the same card as a link (kastlan's overview section tiles).
  *
  * A separate component rather than `ChoiceCard as="button"`: a ChoiceCard is an
  * `<input>` (its ref, its `checked`, its form value), and a button shares none of it.
@@ -262,9 +313,24 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
  * "Keep the key yourself, button" and then the explanation, not one long name.
  */
 export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(function ActionCard(
-  { title, description, meta, metaTone = "muted", icon: Icon, className, id, type = "button", ...rest },
+  {
+    title,
+    description,
+    meta,
+    metaTone = "muted",
+    icon: Icon,
+    iconTone = "default",
+    iconClassName,
+    href,
+    renderLink,
+    className,
+    id,
+    type = "button",
+    ...rest
+  },
   ref,
 ) {
+  const kitLink = useKitLink();
   const generated = useId();
   const baseId = id ?? generated;
   const titleId = `${baseId}-title`;
@@ -272,28 +338,23 @@ export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(functio
   const metaId = `${baseId}-meta`;
   const showDescription = hasMessage(description);
   const showMeta = hasMessage(meta);
-  return (
-    <button
-      ref={ref}
-      id={id}
-      type={type}
-      {...rest}
-      aria-labelledby={rest["aria-labelledby"] ?? titleId}
-      aria-describedby={mergeDescribedBy(
-        rest["aria-describedby"],
-        showDescription && descriptionId,
-        showMeta && metaId,
-      )}
-      className={cn(
-        "flex w-full items-start gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] p-3 text-start shadow-sm transition-colors",
-        "hover:border-[var(--brand)] hover:bg-[var(--bg-hover)]",
-        // The outline, as on ChoiceCard: the card is what the eye is on.
-        "focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
-        "disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:border-[var(--border)] disabled:hover:bg-[var(--bg-surface)]",
-        className,
-      )}
-    >
-      {Icon && <Icon aria-hidden className="mt-0.5 size-5 shrink-0 text-[var(--text-secondary)]" />}
+  const look = cn(
+    "flex w-full items-start gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] p-3 text-start shadow-sm transition-colors",
+    "hover:border-[var(--brand)] hover:bg-[var(--bg-hover)]",
+    // The outline, as on ChoiceCard: the card is what the eye is on.
+    "focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
+    "disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:border-[var(--border)] disabled:hover:bg-[var(--bg-surface)]",
+    className,
+  );
+  const labelledBy = rest["aria-labelledby"] ?? titleId;
+  const describedBy = mergeDescribedBy(
+    rest["aria-describedby"],
+    showDescription && descriptionId,
+    showMeta && metaId,
+  );
+  const body = (
+    <>
+      {Icon && <Icon aria-hidden className={cn("mt-0.5 size-5 shrink-0", ICON_TONE[iconTone], iconClassName)} />}
       <span className="min-w-0 flex-1 space-y-1">
         <span id={titleId} className="block text-sm font-medium leading-5 text-[var(--text-primary)]">
           {title}
@@ -309,11 +370,61 @@ export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(functio
           </span>
         )}
       </span>
+    </>
+  );
+
+  if (href !== undefined && !rest.disabled) {
+    // The button-only attributes stay behind; `aria-*`, `data-*` and handlers ride along.
+    const {
+      disabled: _disabled,
+      form: _form,
+      formAction: _formAction,
+      name: _name,
+      value: _value,
+      onClick,
+      ...anchorRest
+    } = rest;
+    const linkProps: ActionCardLinkProps = {
+      ...(anchorRest as Partial<ActionCardLinkProps>),
+      ref: ref as unknown as Ref<HTMLAnchorElement>,
+      id,
+      href,
+      "aria-labelledby": labelledBy,
+      "aria-describedby": describedBy,
+      onClick: onClick as unknown as ActionCardLinkProps["onClick"],
+      className: look,
+      children: body,
+    };
+    const render = pickLinkRenderer(renderLink, kitLink, href);
+    if (render) return <RenderedActionLink render={render} {...linkProps} />;
+    const { children: content, ...anchor } = linkProps;
+    return <a {...anchor}>{content}</a>;
+  }
+
+  return (
+    <button
+      ref={ref}
+      id={id}
+      type={type}
+      {...rest}
+      aria-labelledby={labelledBy}
+      aria-describedby={describedBy}
+      className={look}
+    >
+      {body}
     </button>
   );
 });
 ActionCard.displayName = "ActionCard";
 
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedActionLink({
+  render,
+  ...props
+}: ActionCardLinkProps & { render: (props: ActionCardLinkProps) => ReactElement }) {
+  return render(props);
+}
+
 /* ── ChoiceCardGroup ─────────────────────────────────────────────────────── */
 
 export interface ChoiceCardOption<T extends string> {

package/src/components/combobox-core.tsx

@@ -10,6 +10,7 @@ import type {
 } from "react";
 import { Check, Plus } from "lucide-react";
 import { cn } from "../lib/cn";
+import { CLIPS_ATTRIBUTE } from "../lib/clipping";
 import { DropdownSearchHeader } from "./dropdown";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import { useMediaQuery } from "../hooks/use-media-query";
@@ -636,6 +637,10 @@ export function ComboboxPanel<V extends string | number>({
       // The rows are provisional while a lookup is in flight — whether or not the
       // previous query's are still showing.
       aria-busy={busy || undefined}
+      // It scrolls, and says so where jsdom can see it (see `CLIPS_ATTRIBUTE`): a
+      // Tooltip in a row then portals out in a test exactly as it does in the
+      // browser, instead of joining the option's accessible name (keksdose E8).
+      {...{ [CLIPS_ATTRIBUTE]: "" }}
       className={cn("min-h-0 flex-1 overflow-y-auto py-1", isPhone && "flex-none")}
     >
       {results.map((o, i) => {

package/src/components/combobox.tsx

@@ -113,7 +113,7 @@ function SuggestionList({
       dir={dir}
       style={{ top, left: rect.left, width: rect.width }}
     >
-      <ul id={id} role="listbox" className={LIST_CLASS} style={{ maxHeight }}>
+      <ul id={id} role="listbox" data-clips="" className={LIST_CLASS} style={{ maxHeight }}>
         {children}
       </ul>
     </div>,
@@ -238,9 +238,19 @@ export function Combobox({
   onBlur,
   onSubmit,
   "aria-label": ariaLabel,
+  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+  // on the wrapper div the hint and required state described nothing.
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: ComboboxProps) {
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy,
+  );
   const generated = useId();
   const fieldId = id ?? generated;
   // Derived from the GENERATED id, never from `id`: a caller's id is theirs to
@@ -366,9 +376,9 @@ export function Combobox({
       : null;
 
   return (
-    // `rest` dresses the outer box — a `data-tour` anchor, a test id, a form-level
-    // `aria-describedby`. Not the NAME: that belongs on the <input> below, which is
-    // the combobox a reader meets. Spread FIRST, so the field's ARIA and the
+    // `rest` dresses the outer box — a `data-tour` anchor, a test id. Not the NAME,
+    // description, invalid or required state: those belong on the <input> below,
+    // which is the combobox a reader meets. Spread FIRST, so the field's ARIA and the
     // handlers carrying live #309 and dev#549 cannot be replaced from outside.
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> since lenkbank's tests met a field `getByLabelText` could
@@ -407,6 +417,7 @@ export function Combobox({
           aria-autocomplete="list"
           aria-invalid={field.isInvalid || undefined}
           aria-describedby={field.describedBy}
+          aria-required={ariaRequired}
           autoComplete="off"
           disabled={disabled}
           autoFocus={autoFocus}
@@ -729,12 +740,22 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   invalid,
   error,
   "aria-label": ariaLabel,
+  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+  // on the wrapper div the hint and required state described nothing.
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: InlineEntityComboboxProps<V, C>) {
   // The clear value reads as "nothing selected", whichever one the caller picked —
   // so from here down `value` is the id or `null`, as it always was.
   const value: V | null = rawValue == null || rawValue === clearValue ? null : (rawValue as V);
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy,
+  );
   const generated = useId();
   const fieldId = id ?? generated;
   // See the twin above on why these hang off the generated id.
@@ -853,9 +874,9 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   };
 
   return (
-    // `rest` dresses the outer box — a `data-tour` anchor, a test id, a form-level
-    // `aria-describedby`. Not the NAME: that belongs on the <input> below, which is
-    // the combobox a reader meets. Spread FIRST, so the field's ARIA and the
+    // `rest` dresses the outer box — a `data-tour` anchor, a test id. Not the NAME,
+    // description, invalid or required state: those belong on the <input> below,
+    // which is the combobox a reader meets. Spread FIRST, so the field's ARIA and the
     // handlers carrying live #309 and dev#549 cannot be replaced from outside.
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> — see {@link Combobox}. */}
@@ -889,6 +910,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
           aria-autocomplete="list"
           aria-invalid={field.isInvalid || undefined}
           aria-describedby={field.describedBy}
+          aria-required={ariaRequired}
           autoComplete="off"
           disabled={disabled}
           autoFocus={autoFocus}

package/src/components/copy-button.tsx

@@ -56,7 +56,8 @@ export interface CopyButtonProps
   stopPropagation?: boolean;
   /** Icon variant only: where the result tooltip opens. */
   tooltipSide?: TooltipSide;
-  /** Pass through to the tooltip — needed inside a scroll container (see Tooltip). */
+  /** Pass through to the tooltip. Left unset, the Tooltip decides on its own — it
+   *  portals inside a clipping container (a DataTable's `data-clips` scroller). */
   tooltipPortal?: boolean;
   /** ms until the button returns to idle. Default 2000. */
   resetAfter?: number;
@@ -93,7 +94,7 @@ export function CopyButton({
   tone,
   stopPropagation,
   tooltipSide = "top",
-  tooltipPortal = false,
+  tooltipPortal,
   resetAfter = 2000,
   onCopied,
   labels,