@eifi1/ui-kit 0.16.1 → 0.18.0

package/src/components/toast.tsx

@@ -135,9 +135,33 @@ type Kind = "default" | "success" | "error" | "warning" | "info" | "loading";
 
 const privately = (node: ReactNode) => <span data-private="">{node}</span>;
 
+/**
+ * The toast's id, written onto its `<li>` as a class — the one per-toast attribute
+ * sonner passes through untouched besides `testId`, which is the app's (sonner keeps the
+ * id in React state only). `<Toaster dismissOnMiddleClick>` reads it back to dismiss
+ * the toast under the pointer, close button or not. The type is kept (`s`/`n`) because
+ * sonner matches ids with `===`, and the value is URI-encoded so any string id is one
+ * whitespace-free class token.
+ */
+const ID_CLASS = "kit-toast-id-";
+const idClass = (id: ToastId) =>
+  `${ID_CLASS}${typeof id === "number" ? "n" : "s"}-${encodeURIComponent(String(id))}`;
+
+/** The id {@link idClass} stamped on a toast element, or null for a toast the kit did
+ *  not make (an app still calling sonner directly). */
+function readToastId(el: Element): ToastId | null {
+  for (const token of el.classList) {
+    if (!token.startsWith(ID_CLASS)) continue;
+    const kind = token.charAt(ID_CLASS.length);
+    const raw = decodeURIComponent(token.slice(ID_CLASS.length + 2));
+    return kind === "n" ? Number(raw) : raw;
+  }
+  return null;
+}
+
 function toSonnerData(opts: ToastOptions | undefined, id: ToastId): SonnerData {
-  const { redact, description, duration, action, ...rest } = opts ?? {};
-  const data: SonnerData = { ...rest, id };
+  const { redact, description, duration, action, className, ...rest } = opts ?? {};
+  const data: SonnerData = { ...rest, id, className: className ? `${idClass(id)} ${className}` : idClass(id) };
   if (description !== undefined) data.description = redact ? privately(description) : description;
   if (action) data.action = action;
   const resolved = duration ?? (action ? TOAST_ACTION_DURATION : undefined);
@@ -312,6 +336,15 @@ export interface ToasterProps {
   hotkey?: string[];
   gap?: number;
   dir?: "ltr" | "rtl" | "auto";
+  /**
+   * A middle click on a toast dismisses it (0.18.0) — the gesture that closes a tab,
+   * which is what keksdose's users reached for (dev #583). By id, so it works on a
+   * toast with `closeButton: false` too; it counts as the user closing it, so
+   * `onDismiss` runs. Not on a link or a button inside the toast — a middle click on a
+   * link still opens it in a new tab — and not on a `dismissible: false` toast.
+   * Default true.
+   */
+  dismissOnMiddleClick?: boolean;
   className?: string;
   style?: CSSProperties;
 }
@@ -385,6 +418,7 @@ export function Toaster({
   swipeDirections = ALL_DIRECTIONS,
   offset,
   mobileOffset,
+  dismissOnMiddleClick = true,
   className,
   style,
   ...rest
@@ -409,6 +443,42 @@ export function Toaster({
     };
   }, [labels]);
 
+  useEffect(() => {
+    if (!dismissOnMiddleClick || !mod) return;
+    // On the document rather than the toaster: sonner owns the `<ol>`, and a listener
+    // there would have to be re-attached whenever it remounts it.
+    const toastUnder = (e: globalThis.MouseEvent) => {
+      if (e.button !== 1 || !(e.target instanceof Element)) return null;
+      const li = e.target.closest<HTMLElement>("[data-sonner-toast]");
+      if (!li || li.dataset.dismissible === "false") return null;
+      // A link keeps its middle click (open in a new tab); a button or a field inside
+      // the toast is the app's, not a background to click.
+      const control = e.target.closest("a[href], button, input, select, textarea, [role='button'], [role='link']");
+      if (control && li.contains(control)) return null;
+      return li;
+    };
+    // `mousedown`: the middle button starts autoscroll (Windows) before any click.
+    const onDown = (e: globalThis.MouseEvent) => {
+      if (toastUnder(e)) e.preventDefault();
+    };
+    const onAux = (e: globalThis.MouseEvent) => {
+      const li = toastUnder(e);
+      if (!li) return;
+      // No paste of the primary selection on Linux, no other handler's idea of it.
+      e.preventDefault();
+      const id = readToastId(li);
+      if (id !== null) mod.toast.dismiss(id);
+      // A toast made by sonner directly carries no id: its close button, if any.
+      else li.querySelector<HTMLButtonElement>("[data-close-button]")?.click();
+    };
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("auxclick", onAux);
+    return () => {
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("auxclick", onAux);
+    };
+  }, [dismissOnMiddleClick, mod]);
+
   const documentTheme = useSyncExternalStore(subscribeDocumentTheme, readDocumentTheme, () => "light" as const);
   const phone = useMediaQuery(PHONE_QUERY, false);
   const resolved: ToastPosition = position ?? (phone ? "bottom-center" : "top-center");

package/src/components/toggle-group.tsx

@@ -340,8 +340,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
                 ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
                 : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
               // No hover fill on a group that cannot be changed — a segment that
-              // lights up under the pointer is an offer, and there is none here.
-              disabled && "cursor-not-allowed hover:bg-transparent dark:hover:bg-transparent",
+              // lights up under the pointer is an offer, and there is none here. Not on
+              // the chosen segment: its fill IS its state, and its inverse text would
+              // vanish on a transparent hover.
+              disabled && "cursor-not-allowed",
+              disabled && !active && "hover:bg-transparent dark:hover:bg-transparent",
               optionClassName,
               opt.className,
             )}

