@eifi1/ui-kit 0.12.0 → 0.13.0

package/src/components/text-link.tsx

@@ -60,6 +60,58 @@ export function pickLinkRenderer<P>(
   return kitLink as unknown as (props: P) => ReactElement;
 }
 
+/** The plain primary click a page navigates on — not a middle click, not ⌘ / Ctrl /
+ *  Shift / Alt (new tab, new window, download), and not one a handler already took. */
+function isPlainNavigationClick(event: MouseEvent<HTMLAnchorElement>): boolean {
+  return (
+    !event.defaultPrevented &&
+    event.button === 0 &&
+    !event.metaKey &&
+    !event.ctrlKey &&
+    !event.shiftKey &&
+    !event.altKey
+  );
+}
+
+/**
+ * The `onClick` of a PLAIN `<a>` whose kit link was asked to `replace` (keksdose F1).
+ *
+ * A router link replaces the history entry itself (it is handed `replace`, see
+ * {@link routerLinkNavigation}); a plain `<a>` has no attribute that says so, and the
+ * browser's own navigation always pushes. So a plain click is taken over — the caller's
+ * `onClick` runs first and may still `preventDefault` — and becomes
+ * `location.replace(href)`: the same document load, with Back skipping the one-shot URL.
+ * That is the case of `replace` together with `reloadDocument`, or an app with no
+ * `linkComponent`. A modified click (new tab) and a `target` other than `_self` are left
+ * to the browser: they do not navigate THIS history. Without `replace`, `onClick` comes
+ * back untouched.
+ * @internal
+ */
+export function replacingClick(
+  onClick: ((event: MouseEvent<HTMLAnchorElement>) => void) | undefined,
+  href: string,
+  replace: boolean | undefined,
+  target?: string,
+): ((event: MouseEvent<HTMLAnchorElement>) => void) | undefined {
+  if (!replace || (target !== undefined && target !== "" && target !== "_self")) return onClick;
+  return (event) => {
+    onClick?.(event);
+    if (!isPlainNavigationClick(event)) return;
+    event.preventDefault();
+    window.location.replace(href);
+  };
+}
+
+/**
+ * What a ROUTER link is handed for `replace`: `{ replace: true }` when asked, else
+ * nothing at all — so a provider link that spreads its props onto a DOM `<a>` never
+ * receives an unknown attribute from a link that did not ask (see `KitLinkProps.replace`).
+ * @internal
+ */
+export function routerLinkNavigation(replace: boolean | undefined): { replace?: true } {
+  return replace ? { replace: true } : {};
+}
+
 /**
  * Draws `props` through `render` as a component of its own, so a router link's hooks
  * belong to it and not to the kit component calling it — for the kit components that
@@ -72,14 +124,33 @@ export function RenderedKitLink<P>({ render, props }: { render: (props: P) => Re
 
 /* ── TextLink ─────────────────────────────────────────────────────────────── */
 
-/** `brand` (default) for a link in running text, `muted` for footer and meta links
- *  that should not compete with the content, `danger` for a destructive one ("Leave
- *  group"), `inherit` for a link that takes its surroundings' colour. */
-export type TextLinkTone = "brand" | "muted" | "danger" | "inherit";
+/**
+ * `brand` (default) for a link in running text, `muted` for footer and meta links
+ * that should not compete with the content, `danger` for a destructive one ("Leave
+ * group"), `inherit` for a link that takes its surroundings' colour.
+ *
+ * `primary` and `secondary` are the body and the secondary text colour, UNDERLINED
+ * (keksdose F3): a link that must read as part of the text around it — a name in a
+ * list row, a reference in a card's meta line — where `brand` repaints it in the accent
+ * and `muted` is a step too light to read as content. `secondary` darkens to the body
+ * colour under the pointer, as `muted` does; `primary` has nowhere darker to go, so its
+ * underline thickens instead.
+ *
+ * `warning` is the kit's `--warning` text colour, underlined (kastlan 46): a link inside
+ * a `<Tone tone="warning">` sentence or a warning banner, which `brand` would paint in a
+ * second hue and `inherit` would leave indistinguishable from the sentence. Like
+ * `primary`, it keeps its colour on hover and thickens the underline.
+ *
+ * The three colours that sit IN the text default to `underline="always"`: with the
+ * colour of their surroundings, the underline is the only thing that says "link"
+ * (WCAG 1.4.1). An explicit `underline` still wins.
+ */
+export type TextLinkTone = "brand" | "muted" | "danger" | "inherit" | "primary" | "secondary" | "warning";
 
