@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/components/button-look.ts

@@ -0,0 +1,230 @@
+import { cn } from "../lib/cn";
+import { FOCUS_RING_WIDTH } from "./focus-ring";
+import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
+
+/**
+ * The button look, which {@link Button} and {@link IconButton} share (0.34, MOD-2, refactor
+ * audit 2026-10). In ui.tsx it was the one knot in an otherwise one-way graph: Button drew
+ * IconButton's pressed look, and IconButton drew Button's variant colours, its hover ink
+ * and its router link. Both now draw from this module, which renders nothing, so neither
+ * imports the other.
+ *
+ * Public through ./ui by name: `buttonClasses`, `TOUCH_TARGET_LARGE` and the four types.
+ * The other exports are the two buttons' shared parts (`@internal`).
+ */
+
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "brand" | "link";
+
+// Shared base ring for every button-styled element. Kept as a named const so the
+// <Button> component and the {@link buttonClasses} helper draw from one source and
+// can never drift apart.
+//
+// The ring is the kit's focus frame (§5): {@link FOCUS_RING_WIDTH} wide, on keyboard focus
+// (`focus-visible`) — a tap or a click no longer leaves a ring on the button — in each
+// variant's own colour below.
+//
+// `[&_svg]:shrink-0` (0.32.2, kastlan's 0.32.1 report): an icon beside a label keeps its
+// size when the label wraps at Large. Without it the svg was a flex item like the text,
+// and a two-line label squeezed it to a sliver ("New invoice" in a page header at 360 px
+// / Extra large).
+const BUTTON_BASE = cn(
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus:outline-none disabled:opacity-50 disabled:cursor-not-allowed [&_svg]:shrink-0",
+  FOCUS_RING_WIDTH,
+);
+
+/**
+ * The touch target at Large and Extra large (docs/text-size-harmonization.md §4): at
+ * least 48 px, the size a finger needs whatever the type. In px on purpose, like the
+ * field floor ({@link FIELD_TOUCH_TEXT}): it is a physical threshold, not a size that
+ * follows the text. Normal keeps the kit's own heights; a `large:` variant, so it costs
+ * no render and is right on the first paint.
+ */
+export const TOUCH_TARGET_LARGE = "large:min-h-[48px] large:min-w-[48px]";
+
+export type ButtonSize = "sm" | "md";
+
+// Box geometry per size, split out of the base so the two cannot be merged into one
+// string that a size then has to fight. `md` is the pre-0.8.0 look, unchanged. `sm` is
+// the compact secondary action keksdose repeats by hand as `px-2 py-1 text-xs` (and
+// `px-2 py-0.5 text-xs`) on the buttons in a toolbar or a table header; one rung is
+// enough, so the two spellings meet at `py-1`. There is no `lg`: no app has asked for
+// a bigger text button (IconButton's `lg` is a touch target, not a text size). The
+// variant map comes AFTER the size, so `link`'s `p-0` still wins at either size.
+//
+// At Large and above (§4) `sm` grows to `md`'s height — the padding that makes its
+// 1rem line as tall as `md`'s 1.25rem one — and both reach the 48 px touch target. The
+// type stays `sm`'s: the compact button is still the quieter one. Not on `link`, which
+// is a word in a sentence and has no box to grow (see `buttonLook`).
+const BUTTON_SIZES: Record<ButtonSize, string> = {
+  md: "gap-2 px-3 py-2 text-sm",
+  sm: "gap-1.5 px-2 py-1 text-xs",
+};
+const BUTTON_SIZES_LARGE: Record<ButtonSize, string> = {
+  md: "large:min-h-[48px]",
+  sm: "large:min-h-[48px] large:py-2.5",
+};
+
+/**
+ * The hover of a control that may sit on the page, a card or a well (0.33, B′ —
+ * docs/colour-roles-harmonization.md §12.1, §12.10): the body ink at 7 %, TRANSLUCENT,
+ * so it darkens (in dark, lightens) whatever is under it by the same step — 1.11:1 or
+ * more on all three surfaces, both themes, with the label at 7:1 and up. It was
+ * `--bg-surface-2`, which since 0.33 is the page itself in light: a ghost button on the
+ * page would not have moved at all. Not `--bg-hover` either, which is mixed against the
+ * CARD and stands only 1.04:1 from the page. IconButton's `custom` tone uses the same
+ * recipe at 12 %.
+ */
+export const HOVER_INK = "hover:bg-[color-mix(in_srgb,var(--text-primary)_7%,transparent)]";
+
+// Warm, palette-token-driven so buttons blend with the fields + cards in every theme.
+// Actions default to a warm bordered look (primary = filled warm chip, secondary =
+// outline); `brand` stays the solid accent for the rare strong CTA; `danger` takes the
+// semantic `--danger` family (destructive semantics), so a consumer can re-point the
+// destructive hue instead of inheriting a hard-coded red. Focus rings follow each
+// variant's own accent: brand for the four neutral ones, danger for `danger`.
+export const buttonVariantClasses: Record<ButtonVariant, string> = {
+  primary:
+    // Hovers onto `--bg-active`, not `--border` (0.33, §12.9): More contrast steps the
+    // border until it is a 3:1 LINE, and as a fill under the label that left 2.7:1.
+    "border border-subtle bg-surface-2 text-primary hover:bg-active focus-visible:ring-brand",
+  secondary: `border border-subtle bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,
+  ghost: `bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,
+  danger:
+    "bg-danger text-danger-contrast hover:bg-danger-hover focus-visible:ring-danger-strong",
+  brand:
+    "bg-brand text-brand-contrast hover:bg-brand-hover focus-visible:ring-brand",
+  // A text link that is still a `<button>` — keksdose's six hand-rolled
+  // `<button className="text-brand underline">` sites ("Resend code", "Show all",
+  // "Undo" in a toast…), which act rather than navigate and so must not be anchors.
+  // The box padding goes (`p-0`) so it sits in a sentence at the text's own size, but
+  // the base's focus ring stays: those copies had `outline-none` and no ring, so
+  // a keyboard user tabbing onto them saw nothing at all. `rounded-sm` keeps that
+  // ring hugging the word instead of drawing a pill round it.
+  link:
+    "rounded-sm p-0 bg-transparent text-brand underline-offset-4 hover:underline focus-visible:ring-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`.
+ *
+ * `danger` also reaches the two NEUTRAL boxed variants, where the box carries it:
+ * `secondary` becomes an outlined destructive button (`--danger` text and a
+ * `--danger-border` outline, the quiet danger fill on hover) and `primary` a soft one
+ * (the quiet fill at rest, solid `--danger` on hover). kastlan's meeting-invitations-
+ * tab.tsx "Remove all" is `variant="secondary" className="text-destructive"` — a
+ * destructive action that must sit in a row of secondary buttons without shouting
+ * like the solid `variant="danger"` would, and whose red text alone left the border
+ * and hover saying "neutral". `muted` stays a text look and does nothing on a box, and
+ * `danger`, `brand` and `link`'s own colours are left alone: a tone that recoloured a
+ * solid danger or brand button would be a second variant under another name.
+ */
+export type ButtonTone = "default" | "muted" | "danger";
+
+const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
+  muted:
+    "text-secondary hover:text-primary disabled:hover:text-secondary",
+  danger:
+    "text-secondary hover:text-danger focus-visible:ring-danger-strong disabled:hover:text-secondary",
+};
+
+/** Only the two transparent variants take every tone; see {@link ButtonTone}. */
+const TONED_VARIANTS = new Set<ButtonVariant>(["link", "ghost"]);
+
+// `tone="danger"` on the neutral boxed variants — see {@link ButtonTone}. Each string
+// restates every colour the variant sets (border, fill, text, hover, ring) so none of
+// the neutral ones survives the merge.
+const BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {
+  // Not boxed, but its hover is a fill: the danger wash under the danger text, as
+  // IconButton's danger tone (0.33). On B′'s translucent ink `--danger` fell to 4.2:1
+  // over a light page.
+  ghost: "hover:bg-danger-soft",
+  secondary:
+    "border-danger bg-transparent text-danger hover:bg-danger-soft focus-visible:ring-danger-strong",
+  primary:
+    "border-danger bg-danger-soft text-danger hover:border-[var(--danger)] hover:bg-danger hover:text-danger-contrast focus-visible:ring-danger-strong disabled:hover:border-danger disabled:hover:bg-danger-soft disabled:hover:text-danger",
+};
+
+// `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.
+export const BUTTON_LINK_PRESSED =
+  "font-medium text-brand hover:text-brand disabled:hover:text-brand";
+
+/** The second argument of {@link buttonClasses} in its options form. */
+export interface ButtonClassesOptions {
+  /** See {@link ButtonProps.size}. */
+  size?: ButtonSize;
+  className?: string;
+}
+
+/**
+ * Button classes for the rare case where the styling must land on a non-`<button>`
+ * element that {@link Button} can't render — e.g. a router `<Link>` or a Radix
+ * AlertDialog Action/Cancel (which must stay the Radix element). Everywhere a real
+ * button works, prefer `<Button>`. Draws from the same base, size and variant maps as
+ * `<Button>`, so the two stay in lockstep.
+ *
+ * The second argument is either the extra classes (the pre-0.8.0 form) or
+ * `{ size, className }` — `buttonClasses("secondary", { size: "sm" })` for keksdose's
+ * compact toolbar links.
+ */
+export function buttonClasses(
+  variant: ButtonVariant = "primary",
+  classNameOrOptions?: string | ButtonClassesOptions,
+): string {
+  const { size = "md", className } =
+    typeof classNameOrOptions === "object" ? classNameOrOptions : { className: classNameOrOptions };
+  return cn(
+    BUTTON_BASE,
+    BUTTON_SIZES[size],
+    variant !== "link" && BUTTON_SIZES_LARGE[size],
+    buttonVariantClasses[variant],
+    className,
+  );
+}
+
+// `pressed`: a toggle that is on. The brand glyph on the quiet brand fill — the
+// "selected" look of a Chip or a SegmentedControl option, so an on toggle reads as on
+// beside them. After the tone, so a pressed `muted` button is brand, not grey. On hover
+// the glyph turns brand-muted: `--brand` on `--brand-bg-hover` is 2.69–2.80 in four dark
+// presets, under an icon's 3:1 (colour-roles §12.12). Button's `pressed` draws it on its
+// boxed variants too, which is why it lives here and not in ./icon-button.
+export const ICON_BUTTON_PRESSED =
+  "bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted disabled:hover:bg-brand-soft disabled:hover:text-brand";
+
+/** @internal The button look shared by the `<button>` and the `<a>` form. */
+export function buttonLook(variant: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {
+  return cn(
+    BUTTON_BASE,
+    BUTTON_SIZES[size],
+    // §4: `sm` at `md`'s height and the 48 px target at Large — not on a `link`. In the
+    // order `buttonClasses` has it, so the two strings stay identical.
+    variant !== "link" && BUTTON_SIZES_LARGE[size],
+    // In a flex row next to a taller labelled field, `stretch` makes the button
+    // fill the field's height so the two line up (self-stretch overrides the row's
+    // 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],
+    tone === "danger" && BUTTON_BOXED_DANGER[variant],
+  );
+}
+
+/** @internal Calls a `renderLink` / provider link as a function, as ListItem and Chip
+ *  do — an inline `renderLink` arrow would otherwise be a new component type every
+ *  render. Both buttons' link forms render through it. */
+export function RenderedButtonLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
+  return render(props);
+}

