@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/components/icon-button.tsx

@@ -1,959 +0,0 @@
-import { useContext, useId } from "react";
-import type {
-  AnchorHTMLAttributes,
-  ButtonHTMLAttributes,
-  CSSProperties,
-  KeyboardEvent,
-  MouseEvent,
-  ReactElement,
-  ReactNode,
-  Ref,
-} from "react";
-import { cn } from "../lib/cn";
-import { FOCUS_RING_WIDTH } from "./focus-ring";
-import { useLargeText } from "../hooks/use-large-text";
-import { Tooltip, type TooltipSide } from "./tooltip";
-import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLink } from "../i18n/kit-labels";
-import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
-import { pickLinkRenderer, replacingClick, routerLinkNavigation } from "./text-link";
-import { useCommitReason } from "./write-lock";
-import type { CommitScope } from "./write-lock";
-import { hasContent } from "../lib/presence";
-import { CompactControlsContext, LockedReason, type DisabledReasonDisplay } from "./field-parts";
-import { Spinner } from "./spinner";
-import {
-  HOVER_INK,
-  ICON_BUTTON_PRESSED,
-  RenderedButtonLink,
-  HIT_AREA_LARGE,
-  TOUCH_TARGET_LARGE,
-  buttonVariantClasses,
-} from "./button-look";
-import type { ButtonVariant } from "./button-look";
-
-// Canonical square icon-only button. <Button> carries TEXT geometry — px-3 py-2
-// gap-2 — so rendering a bare glyph through it gives a small icon in a wide,
-// text-shaped box. This fixes a square box instead and, crucially, forces the
-// child icon to a size set by the BOX (20px at md/sm) via `[&_svg]:size-*` so a
-// caller cannot under-size it. Use it wherever an action is a bare icon
-// (edit/delete/tools) so they all match the top-bar icon buttons and can never
-// drift apart again.
-//
-// Draws its colours from the same `buttonVariantClasses` map as <Button>, so the
-// two re-skin together with the palette.
-const ICON_BUTTON_BASE = cn(
-  "inline-flex items-center justify-center rounded-md transition-colors focus:outline-none disabled:opacity-50 disabled:cursor-not-allowed",
-  FOCUS_RING_WIDTH,
-);
-
-export type IconButtonSize = "2xl" | "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> = {
-  // 64px with a 28px glyph: a camera's shutter (keksdose invoices/camera-capture.tsx:248,
-  // `size-16` by hand) — the one control of a full-screen capture view, thumb-sized.
-  "2xl": "size-16 [&_svg]:size-7",
-  // 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",
-  md: "size-9 [&_svg]:size-5",
-  sm: "size-8 [&_svg]:size-5",
-  xs: "size-7 rounded [&_svg]:size-4",
-  "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> = {
-  "2xl": "w-16 min-h-16 self-stretch [&_svg]:size-7",
-  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",
-};
-
-// The label as visible text beside the glyph (0.32, §4: at Large "IconButton shows its
-// label"): the same height and glyph as the square, a width taken from the words. A
-// map of its own rather than `w-auto` over `size-*`, which tailwind-merge cannot undo
-// in one direction.
-const ICON_BUTTON_TEXT_SIZES: Record<IconButtonSize, string> = {
-  "2xl": "h-16 gap-2 px-4 text-base [&_svg]:size-7",
-  xl: "h-12 gap-2 px-3.5 text-sm [&_svg]:size-6",
-  lg: "h-11 gap-2 px-3 text-sm [&_svg]:size-5",
-  md: "h-9 gap-1.5 px-2.5 text-sm [&_svg]:size-5",
-  sm: "h-8 gap-1.5 px-2 text-sm [&_svg]:size-5",
-  xs: "h-7 gap-1 rounded px-1.5 text-xs [&_svg]:size-4",
-  "2xs": "h-6 gap-1 rounded px-1.5 text-xs [&_svg]:size-3.5",
-};
-const ICON_BUTTON_TEXT_STRETCH_SIZES: Record<IconButtonSize, string> = {
-  "2xl": "min-h-16 self-stretch gap-2 px-4 text-base [&_svg]:size-7",
-  xl: "min-h-12 self-stretch gap-2 px-3.5 text-sm [&_svg]:size-6",
-  lg: "min-h-11 self-stretch gap-2 px-3 text-sm [&_svg]:size-5",
-  md: "min-h-9 self-stretch gap-1.5 px-2.5 text-sm [&_svg]:size-5",
-  sm: "min-h-8 self-stretch gap-1.5 px-2 text-sm [&_svg]:size-5",
-  xs: "min-h-7 self-stretch gap-1 rounded px-1.5 text-xs [&_svg]:size-4",
-  "2xs": "min-h-6 self-stretch gap-1 rounded px-1.5 text-xs [&_svg]:size-3.5",
-};
-
-// The 48 px touch target at Large (§4), per size. `lg` and up are past it already
-// (2.75rem is 55 px at Large). `md` … `xs` grow their box to it. `2xs` is the action ON
-// a chip or a tab, whose box cannot grow without growing the chip: it keeps its box and
-// gets a 48 px hit area instead — an invisible `::after` centred on it, which takes the
-// taps a finger lands round the glyph (`HIT_AREA_LARGE`).
-const ICON_BUTTON_TOUCH_LARGE: Record<IconButtonSize, string> = {
-  "2xl": "",
-  xl: "",
-  lg: "",
-  md: TOUCH_TARGET_LARGE,
-  sm: TOUCH_TARGET_LARGE,
-  xs: TOUCH_TARGET_LARGE,
-  "2xs": HIT_AREA_LARGE,
-};
-
-// 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
-// family; TONED wears the tone's colour at rest. The defaults are the looks each tone
-// had before `quiet` existed: `danger` is quiet — an action in every row of a list
-// must not shout from every row, so the red arrives only on the one row you are about
-// to act on — while `warning` and `info` are toned, because they mark the ONE thing
-// 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.
-//
-// `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" | "success" | "custom";
-
-const ICON_BUTTON_TONES: Record<ColouredTone, { quiet: string; toned: string }> = {
-  danger: {
-    quiet: "text-placeholder hover:bg-danger-soft hover:text-danger focus-visible:ring-danger-strong",
-    toned: "text-danger hover:bg-danger-soft focus-visible:ring-danger-strong",
-  },
-  warning: {
-    quiet: "text-placeholder hover:bg-warning-soft hover:text-warning focus-visible:ring-warning-strong",
-    // The ring is warning's loud line (0.33, k27): `--warning-border`, amber-300, was a
-    // focus ring at 1.1:1 on the light surfaces.
-    toned: "text-warning hover:bg-warning-soft focus-visible:ring-warning-strong",
-  },
-  // The ring is the tone's own text colour (0.52, refactor audit 2026-10-30, DSP-6):
-  // `--info-border` and `--success-border` rang at 1.2–1.4:1 on the light grounds and
-  // about 2:1 in dark, and More contrast re-solves neither — while `--info` / `--success`
-  // clear 4.5:1 and are re-solved there. The sync chip wears these two on every page.
-  info: {
-    quiet: "text-placeholder hover:bg-info-soft hover:text-info focus-visible:ring-[var(--info)]",
-    toned: "text-info hover:bg-info-soft focus-visible:ring-[var(--info)]",
-  },
-  success: {
-    quiet: "text-placeholder hover:bg-success-soft hover:text-success focus-visible:ring-[var(--success)]",
-    toned: "text-success hover:bg-success-soft focus-visible:ring-[var(--success)]",
-  },
-  // The hover fill is MIXED from the one colour, since a custom tone brings no `-bg` of
-  // its own; the ring is the colour at full strength (0.52, DSP-6: at 40 % it was a ring
-  // nobody could see). The fallback is the body colour, so a `custom` tone with no colour
-  // set is the default look rather than invisible.
-  custom: {
-    quiet:
-      "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-visible:ring-[var(--icon-button-tone,var(--text-primary))]",
-    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-visible:ring-[var(--icon-button-tone,var(--text-primary))]",
-  },
-};
-
-// The translucent ink on hover, as Button's secondary/ghost (B′, see HOVER_INK).
-const ICON_BUTTON_MUTED = `text-placeholder ${HOVER_INK} hover: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,
-  success: false,
-  custom: false,
-};
-
-function iconButtonToneClass(tone: IconButtonTone, quiet: boolean | undefined): string {
-  if (tone === "default") return "";
-  if (tone === "muted") return cn(ICON_BUTTON_MUTED, ICON_BUTTON_QUIET_DISABLED_REST);
-  const isQuiet = quiet ?? QUIET_BY_DEFAULT[tone];
-  const look = ICON_BUTTON_TONES[tone];
-  return isQuiet ? cn(look.quiet, ICON_BUTTON_QUIET_DISABLED_REST) : look.toned;
-}
-
-// A disabled button must not answer the pointer. The hover classes above are plain
-// `hover:` (so a caller's `className="hover:…"` still replaces them through
-// tailwind-merge), which means they fire on a disabled button too — the old grey
-// icon lit up on hover while refusing the click. Rather than rewrite every hover as
-// `enabled:hover:` (which never matches the `<a>` that `buttonClasses` also styles,
-// and would out-rank a caller's plain `hover:` override), each variant pins its
-// RESTING look under `disabled:hover:`, which out-ranks any `hover:` by specificity
-// and only ever matches a disabled button.
-const ICON_BUTTON_DISABLED_REST: Record<ButtonVariant | "overlay" | "shutter", string> = {
-  default: "disabled:hover:bg-surface-2",
-  secondary: "disabled:hover:bg-transparent",
-  ghost: "disabled:hover:bg-transparent",
-  danger: "disabled:hover:bg-danger",
-  accent: "disabled:hover:bg-brand",
-  link: "disabled:hover:bg-transparent disabled:hover:no-underline",
-  overlay: "disabled:hover:bg-[color-mix(in_srgb,var(--bg-inverse)_60%,transparent)]",
-  shutter: "disabled:hover:bg-media-scrim",
-};
-
-// The quiet looks change the glyph on hover, so they pin their resting glyph the
-// same way. A toned look keeps its glyph on hover and needs no pin.
-const ICON_BUTTON_QUIET_DISABLED_REST = "disabled:hover:text-placeholder";
-
-// `variant="overlay"`: a round, translucent disc for a control that sits ON a photo
-// (keksdose's receipt-scan preview: close, rotate, retake over the camera image).
-// The inverse pair, not the surface one: what has to hold is the contrast between the
-// disc and its glyph, whatever the picture underneath is, and `--bg-inverse` /
-// `--text-inverse` are the one token pair defined as each other's opposite in both
-// themes. The disc is the inverse at 60% (`color-mix`, so it stays a token a palette
-// can re-point); the blur keeps a busy background from breaking the glyph's edge.
-const ICON_BUTTON_OVERLAY =
-  "rounded-full bg-[color-mix(in_srgb,var(--bg-inverse)_60%,transparent)] text-inverse backdrop-blur-sm hover:bg-[color-mix(in_srgb,var(--bg-inverse)_75%,transparent)] focus-visible:ring-[var(--text-inverse)]";
-
-// `variant="shutter"`: the camera's release — keksdose's camera-capture.tsx:248 draws
-// it by hand as a 64px circle with a thick white ring round a translucent fill. It sits
-// on a live camera picture, which is dark whatever the theme, so it uses the MEDIA
-// tokens (tokens.css), white ink on a dark scrim in both themes — the inverse pair
-// `overlay` uses would give a dark ring on a dark viewfinder in dark mode. The focus ring stands off by 2px, or it would
-// merge into the ring that is part of the look.
-const ICON_BUTTON_SHUTTER =
-  "rounded-full border-4 border-media-ink bg-media-scrim text-media-ink backdrop-blur-sm hover:bg-media-scrim-hover focus-visible:ring-media-ink focus-visible:ring-offset-2 focus-visible:ring-offset-media-scrim-hover";
-
-export type IconButtonVariant = ButtonVariant | "overlay" | "shutter";
-
-/**
- * The glyph's size in px, over the one the box size implies — see
- * {@link IconButtonProps.glyphSize}.
- */
-export type IconButtonGlyphSize = 12 | 14 | 16 | 20 | 24 | 28;
-
-const ICON_BUTTON_GLYPH_SIZES: Record<IconButtonGlyphSize, string> = {
-  12: "[&_svg]:size-3",
-  14: "[&_svg]:size-3.5",
-  16: "[&_svg]:size-4",
-  20: "[&_svg]:size-5",
-  24: "[&_svg]:size-6",
-  28: "[&_svg]:size-7",
-};
-
-// `pending`'s spinner, the size of the glyph it replaces (the `[&_svg]` rules above
-// size only an svg, and the spinner is a bordered span).
-const ICON_BUTTON_SPINNER: Record<IconButtonSize, string> = {
-  "2xl": "size-7",
-  xl: "size-6",
-  lg: "size-5",
-  md: "size-5",
-  sm: "size-5",
-  xs: "size-4",
-  "2xs": "size-3.5",
-};
-const ICON_BUTTON_SPINNER_GLYPH: Record<IconButtonGlyphSize, string> = {
-  12: "size-3",
-  14: "size-3.5",
-  16: "size-4",
-  20: "size-5",
-  24: "size-6",
-  28: "size-7",
-};
-
-export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  /** Any {@link ButtonVariant}; `overlay` — a round translucent disc for use over
-   *  an image (see `ICON_BUTTON_OVERLAY`); or `shutter` — a camera's release, a ringed
-   *  disc over the viewfinder (see `ICON_BUTTON_SHUTTER`; pair it with `size="2xl"`). */
-  variant?: IconButtonVariant;
-  /** Box size: 2xl = 64px with a 28px icon (a camera shutter), xl = 48px with a 24px
-   *  icon, lg = 44px (a phone's touch target), md = 36px (matches the top bar),
-   *  sm = 32px — all three with a 20px icon;
-   *  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). `glyphSize` overrides the icon. */
-  size?: IconButtonSize;
-  /**
-   * The icon's size in px, when the box's own is not the one wanted. keksdose's sync
-   * chip (app/sync-status-indicator.tsx:142) is a 24px round chip round a 20px cloud —
-   * `size="2xs" glyphSize={20} shape="round"` — where `2xs` alone draws 14px. A number
-   * over a new size step because the box and the glyph are two independent choices; a
-   * step per combination (`"sm-lg"`) would have to be named for every one.
-   */
-  glyphSize?: IconButtonGlyphSize;
-  /**
-   * A small mark on the button's corner — the sync chip's 12px check over its cloud
-   * ("all good", feedback #67). Rendered OUTSIDE the `<button>`, in a wrapper beside
-   * it, so the box's `[&_svg]:size-*` rule that sizes the glyph does not blow the badge
-   * up to the glyph's size; a bare `<Check />` comes out 12px, on a
-   * `--bg-surface` disc that keeps it legible over the glyph. Decorative
-   * (`aria-hidden`): the name (`label` / `aria-label`) must already carry the state.
-   * With a badge, `className` still lands on the button; the wrapper is the flex item.
-   */
-  badge?: ReactNode;
-  /**
-   * `keep`: a disabled button keeps its full colour (no 50% drop) and an ordinary
-   * cursor. For a STATUS that is also an action — the sync chip shows "in sync" in
-   * green and refreshes on click, and is disabled while offline or syncing, when the
-   * state it shows matters most; dimmed it read as broken (keksdose wrote
-   * `disabled:cursor-default` by hand and left out the dimming). Default `dim`.
-   */
-  disabledStyle?: "dim" | "keep";
-  /**
-   * 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)]"`).
-   *
-   * Or a `{ light, dark }` pair, one colour per theme — keksdose: a raw colour that reads
-   * on the light surface (`#be123c`) is too dark on the dark one, and an inline style
-   * cannot say "in dark mode". See {@link IconButtonToneColor}.
-   */
-  toneColor?: IconButtonToneColor;
-  /** 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). `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;
-  /**
-   * Whether a coloured tone (`danger`, `warning`, `info`) waits for the pointer:
-   * `true` is placeholder grey at rest and the tone's colour on hover and focus;
-   * `false` wears the tone's colour at rest. Left out, each tone keeps its own
-   * default — `danger` quiet, `warning` and `info` not. Ignored for `muted` (quiet by
-   * definition) and `default` (no tone).
-   *
-   * `quiet={false}` on `danger` is for a destructive action that stands ALONE, where
-   * hover-to-reveal hides it: keksdose's phone bulk bar (mobile-bulk-bar.tsx) has one
-   * "delete all" and a touch screen that never hovers, so it painted rose by hand.
-   * `quiet` on `warning`/`info` is the same switch the other way, for a flag repeated
-   * down a list. A boolean over the tone rather than a new tone (`danger-solid`) or an
-   * `emphasis` scale: there are exactly two resting looks, every coloured tone has
-   * both, and which one fits is a question about the SITE (alone or repeated, touch or
-   * pointer), not about the tone — so it is one switch the family shares.
-   */
-  quiet?: boolean;
-  /**
-   * Make it a toggle button. `true` sets `aria-pressed="true"` and draws the "on" look
-   * (brand glyph on the quiet brand fill); `false` sets `aria-pressed="false"` with the
-   * normal look, so a screen reader still hears a toggle that is off. Left out, it is
-   * an ordinary button with no `aria-pressed` — or whatever `aria-pressed` the caller
-   * passes. For keksdose's budget share toggle (budgets-page:291), which paints its own
-   * brand colour over a ghost button today. Keep the `aria-label` the same in both
-   * states ("Share budget"): the pressed state already says whether it is on.
-   */
-  pressed?: boolean;
-  /** Keep the click (and the Enter/Space that produces it) from reaching an
-   *  ancestor's handler — for an action inside a clickable table row or card.
-   *
-   *  **Not a licence to put this inside another `<button>`.** HTML forbids any
-   *  interactive content, and any element with a `tabindex`, inside a button — so
-   *  the `<span role="button" tabIndex={0}>` workaround is invalid too — and ARIA
-   *  makes a button's children presentational, so a screen reader flattens the
-   *  inner one into the outer one's name and it cannot be reached at all. Make the
-   *  row's main action a button that fills the row and put this one BESIDE it, on
-   *  top:
-   *
-   *  ```tsx
-   *  <div className="relative">
-   *    <button className="w-full pe-16 …" onClick={open}>…row…</button>
-   *    <div className="absolute inset-y-0 end-2 flex items-center gap-0.5">
-   *      <IconButton size="xs" tone="danger" aria-label="Delete" onClick={remove}>
-   *        <Trash2 />
-   *      </IconButton>
-   *    </div>
-   *  </div>
-   *  ```
-   *
-   *  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 visible text beside the icon at Large and Extra large (0.32,
-   * docs/text-size-harmonization.md §4, §10.8). A reader who asked for bigger type is
-   * the one an unlabelled glyph fails, and on touch the tooltip never opens. Then there
-   * is no tooltip: the words are on the button.
-   *
-   * Default `true` — except for `variant="overlay"` and `"shutter"`, which sit ON a
-   * picture, and inside {@link CompactControls} (AppShell's top bar, `RowActions`'
-   * inline icons). `false`: the icon alone at every size, for an icon on content — a
-   * receipt overlay, a map's zoom, a viewfinder, a photo thumbnail. That must be rare;
-   * a dense row's actions belong in `RowActions`, which collapses them into a "⋯" menu
-   * at Large instead (§10.8). Normal never shows it. `tooltip={false}` (a universally
-   * read glyph, a dialog's ✕) keeps the icon alone too.
-   */
-  labelVisible?: boolean;
-  /** 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. It also keeps the
-   *  label from showing as text at Large (see `labelVisible`). */
-  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;
-  /**
-   * Mount the `label` bubble only while it is up — {@link Tooltip}'s `lazy`. Default
-   * `true` since 0.16.0; `false` is the always-mounted in-place bubble of before.
-   *
-   * Why the label bubble can be lazy when Tooltip's default is not: this bubble
-   * describes nothing. It is wrapped round the button in a fragment precisely so that
-   * it is NOT the button's `aria-describedby` (it would repeat the button's own name),
-   * so there is no description for a lazy mount to take away — the name is the
-   * `aria-label` either way, read in browse mode and on focus alike. What the
-   * always-mounted bubble did do was sit in the DOM as a `role="tooltip"` node full of
-   * text: every IconButton in a row added one to `getAllByRole("tooltip")` and its label
-   * to the row's `textContent`, and two keksdose tests tripped over that (0.15.5 P6).
-   * The cost is the one {@link Tooltip}'s "Lazy in place" note names — a test that
-   * looked the bubble up without hovering now has to hover (or focus) first; pass
-   * `false` while it is migrated. A `disabledReason` bubble is unaffected: that one
-   * stays mounted as it was.
-   */
-  tooltipLazy?: boolean;
-  /**
-   * Busy — the action is in flight: the glyph is swapped for a spinner of the same
-   * size, the button is `aria-busy`, and clicks (and the Enter/Space and form
-   * submission they stand for) are swallowed, so a second press cannot start the
-   * action twice. {@link Button}'s `pending`, with the same contract: `aria-disabled`
-   * rather than `disabled`, so the button that was pressed keeps its focus. The name
-   * (`label` / `aria-label`) stays — `aria-busy` is what says it is working. A SWAP
-   * rather than Button's overlay: the box is square and fixed, so there is no width
-   * for the glyph to hold, and a spinner drawn over a glyph would be two marks in one
-   * 20px square.
-   */
-  pending?: 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.
-   *
-   * 0.32: at Large and on a touch screen the reason is a line under the button rather
-   * than a bubble — see `disabledReasonDisplay`.
-   */
-  disabledReason?: ReactNode;
-  /** Where `disabledReason` shows — {@link Button}'s `disabledReasonDisplay`. */
-  disabledReasonDisplay?: DisabledReasonDisplay;
-  /** This action COMMITS — {@link Button}'s `commit`: under a locked
-   *  {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
-   *  reason. No effect without a lock. A {@link CommitScope} since 0.33. */
-  commit?: CommitScope;
-  /** The `<button>` element — a prop in React 19, as on {@link Button}. */
-  ref?: Ref<HTMLButtonElement>;
-  /** Only on the link form — see {@link IconButtonLinkProps}. */
-  href?: never;
-  renderLink?: never;
-  external?: never;
-  replace?: never;
-  reloadDocument?: never;
-}
-
-/**
- * `<IconButton href>`: an icon-only LINK — keksdose F2 and kastlan 45, whose icon
- * actions that navigate (a row's "open", a card's "edit" that goes to the edit page, a
- * top bar's settings cog) were `<IconButton onClick={() => navigate(…)}>`: a button that
- * changes the page, with no middle click, no "open in new tab" and no URL on hover.
- *
- * The same rule as {@link Button}'s `href` (see {@link ButtonLinkProps}): an in-app
- * `href` goes through `renderLink`, else the provider's `linkComponent`; an external one
- * or an in-page `#anchor` stays a plain `<a>`; `external` opens a new tab and says so to
- * a screen reader; `replace` and `reloadDocument` as on Button. The look, the `label` →
- * `aria-label` + Tooltip, the badge, `toneColor` and `stopPropagation` are the button's.
- *
- * `disabled` renders an inert `<a>` with no `href` — `role="link"`, `aria-disabled`, out
- * of the tab order, dimmed — like Button's disabled link. `pressed`, `disabledReason` and
- * `disabledStyle` are a button's and are typed out: a link is not a toggle, and a link
- * that explains why it cannot be followed is a job for a disabled BUTTON.
- */
-export interface IconButtonLinkProps
-  extends
-    Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "type" | "href">,
-    Pick<
-      IconButtonProps,
-      | "variant"
-      | "size"
-      | "glyphSize"
-      | "badge"
-      | "stretch"
-      | "shape"
-      | "toneColor"
-      | "tone"
-      | "quiet"
-      | "stopPropagation"
-      | "label"
-      | "labelVisible"
-      | "tooltip"
-      | "tooltipSide"
-      | "tooltipPortal"
-      | "tooltipLazy"
-    > {
-  href: string;
-  /** See {@link ButtonLinkProps.renderLink}. */
-  renderLink?: KitLinkComponent;
-  /** See {@link ButtonLinkProps.external}. */
-  external?: boolean;
-  /** See {@link ButtonLinkProps.replace}. */
-  replace?: boolean;
-  /** See {@link ButtonLinkProps.reloadDocument}. */
-  reloadDocument?: boolean;
-  /** See {@link ButtonLinkProps.disabled}. */
-  disabled?: boolean;
-  ref?: Ref<HTMLAnchorElement>;
-  type?: never;
-  form?: never;
-  pressed?: never;
-  disabledReason?: never;
-  disabledReasonDisplay?: never;
-  commit?: never;
-  disabledStyle?: never;
-  pending?: never;
-}
-
-/**
- * Whether an IconButton draws its `label` as text (see `labelVisible`): at Large and
- * above, with a label to draw, not switched off by the caller, the variant (`overlay`,
- * `shutter`), `tooltip={false}` or a {@link CompactControls} region.
- */
-function useIconButtonText(
-  label: string | undefined,
-  labelVisible: boolean | undefined,
-  variant: IconButtonVariant,
-  tooltip: boolean,
-): boolean {
-  const large = useLargeText();
-  const compact = useContext(CompactControlsContext);
-  if (!large || label === undefined || label === "" || !tooltip) return false;
-  const visible = labelVisible ?? (!compact && variant !== "overlay" && variant !== "shutter");
-  return visible;
-}
-
-/** The visible label (see `labelVisible`). */
-function IconButtonText({ label }: { label: string }) {
-  return <span data-slot="icon-button-label">{label}</span>;
-}
-
-/**
- * `toneColor`: one CSS colour, or one per theme.
- *
- * The pair is two custom properties on the element — `--icon-button-tone-light` and
- * `--icon-button-tone-dark` — and a class that points `--icon-button-tone` at one or the
- * other by the kit's `dark` variant (`.dark` on an ancestor, tokens.css), so the colour
- * follows a theme switch in CSS alone, with no re-render and no JS reading the theme.
- * Both values are any CSS colour; a token that already flips (`var(--warning)`) needs no
- * pair.
- */
-export type IconButtonToneColor = string | { light: string; dark: string };
-
-const ICON_BUTTON_TONE_PAIR =
-  "[--icon-button-tone:var(--icon-button-tone-light)] dark:[--icon-button-tone:var(--icon-button-tone-dark)]";
-
-/** The inline custom properties `toneColor` sets over the caller's `style`. */
-function toneColorStyle(toneColor: IconButtonToneColor | undefined, style: CSSProperties | undefined) {
-  if (toneColor === undefined) return style;
-  const vars: Record<string, string> =
-    typeof toneColor === "string"
-      ? { "--icon-button-tone": toneColor }
-      : { "--icon-button-tone-light": toneColor.light, "--icon-button-tone-dark": toneColor.dark };
-  return { ...style, ...vars } as CSSProperties;
-}
-
-/** Everything but the element: the look both forms of IconButton share. */
-function iconButtonLook({
-  variant,
-  size,
-  stretch,
-  glyphSize,
-  shape,
-  tone,
-  quiet,
-  toneColor,
-  withText = false,
-}: {
-  variant: IconButtonVariant;
-  size: IconButtonSize;
-  stretch: boolean | undefined;
-  glyphSize: IconButtonGlyphSize | undefined;
-  shape: "square" | "round";
-  tone: IconButtonTone;
-  quiet: boolean | undefined;
-  toneColor: IconButtonToneColor | undefined;
-  /** The label is drawn beside the glyph (see `labelVisible`). */
-  withText?: boolean;
-}) {
-  return cn(
-    ICON_BUTTON_BASE,
-    withText
-      ? cn(
-          "font-medium whitespace-nowrap",
-          stretch ? ICON_BUTTON_TEXT_STRETCH_SIZES[size] : ICON_BUTTON_TEXT_SIZES[size],
-        )
-      : stretch
-        ? ICON_BUTTON_STRETCH_SIZES[size]
-        : ICON_BUTTON_SIZES[size],
-    // With text the pill is a 48 px target at any size; the square follows its size.
-    withText ? TOUCH_TARGET_LARGE : ICON_BUTTON_TOUCH_LARGE[size],
-    glyphSize !== undefined && ICON_BUTTON_GLYPH_SIZES[glyphSize],
-    // After the size, so the overlay's `rounded-full` beats the small sizes' `rounded`.
-    variant === "overlay"
-      ? ICON_BUTTON_OVERLAY
-      : variant === "shutter"
-        ? ICON_BUTTON_SHUTTER
-        : buttonVariantClasses[variant],
-    shape === "round" && "rounded-full",
-    ICON_BUTTON_DISABLED_REST[variant],
-    iconButtonToneClass(tone, quiet),
-    toneColor !== undefined && typeof toneColor !== "string" && ICON_BUTTON_TONE_PAIR,
-  );
-}
-
-/** The badge beside the control, not in it — see `badge`. The wrapper is only a
- *  positioning box: the control inside it keeps its own focus ring and hit area. */
-function withIconButtonBadge(control: ReactElement, badge: ReactNode, stretch: boolean | undefined) {
-  if (!hasContent(badge)) return control;
-  return (
-    <span className={cn("relative inline-flex shrink-0", stretch && "self-stretch")}>
-      {control}
-      <span
-        aria-hidden
-        data-slot="icon-button-badge"
-        className="pointer-events-none absolute -end-0.5 -bottom-0.5 inline-flex rounded-full bg-surface [&_svg]:size-3"
-      >
-        {badge}
-      </span>
-    </span>
-  );
-}
-
-// Declared link-first, as Button is, so `<IconButton href>` picks the link props and
-// `ComponentProps<typeof IconButton>` (the LAST signature) is still the button's.
-/**
- * An icon-only button whose `label` is its name and its tooltip.
- *
- * Destructive actions (0.49 KIT-12): a delete, revoke or erase is NOT an icon repeated in
- * every row of a list — one stray tap away, and a bin per row draws the eye to the one
- * thing nobody should do by accident. Put it in the row's menu, `RowActions` (where a
- * `tone: "danger"` action goes by default and opens a `ConfirmDialog` first), or in the
- * selection bar ("2 selected" → Delete), and confirm it through `useConfirm`. A single
- * standalone delete — a card's own, a bulk bar's — may be an IconButton
- * `tone="danger"`; it still asks first.
- */
-export function IconButton(props: IconButtonLinkProps): ReactElement;
-export function IconButton(props: IconButtonProps): ReactElement;
-export function IconButton(props: IconButtonProps | IconButtonLinkProps): ReactElement {
-  if (props.href !== undefined) return <IconButtonLink {...(props as IconButtonLinkProps)} />;
-  return <IconButtonElement {...(props as IconButtonProps)} />;
-}
-
-function IconButtonLink({
-  href,
-  renderLink,
-  external,
-  replace,
-  reloadDocument,
-  disabled,
-  variant = "ghost",
-  size = "md",
-  tone: toneProp,
-  quiet,
-  stopPropagation,
-  stretch,
-  shape = "square",
-  toneColor,
-  label,
-  labelVisible,
-  tooltip = true,
-  tooltipSide,
-  tooltipPortal,
-  tooltipLazy = true,
-  glyphSize,
-  badge,
-  className,
-  style,
-  target,
-  rel,
-  onClick,
-  onKeyDown,
-  children: glyph,
-  ref,
-  ...rest
-}: IconButtonLinkProps) {
-  const withText = useIconButtonText(label, labelVisible, variant, tooltip);
-  const children = withText ? (
-    <>
-      {glyph}
-      <IconButtonText label={label!} />
-    </>
-  ) : (
-    glyph
-  );
-  const kitLink = useKitLink();
-  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  const tone = toneProp ?? (toneColor !== undefined ? "custom" : "default");
-  // Button's rule, word for word: `reloadDocument` bypasses the router, an external
-  // href or an in-page `#anchor` never reaches it.
-  const Link = reloadDocument ? undefined : pickLinkRenderer<KitLinkProps>(renderLink, kitLink, href);
-  const newTab = !disabled && (external || target === "_blank");
-  const name = rest["aria-label"] ?? label;
-  // "(opens in a new tab)" joins the NAME here, not the body: an icon link has no text
-  // for an sr-only span to follow, and `aria-label` would override one anyway.
-  const ariaLabel = name !== undefined && newTab ? `${name} (${common.opensInNewTab})` : name;
-  const handleClick = (e: MouseEvent<HTMLAnchorElement>) => {
-    if (stopPropagation) e.stopPropagation();
-    onClick?.(e);
-  };
-  const handleKeyDown = (e: KeyboardEvent<HTMLAnchorElement>) => {
-    // A link activates on Enter only; that key still bubbles to a clickable row.
-    if (stopPropagation && e.key === "Enter") e.stopPropagation();
-    onKeyDown?.(e);
-  };
-  const cls = cn(
-    iconButtonLook({ variant, size, stretch, glyphSize, shape, tone, quiet, toneColor, withText }),
-    // BASE's `disabled:` classes never match an `<a>` — Button's disabled link look.
-    disabled && "pointer-events-none cursor-not-allowed opacity-50",
-    className,
-  );
-  const look = { style: toneColorStyle(toneColor, style), className: cls };
-  let control: ReactElement;
-  if (disabled) {
-    control = (
-      <a {...rest} {...look} ref={ref} role="link" aria-disabled="true" aria-label={ariaLabel}>
-        {children}
-      </a>
-    );
-  } else if (external || !Link) {
-    control = (
-      <a
-        {...rest}
-        {...look}
-        ref={ref}
-        href={href}
-        aria-label={ariaLabel}
-        target={external ? "_blank" : target}
-        rel={external ? (rel ?? "noopener noreferrer") : rel}
-        onClick={external ? handleClick : replacingClick(handleClick, href, replace, target)}
-        onKeyDown={handleKeyDown}
-      >
-        {children}
-      </a>
-    );
-  } else {
-    control = (
-      <RenderedButtonLink
-        render={Link}
-        {...rest}
-        {...look}
-        {...routerLinkNavigation(replace)}
-        ref={ref}
-        href={href}
-        aria-label={ariaLabel}
-        target={target}
-        rel={rel}
-        onClick={handleClick}
-        onKeyDown={handleKeyDown}
-      >
-        {children}
-      </RenderedButtonLink>
-    );
-  }
-  control = withIconButtonBadge(control, badge, stretch);
-  // The words are on the link at Large: a bubble would only repeat them.
-  if (!tooltip || withText || label === undefined || label === "") return control;
-  return (
-    // A fragment, as on the button: the bubble says what `aria-label` already does.
-    <Tooltip
-      label={label}
-      side={tooltipSide}
-      portal={tooltipPortal}
-      lazy={tooltipLazy}
-      className={stretch ? "self-stretch" : undefined}
-    >
-      <>{control}</>
-    </Tooltip>
-  );
-}
-
-function IconButtonElement({
-  variant = "ghost",
-  size = "md",
-  tone: toneProp,
-  quiet,
-  pressed,
-  stopPropagation,
-  stretch,
-  shape = "square",
-  toneColor,
-  label,
-  labelVisible,
-  tooltip = true,
-  tooltipSide,
-  tooltipPortal,
-  tooltipLazy = true,
-  disabledReason: ownDisabledReason,
-  disabledReasonDisplay,
-  commit,
-  pending,
-  glyphSize,
-  badge,
-  disabledStyle = "dim",
-  className,
-  style,
-  onClick,
-  onKeyDown,
-  children,
-  href: _href,
-  renderLink: _renderLink,
-  external: _external,
-  replace: _replace,
-  reloadDocument: _reloadDocument,
-  ref,
-  ...rest
-}: IconButtonProps) {
-  const tone = toneProp ?? (toneColor !== undefined ? "custom" : "default");
-  const keep = disabledStyle === "keep";
-  const withText = useIconButtonText(label, labelVisible, variant, tooltip);
-  const reasonId = useId();
-  const disabledReason = useCommitReason(commit, ownDisabledReason);
-  const locked = hasContent(disabledReason);
-  // Pending is inert like a locked button — focusable, every activation swallowed —
-  // without the locked look: the spinner is the state.
-  const inert = locked || Boolean(pending);
-  const ownDescribedBy = rest["aria-describedby"];
-  const button = (
-    <button
-      ref={ref}
-      {...rest}
-      disabled={inert ? undefined : rest.disabled}
-      aria-disabled={inert || rest["aria-disabled"]}
-      aria-busy={pending || rest["aria-busy"]}
-      aria-describedby={locked ? (ownDescribedBy ? `${ownDescribedBy} ${reasonId}` : reasonId) : ownDescribedBy}
-      aria-label={rest["aria-label"] ?? label}
-      aria-pressed={pressed ?? rest["aria-pressed"]}
-      style={toneColorStyle(toneColor, style)}
-      onClick={(e) => {
-        if (stopPropagation) e.stopPropagation();
-        // `preventDefault` too: a locked (or pending) submit must not submit its form.
-        if (inert) {
-          e.preventDefault();
-          return;
-        }
-        onClick?.(e);
-      }}
-      onKeyDown={(e) => {
-        // A button turns Enter/Space into a click of its own, but the KEY still
-        // bubbles — and a clickable row listening for Enter would act on it too.
-        if (stopPropagation && (e.key === "Enter" || e.key === " ")) e.stopPropagation();
-        onKeyDown?.(e);
-      }}
-      className={cn(
-        iconButtonLook({ variant, size, stretch, glyphSize, shape, tone, quiet, toneColor, withText }),
-        pressed && ICON_BUTTON_PRESSED,
-        // The disabled look for the focusable kind of disabled, as on Button.
-        locked && (keep ? "cursor-default" : "cursor-not-allowed opacity-50"),
-        keep && "disabled:cursor-default disabled:opacity-100",
-        pending && "cursor-progress",
-        className,
-      )}
-    >
-      {pending ? (
-        // Decorative, as on Button: `aria-busy` says it. Sized to the glyph it stands
-        // in for, in the glyph's colour, so the swap does not change the button's look.
-        <Spinner
-          label={null}
-          className={cn(
-            "border-current/30 border-t-current",
-            glyphSize !== undefined ? ICON_BUTTON_SPINNER_GLYPH[glyphSize] : ICON_BUTTON_SPINNER[size],
-          )}
-        />
-      ) : (
-        children
-      )}
-      {withText && <IconButtonText label={label!} />}
-    </button>
-  );
-  const control = withIconButtonBadge(button, badge, stretch);
-  if (locked) {
-    return (
-      // Button's shape: the reason as a line under it, or the bubble with a hidden copy
-      // for the description (see LockedReason).
-      <LockedReason
-        lock={{ reason: disabledReason, reasonId }}
-        display={disabledReasonDisplay}
-        side={tooltipSide}
-        portal={tooltipPortal}
-        className={stretch ? "self-stretch" : undefined}
-      >
-        {control}
-      </LockedReason>
-    );
-  }
-  // The words are on the button at Large: a bubble would only repeat them.
-  if (!tooltip || withText || label === undefined || label === "") return control;
-  return (
-    // A fragment, so Tooltip leaves the button's description alone: the bubble says
-    // exactly what `aria-label` already does. Lazy by default — see `tooltipLazy`.
-    <Tooltip
-      label={label}
-      side={tooltipSide}
-      portal={tooltipPortal}
-      lazy={tooltipLazy}
-      className={stretch ? "self-stretch" : undefined}
-    >
-      <>{control}</>
-    </Tooltip>
-  );
-}