-/** `hover` (default): underlined under the pointer — the idiom all three apps draw.
- *  `always` for a link inside prose, where colour alone must not be the only mark
- *  (WCAG 1.4.1). `none` where the context already says "link" (a footer nav). */
+/** `hover` (the default for `brand`, `muted`, `danger`, `inherit`): underlined under
+ *  the pointer — the idiom all three apps draw. `always` (the default for `primary`,
+ *  `secondary`, `warning`) for a link inside prose, where colour alone must not be the
+ *  only mark (WCAG 1.4.1). `none` where the context already says "link" (a footer nav). */
 export type TextLinkUnderline = "hover" | "always" | "none";
 
 /** The `aria-current` token. `true` on {@link TextLinkProps.current} means `page`. */
@@ -98,6 +169,9 @@ export interface TextLinkRenderProps {
   "aria-current"?: TextLinkCurrent;
   id?: string;
   title?: string;
+  /** Present, as `true`, only when the link was given `replace` — see
+   *  `KitLinkProps.replace`. Map it to your router's replace; never onto a DOM `<a>`. */
+  replace?: boolean;
   [key: `aria-${string}`]: string | boolean | number | undefined;
   [key: `data-${string}`]: unknown;
 }
@@ -108,8 +182,24 @@ export interface TextLinkProps
   children: ReactNode;
   /** Default `brand`. */
   tone?: TextLinkTone;
-  /** Default `hover`. */
+  /** Default `always` for `primary`, `secondary` and `warning`, else `hover`. */
   underline?: TextLinkUnderline;