package/src/components/button.tsx

@@ -0,0 +1,339 @@
+import { useId } from "react";
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ReactElement, ReactNode, Ref } from "react";
+import { cn } from "../lib/cn";
+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 { LockedReason, type DisabledReasonDisplay } from "./field-parts";
+import { Spinner } from "./spinner";
+import { BUTTON_LINK_PRESSED, ICON_BUTTON_PRESSED, RenderedButtonLink, buttonLook } from "./button-look";
+import type { ButtonSize, ButtonTone, ButtonVariant } from "./button-look";
+
+// The kit's text button, and `<Button href>`, the link that looks like one. Its look —
+// the variant, size and tone maps, and `buttonClasses` — is ./button-look, which
+// IconButton shares (0.34, MOD-2, refactor audit 2026-10).
+
+/**
+ * ⚠️ No default `type`: like a native `<button>`, a `Button` inside a `<form>` SUBMITS
+ * it unless you pass `type="button"`. Kept native on purpose — a form's own submit
+ * button relies on it, and changing the default would silently stop those forms from
+ * submitting. Pass `type="button"` for every other action in a form (keksdose had six
+ * link buttons submitting their form).
+ */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  /** `md` (default) is the page's action button. `sm` is the compact one — 12px text
+   *  and `px-2 py-1` — for the secondary actions in a toolbar, a card header or a
+   *  table's header row (keksdose writes `px-2 py-1 text-xs` over `secondary` by hand
+   *  there). Every variant takes either size. */
+  size?: ButtonSize;
+  /** In a flex row next to a taller labelled field, fill the field's height so the
+   *  two line up. No effect outside a flex row. */
+  stretch?: boolean;
+  /** The `<button>` element. React 19 passes `ref` to a function component as an
+   *  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). `danger` also makes `secondary` an
+   *  outlined destructive button and `primary` a soft one; 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;
+  /**
+   * Where `disabledReason` shows (0.32, §4 "No fact only in a tooltip"): by default a
+   * line under the button at Large and on a touch screen, the tooltip otherwise. See
+   * {@link DisabledReasonDisplay}.
+   */
+  disabledReasonDisplay?: DisabledReasonDisplay;
+  /**
+   * This button COMMITS — it saves, creates, deletes. Under a locked
+   * {@link WriteLockProvider} it is disabled the `disabledReason` way, with the lock's
+   * reason (which wins over a `disabledReason` of its own). No provider, or an
+   * unlocked one: no effect. See {@link WriteLockProvider}; a {@link CommitScope} since
+   * 0.33 (`COMMIT_EXCEPT_BILLING`: every lock but a lapsed plan's).
+   */
+  commit?: CommitScope;
+  /**
+   * Busy — the save is in flight: a spinner, `aria-busy`, and no second submit.
+   *
+   * kastlan's FormActions (form-actions.tsx:50) disables its submit and swaps in a
+   * `submittingLabel`, so the button jumps width mid-click and a screen reader hears
+   * the name change instead of "busy". Here the label STAYS — it is still the
+   * accessible name and still holds the button's width — and the spinner is drawn over
+   * it in the text colour, so nothing beside the button moves.
+   *
+   * The same prop {@link FileButton} has (`pending`), with one difference: this one is
+   * `aria-disabled`, not `disabled`. The button being pressed is the one that has focus,
+   * and a native `disabled` drops that focus to `<body>` the moment the save starts;
+   * clicks, and the Enter that submits a form through it, are swallowed instead.
+   */
+  pending?: boolean;
+  /** Only on the link form — see {@link ButtonLinkProps}. */
+  href?: never;
+  renderLink?: never;
+  external?: never;
+  replace?: never;
+  reloadDocument?: never;
+}
+
+/**
+ * `<Button href>`: a link that looks like a button — for an action that NAVIGATES.
+ *
+ * kastlan paints `buttonClasses(…)` onto router Links by hand in six places (the
+ * invoice / lease / unit preview dialogs' "Open" at invoice-preview-dialog.tsx:36,
+ * platform-companies-page.tsx:111, verify-email-page.tsx:86's "Log in",
+ * billing-history-page.tsx:85's PDF download), and has 26 `<Button onClick={() =>
+ * navigate(…)}>` that are links in all but markup: no middle-click, no "open in new
+ * tab", no URL on hover, and a screen reader announces a button that then changes the
+ * page. With `href` it is an `<a>`: the provider's router link
+ * ({@link UiKitProvider}'s `linkComponent`), or `renderLink` if given, else a plain one.
+ *
+ * `type` and `form` are typed out: they are a `<button>`'s, and a link never submits.
+ */
+export interface ButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "type" | "href"> {
+  href: string;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  stretch?: boolean;
+  tone?: ButtonTone;
+  /** The in-app router link, over the provider's `linkComponent` (see
+   *  {@link KitLinkComponent}). Ignored when `external`. */
+  renderLink?: KitLinkComponent;
+  /** Leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`, never the
+   *  router link, and "(opens in a new tab)" read after the label — billing-history's
+   *  Stripe PDF. A `target="_blank"` of your own is announced the same way. */
+  external?: boolean;
+  /**
+   * Navigate by replacing the current history entry, so Back does not return here —
+   * keksdose F1: the "Continue" out of a one-shot page (an emailed confirmation link, a
+   * payment return URL) that must not be landed on again. Handed to the router link as
+   * `replace` (see `KitLinkProps.replace` for mapping it); on a plain `<a>` a plain click
+   * becomes `location.replace(href)`. Ignored when `external`.
+   */
+  replace?: boolean;
+  /**
+   * A plain `<a>` for an in-app `href`, so the browser loads the whole document instead
+   * of the router swapping the view — keksdose F1: a route the SPA does not own (a
+   * server-rendered export, a logout that must drop every in-memory cache). Wins over
+   * `renderLink` and the provider's `linkComponent`.
+   */
+  reloadDocument?: boolean;
+  /** A link cannot be `disabled`, so this renders an `<a>` with NO `href` —
+   *  `role="link"` and `aria-disabled`, out of the tab order like a disabled button,
+   *  with the disabled look. The router link is not used: it needs somewhere to go. */
+  disabled?: boolean;
+  ref?: Ref<HTMLAnchorElement>;
+  type?: never;
+  form?: never;
+  pending?: never;
+  pressed?: never;
+  disabledReason?: never;
+  disabledReasonDisplay?: never;
+  commit?: never;
+}
+
+// Declared link-first so `<Button href>` picks the link props; the LAST signature is
+// what `ComponentProps<typeof Button>` reads, so wrappers (FileButton) still see the
+// `<button>` props they always did.
+export function Button(props: ButtonLinkProps): ReactElement;
+export function Button(props: ButtonProps): ReactElement;
+export function Button(props: ButtonProps | ButtonLinkProps): ReactElement {
+  if (props.href !== undefined) return <ButtonLink {...(props as ButtonLinkProps)} />;
+  return <ButtonElement {...(props as ButtonProps)} />;
+}
+
+function ButtonLink({
+  href,
+  renderLink,
+  external,
+  replace,
+  reloadDocument,
+  disabled,
+  variant = "primary",
+  size = "md",
+  stretch,
+  tone = "default",
+  className,
+  children,
+  target,
+  rel,
+  onClick,
+  ...rest
+}: ButtonLinkProps) {
+  const kitLink = useKitLink();
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  // The same rule as every kit link (`pickLinkRenderer`): an external `href` or an
+  // in-page `#anchor` is never handed to the provider's router link, even without
+  // `external`.
+  // `reloadDocument` is the caller saying "not the router" for this one link.
+  const Link = reloadDocument ? undefined : pickLinkRenderer<KitLinkProps>(renderLink, kitLink, href);
+  const newTab = !disabled && (external || target === "_blank");
+  const cls = cn(
+    buttonLook(variant, size, stretch, tone),
+    // `relative` holds the sr-only note (see sr-only-containment.test).
+    newTab && "relative",
+    // BUTTON_BASE's `disabled:` classes never match an `<a>`; no pointer events also
+    // keeps the hover fill from lighting up on something that refuses the click.
+    disabled && "pointer-events-none cursor-not-allowed opacity-50",
+    className,
+  );
+  const body = (
+    <>
+      {children}
+      {/* The space OUTSIDE the sr-only span: a name computation trims each child's
+          text, so one inside it was lost ("Download(opens…"). In a flex box a bare
+          space draws nothing. */}
+      {newTab && " "}
+      {newTab && <span className="sr-only">({common.opensInNewTab})</span>}
+    </>
+  );
+  if (disabled) {
+    return (
+      <a {...rest} role="link" aria-disabled="true" className={cls}>
+        {body}
+      </a>
+    );
+  }
+  if (external || !Link) {
+    return (
+      <a
+        {...rest}
+        href={href}
+        target={external ? "_blank" : target}
+        rel={external ? (rel ?? "noopener noreferrer") : rel}
+        onClick={external ? onClick : replacingClick(onClick, href, replace, target)}
+        className={cls}
+      >
+        {body}
+      </a>
+    );
+  }
+  return (
+    <RenderedButtonLink
+      render={Link}
+      {...rest}
+      {...routerLinkNavigation(replace)}
+      href={href}
+      target={target}
+      rel={rel}
+      onClick={onClick}
+      className={cls}
+    >
+      {body}
+    </RenderedButtonLink>
+  );
+}
+
+function ButtonElement({
+  variant = "primary",
+  size = "md",
+  stretch,
+  tone = "default",
+  pressed,
+  disabledReason: ownDisabledReason,
+  disabledReasonDisplay,
+  commit,
+  pending,
+  className,
+  onClick,
+  children,
+  href: _href,
+  renderLink: _renderLink,
+  external: _external,
+  replace: _replace,
+  reloadDocument: _reloadDocument,
+  ...rest
+}: ButtonProps) {
+  const reasonId = useId();
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
+  const locked = hasContent(disabledReason);
+  const inert = locked || Boolean(pending);
+  const ownDescribedBy = rest["aria-describedby"];
+  const button = (
+    <button
+      {...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-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 (inert) {
+          e.preventDefault();
+          return;
+        }
+        onClick?.(e);
+      }}
+      className={cn(
+        buttonLook(variant, size, stretch, 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",
+        // No dimming while pending: the spinner IS the state, and at half opacity it
+        // would be the faintest thing on the button. `relative` anchors it.
+        pending && "relative cursor-progress",
+        className,
+      )}
+    >
+      {pending ? (
+        <>
+          {/* Transparent, not hidden: it keeps the width AND stays the accessible
+              name (`visibility: hidden` would drop it from the name). `gap-[inherit]`
+              keeps an icon + text spaced as the button spaces them. */}
+          <span className="inline-flex items-center justify-center gap-[inherit] opacity-0">{children}</span>
+          {/* Decorative: `aria-busy` says it, as on FileButton. */}
+          <Spinner
+            label={null}
+            className="absolute inset-0 m-auto size-4 border-current/30 border-t-current"
+          />
+        </>
+      ) : (
+        children
+      )}
+    </button>
+  );
+  if (!locked) return button;
+  return (
+    <LockedReason
+      lock={{ reason: disabledReason, reasonId }}
+      display={disabledReasonDisplay}
+      className={stretch ? "self-stretch" : undefined}
+    >
+      {button}
+    </LockedReason>
+  );
+}

