@eifi1/ui-kit 0.13.0 → 0.14.0

package/src/components/amount-input.tsx

@@ -158,6 +158,12 @@ interface AmountInputProps {
    * zero (12.345 → 12.35, -12.345 → -12.35) and happens when the figure settles: on
    * blur, on Enter, and on every result the calculator writes back. Keystrokes are left
    * alone, so "12.3" can still become "12.34".
+   *
+   * ⚠️ **A unit price or a rate needs `digits`.** The default is right for an amount of
+   * money and silently wrong for a price per unit: a fund's NAV of 123.4567 or fuel at
+   * 1.789 €/l is stored as 123.46 / 1.79, and no test fails (keksdose G2, a
+   * `Numeric(18,6)` holding price and a `Numeric(18,4)` unit price). Pass the column's
+   * scale: `digits={4}`, `digits={6}`.
    */
   digits?: number;
   /** The smallest amount the field settles on. A lower figure is raised to it when it
@@ -218,6 +224,36 @@ function decimalMark(locale: string | undefined): "," | "." {
   }
 }
 
+/**
+ * Which typed mark is the decimal one (keksdose G1). {@link sanitizeLive} folds every
+ * "," into ".", so on its own it read the German "1.234,56" as 1.23456 — and the
+ * settle then made that 1.23, final. This decides per operand, from the typist's own
+ * text, before that fold:
+ *
+ * - both marks present: the one that is not the locale's is grouping, and goes;
+ * - in a "," locale, only "." present: grouping when it cannot be a decimal as a
+ *   German reader writes it — twice ("1.234.567"), or in thousands shape ("1.234",
+ *   "12.500") — otherwise a decimal ("1.5", typed by a dot-decimal habit);
+ * - in a "." locale, only "," present: grouping when it appears twice ("1,234,567");
+ *   once it stays a decimal, because Swiss and German typists write "1,5" in a
+ *   de-CH form (kastlan 40) and a unit price "1,789" is a decimal.
+ *
+ * Only a keystroke's text comes through here. A calculator result is dot-decimal
+ * already, and "1.234" from `100/81.03…` is never a thousand.
+ */
+function normalizeTypedMarks(raw: string, mark: "," | "."): string {
+  const other = mark === "," ? "." : ",";
+  return raw.replace(/[0-9.,]+/g, (operand) => {
+    const hasMark = operand.includes(mark);
+    const count = operand.split(other).length - 1;
+    if (count === 0) return operand;
+    const grouping = hasMark
+      ? true
+      : count > 1 || (mark === "," && /^\d{1,3}(\.\d{3})+$/.test(operand));
+    return grouping ? operand.split(other).join("") : operand;
+  });
+}
+
 // The consuming app's ONE money palette (`--money-expense` / `--money-income`),
 // not a bespoke rose/emerald pairing: a figure being typed has to wear the same
 // colour the same figure will wear once it is a row in the table behind the form
@@ -310,7 +346,23 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
     // follows `Intl` rather than a guess about a country.
     const locale = useKitLocale();
     const mark = decimalMark(locale);
-    const display = mark === "," ? shown.replace(/\./g, ",") : shown;
+    // While the typist is typing, the field shows THEIR text ("1.234,5" stays exactly
+    // that), not the value re-spelt: re-spelling turned a grouping "." into a "," under
+    // their fingers, after which no rule could tell the two apart (keksdose G1). The
+    // draft is shown only while it still spells what the field holds; a value set from
+    // outside, a calculator result or a commit falls back to the derived spelling.
+    const [draft, setDraft] = useState<string | null>(null);
+    const derived = mark === "," ? shown.replace(/\./g, ",") : shown;
+    const draftAs = draft === null ? "" : sanitizeLive(normalizeTypedMarks(draft, mark));
+    const display =
+      draft === null
+        ? derived
+        : draftAs === shown
+          ? draft
+          : // The caller owns the sign: the typed "12" is shown as the "-12" it is.
+            signOwned && negative && `-${draftAs}` === shown
+            ? `-${draft}`
+            : derived;
     // Every route into the field — typing, the numpad sheet, the desktop
     // calculator, the blur/Enter commit — funnels through here, so the split is
     // written once and the four entry paths cannot drift.
@@ -345,7 +397,14 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
       }
       onChange(sign ? rest : text);
     };
