@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/components/ui.tsx

@@ -57,6 +57,40 @@ const buttonVariantClasses: Record<ButtonVariant, string> = {
     "rounded-sm p-0 bg-transparent text-[var(--brand)] underline-offset-4 hover:underline focus:ring-[var(--brand)]",
 };
 
+/**
+ * The text colour of a `link` or `ghost` button, over the variant's own.
+ *
+ * `muted` is the QUIET link keksdose hand-rolls in six places (tours-page:321's "Mark
+ * undone", transaction-fields:176/215's "Add line" / "Fill total",
+ * invoice-lines-table:376, invoice-review:464): secondary text that darkens to the
+ * body colour under the pointer, for an action that must be findable but not compete
+ * with the brand-coloured one beside it. `danger` is the same quiet look turning
+ * `--danger` on hover — transaction-editor:401's "Remove split", which is a text
+ * action that destroys something.
+ *
+ * A `tone` rather than a `link-muted` variant, because it is the axis IconButton
+ * already has (`tone="muted"`, `tone="danger"`, same quiet-until-hover meaning), and
+ * because the same two looks are wanted on `ghost`. The filled and bordered variants
+ * carry their meaning in the box, not the text, so a tone on them does nothing.
+ */
+export type ButtonTone = "default" | "muted" | "danger";
+
+const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
+  muted:
+    "text-[var(--text-secondary)] hover:text-[var(--text-primary)] disabled:hover:text-[var(--text-secondary)]",
+  danger:
+    "text-[var(--text-secondary)] hover:text-[var(--danger)] focus:ring-[var(--danger-border)] disabled:hover:text-[var(--text-secondary)]",
+};
+
+/** Only the two transparent variants take a tone; see {@link ButtonTone}. */
+const TONED_VARIANTS = new Set<ButtonVariant>(["link", "ghost"]);
+
+// `pressed` on a `link`: the brand colour and a heavier weight, which is exactly what
+// lenkbank's "All speeds" toggle paints by hand (gear/hysteresis-charts.tsx:482). After
+// the tone, so a pressed muted link is brand, and an unpressed one is quiet grey.
+const BUTTON_LINK_PRESSED =
+  "font-medium text-[var(--brand)] hover:text-[var(--brand)] disabled:hover:text-[var(--brand)]";
+
 /** The second argument of {@link buttonClasses} in its options form. */
 export interface ButtonClassesOptions {
   /** See {@link ButtonProps.size}. */
@@ -105,12 +139,75 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
    *  ordinary prop, so it rides `...rest` onto the element with no `forwardRef` —
    *  declared here only because `ButtonHTMLAttributes` does not carry it. */
   ref?: Ref<HTMLButtonElement>;
+  /** Text colour for `link` and `ghost`: `muted` (quiet, body colour on hover) or
+   *  `danger` (quiet, `--danger` on hover). Ignored by the other variants. See
+   *  {@link ButtonTone}. */
+  tone?: ButtonTone;
+  /**
+   * Make it a toggle button, as {@link IconButton}'s `pressed` does. `true` sets
+   * `aria-pressed="true"` and draws the "on" look — on a `link`, the brand colour and a
+   * medium weight; on the boxed variants, the quiet brand fill IconButton uses — and
+   * `false` sets `aria-pressed="false"` with the ordinary look. Left out, no
+   * `aria-pressed` (or the caller's own). For lenkbank's "All speeds" text toggle
+   * (gear/hysteresis-charts.tsx:482), which is a hand-rolled `<button aria-pressed>`
+   * swapping two class strings; with `variant="link" tone="muted"` it is this.
+   */
+  pressed?: boolean;
+  /**
+   * Why the action is not available — the button's half of DangerConfirm's
+   * `lockedReason` (kastlan handover-detail-page.tsx:197 locks a signed handover).
+   *
+   * A disabled button that cannot say why is a dead end: the native `disabled` takes it
+   * out of the tab order, so a keyboard user never lands on it, and a pointer gets a
+   * `not-allowed` cursor and nothing else. With a reason the button is `aria-disabled`
+   * instead — still focusable, still hoverable — clicks (and the Enter/Space and form
+   * submission they stand for) do nothing, and the reason is shown in the kit
+   * {@link Tooltip} and attached with `aria-describedby`, so a screen reader hears it
+   * on focus. It wins over `disabled`: passing both keeps the button reachable, which is
+   * the point of giving a reason.
+   *
+   * The description is a `hidden` copy of the reason rather than the bubble itself: the
+   * bubble exists only while hovered or focused once it is portalled, and a description
+   * that comes and goes is read inconsistently. The bubble is kept visual, the way
+   * DangerConfirm keeps its own.
+   */
+  disabledReason?: ReactNode;
 }
 