package/src/components/ui.tsx

@@ -9,6 +9,7 @@ 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";
 
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "brand" | "link";
 
@@ -196,6 +197,13 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
    * DangerConfirm keeps its own.
    */
   disabledReason?: ReactNode;
+  /**
+   * 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}.
+   */
+  commit?: boolean;
   /**
    * Busy — the save is in flight: a spinner, `aria-busy`, and no second submit.
    *
@@ -271,6 +279,7 @@ export interface ButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorEle
   pending?: never;
   pressed?: never;
   disabledReason?: never;
+  commit?: never;
 }
 
 function hasContent(node: ReactNode): boolean {
@@ -396,7 +405,8 @@ function ButtonElement({
   stretch,
   tone = "default",
   pressed,
-  disabledReason,
+  disabledReason: ownDisabledReason,
+  commit,
   pending,
   className,
   onClick,
@@ -409,6 +419,7 @@ function ButtonElement({
   ...rest
 }: ButtonProps) {
   const reasonId = useId();
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
   const locked = hasContent(disabledReason);
   const inert = locked || Boolean(pending);
   const ownDescribedBy = rest["aria-describedby"];
@@ -874,6 +885,10 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
    * reason nobody can see is not one. Wins over `disabled`, as on Button.
    */
   disabledReason?: ReactNode;
+  /** 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. */
+  commit?: boolean;
   /** The `<button>` element — a prop in React 19, as on {@link Button}. */
   ref?: Ref<HTMLButtonElement>;
   /** Only on the link form — see {@link IconButtonLinkProps}. */
@@ -937,6 +952,7 @@ export interface IconButtonLinkProps
   form?: never;
   pressed?: never;
   disabledReason?: never;
+  commit?: never;
   disabledStyle?: never;
   pending?: never;
 }