package/src/components/calculator.tsx

@@ -2,7 +2,8 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { Calculator as CalculatorIcon, Delete } from "lucide-react";
 import { Popover } from "./popover";
 import { cn } from "../lib/cn";
-import { FIELD_TOUCH_TEXT } from "./ui";
+import { FIELD_TOUCH_TEXT } from "./field-base";
+import { FOCUS_RING } from "./focus-ring";
 import { evaluateExpression, formatResult, isBareAmount, splitLeadingSign } from "../lib/calc";
 import {
   DEFAULT_CALCULATOR_LABELS,
@@ -35,8 +36,8 @@ interface CalculatorButtonProps {
   onChange: (value: string, expression?: string) => void;
   className?: string;
   /** The trigger's accessible name; wins over `calculator.open` from the provider. */
-  ariaLabel?: string;
-  /** Screen-reader names for the panel's own controls. `ariaLabel` above already
+  "aria-label"?: string;
+  /** Screen-reader names for the panel's own controls. `aria-label` above already
    *  covers the trigger; these three were hardcoded English inside the popover,
    *  which a translating host had no way to reach. */
   labels?: CalculatorButtonLabels;
@@ -70,8 +71,9 @@ const KEYS: Key[] = [
   { kind: "ins", label: "+", ins: "+", accent: true, name: "plus" },
 ];
 
-const KEY_BASE =
-  "flex h-9 items-center justify-center rounded-md text-sm font-medium transition-colors focus:outline-none focus:ring-[length:var(--focus-ring-width)] focus:ring-[var(--border-strong)]";
+// The kit's one focus frame (text-size §5). Until 0.34 the keys rang in `ring-strong` on
+// `focus:`, so a pointer click left a grey ring on the key it pressed (DOC-7).
+const KEY_BASE = `flex h-9 items-center justify-center rounded-md text-sm font-medium transition-colors ${FOCUS_RING}`;
 // Two key families, two fills: digits sit on the inset surface and darken on
 // hover, operators sit a step down on `--bg-active` and lift toward that surface —
 // the same split `NumberPadSheet` uses for this keypad on a phone. The tokens
@@ -156,9 +158,9 @@ function CalculatorPanel({
         // is right-aligned in every script too — so both stay physical, pinned
         // with `dir="ltr"` rather than mirrored in a right-to-left form.
         dir="ltr"
-        className={cn("block w-full rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1.5 text-right font-mono text-sm text-[var(--text-primary)] focus:border-[var(--border-strong)] focus:ring-[var(--border-strong)]", FIELD_TOUCH_TEXT)}
+        className={cn("block w-full rounded-md border border-subtle bg-surface px-2 py-1.5 text-right font-mono text-sm text-primary focus:border-strong focus:ring-strong", FIELD_TOUCH_TEXT)}
       />
-      <div dir="ltr" className="h-4 pr-1 text-right font-mono text-xs text-[var(--text-placeholder)]">
+      <div dir="ltr" className="h-4 pr-1 text-right font-mono text-xs text-placeholder">
         {result !== null && formatResult(result) !== text.trim() ? `= ${formatResult(result)}` : ""}
       </div>
       <div className="grid grid-cols-4 gap-1.5">
@@ -204,7 +206,7 @@ function CalculatorPanel({
             // an inverted fill, so the hover is the chip mixed back toward the
             // surface — a step quieter in either theme, and still a colour, so
             // KEY_BASE's `transition-colors` carries it.
-            "col-span-2 bg-[var(--bg-inverse)] text-[var(--text-inverse)] hover:bg-[color-mix(in_oklab,var(--bg-inverse)_88%,var(--bg-surface))]",
+            "col-span-2 bg-inverse text-inverse hover:bg-[color-mix(in_oklab,var(--bg-inverse)_88%,var(--bg-surface))]",
           )}
         >
           =
@@ -224,11 +226,11 @@ export function CalculatorButton({
   value,
   onChange,
   className,
-  ariaLabel,
+  "aria-label": ariaLabel,
   labels: labelsProp,
 }: CalculatorButtonProps) {
-  // prop > provider > English, with the older `ariaLabel` prop folded in as the
-  // `open` key it has always been.
+  // prop > provider > English, with the name prop folded in as the `open` key it has
+  // always been.
   const fromProps = useMemo(
     () => (ariaLabel === undefined ? labelsProp : { ...labelsProp, open: ariaLabel }),
     [ariaLabel, labelsProp],
@@ -247,7 +249,7 @@ export function CalculatorButton({
           aria-label={labels.open}
           aria-expanded={open}
           className={cn(
-            "flex items-center justify-center text-[var(--text-placeholder)] transition-colors hover:text-[var(--text-secondary)]",
+            "flex items-center justify-center text-placeholder transition-colors hover:text-secondary",
             className,
           )}
         >

package/src/components/calendar-heatmap-labels.ts

@@ -0,0 +1,15 @@
+// The English words of ./calendar-heatmap, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./calendar-heatmap re-exports them.
+
+import type { CalendarHeatmapLabels } from "./calendar-heatmap";
+
+/** English defaults, exported as the `calendarHeatmap` namespace of `UiKitLabels`. */
+export const DEFAULT_CALENDAR_HEATMAP_LABELS: CalendarHeatmapLabels = {
+  grid: "Daily values",
+  day: (date, value) => `${date}: ${value}`,
+  less: "Less",
+  more: "More",
+  truncated: (count) =>
+    `Showing the most recent days; ${count} earlier ${count === 1 ? "day is" : "days are"} not shown.`,
+};