-    const commit = () => handleText(settle(commitExpression(shown)));
+    const commit = () => {
+      setDraft(null);
+      handleText(settle(commitExpression(shown)));
+    };
+    const typed = (raw: string) => {
+      setDraft(raw);
+      handleText(normalizeTypedMarks(raw, mark));
+    };
     const { open, setOpen, wrapperRef, panelRef, query, setQuery, inputRef } = useDropdownSearch();
     // The chip the currency list hangs off (Keksdose dev#548). It is portalled now, so
     // the panel needs a real trigger rect rather than a relative parent — see
@@ -404,7 +463,7 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
           // only the app knows the locale's decimal separator.
           placeholder={asDisplay ? (placeholder ?? "0") : label !== undefined ? " " : placeholder}
           value={display}
-          onChange={(e) => handleText(e.target.value)}
+          onChange={(e) => typed(e.target.value)}
           onFocus={() => setFocused(true)}
           onBlur={() => {
             commit();
@@ -472,7 +531,10 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
               // The mark the field shows, as NumberInput hands its calculator; the
               // evaluator reads either, and its result comes back dot-decimal.
               value={display}
-              onChange={(result, expression) => handleText(settle(result), expression)}
+              onChange={(result, expression) => {
+                setDraft(null);
+                handleText(settle(result), expression);
+              }}
               className="px-1.5"
               ariaLabel={labels?.calculatorTrigger}
               labels={labels?.calculator}
@@ -554,10 +616,14 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
         </div>
         {showNumpad && (
           <NumberPadSheet
-            // Localised like the field it mirrors; its keys come back through
-            // `sanitizeLive`, so the "." key and a "," both land as a dot.
+            // Localised like the field it mirrors. Keys are typing, read by the
+            // locale's marks like the keyboard's; "=" is a result, dot-decimal.
             value={display}
-            onChange={handleText}
+            onChange={typed}
+            onResult={(result) => {
+              setDraft(null);
+              handleText(result);
+            }}
             onDone={() => innerRef.current?.blur()}
             label={label}
             labels={labels?.pad}

package/src/components/error-boundary.tsx

@@ -73,13 +73,29 @@ function read(get: () => unknown): string | undefined {
   }
 }
 
+/** `JSON.stringify` that never throws (a cycle, a BigInt, a hostile getter) and never
+ *  returns more than 500 characters. "" when there is nothing to say. */
+function safeJson(value: unknown): string {
+  try {
+    const json = JSON.stringify(value);
+    if (!json || json === "{}") return "";
+    return json.length > 500 ? `${json.slice(0, 499)}…` : json;
+  } catch {
+    return "";
+  }
+}
+
 /** {@link ErrorBoundaryDetails} of any thrown value, without ever throwing. */
 export function describeThrown(error: unknown): ErrorBoundaryDetails {
   if (typeof error === "object" && error !== null) {
     const e = error as { name?: unknown; message?: unknown; stack?: unknown };
+    const message = read(() => e.message) ?? "";
     return {
       name: read(() => e.name) ?? "Error",
-      message: read(() => e.message) ?? "",
+      // `throw { code: 500 }` has no message, and an empty line leaves crash triage with
+      // nothing (keksdose G3a; its old reporter filed `{"code":500}`). Such a value is
+      // quoted as JSON instead, capped, and never at the cost of a throw.
+      message: message || (error instanceof Error ? "" : safeJson(error)),
       stack: read(() => e.stack),
     };
   }
@@ -135,6 +151,9 @@ export interface CrashReport {
   userAgent: string;
   /** The boundary's `appVersion` prop. */
   appVersion?: string;
+  /** The boundary's `placement` prop ("app", "page", "widget"): which boundary caught
+   *  it, so triage can tell a whole-app crash from one page's (keksdose G3b). */
+  placement?: string;
   /** `navigator.onLine` at the moment of the crash; left out where there is none. */
   online?: boolean;
   /** {@link isChunkLoadError} of the thrown value. Such a crash is never handed to
@@ -161,6 +180,7 @@ export function formatCrashReport(report: CrashReport): string {
     `User agent: ${report.userAgent}`,
   ];
   if (report.appVersion) lines.push(`App version: ${report.appVersion}`);
+  if (report.placement) lines.push(`Placement: ${report.placement}`);
   if (report.online === false) lines.push("Online: no");
   for (const [key, value] of Object.entries(report.extras)) lines.push(`${key}: ${value}`);
   if (report.stack) lines.push("", "Stack:", report.stack.trim());
@@ -178,9 +198,14 @@ export function formatCrashReport(report: CrashReport): string {
  * times a second. The page and the time are left out on purpose: the same bug on two
  * routes is still one bug.
  */
-export function crashFingerprint(report: Pick<CrashReport, "name" | "message" | "stack">): string {
+export function crashFingerprint(
+  report: Pick<CrashReport, "name" | "message" | "stack"> & Pick<Partial<CrashReport>, "placement">,
+): string {
   const frames = (report.stack ?? "").split("\n").slice(0, 4).join("|");
-  return `${report.name}::${report.message}::${frames}`;
+  // The placement is part of it (keksdose G3b): the same error caught by the page
+  // boundary and, after Try again fails, by the app boundary is two facts for triage.
+  const where = report.placement ? `${report.placement}::` : "";
+  return `${where}${report.name}::${report.message}::${frames}`;
 }
 
 /**
@@ -305,6 +330,10 @@ export interface ErrorBoundaryProps {
   copyReport?: boolean;
   /** The app's version, printed in the report — the first question on every crash. */
   appVersion?: string;
+  /** Which boundary this is — "app" at the root, "page" in the layout — carried into
+   *  the report (`placement`) and its fingerprint, so `onReport` needs no closure to say
+   *  where the crash was caught (keksdose G3b). */
+  placement?: string;
   /** More `key: value` lines for the report, read when the boundary catches (a tenant
    *  id, the feature flags). A throw from it is swallowed and the lines are left out. */
   reportExtras?: () => Record<string, string>;
@@ -411,6 +440,7 @@ function buildReport(details: ErrorBoundaryDetails, componentStack: string | und
     time: new Date().toISOString(),
     userAgent,
     appVersion: props.appVersion,
+    placement: props.placement,
     online,
     chunkLoad: isChunkLoadError(details),
     extras,

package/src/components/numpad-sheet.tsx

@@ -100,15 +100,20 @@ export function NumberPadSheet({
   label,
   labels,
   decimalMark = ".",
+  onResult,
 }: {
   value: string;
   /** Fired with the raw (sanitised) field text on every key — same contract as
    * the host field's own `onChange`. */
   onChange: (value: string) => void;
   /** The glyph on the decimal key — "," where the host shows a comma (AmountInput
-   *  in fr-CH, kastlan 40). The key still inserts a dot; the host's text is dot-form
-   *  underneath and `sanitizeLive` reads either. */
+   *  in fr-CH, kastlan 40). With "," the key inserts a comma and the text is handed
+   *  back unsanitized, for the host to read by its locale (keksdose G1). */
   decimalMark?: "." | ",";
+  /** "=": the evaluated result, dot-decimal. Default `onChange`. A host that reads
+   *  typed text by the locale's marks takes it apart from keystrokes, since a result
+   *  like "1.234" is a decimal and never a grouped thousand. */
+  onResult?: (value: string) => void;
   /** Fired on "Done": the host blurs the input, which commits (evaluates) and
    * unmounts the sheet via its existing blur handler. */
   onDone: () => void;
@@ -185,11 +190,15 @@ export function NumberPadSheet({
   const result = evaluateExpression(value);
   const preview = result !== null && formatResult(result) !== value.trim() ? `= ${formatResult(result)}` : "";
 
-  const insert = (ch: string) => onChange(sanitizeLive(value + ch));
+  // With a "," mark the host keeps the typist's own text (AmountInput, keksdose G1):
+  // the key inserts the comma it shows, and the host, not this pad, decides which mark
+  // is the decimal one — sanitizing here would fold a grouping "." into a decimal.
+  const insert = (ch: string) =>
+    onChange(decimalMark === "," ? value + (ch === "." ? "," : ch) : sanitizeLive(value + ch));
   const backspace = () => onChange(value.slice(0, -1));
   const clearAll = () => onChange("");
   const equals = () => {
-    if (result !== null) onChange(formatResult(result));
+    if (result !== null) (onResult ?? onChange)(formatResult(result));
   };
 
   const sheet = (

package/src/components/page-header.tsx

@@ -34,6 +34,21 @@ const ROW: Record<PageHeaderMobileLayout, string> = {
   inline: "flex-row items-center justify-between gap-2 sm:gap-4",
 };
 
+/**
+ * Where the actions sit on the title block's height, in the one row the header is from
+ * `sm` up (and on a phone too when {@link PageHeaderMobileLayout} is `inline`, the only
+ * layout that has a row there). Unset keeps each layout's own: `start` for `stacked`,
+ * `center` for `inline`.
+ */
+export type PageHeaderActionsAlign = "start" | "center" | "end";
+
+/** Per layout, because `stacked` is a column on a phone — a `self-center` there would
+ *  centre the actions HORIZONTALLY — so it only aligns from `sm` up. */
+const ACTIONS_ALIGN: Record<PageHeaderMobileLayout, Record<PageHeaderActionsAlign, string>> = {
+  stacked: { start: "sm:self-start", center: "sm:self-center", end: "sm:self-end" },
+  inline: { start: "self-start", center: "self-center", end: "self-end" },
+};
+
 export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
   title: ReactNode;
   /** A sentence under the title. */
@@ -63,6 +78,52 @@ export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * button, a month picker); a long title wraps to make room for them instead.
    */
   mobileLayout?: PageHeaderMobileLayout;
+  /**
+   * A second group of actions that gets its OWN full-width row under the header on a
+   * phone, and joins the actions' row from `sm` up, between the title and
+   * {@link actions}.
+   *
+   * keksdose's budget page (budget-page.tsx, feedback #60) is the case: title and month
+   * navigation on row 1, the fold/unfold toggles on row 2 on a phone — "two tidy rows
+   * instead of the old ragged justify-between overflow" — and one row, title | toggles |
+   * month nav, on a wider screen. It builds that by hand with a wrapping flex row and
+   * swapped order utilities; adopting `PageHeader` (keksdose G6b) must not lose it.
+   * There: `actions` is the month navigation, this is the toggles.
+   *
+   * The DOM order is title, `actions`, `secondaryActions` — the phone's visual order,
+   * and the one a screen reader and the Tab key follow at every width. From `sm` up the
+   * two groups swap places visually only, which keeps the page's primary control (the
+   * month) at the row's end, where keksdose had it, and first in reading order. The
+   * breakpoint is `sm`, the one {@link mobileLayout} switches at, not keksdose's `md`:
+   * one header, one breakpoint.
+   */
+  secondaryActions?: ReactNode;
+  /**
+   * The actions' vertical alignment against the title block — see
+   * {@link PageHeaderActionsAlign}. Unset keeps the layout's own.
+   *
+   * keksdose's reports page (reports-page.tsx, keksdose G8) carries a LABELLED
+   * `CurrencySelect` as its action: a field with its label on top is taller than the
+   * title, and `stacked`'s default top alignment hangs it from the title's cap height
+   * with its control well below the title's line. `center` sets it on the title's
+   * middle, as that page's hand-written `items-center` row did.
+   */
+  actionsAlign?: PageHeaderActionsAlign;
+  /**
+   * One line, cut with an ellipsis, instead of the default breaking of a long word onto
+   * as many lines as it needs.
+   *
+   * keksdose's payees page (payees-page.tsx, live #263, keksdose G6a) wraps its title in
+   * its own truncating span so a long name gives way to the `inline` header's actions
+   * instead of pushing them. This is that span's behaviour on the heading itself; the
+   * title block is already allowed to shrink below its content, which is what lets the
+   * cut happen inside a flex row.
+   *
+   * The full title stays in the DOM as the heading's text, so a screen reader and the
+   * document outline read all of it. There is deliberately no native `title` tooltip:
+   * the kit does not use them (not on touch, not on keyboard focus, not styled).
+   */
+  truncateTitle?: boolean;
 }
 
 /**
@@ -85,20 +146,54 @@ export function PageHeader({
   as = "h1",
   size = "md",
   mobileLayout = "stacked",
+  secondaryActions,
+  actionsAlign,
+  truncateTitle = false,
   className,
   ...rest
 }: PageHeaderProps) {
   const Heading = as as ElementType;
+  const hasSecondary = secondaryActions != null;
+  const wrapsSecondary = hasSecondary && mobileLayout === "inline";
+  const align = actionsAlign != null ? ACTIONS_ALIGN[mobileLayout][actionsAlign] : undefined;
   return (
     <div {...rest} className={cn("flex min-w-0 flex-col gap-2", className)}>
       {breadcrumbs}
-      <div className={cn("flex min-w-0", ROW[mobileLayout])}>
+      {/* With a second group, `inline` wraps so that group's full-width basis puts it
+          on a row of its own on a phone (`stacked` is a column there already, and a
+          basis would size a column item's HEIGHT); from `sm` up the row stops wrapping
+          and the order utilities seat it between the title and the actions. Without
+          one, nothing changes. */}
+      <div className={cn("flex min-w-0", ROW[mobileLayout], wrapsSecondary && "flex-wrap sm:flex-nowrap")}>
         <div className="min-w-0 flex-1">
           {eyebrow != null && <p className={cn(SECTION_LABEL_CLASS.xs, "mb-1")}>{eyebrow}</p>}
-          <Heading className={cn("break-words text-[var(--text-primary)]", TITLE[size])}>{title}</Heading>
+          <Heading
+            className={cn(
+              truncateTitle ? "truncate" : "break-words",
+              "text-[var(--text-primary)]",
+              TITLE[size],
+            )}
+          >
+            {title}
+          </Heading>
           {description != null && <p className="mt-1 text-sm text-[var(--text-muted)]">{description}</p>}
         </div>
-        {actions != null && <div className="flex shrink-0 flex-wrap items-center gap-2">{actions}</div>}
+        {actions != null && (
+          <div className={cn("flex shrink-0 flex-wrap items-center gap-2", hasSecondary && "sm:order-2", align)}>
+            {actions}
+          </div>
+        )}
+        {hasSecondary && (
+          <div
+            className={cn(
+              "flex flex-wrap items-center gap-2 sm:order-1 sm:shrink-0",
+              wrapsSecondary && "basis-full sm:basis-auto",
+              align,
+            )}
+          >
+            {secondaryActions}
+          </div>
+        )}
       </div>
     </div>
   );

package/src/components/text.tsx

@@ -58,7 +58,8 @@ 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(…)]`. */
+ *  a font-size arbitrary `text-` value from a colour one. (Not spelt out as class
+ *  names here: Tailwind scans comments, and a literal one broke the showcase CSS.) */
 const SECTION_LABEL_BAND_CLASS: Record<SectionLabelSize, string> = {
   xs: "text-[10px]",
   md: "text-[11px]",

package/src/components/tooltip.tsx

@@ -50,8 +50,11 @@ function physicalSide(side: TooltipSide, dir: Direction): PhysicalSide {
  *  the viewport as well, for narrow screens where 20rem is already most of it.
  *  `side` is a preference rather than an instruction for the PORTALLED variant,
  *  which measures the bubble and turns it round when it would not fit
- *  (Steering Design feedback #126). The CSS-only one never learns its own size,
- *  so there `side` is still the whole of the placement. */
+ *  (Steering Design feedback #126). The CSS-placed one never turns round, so there
+ *  `side` is still the whole of which side it is on — but since 0.14 it is slid back
+ *  along the cross axis when it would cross the viewport edge (keksdose G7), which the
+ *  viewport term in this cap is what makes possible: a bubble never wider than the glass
+ *  minus the margins always fits once slid. */
 const TOOLTIP_SURFACE =
   "w-max max-w-[min(20rem,calc(100vw-1rem))] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 text-xs font-medium text-[var(--text-primary)] shadow-lg";
 
@@ -220,6 +223,37 @@ type TooltipVariantProps = Omit<TooltipProps, "side" | "portal" | "lazy"> & { si
  * 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.
+ *
+ * ⚠️ **The in-place bubble is clamped to the viewport when it opens (keksdose G7).** The
+ * portalled bubble has always measured itself and been pushed back onto the glass
+ * ({@link placeTooltip}); the in-place one never learnt its own size, so `side` was the
+ * whole of its placement and a `top` / `bottom` bubble sat centred on its trigger
+ * whatever that cost. The cost shows on a phone: long labels live at a row's START edge
+ * — a gcloud command in keksdose's jobs panel, a canned reply in a support thread — and
+ * a 20rem bubble centred on a trigger 16px from the edge hangs half its text off the
+ * screen. keksdose pinned `portal` on those sites for that alone, which gave up `lazy`'s
+ * point (the cheap, in-place bubble) to buy a placement.
+ *
+ * So now, when an in-place bubble goes up (default or `lazy`), a layout effect measures
+ * it and, if it crosses the viewport edge minus the same margin the portalled bubble
+ * keeps, slides it back along its CROSS axis only — sideways for `top` / `bottom`, up or
+ * down for the four side placements — with an inline `transform`, which composes with the
+ * placement classes' own `translate`. The main axis is left alone on purpose: sliding a
+ * `start` bubble along the main axis would slide it over its own trigger, and turning it
+ * round is a measured-placement decision this CSS-placed bubble does not make (pass
+ * `portal` for that). The width is already capped to the viewport (see
+ * `TOOLTIP_SURFACE`), so a bubble can always fit once slid, and a long label wraps
+ * instead of growing past the glass.
+ *
+ * Why on by default, with no prop? Because it is a no-op for every bubble that already
+ * fits — the shift is zero unless the bubble would overflow — so the only placements it
+ * changes are ones that were broken. The maths is in physical viewport pixels, so it
+ * needs no `dir`: an RTL row puts its long label at the RIGHT edge and gets slid left by
+ * the same code. Under jsdom there is no layout — every rect is zero-sized — and a
+ * zero-sized bubble is taken to be unmeasured, so tests see no transform at all. It is
+ * measured on open (and when the label or side changes while open), not on every scroll:
+ * an in-place bubble follows its trigger for free, and a page that scrolls sideways under
+ * an open tooltip is not a case worth a listener per tooltip.
  */
 export function Tooltip({
   label,
@@ -300,6 +334,10 @@ function InPlaceTooltip({
   const [dir, setDir] = useState<Direction>("ltr");
   const open = (hovered || focused) && !dismissed;
   useEscapeKey(() => setDismissed(true), open);
+  // keksdose G7: slide an open in-place bubble back onto the screen. See "The in-place
+  // bubble is clamped" on {@link Tooltip}.
+  const bubbleRef = useRef<HTMLSpanElement | null>(null);
+  const shift = useViewportClamp(bubbleRef, open && !clipped, side, label);
   // At mount, before the first paint: the in-place bubble inside a scroller is the
   // phantom-scroll bug whether or not anyone opens it.
   useLayoutEffect(() => {
@@ -353,9 +391,11 @@ function InPlaceTooltip({
         // CSS that shows it) that can disagree for a frame after Escape.
         open && (
           <span
+            ref={bubbleRef}
             id={id}
             role="tooltip"
             data-private={redact ? "" : undefined}
+            style={shiftStyle(shift)}
             className={cn(TOOLTIP_SURFACE, "pointer-events-none absolute z-50 opacity-100", sidePositionClass[side])}
           >
             {label}
@@ -363,8 +403,10 @@ function InPlaceTooltip({
         )
       ) : (
         <span
+          ref={bubbleRef}
           id={id}
           role="tooltip"
+          style={shiftStyle(shift)}
           // The `hidden` ATTRIBUTE, not an opacity class: dismissing has to take the
           // bubble out of the accessibility tree as well as off the screen, or a screen
           // reader still reads out the description of a bubble the user just closed.
@@ -413,6 +455,71 @@ const TOOLTIP_GAP = 4;
  *  against the glass reads as clipped even when every character is on screen. */
 const TOOLTIP_MARGIN = 4;
 
+/** A cross-axis slide, in viewport pixels, for an in-place bubble. */
+interface Shift {
+  x: number;
+  y: number;
+}
+
+const NO_SHIFT: Shift = { x: 0, y: 0 };
+
+/** How far to slide the span `[low, high]` so it sits inside `[TOOLTIP_MARGIN,
+ *  extent - TOOLTIP_MARGIN]`. Zero when it already does. The start edge wins when the
+ *  span is wider than the room — as in {@link clamp}, the start of a label is the half
+ *  worth keeping (and the width cap means that only happens on a viewport narrower than
+ *  twice the margin). */
+function slideInto(low: number, high: number, extent: number): number {
+  if (low < TOOLTIP_MARGIN) return TOOLTIP_MARGIN - low;
+  if (high > extent - TOOLTIP_MARGIN) return Math.max(extent - TOOLTIP_MARGIN - high, TOOLTIP_MARGIN - low);
+  return 0;
+}
+
+/**
+ * The in-place bubble's viewport clamp (keksdose G7): while `active`, measure the bubble
+ * in a LAYOUT effect — before paint, so there is no frame with the label off the screen —
+ * and return the cross-axis slide that brings it inside the viewport minus
+ * `TOOLTIP_MARGIN`. `top` / `bottom` slide along x; `left` / `right` / `start` / `end`
+ * along y. {@link NO_SHIFT} while closed, so the next open measures the bubble where the
+ * CSS alone puts it.
+ *
+ * The rect it reads already includes the slide it applied last time (a label that
+ * changed while open), so that slide is taken back out before deciding the new one.
+ * A zero-sized rect means no layout (jsdom, `display: none`) and leaves the bubble put.
+ */
+function useViewportClamp(
+  bubbleRef: RefObject<HTMLSpanElement | null>,
+  active: boolean,
+  side: TooltipSide,
+  label: ReactNode,
+): Shift {
+  const [shift, setShift] = useState<Shift>(NO_SHIFT);
+  useLayoutEffect(() => {
+    const el = bubbleRef.current;
+    if (!active || !el) {
+      setShift(NO_SHIFT);
+      return;
+    }
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return;
+    const horizontal = side === "top" || side === "bottom";
+    setShift((previous) => {
+      const next = horizontal
+        ? { x: slideInto(r.left - previous.x, r.right - previous.x, window.innerWidth), y: 0 }
+        : { x: 0, y: slideInto(r.top - previous.y, r.bottom - previous.y, window.innerHeight) };
+      return next.x === previous.x && next.y === previous.y ? previous : next;
+    });
+  }, [bubbleRef, active, side, label]);
+  return shift;
+}
+
+/** The inline style for a slide: none at all when there is nothing to slide, so a bubble
+ *  that fits renders exactly as it did before G7. `transform` rather than `translate`
+ *  because the placement classes own the `translate` property (Tailwind v4's
+ *  `-translate-x-1/2`); the two compose instead of one replacing the other. */
+function shiftStyle(shift: Shift) {
+  return shift.x === 0 && shift.y === 0 ? undefined : { transform: `translate(${shift.x}px, ${shift.y}px)` };
+}
+
 const portalTransformBySide: Record<PhysicalSide, string> = {
   right: "translate(0, -50%)",
   left: "translate(-100%, -50%)",