+  /**
+   * Navigate by replacing the current history entry, so Back does not return to this
+   * URL — keksdose F1, a one-shot URL (a confirmation landing, a `?done=1` hop). Handed
+   * to the router link as `replace` (see `KitLinkProps.replace` for mapping it); on a
+   * plain `<a>` (no `linkComponent`, or `reloadDocument`) a plain click becomes
+   * `location.replace(href)`. Ignored on an `external` link, which opens a new tab.
+   */
+  replace?: boolean;
+  /**
+   * A plain `<a>` for an in-app `href`: the browser loads the whole document instead of
+   * the router swapping the view — keksdose F1, a route served outside the SPA (a file
+   * download, a server-rendered page, a logout that must drop every in-memory cache).
+   * Wins over `renderLink` and the provider's `linkComponent`: it is the caller saying
+   * "not the router" for this one link.
+   */
+  reloadDocument?: boolean;
   /**
    * The link leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`
    * (never the router's), an external-link mark after the text (mirrored in RTL), and
@@ -141,8 +231,15 @@ const TONE: Record<TextLinkTone, string> = {
   muted: "text-[var(--text-muted)] hover:text-[var(--text-primary)]",
   danger: "text-[var(--danger)] hover:text-[var(--danger-hover)]",
   inherit: "",
+  primary: "text-[var(--text-primary)] hover:decoration-2",
+  secondary: "text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
+  warning: "text-[var(--warning)] hover:decoration-2",
 };
 
+/** The tones whose colour is their surroundings' — underlined by default; see
+ *  {@link TextLinkTone}. */
+const UNDERLINED_BY_DEFAULT = new Set<TextLinkTone>(["primary", "secondary", "warning"]);
+
 const UNDERLINE: Record<TextLinkUnderline, string> = {
   hover: "no-underline hover:underline",
   always: "underline",
@@ -168,8 +265,10 @@ export function TextLink({
   href,
   children,
   tone = "brand",
-  underline = "hover",
+  underline: underlineProp,
   external = false,
+  replace,
+  reloadDocument = false,
   stopPropagation = false,
   current,
   icon: Icon,
@@ -182,6 +281,7 @@ export function TextLink({
 }: TextLinkProps) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const kitLink = useKitLink();
+  const underline = underlineProp ?? (UNDERLINED_BY_DEFAULT.has(tone) ? "always" : "hover");
   const ariaCurrent: TextLinkCurrent | undefined =
     current === true ? "page" : current === false ? undefined : current;
 
@@ -208,18 +308,19 @@ export function TextLink({
     </>
   );
 
+  const handleClick: TextLinkRenderProps["onClick"] = stopPropagation
+    ? (event) => {
+        event.stopPropagation();
+        onClick?.(event);
+      }
+    : onClick;
   const props: TextLinkRenderProps = {
     ...(rest as Partial<TextLinkRenderProps>),
     ref,
     href,
     className: look,
     "aria-current": ariaCurrent,
-    onClick: stopPropagation
-      ? (event) => {
-          event.stopPropagation();
-          onClick?.(event);
-        }
-      : onClick,
+    onClick: handleClick,
     onKeyDown: stopPropagation
       ? (event) => {
           if (event.key === "Enter") event.stopPropagation();
@@ -229,11 +330,18 @@ export function TextLink({
     children: body,
   };
 
-  const render = external ? undefined : pickLinkRenderer(renderLink, kitLink, href);
-  if (render) return <RenderedTextLink render={render} {...props} />;
+  const render = external || reloadDocument ? undefined : pickLinkRenderer(renderLink, kitLink, href);
+  if (render) return <RenderedTextLink render={render} {...props} {...routerLinkNavigation(replace)} />;
+  // A plain `<a>` never gets `replace` as an attribute; asked for, it takes the click.
+  const plainClick = external ? handleClick : replacingClick(handleClick, href, replace, rest.target);
   const { children: content, ...anchor } = props;
   return (
-    <a {...anchor} {...(external ? { target: "_blank", rel: "noopener noreferrer" } : null)}>
+    <a
+      {...anchor}
+      href={href}
+      onClick={plainClick}
+      {...(external ? { target: "_blank", rel: "noopener noreferrer" } : null)}
+    >
       {content}
     </a>
   );

package/src/components/text.tsx

@@ -16,6 +16,14 @@ import { cn } from "../lib/cn";
  * (support-thread:153/223) at `text-[11px]` by hand — 10px read as a footnote under a
  * figure that size, 12px competed with it. Named `md` rather than slotted in order
  * because `sm` was already the default and renaming it would move every caller.
+ *
+ * `md` is also the heading over a CHART COLUMN (lenkbank P9): the small label centred
+ * over each of a pair of facing charts, or over each column of a small-multiples grid.
+ * There the label names a plot, not a section of the page, so `sm` (12px, the page's
+ * section heading) out-ranks the card title above it, and `xs` (10px, a legend's
+ * title) sinks below the axis ticks it sits beside. Rule of thumb: `xs` inside a
+ * control (legend, menu), `md` over a figure or a plot, `sm` over a block of page
+ * content.
  */
 export type SectionLabelSize = "xs" | "md" | "sm";
 
@@ -34,6 +42,31 @@ export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
   sm: "text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]",
 };
 
+/**
+ * `plain` (default): the label alone, as above.
+ *
+ * `band` (0.13, keksdose F5): the label on a full-width `surface-2` bar with a bottom
+ * border — the day-group header of keksdose's mobile transaction list
+ * (mobile-transaction-list.tsx:171), which separates one day's rows from the next.
+ * Its type is kept as keksdose drew it — `font-medium` in the SECONDARY text colour,
+ * not the plain label's semibold muted — so adopting the kit does not restyle a live
+ * list: the bar already sets the label apart, and needs no extra weight. The padding (`px-4 py-2`) lines the text up with a
+ * `ListItem density="comfortable"` row below it; override it with `className` for a
+ * list at another density. A sticky header is the caller's: add `sticky top-0`.
+ */
+export type SectionLabelVariant = "plain" | "band";
+
+/** The band's own type and box, per size — spelled out rather than merged over
+ *  {@link SECTION_LABEL_CLASS}, so the result does not hang on tailwind-merge telling
+ *  a font-size `text-[…]` from a colour `text-[var(…)]`. */
+const SECTION_LABEL_BAND_CLASS: Record<SectionLabelSize, string> = {
+  xs: "text-[10px]",
+  md: "text-[11px]",
+  sm: "text-xs",
+};
+const BAND =
+  "block border-b border-[var(--border)] bg-[var(--bg-surface-2)] px-4 py-2 font-medium uppercase tracking-wide text-[var(--text-secondary)]";
+
 type SectionLabelElement = "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "div" | "legend";
 
 export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
@@ -45,6 +78,9 @@ export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
    */
   as?: SectionLabelElement;
   size?: SectionLabelSize;
+  /** `band` draws the label on a `surface-2` bar with a bottom border — a list's group
+   *  header. See {@link SectionLabelVariant}. */
+  variant?: SectionLabelVariant;
   children: ReactNode;
 }
 
@@ -55,10 +91,18 @@ export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
  * 10px version on a menu row. One component, the token colour, and the level chosen
  * where the outline is known.
  */
-export function SectionLabel({ as = "h3", size = "sm", className, children, ...rest }: SectionLabelProps) {
+export function SectionLabel({
+  as = "h3",
+  size = "sm",
+  variant = "plain",
+  className,
+  children,
+  ...rest
+}: SectionLabelProps) {
   const Tag = as as ElementType;
+  const type = variant === "band" ? cn(SECTION_LABEL_BAND_CLASS[size], BAND) : SECTION_LABEL_CLASS[size];
   return (
-    <Tag {...rest} className={cn(SECTION_LABEL_CLASS[size], className)}>
+    <Tag {...rest} className={cn(type, className)}>
       {children}
     </Tag>
   );

package/src/components/toggle-group.tsx

@@ -104,6 +104,25 @@ type ToggleGroupCaption<V> = ReactNode | ((value: V) => ReactNode);
 /** The group as it has always been: one option is always the answer. */
 export interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupBaseProps<T> {
   allowEmpty?: false;
+  /**
+   * What the options ARE to a screen reader, separately from whether the group can be
+   * emptied (kastlan feedback #47).
+   *
+   *  - `"radio"` (default) — a `radiogroup` of radios: one Tab stop, arrow keys MOVE the
+   *    choice. Right for a choice between answers ("Monthly / Yearly").
+   *  - `"pressed"` — a `group` of toggle buttons (`aria-pressed`), each its own Tab stop,
+   *    Space/Enter to press; still one option always pressed. Right for a row that reads
+   *    as a set of switches — a view mode, a toolbar-like filter — where arrows moving the
+   *    selection on focus would be a surprise.
+   *
+   * Before this the only way to `aria-pressed` was `allowEmpty`, which also let a second
+   * press clear the choice — so kastlan took the clearable shape and threw the `null`
+   * away in `onChange` (`(v) => v && setMode(v)`), a group announcing that a press would
+   * unpress what it would not. Here a press on the pressed option re-sends its value, as
+   * the radio shape does, and nothing is ever unpressed. A clearable group
+   * (`allowEmpty`) is always `"pressed"`: a radio cannot be unchecked by activating it.
+   */
+  semantics?: "radio" | "pressed";
   value: T;
   onChange: (value: T) => void;
   /** See {@link ToggleGroupCaption}. */
@@ -122,6 +141,9 @@ export interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupB
  */
 export interface ToggleGroupClearableProps<T extends string> extends ToggleGroupBaseProps<T> {
   allowEmpty: true;
+  /** Always toggle buttons — see {@link ToggleGroupRequiredProps.semantics}. Accepted so
+   *  a wrapper can forward one `semantics` to either shape. */
+  semantics?: "pressed";
   value: T | null;
   onChange: (value: T | null) => void;
   /** See {@link ToggleGroupCaption}. `null` while nothing is chosen. */
@@ -171,7 +193,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   const hasError = labelled && error !== undefined && error !== null && error !== false && error !== "";
   // Taken off the rest so neither reaches the DOM; `props` keeps them paired, which is
   // what lets the `onChange` below be called with `null` only in the mode that allows it.
-  const { allowEmpty: _allowEmpty, onChange: _onChange, caption, ...rest } = restWithMode;
+  const { allowEmpty: _allowEmpty, onChange: _onChange, caption, semantics: _semantics, ...rest } = restWithMode;
   // Invalid from outside too: a `Field` hands the bare group `aria-invalid`, and the
   // border has to say what the attribute says.
   const outsideInvalid = rest["aria-invalid"] === true || rest["aria-invalid"] === "true";
@@ -183,11 +205,14 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
   };
-  const clearable = props.allowEmpty === true;
+  // `pressed`: toggle buttons. Every clearable group is; a required one is when it asks
+  // (kastlan #47) — the role, and not whether a second press clears, is what this flag
+  // decides from here on, so `choose` above still keys off `allowEmpty` alone.
+  const pressed = props.allowEmpty === true || props.semantics === "pressed";
   // A radio group is ONE tab stop (the checked radio, else the first) and arrows move
   // the choice — the pattern `role="radiogroup"` promises a screen-reader user. Before
-  // 0.7.0 each segment was its own tab stop with no arrow keys. The clearable mode is a
-  // row of toggle buttons, where separate tab stops are the pattern.
+  // 0.7.0 each segment was its own tab stop with no arrow keys. The toggle-button shape
+  // is a row of buttons, where separate tab stops are the pattern.
   const tabStop = options.some((o) => o.value === value) ? value : options[0]?.value;
   const onRadioKey = (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
     const last = options.length - 1;
@@ -218,7 +243,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       // radiogroup role or the disabled state by accident. `className` is destructured
       // out entirely and merged through `cn`, so it is never in here.
       {...rest}
-      role={clearable ? "group" : "radiogroup"}
+      role={pressed ? "group" : "radiogroup"}
       // The DOM spelling wins; `ariaLabel` is the fallback for the call sites that
       // have not moved yet.
       aria-label={ariaLabelAttr ?? ariaLabel}
@@ -263,12 +288,12 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           <button
             key={opt.value}
             type="button"
-            role={clearable ? undefined : "radio"}
-            aria-checked={clearable ? undefined : active}
-            aria-pressed={clearable ? active : undefined}
+            role={pressed ? undefined : "radio"}
+            aria-checked={pressed ? undefined : active}
+            aria-pressed={pressed ? active : undefined}
             disabled={disabled}
-            tabIndex={clearable ? undefined : opt.value === tabStop ? 0 : -1}
-            onKeyDown={clearable ? undefined : (e) => onRadioKey(e, index)}
+            tabIndex={pressed ? undefined : opt.value === tabStop ? 0 : -1}
+            onKeyDown={pressed ? undefined : (e) => onRadioKey(e, index)}
             onClick={() => choose(opt.value)}
             className={cn(
               // `truncate` (which carries whitespace-nowrap) rather than letting a

package/src/components/toggle-legend.tsx

@@ -83,6 +83,23 @@ export interface LegendEntry {
    * "today"). Decorative: it is wrapped `aria-hidden`, and the label is the name.
    */
   icon?: ReactNode;
+  /**
+   * `"end"`: push this entry to the legend's inline END — the far right in LTR, the far
+   * left in RTL — with everything before it kept at the start. kastlan's lease gantt
+   * (feedback #49) keys its bars at the start and its "today" hairline at the end, over
+   * the time axis whose end "today" is nearest, and wrote it as
+   * `className="[&>li:last-child]:ms-auto"` — a selector that breaks the moment the
+   * entries are reordered and that reaches into the legend's markup.
+   *
+   * An auto inline-start margin, so it is logical (RTL mirrors it) and it takes only the
+   * row's LEFTOVER space: on a narrow screen where the row wraps, the entry wraps with it
+   * and sits at the end of its own line rather than overflowing. Give it to the LAST
+   * entry — auto margins push everything after them too, so an end entry in the middle
+   * drags the rest over with it (which is also how to end-align a GROUP: mark its first).
+   * In a vertical legend it sits at the column's inline end. Honoured by both
+   * {@link StaticLegend} and {@link ToggleLegend}, which share this entry type.
+   */
+  align?: "start" | "end";
 }
 
 export interface ToggleLegendProps {
@@ -159,6 +176,7 @@ export function ToggleLegend({
               "flex items-center gap-1.5 rounded text-start text-[11px] text-[var(--text-secondary)] transition-opacity hover:opacity-80",
               "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
               off && "opacity-35",
+              entry.align === "end" && "ms-auto",
             )}
           >
             <LegendMark entry={entry} off={off} />
@@ -219,7 +237,10 @@ export function StaticLegend({
       {entries.map((entry) => (
         <li
           key={entry.key}
-          className="flex items-center gap-1.5 text-[11px] text-[var(--text-secondary)]"
+          className={cn(
+            "flex items-center gap-1.5 text-[11px] text-[var(--text-secondary)]",
+            entry.align === "end" && "ms-auto",
+          )}
         >
           <LegendMark entry={entry} off={false} />
           {entry.label}

package/src/components/tooltip.tsx

@@ -87,6 +87,19 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
    * what they were before the default existed.
    */
   portal?: boolean;
+  /**
+   * Mount the IN-PLACE bubble only while it is up (hovered or focused, not dismissed),
+   * instead of always. It still sits next to its trigger and is still placed by CSS
+   * alone; what changes is that, while closed, it is not in the DOM — so it is not in
+   * `getAllByRole("tooltip")`, not in an ancestor's `textContent` and not in an
+   * ancestor's accessible name. The trigger is described (`aria-describedby`) while
+   * the bubble is up, exactly as a portalled one is. See "Lazy in place" on
+   * {@link Tooltip} for why this exists (keksdose F6) and why it is not the default.
+   *
+   * Has no effect on a bubble that is portalled (`portal`, or auto-portalled inside a
+   * clipping container) — that one is already mounted only while up.
+   */
+  lazy?: boolean;
   /** Tag the bubble `data-private`, for a label that repeats the user's own data. */
   redact?: boolean;
   children: ReactNode;
@@ -94,7 +107,7 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
 
 /** What each variant below takes: the resolved `side`, and every span attribute the
  *  caller handed {@link Tooltip}, forwarded to that variant's own wrapper. */
-type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: TooltipSide };
+type TooltipVariantProps = Omit<TooltipProps, "side" | "portal" | "lazy"> & { side: TooltipSide };
 
 /**
  * Hover/focus label for a control.
@@ -170,12 +183,50 @@ type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: Toolt
  * Why not simply portal everything? Because the in-place bubble is the one existing
  * app tests rely on (it is in the DOM without a hover), and because it follows its
  * trigger through a scroll or an animation for free — the portalled one re-measures.
+ *
+ * ⚠️ **Lazy in place: `lazy` keeps the bubble next to its trigger but out of the DOM
+ * until it is up (keksdose F6).** `data-clips` cured the doubled text for tooltips
+ * inside a table; it did nothing for the ones outside any clipping container, where the
+ * always-mounted bubble is still a real `role="tooltip"` node full of text. About seven
+ * keksdose sites — column-header tooltips, a direction toggle, an fx-estimate row, a
+ * FlagBadge, a toast inside a `<button>` — still pinned `portal` for that alone: their
+ * tests found two tooltips with `getAllByRole("tooltip")`, read the label twice in a
+ * `textContent`, or got a button whose accessible name had the bubble's sentence glued
+ * on. `portal` fixed the test and cost the browser the measured, re-positioning bubble
+ * for no reason. `lazy` is the in-place bubble with the portalled one's lifetime: it is
+ * rendered only while hovered or focused (and not dismissed), in the same slot, with the
+ * same classes, so it looks and sits exactly as the default one does when it is up.
+ *
+ * Why unmount rather than hide? Hiding was the other option — keep the bubble mounted
+ * with `hidden` (or `aria-hidden` plus `display: none` until `:hover` / `:focus-within`)
+ * and let `aria-describedby` go on pointing at it, which the accname algorithm allows:
+ * a node referenced directly by `aria-describedby` contributes its text even while
+ * hidden. That would take the bubble out of the role queries and out of an ancestor's
+ * accessible name — but NOT out of `textContent`, which is plain DOM and counts hidden
+ * text too, and `textContent` is one of the three things F6 lists. Only a bubble that
+ * is not there solves all three. The cost is the portalled variant's: the trigger is
+ * described while the bubble is up rather than always. Focusing the trigger IS what
+ * puts it up, and React commits the `aria-describedby` in the same task as that focus
+ * event, so a screen reader landing on the control still hears it; what goes is the description
+ * of a trigger that is read in browse mode without ever being focused.
+ *
+ * Escape still dismisses it — here by unmounting it, which takes it off the screen and
+ * out of the accessibility tree at once — and the next hover or focus brings it back.
+ * There is no fade to lose: neither in-place bubble has ever had a transition, only the
+ * `opacity` switch, so appearing on a state change looks the same as appearing on
+ * `:hover`.
+ *
+ * Why opt-in rather than the new default? Because the always-mounted bubble is the one
+ * existing app tests find without a hover (see above): flipping it would turn every
+ * `getByRole("tooltip")` written against 0.12 into a failure in all three apps at once.
+ * Reach for `lazy` wherever a `portal` was pinned only to keep a test's DOM clean.
  */
 export function Tooltip({
   label,
   side = "top",
   className,
   portal,
+  lazy = false,
   redact = false,
   children,
   ...rest
@@ -208,6 +259,7 @@ export function Tooltip({
       className={className}
       redact={redact}
       detect={portal === undefined}
+      lazy={lazy}
       {...rest}
     >
       {children}
@@ -235,9 +287,10 @@ function InPlaceTooltip({
   className,
   redact,
   detect,
+  lazy,
   children,
   ...rest
-}: TooltipVariantProps & { detect: boolean }) {
+}: TooltipVariantProps & { detect: boolean; lazy: boolean }) {
   const id = useId();
   const triggerRef = useRef<HTMLSpanElement | null>(null);
   const [clipped, setClipped] = useState(false);
@@ -263,6 +316,9 @@ function InPlaceTooltip({
     setClipped(hasClippingAncestor(el));
   };
   return (
+    /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- the handlers track
+       whether the bubble is up and activate nothing; the caller's child is the
+       interactive element, keeps its own handlers, and its focus shows the bubble too. */
     <span
       // `...rest` first: the four handlers below are what decides whether a bubble is
       // up, and a caller passing an `onFocus` of its own must not replace them.
@@ -272,10 +328,6 @@ function InPlaceTooltip({
       // These four track WHETHER A BUBBLE IS UP. They activate nothing — the only thing
       // here that can be activated is the caller's child, which keeps every handler it
       // arrived with — so this wrapper needs no role and no key handling of its own.
-      // `jsx-a11y/no-static-element-interactions` warns about it all the same, as it
-      // already does about the portal variant's identical trigger below; both are left
-      // visible rather than silenced, because a rule this package ratchets should be
-      // argued with in the backlog and not in a disable comment.
       onMouseEnter={(e) => {
         setHovered(true);
         arm(e.currentTarget);
@@ -287,12 +339,28 @@ function InPlaceTooltip({
       }}
       onBlur={() => setFocused(false)}
     >
-      {/* In place the bubble is always there to point at; portalled, only while up. */}
-      {describedBy(children, clipped ? (open ? id : undefined) : dismissed ? undefined : id)}
+      {/* In place the bubble is always there to point at; portalled or lazy, only while up. */}
+      {describedBy(children, clipped || lazy ? (open ? id : undefined) : dismissed ? undefined : id)}
       {clipped ? (
         open && (
           <PortalBubble triggerRef={triggerRef} id={id} label={label} side={side} dir={dir} redact={redact} />
         )
+      ) : lazy ? (
+        // keksdose F6: the in-place slot and classes, the portalled lifetime. Mounted only
+        // while up, so it is visible whenever it exists — `opacity-100` outright rather
+        // than the `group-hover` switch, which would also be right but would make the
+        // bubble's visibility depend on two sources (the state that mounted it and the
+        // CSS that shows it) that can disagree for a frame after Escape.
+        open && (
+          <span
+            id={id}
+            role="tooltip"
+            data-private={redact ? "" : undefined}
+            className={cn(TOOLTIP_SURFACE, "pointer-events-none absolute z-50 opacity-100", sidePositionClass[side])}
+          >
+            {label}
+          </span>
+        )
       ) : (
         <span
           id={id}
@@ -506,6 +574,9 @@ function PortalTooltip({
 
   return (
     <>
+      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- as in
+          `InPlaceTooltip`: the handlers only show and hide the bubble; the caller's child
+          is the interactive element, and focusing it shows the bubble. */}
       <span
         // As in `InPlaceTooltip`: the caller's attributes first, the four handlers that
         // run this component after them. The BUBBLE is deliberately not given them — it