@@ -1164,7 +1180,8 @@ function IconButtonElement(
     tooltipSide,
     tooltipPortal,
     tooltipLazy = true,
-    disabledReason,
+    disabledReason: ownDisabledReason,
+    commit,
     pending,
     glyphSize,
     badge,
@@ -1186,6 +1203,7 @@ function IconButtonElement(
   const tone = toneProp ?? (toneColor !== undefined ? "custom" : "default");
   const keep = disabledStyle === "keep";
   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.
@@ -1750,15 +1768,48 @@ function useFieldError(
  * down out of the field, between the value and the text. So the field keeps its box
  * and this wraps the pair.
  *
- * It renders nothing of its own when there is no message, which is what keeps `error`
- * additive: a field without one is exactly the DOM it was before the prop existed,
- * down to the bare `<input>` an unlabelled {@link Input} drops straight into a
- * caller's flex row. For the same reason `className` is NOT moved out here — it goes
- * on the field, as it always has, so adding a message cannot silently change what
- * that prop styles.
+ * WHEN IT WRAPS. A field that never takes `error` renders nothing of its own here,
+ * which is what keeps the prop additive: it is exactly the DOM it was before the prop
+ * existed, down to the bare `<input>` an unlabelled {@link Input} drops straight into a
+ * caller's flex row. A field that DOES take `error` — the key is passed, whatever its
+ * value — is wrapped for as long as it is mounted, message or not (`reserve`).
+ *
+ * It used to wrap only while a message showed, and that cost the control its
+ * identity: a fragment and a `<div>` are different elements at the same spot in the
+ * tree, so React threw the `<input>` away and mounted a new one every time the message
+ * came or went. Focus fell to `<body>`, the caret went with it, and an uncontrolled
+ * field lost what had been typed — Kurvenschmiede's confirm-password dialog clears its
+ * "Wrong password" on change, so the first keystroke of the retry dropped the user out
+ * of the field. Keeping the box stops that; the field is never reparented.
+ *
+ * The other ways to keep it stable were worse. A box on EVERY field changes what every
+ * flex row and grid in three apps lays out (`flex-1`, `w-56`, `col-span-2` on the
+ * field would land on a child of the item instead of the item). A `display: contents`
+ * box would keep the flex/grid item, but a contents box takes no margin, so a parent's
+ * `space-y-*` stops spacing the field — the shape of Kurvenschmiede's reset-password
+ * form and gear wizard, both `space-y-*` stacks of fields with `error` — and it moves
+ * `first:`/`last:`/`> *` matches. A field passing `error` already took this plain box
+ * whenever its message showed, so what changes is only that it keeps it while none
+ * does; every such call site in the three apps sits in a block or a `space-y`/grid
+ * stack where a full-width block box is the field's own size. The case it does change
+ * is a field passing `error` whose `className` sizes it as a flex item (`flex-1` in a
+ * row): that caller already lost the sizing while a message showed, and now sees the
+ * same box without one. Pass `error` only where a message can actually appear.
+ *
+ * `className` is NOT moved out here, for the same reason — it goes on the field, as it
+ * always has, so the box cannot silently change what that prop styles.
  */
-function FieldGroup({ errorEl, children }: { errorEl: ReactNode; children: ReactNode }) {
-  if (errorEl === null) return <>{children}</>;
+function FieldGroup({
+  errorEl,
+  reserve = false,
+  children,
+}: {
+  errorEl: ReactNode;
+  /** The caller passed `error`: keep the box even while there is no message. */
+  reserve?: boolean;
+  children: ReactNode;
+}) {
+  if (errorEl === null && !reserve) return <>{children}</>;
   return (
     <div>
       {children}
@@ -1829,8 +1880,8 @@ export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
   passwordLabels?: Partial<PasswordRevealLabels>;
 }
 
-export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
-  {
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(props, ref) {
+  const {
     className,
     inputClassName,
     label,
@@ -1842,9 +1893,9 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
     error,
     passwordLabels,
     ...rest
-  },
-  ref,
-) {
+  } = props;
+  // Passed at all — even as `undefined` — the field keeps its box; see FieldGroup.
+  const reserve = "error" in props;
   const generated = useId();
   const fieldId = id ?? generated;
   const { isInvalid, describedBy, errorEl } = useFieldError(
@@ -1894,7 +1945,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
   if (label === undefined) {
     if (!isPassword) {
       return (
-        <FieldGroup errorEl={errorEl}>
+        <FieldGroup errorEl={errorEl} reserve={reserve}>
           <input
             ref={ref}
             id={id}
@@ -1915,7 +1966,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
       );
     }
     return (
-      <FieldGroup errorEl={errorEl}>
+      <FieldGroup errorEl={errorEl} reserve={reserve}>
         <div className={cn("relative", className)}>
           <input
             ref={ref}
@@ -1933,7 +1984,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
     );
   }
   return (
-    <FieldGroup errorEl={errorEl}>
+    <FieldGroup errorEl={errorEl} reserve={reserve}>
       <FloatingField className={className} htmlFor={fieldId} label={label} srOnlyLabel={asDisplay}>
         <input
           ref={ref}
@@ -2001,10 +2052,11 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
 // height the caller's type brings with it.
 const SELECT_SM = "h-7 py-0 ps-2 pe-7 text-xs";
 
-export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(
-  { className, label, id, children, invalid, error, hint, size, selectClassName, ...rest },
-  ref,
-) {
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(props, ref) {
+  const { className, label, id, children, invalid, error, hint, size, selectClassName, ...rest } =
+    props;
+  // See Input's `reserve`.
+  const reserve = "error" in props;
   const generated = useId();
   // Only a number reaches the DOM; the two words are this component's own.
   const nativeSize = typeof size === "number" ? size : undefined;
@@ -2100,7 +2152,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
     // box, as the label line's own hint goes at the end of the label.
     if (hasContent(hint) && !textHint) {
       return (
-        <FieldGroup errorEl={below}>
+        <FieldGroup errorEl={below} reserve={reserve}>
           <div className={cn("flex items-center gap-1.5", className)}>
             <div className="relative min-w-0 flex-1">
               {select}
@@ -2112,7 +2164,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
       );
     }
     return (
-      <FieldGroup errorEl={below}>
+      <FieldGroup errorEl={below} reserve={reserve}>
         <div className={cn("relative", className)}>
           {select}
           {chevron}
@@ -2121,7 +2173,7 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
     );
   }
   return (
-    <FieldGroup errorEl={below}>
+    <FieldGroup errorEl={below} reserve={reserve}>
       <FloatingField className={className} htmlFor={fieldId} label={label} staticLabel hint={textHint ? undefined : hint}>
         <select
           ref={ref}
@@ -2159,10 +2211,10 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
   error?: ReactNode;
 }
 
-export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(
-  { className, label, id, placeholder, invalid, error, ...rest },
-  ref,
-) {
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(props, ref) {
+  const { className, label, id, placeholder, invalid, error, ...rest } = props;
+  // See Input's `reserve`.
+  const reserve = "error" in props;
   const generated = useId();
   const fieldId = id ?? generated;
   const { isInvalid, describedBy, errorEl } = useFieldError(
@@ -2173,7 +2225,7 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
   );
   if (label === undefined) {
     return (
-      <FieldGroup errorEl={errorEl}>
+      <FieldGroup errorEl={errorEl} reserve={reserve}>
         <textarea
           ref={ref}
           id={id}
@@ -2187,7 +2239,7 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
     );
   }
   return (
-    <FieldGroup errorEl={errorEl}>
+    <FieldGroup errorEl={errorEl} reserve={reserve}>
       <FloatingField className={className} htmlFor={fieldId} label={label}>
         <textarea
           ref={ref}
@@ -2269,8 +2321,33 @@ export interface CardProps extends ComponentPropsWithoutRef<"div"> {
    * nor on `inset`, which has no border to make louder (its tone is a fill).
    */
   toneStrength?: "soft" | "strong";
+  /**
+   * Wash the card in the tone's quiet `-bg` surface as well as framing it. A toned
+   * card is a border and a title colour, at either strength — the wash belongs to
+   * `AlertBanner`, the message, not to a card that holds a form — so it stays
+   * off by default. Some tiles want both: keksdose's password / delete-account tile
+   * was `toneFrameClass(tone)` (border AND wash) before 0.16, and after moving to
+   * `toneStrength="strong"` it re-added `bg-[var(--danger-bg)]` by hand. The wash is
+   * layered OVER the card's own `--bg-surface` (as AlertBanner's `elevated` does), so
+   * the dark theme's translucent tints stay a card, not a hole to the page below.
+   *
+   * No effect without `tone`, nor on `inset`, whose tone is already the fill.
+   */
+  toneFill?: boolean;
+  /**
+   * The parts' type scale. `"compact"`: CardTitle `text-sm font-medium`,
+   * CardDescription `text-xs` and the CardHeader's title-to-description gap
+   * `gap-0.5` — the small settings / admin card. keksdose wrote those three classes by
+   * hand on ~25 cards. Set here, they reach the parts through context; a class on a
+   * part still wins, and a Card nested inside starts again from its own density.
+   *
+   * Default `"comfortable"`: the parts as they have always been.
+   */
+  density?: CardDensity;
 }
 
+export type CardDensity = "comfortable" | "compact";
+
 export type CardTone = "warning" | "danger" | "info" | "success";
 
 // The title is reached through its `data-slot`, so the tone needs no context and a
@@ -2312,6 +2389,16 @@ const CARD_PADDING_STRONG: Record<NonNullable<CardProps["padding"]>, string> = {
   md: "p-[15px]",
 };
 
+// The wash as a background IMAGE over the card's opaque `--bg-surface` — see
+// `toneFill`. A plain `bg-[var(--danger-bg)]` would REPLACE the surface, and the dark
+// theme's washes are a translucent tint.
+const CARD_TONE_WASH: Record<CardTone, string> = {
+  warning: "bg-[image:linear-gradient(var(--warning-bg),var(--warning-bg))]",
+  danger: "bg-[image:linear-gradient(var(--danger-bg),var(--danger-bg))]",
+  info: "bg-[image:linear-gradient(var(--info-bg),var(--info-bg))]",
+  success: "bg-[image:linear-gradient(var(--success-bg),var(--success-bg))]",
+};
+
 const CARD_TONES_STRONG: Record<CardTone, string> = {
   warning: "border-2 border-[var(--warning)]",
   danger: "border-2 border-[var(--danger-border-strong)]",
@@ -2326,6 +2413,9 @@ const CARD_TONES_STRONG: Record<CardTone, string> = {
  */
 const CardPaddedContext = createContext(false);
 
+/** The {@link CardProps.density} of the nearest Card — the parts' type scale. */
+const CardDensityContext = createContext<CardDensity>("comfortable");
+
 export function Card({
   className,
   children,
@@ -2333,6 +2423,8 @@ export function Card({
   variant = "default",
   tone,
   toneStrength = "soft",
+  toneFill = false,
+  density = "comfortable",
   padding,
   ...rest
 }: CardProps) {
@@ -2347,6 +2439,7 @@ export function Card({
     <div
       data-tone={tone}
       data-tone-strength={strong ? "strong" : undefined}
+      data-density={density === "compact" ? "compact" : undefined}
       {...rest}
       className={cn(
         variant === "inset"
@@ -2365,12 +2458,15 @@ export function Card({
             ),
         toned && (bordered ? toned.border : toned.fill),
         strong && tone && CARD_TONES_STRONG[tone],
+        toneFill && bordered && tone && CARD_TONE_WASH[tone],
         toned?.title,
         ownPadding && (strong ? CARD_PADDING_STRONG : CARD_PADDING)[ownPadding],
         className,
       )}
     >
-      <CardPaddedContext.Provider value={ownPadding !== undefined}>{children}</CardPaddedContext.Provider>
+      <CardPaddedContext.Provider value={ownPadding !== undefined}>
+        <CardDensityContext.Provider value={density}>{children}</CardDensityContext.Provider>
+      </CardPaddedContext.Provider>
     </div>
   );
 }
@@ -2415,6 +2511,7 @@ export type CardFooterProps = ComponentPropsWithoutRef<"div">;
 
 export function CardHeader({ className, stackAction = false, ...props }: CardHeaderProps) {
   const padded = useContext(CardPaddedContext);
+  const compact = useContext(CardDensityContext) === "compact";
   return (
     <div
       data-slot="card-header"
@@ -2433,6 +2530,7 @@ export function CardHeader({ className, stackAction = false, ...props }: CardHea
         // never inherits an ancestor header's two columns.
         "grid auto-rows-min items-start gap-1.5 [--card-header-cols:1fr] has-data-[slot=card-action]:[--card-header-cols:1fr_auto] grid-cols-[var(--card-header-cols,1fr)]",
         padded ? "px-0 pt-0" : "px-6 pt-6",
+        compact && "gap-0.5",
         // One column under `sm`, and the action back into the flow (DOM order, so
         // after the description when it is written after it), at the start edge.
         // The descendant selector outranks CardAction's own placement classes.
@@ -2446,10 +2544,23 @@ export function CardHeader({ className, stackAction = false, ...props }: CardHea
 }
 
 export function CardTitle({ className, as: Tag = "div", ...props }: CardTitleProps) {
-  return <Tag data-slot="card-title" className={cn("font-semibold leading-none", className)} {...props} />;
+  const compact = useContext(CardDensityContext) === "compact";
+  return (
+    <Tag
+      data-slot="card-title"
+      // Compact is `leading-snug`, not `leading-none`: there the title sits on a
+      // 12px description `gap-0.5` below, and a line box exactly the cap height left
+      // the hint hugging the title's descenders (every keksdose admin card added
+      // `leading-normal` by hand). Comfortable keeps `leading-none` — its 14px
+      // description is `gap-1.5` away and has always read right.
+      className={cn(compact ? "text-sm font-medium leading-snug" : "font-semibold leading-none", className)}
+      {...props}
+    />
+  );
 }
 
 export function CardDescription({ className, ...props }: CardDescriptionProps) {
+  const compact = useContext(CardDensityContext) === "compact";
   return (
     <div
       data-slot="card-description"
@@ -2457,7 +2568,7 @@ export function CardDescription({ className, ...props }: CardDescriptionProps) {
       // field captions). It was `--money-neutral`, a MONEY token that happened to be
       // a similar grey — and a palette that re-tunes the money colours moved every
       // card's description with them.
-      className={cn("text-sm text-[var(--text-muted)]", className)}
+      className={cn(compact ? "text-xs" : "text-sm", "text-[var(--text-muted)]", className)}
       {...props}
     />
   );

package/src/components/write-lock.tsx

@@ -0,0 +1,96 @@
+import { createContext, useContext, useMemo } from "react";
+import type { ReactNode } from "react";
+import { useKitLabels } from "../i18n/kit-labels";
+
+/** The words {@link WriteLockProvider} renders on its own behalf. */
+export interface WriteLockLabels {
+  /** The tooltip of a locked commit when the provider gives no `reason`. */
+  reason: string;
+}
+
+export const DEFAULT_WRITE_LOCK_LABELS: WriteLockLabels = {
+  reason: "You can view this but not change it.",
+};
+
+/** What {@link useWriteLock} returns: whether commits are locked here, and why. */
+export interface WriteLock {
+  locked: boolean;
+  /** The one sentence a locked commit shows in its tooltip. Always set while
+   *  `locked`; `undefined` when not. */
+  reason: ReactNode | undefined;
+}
+
+const UNLOCKED: WriteLock = { locked: false, reason: undefined };
+
+const WriteLockContext = createContext<WriteLock>(UNLOCKED);
+
+export interface WriteLockProviderProps {
+  /** Commits below are locked. `false` unlocks a subtree under an outer lock. */
+  locked: boolean;
+  /**
+   * The one sentence that says why — "Shared with you to read", "Read-only demo —
+   * saving is disabled", "A customer account cannot create curves". The app's policy,
+   * already translated. Left out: `labels.reason`.
+   */
+  reason?: ReactNode;
+  labels?: Partial<WriteLockLabels>;
+  children?: ReactNode;
+}
+
+/**
+ * The read-only lock — **everything renders; only the commit is locked.**
+ *
+ * keksdose (features/budgets/write-lock.tsx, the read-only demo budget) and
+ * Kurvenschmiede (features/sharing/write-lock.tsx, a curve shared to view, a customer
+ * account that owns nothing) each built the same `SaveGuard`: the page, its tabs,
+ * forms and dialogs render exactly as for an owner, because a viewer looking at half
+ * a page is not looking at what they were sent; what changes is that the control
+ * that SAVES is off and says why on hover or focus. Both wrapped each Save in a
+ * Tooltip and forced a native `disabled` on it — out of the tab order, so the reason
+ * never reached a keyboard — and both had to remember it at thirty call sites.
+ *
+ * Here the page mounts one provider and each commit control opts in with `commit`
+ * ({@link Button}, {@link IconButton}, {@link FormActions}): under a lock it takes the
+ * kit's `disabledReason` path with this reason — `aria-disabled` and focusable,
+ * every activation swallowed, the reason in the kit Tooltip and its description.
+ *
+ * Who is locked is the app's: the provider takes a boolean, never a role. Fields stay
+ * editable — nothing in them reaches the server until the commit is pressed, and a
+ * form you cannot fill in is not a demo of the form (keksdose accounts-page). A
+ * control that IS its own commit (a toggle that saves on change) reads
+ * {@link useWriteLock} and disables itself. The lock is a courtesy, not a guard: the
+ * server still refuses the write.
+ *
+ * Nested providers: the nearest wins, so an inner `locked={false}` reopens a section
+ * the caller may write (a viewer's own notes on a shared curve), and an inner lock
+ * with its own reason (Kurvenschmiede's owner lock beside the viewer lock) overrides
+ * the outer one's sentence.
+ */
+export function WriteLockProvider({ locked, reason, labels, children }: WriteLockProviderProps) {
+  // The `writeLock` namespace: prop > `<UiKitProvider labels>` > English.
+  const fallback = useKitLabels("writeLock", DEFAULT_WRITE_LOCK_LABELS, labels).reason;
+  // `null`/`""`/`false` count as "no reason given": a lock whose tooltip is empty
+  // would be a disabled button that cannot say why, the thing this replaces.
+  const given = reason !== undefined && reason !== null && reason !== false && reason !== "";
+  const resolved = locked ? (given ? reason : fallback) : undefined;
+  const value = useMemo<WriteLock>(
+    () => (locked ? { locked: true, reason: resolved } : UNLOCKED),
+    [locked, resolved],
+  );
+  return <WriteLockContext.Provider value={value}>{children}</WriteLockContext.Provider>;
+}
+
+/** The nearest {@link WriteLockProvider}'s lock; unlocked with no provider. */
+export function useWriteLock(): WriteLock {
+  return useContext(WriteLockContext);
+}
+
+/**
+ * The `disabledReason` a control with `commit` should use: the lock's reason while
+ * locked — it wins over the control's own, since it is the answer to the question the
+ * hover is asking — else the control's own. Internal to the kit's commit controls.
+ */
+export function useCommitReason(commit: boolean | undefined, own: ReactNode): ReactNode {
+  const lock = useWriteLock();
+  return commit && lock.locked ? lock.reason : own;
+}