-export function Button({ variant = "primary", size = "md", stretch, className, ...rest }: ButtonProps) {
-  return (
+function hasContent(node: ReactNode): boolean {
+  return node !== undefined && node !== null && node !== false && node !== "";
+}
+
+export function Button({
+  variant = "primary",
+  size = "md",
+  stretch,
+  tone = "default",
+  pressed,
+  disabledReason,
+  className,
+  onClick,
+  ...rest
+}: ButtonProps) {
+  const reasonId = useId();
+  const locked = hasContent(disabledReason);
+  const ownDescribedBy = rest["aria-describedby"];
+  const button = (
     <button
       {...rest}
+      disabled={locked ? undefined : rest.disabled}
+      aria-disabled={locked || rest["aria-disabled"]}
+      aria-describedby={locked ? (ownDescribedBy ? `${ownDescribedBy} ${reasonId}` : reasonId) : ownDescribedBy}
+      aria-pressed={pressed ?? rest["aria-pressed"]}
+      onClick={(e) => {
+        // `preventDefault` as well as not calling through: a locked submit button must
+        // not submit its form, and the browser does that after this handler returns.
+        if (locked) {
+          e.preventDefault();
+          return;
+        }
+        onClick?.(e);
+      }}
       className={cn(
         BUTTON_BASE,
         BUTTON_SIZES[size],
@@ -119,10 +216,29 @@ export function Button({ variant = "primary", size = "md", stretch, className, .
         // align-items). No effect outside a flex row / when it's already the tallest.
         stretch && "self-stretch",
         buttonVariantClasses[variant],
+        tone !== "default" && TONED_VARIANTS.has(variant) && BUTTON_TONES[tone],
+        pressed && (variant === "link" ? BUTTON_LINK_PRESSED : ICON_BUTTON_PRESSED),
+        // The disabled look for the focusable kind of disabled.
+        locked && "cursor-not-allowed opacity-50",
         className,
       )}
     />
   );
+  if (!locked) return button;
+  return (
+    // The button in a FRAGMENT so Tooltip does not clone its bubble into the
+    // description as well — the hidden copy below already describes it, and the same
+    // sentence twice would be read on every focus. `stretch` moves to the wrapper,
+    // which is now the flex item.
+    <Tooltip label={disabledReason} className={stretch ? "self-stretch" : undefined}>
+      <>
+        {button}
+        <span id={reasonId} hidden>
+          {disabledReason}
+        </span>
+      </>
+    </Tooltip>
+  );
 }
 
 // Canonical square icon-only button. <Button> carries TEXT geometry — px-3 py-2
@@ -138,12 +254,15 @@ export function Button({ variant = "primary", size = "md", stretch, className, .
 const ICON_BUTTON_BASE =
   "inline-flex items-center justify-center rounded-md transition-colors focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed";
 
-export type IconButtonSize = "lg" | "md" | "sm" | "xs" | "2xs";
+export type IconButtonSize = "xl" | "lg" | "md" | "sm" | "xs" | "2xs";
 
 // Box and glyph together, so a 24px chip action cannot end up holding a 20px icon
 // that touches its edges. The two small steps are lenkbank's list-row (28px) and
 // chip (24px) actions, which it had hand-rolled beside the kit's 32/36px ones.
 const ICON_BUTTON_SIZES: Record<IconButtonSize, string> = {
+  // 48px with a 24px glyph: the one primary action of a phone screen or sheet, a step
+  // past the 44px minimum rather than on it.
+  xl: "size-12 [&_svg]:size-6",
   // The 44px touch target (WCAG 2.5.5's size) with the same 20px glyph — keksdose's
   // bulk-action bars write `size-11` by hand over an `md` button to get it on phones.
   lg: "size-11 [&_svg]:size-5",
@@ -153,6 +272,18 @@ const ICON_BUTTON_SIZES: Record<IconButtonSize, string> = {
   "2xs": "size-6 rounded [&_svg]:size-3.5",
 };
 
+// `stretch`: the same WIDTH and glyph, and a height taken from the row instead of
+// stated — `size-*` sets a height that `self-stretch` cannot override, so the box is
+// written as a width plus a minimum height (the square it would otherwise be).
+const ICON_BUTTON_STRETCH_SIZES: Record<IconButtonSize, string> = {
+  xl: "w-12 min-h-12 self-stretch [&_svg]:size-6",
+  lg: "w-11 min-h-11 self-stretch [&_svg]:size-5",
+  md: "w-9 min-h-9 self-stretch [&_svg]:size-5",
+  sm: "w-8 min-h-8 self-stretch [&_svg]:size-5",
+  xs: "w-7 min-h-7 self-stretch rounded [&_svg]:size-4",
+  "2xs": "w-6 min-h-6 self-stretch rounded [&_svg]:size-3.5",
+};
+
 // A tone re-colours the glyph without changing what the variant draws around it.
 // Each coloured tone comes in two resting looks, picked by `quiet` (see the prop):
 // QUIET is placeholder grey until the pointer or focus arrives, then the tone's
@@ -163,9 +294,14 @@ const ICON_BUTTON_SIZES: Record<IconButtonSize, string> = {
 // on the row to notice (keksdose's "needs review" flag, its reconcile action at
 // accounts-page:867), and quiet grey would hide the very thing they point out.
 // `muted` is quiet by definition and has no toned look; `default` has no tone.
-export type IconButtonTone = "default" | "muted" | "danger" | "warning" | "info";
+//
+// `success` is toned at rest too: the green is the news (keksdose's "in sync" chip).
+// `custom` paints from `--icon-button-tone`, which `toneColor` sets — for a glyph whose
+// colour FOLLOWS STATE across tones (keksdose's sync chip: rose, amber, sky, green as
+// the sync moves), where swapping `tone` would do but the colour is one variable.
+export type IconButtonTone = "default" | "muted" | "danger" | "warning" | "info" | "success" | "custom";
 
-type ColouredTone = "danger" | "warning" | "info";
+type ColouredTone = "danger" | "warning" | "info" | "success" | "custom";
 
 const ICON_BUTTON_TONES: Record<ColouredTone, { quiet: string; toned: string }> = {
   danger: {
@@ -183,13 +319,33 @@ const ICON_BUTTON_TONES: Record<ColouredTone, { quiet: string; toned: string }>
       "text-[var(--text-placeholder)] hover:bg-[var(--info-bg)] hover:text-[var(--info)] focus:ring-[var(--info-border)]",
     toned: "text-[var(--info)] hover:bg-[var(--info-bg)] focus:ring-[var(--info-border)]",
   },
+  success: {
+    quiet:
+      "text-[var(--text-placeholder)] hover:bg-[var(--success-bg)] hover:text-[var(--success)] focus:ring-[var(--success-border)]",
+    toned: "text-[var(--success)] hover:bg-[var(--success-bg)] focus:ring-[var(--success-border)]",
+  },
+  // The hover fill and the ring are MIXED from the one colour, since a custom tone
+  // brings no `-bg` / `-border` pair of its own. The fallback is the body colour, so a
+  // `custom` tone with no colour set is the default look rather than invisible.
+  custom: {
+    quiet:
+      "text-[var(--text-placeholder)] hover:bg-[color-mix(in_srgb,var(--icon-button-tone,var(--text-primary))_12%,transparent)] hover:text-[var(--icon-button-tone,var(--text-primary))] focus:ring-[color-mix(in_srgb,var(--icon-button-tone,var(--text-primary))_40%,transparent)]",
+    toned:
+      "text-[var(--icon-button-tone,var(--text-primary))] hover:bg-[color-mix(in_srgb,var(--icon-button-tone,var(--text-primary))_12%,transparent)] focus:ring-[color-mix(in_srgb,var(--icon-button-tone,var(--text-primary))_40%,transparent)]",
+  },
 };
 
 const ICON_BUTTON_MUTED =
   "text-[var(--text-placeholder)] hover:bg-[var(--bg-surface-2)] hover:text-[var(--text-primary)]";
 
 /** Which tones sit quiet at rest when `quiet` is left out. */
-const QUIET_BY_DEFAULT: Record<ColouredTone, boolean> = { danger: true, warning: false, info: false };
+const QUIET_BY_DEFAULT: Record<ColouredTone, boolean> = {
+  danger: true,
+  warning: false,
+  info: false,
+  success: false,
+  custom: false,
+};
 
 function iconButtonToneClass(tone: IconButtonTone, quiet: boolean | undefined): string {
   if (tone === "default") return "";
@@ -246,11 +402,31 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
    *  xs = 28px with a 16px icon (an action in a list row), 2xs = 24px with a 14px
    *  icon (an action on a chip or a tab). */
   size?: IconButtonSize;
+  /**
+   * Fill the height of the flex row it stands in, keeping its width — the delete at
+   * the end of keksdose's split line (transaction-fields:162), level with the labelled
+   * fields beside it rather than floating at half their height. {@link Button}'s
+   * `stretch`; no effect outside a flex row. With a `label`, the tooltip's wrapper is
+   * what stretches.
+   */
+  stretch?: boolean;
+  /** `round`: a circle instead of the rounded square — a compact status chip in a top
+   *  bar (keksdose's sync indicator). `overlay` is always round. */
+  shape?: "square" | "round";
+  /**
+   * The colour of `tone="custom"`, as any CSS colour — a token (`var(--warning)`),
+   * ideally. Sets `--icon-button-tone` on the button, so passing a different one per
+   * state re-colours the glyph, its hover fill and its focus ring together. Passing it
+   * implies `tone="custom"`. Or leave it out and set the variable yourself from a class
+   * (`className="[--icon-button-tone:var(--success)]"`).
+   */
+  toneColor?: string;
   /** Glyph colour over the variant. `muted`: placeholder grey, full text colour on
    *  hover. `danger`: the same grey at rest, `--danger` on hover and focus — for a
    *  remove/delete that repeats down a list. `warning`: amber at rest — a flag that
    *  wants attention. `info`: sky at rest — a notice-worthy but harmless action
-   *  (keksdose's reconcile). Default: the variant's own colours. See `quiet` for
+   *  (keksdose's reconcile). `success`: green at rest — a good state worth seeing.
+   *  `custom`: the colour of `toneColor` (see there). Default: the variant's own colours. See `quiet` for
    *  turning a coloured tone's resting look the other way. */
   tone?: IconButtonTone;
   /**
@@ -305,19 +481,100 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
    *  The pair look exactly like the nested version, click exactly like it, and
    *  are two tab stops a screen reader can tell apart. */
   stopPropagation?: boolean;
+  /**
+   * The button's name, said once: it becomes the `aria-label` AND the text of a kit
+   * {@link Tooltip} round the button.
+   *
+   * Every app writes the pair by hand. lenkbank's nine icon actions all carry
+   * `aria-label={t(x)} title={t(x)}` (shared/lib/table-columns.tsx:103,
+   * projects-page.tsx:83, setpoint/segment-list.tsx:198/207, profile-bar.tsx:128/142,
+   * shortcut-dialog.tsx:815/857/1007) — and `title` is the browser's own tooltip,
+   * which shows late, never on focus and never on touch, and looks like no other
+   * label in the kit. kastlan's RowAction (shared/components/data-table/row-action.tsx)
+   * and keksdose's icon wrappers each exist to put a Tooltip round an IconButton.
+   *
+   * A caller's own `aria-label` still wins, for the rare name that should be longer
+   * than the bubble. The bubble is visual only: it would otherwise describe the button
+   * with its own name, and a screen reader would read the same word twice. Tooltip's
+   * default placement applies — in place, or portalled inside a scroll container —
+   * unless `tooltipPortal` says otherwise.
+   */
+  label?: string;
+  /** Show `label` as a tooltip. Default `true`; `false` keeps `label` as the
+   *  accessible name only — for a button whose glyph is universally read (a close ✕ in
+   *  a dialog header) or that already sits under a tooltip of its own. */
+  tooltip?: boolean;
+  /** Where the `label` tooltip opens. See {@link Tooltip}'s `side`. */
+  tooltipSide?: TooltipSide;
+  /** Passed to the `label` tooltip's `portal`. Left out, Tooltip decides (see there). */
+  tooltipPortal?: boolean;
+  /**
+   * Why the action is not available — {@link Button}'s `disabledReason`, on the icon
+   * button: keksdose's accounts page cannot hide an account with a balance or delete
+   * one with bookings (accounts-page:879/913 — "hide requires zero", "delete blocked"),
+   * nor its budgets page delete the only budget (budgets-page:330), and each wrapped a
+   * natively disabled IconButton in a Tooltip that swaps its label for the reason — a
+   * bubble a keyboard never opens, since `disabled` leaves the tab order, and a reason
+   * a screen reader never hears.
+   *
+   * The same contract as Button's: `aria-disabled` instead of `disabled`, so it stays
+   * focusable and hoverable; clicks (and the Enter/Space they stand for) are swallowed
+   * — `stopPropagation` still applies, so a locked action in a clickable row does not
+   * open the row either; the reason shows in the kit {@link Tooltip} and is attached
+   * through `aria-describedby` as a `hidden` copy. The NAME stays `aria-label` /
+   * `label` — "Delete", described by "The active budget cannot be deleted" — and the
+   * bubble shows the reason in place of the label, since the glyph already says what
+   * the button is and the reason is the news. Shown even with `tooltip={false}`: a
+   * reason nobody can see is not one. Wins over `disabled`, as on Button.
+   */
+  disabledReason?: ReactNode;
 }
 
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
-  { variant = "ghost", size = "md", tone = "default", quiet, pressed, stopPropagation, className, onClick, onKeyDown, ...rest },
+  {
+    variant = "ghost",
+    size = "md",
+    tone: toneProp,
+    quiet,
+    pressed,
+    stopPropagation,
+    stretch,
+    shape = "square",
+    toneColor,
+    label,
+    tooltip = true,
+    tooltipSide,
+    tooltipPortal,
+    disabledReason,
+    className,
+    style,
+    onClick,
+    onKeyDown,
+    ...rest
+  },
   ref,
 ) {
-  return (
+  const tone = toneProp ?? (toneColor !== undefined ? "custom" : "default");
+  const reasonId = useId();
+  const locked = hasContent(disabledReason);
+  const ownDescribedBy = rest["aria-describedby"];
+  const button = (
     <button
       ref={ref}
       {...rest}
+      disabled={locked ? undefined : rest.disabled}
+      aria-disabled={locked || rest["aria-disabled"]}
+      aria-describedby={locked ? (ownDescribedBy ? `${ownDescribedBy} ${reasonId}` : reasonId) : ownDescribedBy}
+      aria-label={rest["aria-label"] ?? label}
       aria-pressed={pressed ?? rest["aria-pressed"]}
+      style={toneColor !== undefined ? { ...style, ["--icon-button-tone" as string]: toneColor } : style}
       onClick={(e) => {
         if (stopPropagation) e.stopPropagation();
+        // `preventDefault` too: a locked submit must not submit its form.
+        if (locked) {
+          e.preventDefault();
+          return;
+        }
         onClick?.(e);
       }}
       onKeyDown={(e) => {
@@ -328,16 +585,46 @@ export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(functio
       }}
       className={cn(
         ICON_BUTTON_BASE,
-        ICON_BUTTON_SIZES[size],
+        stretch ? ICON_BUTTON_STRETCH_SIZES[size] : ICON_BUTTON_SIZES[size],
         // After the size, so the overlay's `rounded-full` beats the small sizes' `rounded`.
         variant === "overlay" ? ICON_BUTTON_OVERLAY : buttonVariantClasses[variant],
+        shape === "round" && "rounded-full",
         ICON_BUTTON_DISABLED_REST[variant],
         iconButtonToneClass(tone, quiet),
         pressed && ICON_BUTTON_PRESSED,
+        // The disabled look for the focusable kind of disabled, as on Button.
+        locked && "cursor-not-allowed opacity-50",
         className,
       )}
     />
   );
+  if (locked) {
+    return (
+      // Button's shape: the button and the hidden reason in a FRAGMENT, so Tooltip does
+      // not add its bubble to the description as well.
+      <Tooltip
+        label={disabledReason}
+        side={tooltipSide}
+        portal={tooltipPortal}
+        className={stretch ? "self-stretch" : undefined}
+      >
+        <>
+          {button}
+          <span id={reasonId} hidden>
+            {disabledReason}
+          </span>
+        </>
+      </Tooltip>
+    );
+  }
+  if (!tooltip || label === undefined || label === "") return button;
+  return (
+    // A fragment, so Tooltip leaves the button's description alone: the bubble says
+    // exactly what `aria-label` already does.
+    <Tooltip label={label} side={tooltipSide} portal={tooltipPortal} className={stretch ? "self-stretch" : undefined}>
+      <>{button}</>
+    </Tooltip>
+  );
 });
 IconButton.displayName = "IconButton";
 
@@ -1400,10 +1687,90 @@ export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<"div">, "
    *  wrap and centre as one row), kastlan's "Create a rule". Buttons or links the
    *  caller renders; the box only places them. */
   action?: ReactNode;
+  /**
+   * `box` (default): the dashed, padded card that stands in for a whole section.
+   * `inline`: one quiet line with no box — for the empty state INSIDE something that
+   * already has its own frame, where a dashed card would be a box in a box. keksdose
+   * writes that line by hand five times as a muted `<p className="py-6 text-center">`:
+   * the notification inbox (notification-inbox:140), a support thread
+   * (support-thread:144), the assistant (assistant-page:321), the admin support panel
+   * (support-panel:265) and the funding dialog (funding-dialog:89). The icon shrinks
+   * to the text's size and sits before the title, the hint follows on the same line,
+   * and the row wraps only when it must. Centred like the box; `className="justify-start"`
+   * for a list that reads from the start edge (funding-dialog).
+   */
+  variant?: "box" | "inline";
+  /**
+   * Colour the icon and the title: `danger` for an error standing where the content
+   * should be — kastlan's ErrorState (shared/components/feedback/error-state.tsx) and
+   * its error boundary's fallback (error-boundary.tsx:16), both a red triangle over a
+   * message — and `success` for an empty state that is GOOD news, kastlan's "No defects
+   * recorded for this room" (handover defects-step.tsx:142, a green check). Left out,
+   * both stay muted. The hint stays muted either way: it is the explanation, not the
+   * verdict.
+   */
+  tone?: "danger" | "success";
+  /**
+   * `inline` only (0.11.0). `sm`: 12px, start-aligned and tight (`py-1`) — the empty
+   * line INSIDE a detail panel, under a panel heading and among `text-xs` rows, where
+   * the default's 14px centred line with `py-4` read as a section of its own.
+   * keksdose's holdings panel (holdings-panel:563), asset-loan panel
+   * (asset-loan-panel:108) and loan-payment panel (loan-payment-panel:191) each wrote
+   * `className="justify-start py-1"` over it and still got body-size text. Default `md`,
+   * the look it had. Ignored by the box.
+   */
+  size?: "sm" | "md";
 }
 
-export function EmptyState({ title, hint, icon, action, headingAs, className, ...rest }: EmptyStateProps) {
+const EMPTY_STATE_TONE: Record<"danger" | "success", string> = {
+  danger: "text-[var(--danger)]",
+  success: "text-[var(--success)]",
+};
+
+export function EmptyState({
+  title,
+  hint,
+  icon,
+  action,
+  headingAs,
+  variant = "box",
+  tone,
+  size = "md",
+  className,
+  ...rest
+}: EmptyStateProps) {
   const Title = headingAs ?? "div";
+  const toneClass = tone ? EMPTY_STATE_TONE[tone] : undefined;
+  const hasHint = hint != null && hint !== false && hint !== "";
+  if (variant === "inline") {
+    const sm = size === "sm";
+    return (
+      <div
+        {...rest}
+        className={cn(
+          "flex flex-wrap items-center text-[var(--text-muted)]",
+          sm
+            ? "justify-start gap-x-1.5 gap-y-0.5 py-1 text-start text-xs"
+            : "justify-center gap-x-2 gap-y-1 py-4 text-center text-sm",
+          className,
+        )}
+      >
+        {icon != null && (
+          <span
+            aria-hidden
+            className={cn("flex text-[var(--text-placeholder)]", sm ? "[&_svg]:size-3.5" : "[&_svg]:size-4", toneClass)}
+          >
+            {icon}
+          </span>
+        )}
+        {/* No weight of its own: one muted line is what these sites were, and a
+            bold title would turn a quiet "nothing here" into a heading. */}
+        <Title className={cn(sm ? "text-xs" : "text-sm", toneClass)}>{title}</Title>
+        {hasHint && <span className="text-xs">{hint}</span>}
+        {action != null && <span className="flex flex-wrap items-center gap-2">{action}</span>}
+      </div>
+    );
+  }
   return (
     <div
       {...rest}
@@ -1413,13 +1780,13 @@ export function EmptyState({ title, hint, icon, action, headingAs, className, ..
       )}
     >
       {icon != null && (
-        <div aria-hidden className="mb-3 text-[var(--text-placeholder)] [&_svg]:size-8">
+        <div aria-hidden className={cn("mb-3 text-[var(--text-placeholder)] [&_svg]:size-8", toneClass)}>
           {icon}
         </div>
       )}
       {/* `text-sm`: a heading keeps the box's size, not whatever a stylesheet gives h2. */}
-      <Title className="text-sm font-medium text-[var(--text-secondary)]">{title}</Title>
-      {hint != null && hint !== false && hint !== "" && <div className="mt-1 text-xs">{hint}</div>}
+      <Title className={cn("text-sm font-medium text-[var(--text-secondary)]", toneClass)}>{title}</Title>
+      {hasHint && <div className="mt-1 text-xs">{hint}</div>}
       {action != null && (
         <div className="mt-4 flex flex-wrap items-center justify-center gap-2">{action}</div>
       )}

package/src/components/user-avatar.tsx

@@ -1,5 +1,7 @@
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
+import { StatusDot } from "./status-dot";
+import type { StatusDotSize, StatusDotTone } from "./status-dot";
 
 /** Initials from a display name (first + last) or, failing that, an email —
  *  e.g. "Marcel Eifert" → "ME", "marcel@x.com" → "MA". App-agnostic.
@@ -25,19 +27,71 @@ const AVATAR_SIZES = {
   lg: "size-12 text-base",
 } as const;
 
+const CHIP =
+  "inline-flex shrink-0 items-center justify-center rounded-full bg-[var(--bg-inverse)] font-semibold text-[var(--text-inverse)]";
+
+/** The dot grows with the avatar: 8px on `sm`, 10px on `md` (keksdose's), 12px on `lg`. */
+const BADGE_SIZES: Record<keyof typeof AVATAR_SIZES, StatusDotSize> = { sm: "sm", md: "md", lg: "lg" };
+
+/** A status dot in the avatar's top corner — an unread count, presence. */
+export interface UserAvatarBadge {
+  /** What the dot MEANS, for a screen reader ("3 unread"). Required: a coloured circle
+   *  says nothing to someone who cannot see it. */
+  label: ReactNode;
+  /** Default `danger`, the unread dot both apps draw by hand. */
+  tone?: StatusDotTone;
+}
+
 /** A `<span>`'s props, minus `children`: the content is the initials this computes
  *  from `name`/`email`, so there is nothing for a caller to put inside. */
 export interface UserAvatarProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {
   name?: string | null;
   email?: string | null;
   size?: keyof typeof AVATAR_SIZES;
+  /**
+   * A status dot in the top-end corner (the top-right in LTR, top-left in RTL), ringed
+   * in the surface colour so it reads as its own mark (keksdose account-menu ~385,
+   * top-bar :152). Its `label` is read as text where the dot sits — inside a button
+   * named by its content it joins that name. In `TopBarActionMenu`'s `trigger` the
+   * button is named by the menu's `ariaLabel` followed by this label: "Account menu
+   * 3 unread". The initials stay hidden either way, so the person's name is NOT part
+   * of it — put it in `ariaLabel` ("Marcel Eifert, account menu") if it should be.
+   */
+  badge?: UserAvatarBadge | null;
 }
 
 /**
  * A round initials avatar — the common user chip shared across apps (feedback
  * #333). Purely presentational; wrap it in a button for the account menu trigger.
  */
-export function UserAvatar({ name, email, size = "md", className, ...rest }: UserAvatarProps) {
+export function UserAvatar({ name, email, size = "md", badge, className, ...rest }: UserAvatarProps) {
+  if (badge) {
+    // A wrapper, because the chip itself is `aria-hidden` and the badge label must not
+    // be. `className` stays on the chip (a size override still sizes the circle); the
+    // other attributes go on the wrapper, which is what a caller addresses. `relative`
+    // also contains the sr-only text.
+    return (
+      <span {...rest} className="relative inline-flex shrink-0">
+        <span
+          aria-hidden
+          className={cn(
+            CHIP,
+            AVATAR_SIZES[size],
+            className,
+          )}
+        >
+          {avatarInitials(name, email)}
+        </span>
+        <StatusDot
+          ring
+          tone={badge.tone ?? "danger"}
+          size={BADGE_SIZES[size]}
+          className="absolute -end-0.5 -top-0.5"
+        />
+        <span className="sr-only">{badge.label}</span>
+      </span>
+    );
+  }
   return (
     <span
       // `aria-hidden` sits BEFORE the spread, unlike the structural attributes on the
@@ -50,7 +104,7 @@ export function UserAvatar({ name, email, size = "md", className, ...rest }: Use
       aria-hidden
       {...rest}
       className={cn(
-        "inline-flex shrink-0 items-center justify-center rounded-full bg-[var(--bg-inverse)] font-semibold text-[var(--text-inverse)]",
+        CHIP,
         AVATAR_SIZES[size],
         className,
       )}

package/src/hooks/use-close-transition.ts

@@ -6,6 +6,19 @@ import { useCallback, useEffect, useRef, useState } from "react";
  *  by a copy of it. */
 export const OVERLAY_EXIT_MS = 220;
 
+/**
+ * Whether the user has asked for no motion, read NOW. `true` where `matchMedia` is
+ * absent (jsdom, SSR): nothing is painting there, so "no animation" is the only
+ * correct answer. Shared by every exit timer in the package, so they agree.
+ */
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window === "undefined" ||
+    typeof window.matchMedia !== "function" ||
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
 /**
  * The state machine an exit animation needs, written once for every overlay in this
  * package (Keksdose live #320 rework: *"Recognized the opening transition. Choose
@@ -66,11 +79,7 @@ export function useCloseTransition(
     // Read at close time, not at mount: the setting can change under a long-lived
     // page, and `matchMedia` is absent in jsdom and in SSR — where "no animation" is
     // also the only correct answer, since nothing is painting.
-    const reduced =
-      typeof window === "undefined" ||
-      typeof window.matchMedia !== "function" ||
-      window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    if (reduced || ms <= 0) {
+    if (prefersReducedMotion() || ms <= 0) {
       latest.current();
       return;
     }

package/src/hooks/use-copy-to-clipboard.ts

@@ -42,7 +42,7 @@ function legacyCopy(text: string): boolean {
   area.style.opacity = "0";
   document.body.appendChild(area);
   area.select();
-  let ok = false;
+  let ok: boolean;
   try {
     ok = document.execCommand("copy");
   } catch {