@eifi1/ui-kit 0.4.1 → 0.5.0

package/dist/components/toggle-legend.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { useKitLabels } from "../i18n/kit-labels.js";
+import { DEFAULT_SERIES_CHART_LABELS } from "./series-chart-labels.js";
+const STROKE_PATTERNS = [
+  void 0,
+  "5 4",
+  "1 3",
+  "9 3 2 3",
+  "9 3 2 3 2 3"
+];
+function strokeDash(order) {
+  const n = STROKE_PATTERNS.length;
+  return STROKE_PATTERNS[(Math.trunc(order) % n + n) % n];
+}
+const STEP_DASH = 1;
+function toggleHidden(hidden, key) {
+  const next = new Set(hidden);
+  if (!next.delete(key)) next.add(key);
+  return next;
+}
+function ToggleLegend({
+  entries,
+  hidden,
+  onToggle,
+  orientation = "horizontal",
+  showSingle = false,
+  className,
+  labels: labelsProp
+}) {
+  const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
+  if (entries.length < (showSingle ? 1 : 2)) return null;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "group",
+      "aria-label": labels.legend,
+      className: cn(
+        "flex gap-x-3 gap-y-1",
+        orientation === "vertical" ? "flex-col items-start justify-center" : "mt-2 flex-wrap items-center",
+        className
+      ),
+      children: entries.map((entry) => {
+        const off = hidden.has(entry.key);
+        return /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            "aria-pressed": !off,
+            onClick: () => onToggle(entry.key),
+            className: cn(
+              "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"
+            ),
+            children: [
+              /* @__PURE__ */ jsx(LegendMark, { entry, off }),
+              entry.label
+            ]
+          },
+          entry.key
+        );
+      })
+    }
+  );
+}
+function LegendColumn({ children, className }) {
+  return /* @__PURE__ */ jsx("div", { className: cn("flex h-full flex-col justify-center gap-3", className), children });
+}
+function LegendGroup({ title, children }) {
+  return /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-col items-start gap-1", children: [
+    /* @__PURE__ */ jsx("span", { className: "text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]", children: title }),
+    /* @__PURE__ */ jsx("div", { className: "flex flex-col items-start gap-y-0.5", children })
+  ] });
+}
+function LegendMark({ entry, off }) {
+  if (entry.marker === "stroke") {
+    return /* @__PURE__ */ jsx("svg", { "aria-hidden": true, viewBox: "0 0 20 2", className: "h-0.5 w-5 shrink-0 overflow-visible", children: /* @__PURE__ */ jsx(
+      "line",
+      {
+        x1: 0,
+        y1: 1,
+        x2: 20,
+        y2: 1,
+        stroke: entry.color,
+        strokeWidth: 2,
+        strokeDasharray: strokeDash(entry.dash ?? 0),
+        opacity: off ? 0.35 : 1
+      }
+    ) });
+  }
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": true,
+      className: "h-2.5 w-2.5 shrink-0 rounded-[3px]",
+      style: {
+        backgroundColor: off ? "transparent" : entry.color,
+        boxShadow: `inset 0 0 0 1.5px ${entry.color}`
+      }
+    }
+  );
+}
+export {
+  LegendColumn,
+  LegendGroup,
+  STEP_DASH,
+  STROKE_PATTERNS,
+  ToggleLegend,
+  strokeDash,
+  toggleHidden
+};
+//# sourceMappingURL=toggle-legend.js.map

package/dist/components/toggle-legend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/toggle-legend.tsx"],"sourcesContent":["// A legend whose entries are SWITCHES — and the stroke table it shares with\n// `SeriesChart`. Lifted out of lenkbank's measurement plots, where ten legends over\n// thirteen charts took channels on and off the picture.\n//\n// No recharts in this module: a legend of switches is plain buttons, and it is as\n// useful under a chart the consumer drew by hand as under `SeriesChart`.\nimport type { ReactNode } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { DEFAULT_SERIES_CHART_LABELS, type SeriesChartLabels } from \"./series-chart-labels\";\n\n/**\n * The strokes a reader can tell apart, in the order they are handed out.\n *\n * For the charts where the colour is already spoken for: a comparison draws each\n * measurement in its own colour, so a chart carrying several CHANNELS of each has\n * nothing left but the stroke — and \"solid versus dashed\" only gets you two.\n *\n * **Five, and the fifth is the last one.** They are the draughtsman's line types, in\n * the draughtsman's order — continuous, dashed, dotted, dash-dot, dash-dot-dot — the\n * one family of five a century of drawings has already proved legible at a hair's\n * width. A sixth is not distinguishable from one of these at two pixels wide, so a\n * chart needing one is a chart that should be split.\n *\n * Kept here, beside the legend's own mark, and read by `SeriesChart` from here — so\n * the key under a chart and the lines on it cannot disagree.\n */\nexport const STROKE_PATTERNS: readonly (string | undefined)[] = [\n  undefined,\n  \"5 4\",\n  \"1 3\",\n  \"9 3 2 3\",\n  \"9 3 2 3 2 3\",\n];\n\n/** The dash array for the nth pattern, wrapping past the fifth. */\nexport function strokeDash(order: number): string | undefined {\n  const n = STROKE_PATTERNS.length;\n  return STROKE_PATTERNS[((Math.trunc(order) % n) + n) % n];\n}\n\n/** Which of the patterns a `step` series is drawn in.\n *\n *  A whole-number channel that jumps rather than travels is drawn dashed, and it has\n *  to be one of {@link STROKE_PATTERNS} rather than a dash array written out at the\n *  call site: a legend entry says its pattern by index, so a step line drawn in\n *  anything else would be a legend promising a solid line for a dashed one. */\nexport const STEP_DASH = 1;\n\n/**\n * One key switched, as a new hidden set.\n *\n * Every caller writes `onToggle={(key) => setHidden(toggleHidden(hidden, key))}`. A\n * new set rather than a mutated one, because the state is read during render and a\n * mutation of something a component already holds is invisible to React.\n */\nexport function toggleHidden(hidden: ReadonlySet<string>, key: string): ReadonlySet<string> {\n  const next = new Set(hidden);\n  if (!next.delete(key)) next.add(key);\n  return next;\n}\n\nexport interface LegendEntry {\n  key: string;\n  label: ReactNode;\n  /** Any CSS colour — `paletteFor(i)` for the kit's own ramp. */\n  color: string;\n  /**\n   * What the entry's mark looks like. `swatch` — a filled square, the default — says\n   * WHICH MEASUREMENT. `stroke` says WHICH QUANTITY, for the charts that carry both at\n   * once and tell them apart by colour and by dash.\n   */\n  marker?: \"swatch\" | \"stroke\";\n  /** Which of {@link STROKE_PATTERNS}, when the marker is a stroke — the same index\n   *  `SeriesChartSeries.dash` takes, so a legend cannot promise a dot-dash the plot\n   *  draws dashed. */\n  dash?: number;\n}\n\nexport interface ToggleLegendProps {\n  entries: LegendEntry[];\n  /** The keys currently off the chart. */\n  hidden: ReadonlySet<string>;\n  onToggle: (key: string) => void;\n  /** `vertical` is for a legend standing BESIDE the charts rather than under them —\n   *  what a row of charts sharing one legend wants, since under two charts there is\n   *  no \"under\", and putting it under one says it belongs to that one. */\n  orientation?: \"horizontal\" | \"vertical\";\n  /**\n   * Draw a legend of ONE entry rather than nothing.\n   *\n   * A single line's legend is usually noise. It is not where the legend is the only\n   * SWITCH that line has — a series that starts hidden and has no entry to bring it\n   * back is gone for good.\n   */\n  showSingle?: boolean;\n  className?: string;\n  /** Per-instance strings over `<UiKitProvider labels={{ seriesChart }}>`. */\n  labels?: Partial<SeriesChartLabels>;\n}\n\n/**\n * A legend whose entries are switches.\n *\n * `ChartLegendContent` with `onItemClick`/`activeKey` is the other kind: clicking an\n * entry HIGHLIGHTS it and dims the rest, which is right when every series belongs on\n * the chart and one of them is momentarily interesting. This is for the opposite —\n * three coordinates on one axis where y runs to 800 and z barely moves, and the only\n * way to see z is to take y off the chart entirely. Any number may be off at once.\n *\n * A hidden entry keeps its mark and its place. Removing it would reflow the legend on\n * every click and lose the one thing it is for: saying what COULD be shown.\n *\n * Each entry is a real `<button>` with `aria-pressed` — pressed means \"on the chart\" —\n * so Tab reaches every switch and Space/Enter flips it.\n */\nexport function ToggleLegend({\n  entries,\n  hidden,\n  onToggle,\n  orientation = \"horizontal\",\n  showSingle = false,\n  className,\n  labels: labelsProp,\n}: ToggleLegendProps) {\n  const labels = useKitLabels(\"seriesChart\", DEFAULT_SERIES_CHART_LABELS, labelsProp);\n  if (entries.length < (showSingle ? 1 : 2)) return null;\n  return (\n    <div\n      role=\"group\"\n      aria-label={labels.legend}\n      className={cn(\n        \"flex gap-x-3 gap-y-1\",\n        orientation === \"vertical\"\n          ? \"flex-col items-start justify-center\"\n          : \"mt-2 flex-wrap items-center\",\n        className,\n      )}\n    >\n      {entries.map((entry) => {\n        const off = hidden.has(entry.key);\n        return (\n          <button\n            key={entry.key}\n            type=\"button\"\n            // Pressed rather than a checkbox: it is a control over what the chart\n            // draws, and \"not pressed\" is the same sentence the dimmed mark says.\n            aria-pressed={!off}\n            onClick={() => onToggle(entry.key)}\n            className={cn(\n              \"flex items-center gap-1.5 rounded text-start text-[11px] text-[var(--text-secondary)] transition-opacity hover:opacity-80\",\n              \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]\",\n              off && \"opacity-35\",\n            )}\n          >\n            <LegendMark entry={entry} off={off} />\n            {entry.label}\n          </button>\n        );\n      })}\n    </div>\n  );\n}\n\n/**\n * The column a vertical legend stands in: beside the charts, on their horizontal\n * centre line. `h-full` + `justify-center`, so it centres in a grid cell or a flex row\n * that stretches it — and stacks whatever it is given, which is what a panel showing\n * two legends at once needs. The width is the caller's: how wide a legend column is\n * is a fact about that screen's layout.\n */\nexport function LegendColumn({ children, className }: { children: ReactNode; className?: string }) {\n  return (\n    <div className={cn(\"flex h-full flex-col justify-center gap-3\", className)}>{children}</div>\n  );\n}\n\n/**\n * A legend and what it is a legend OF, as a headed column.\n *\n * For legends that are several vocabularies at once — which measurement and which\n * channel — so the entries are read down a group and the groups across. Wrapped rows\n * would put the second half of one group on a line under the first half of the next.\n */\nexport function LegendGroup({ title, children }: { title: ReactNode; children: ReactNode }) {\n  return (\n    <div className=\"flex min-w-0 flex-col items-start gap-1\">\n      <span className=\"text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]\">\n        {title}\n      </span>\n      <div className=\"flex flex-col items-start gap-y-0.5\">{children}</div>\n    </div>\n  );\n}\n\n/** The entry's mark: a square for a measurement, a stroke for a quantity. A hidden one\n *  keeps its outline — a mark that vanished would leave a line of text with nothing in\n *  front of it.\n *\n *  A stroke is an SVG line with the chart's own `strokeDasharray`, not a CSS gradient\n *  approximating it: a gradient can say \"solid or dashed\" and nothing more. */\nfunction LegendMark({ entry, off }: { entry: LegendEntry; off: boolean }) {\n  if (entry.marker === \"stroke\") {\n    return (\n      <svg aria-hidden viewBox=\"0 0 20 2\" className=\"h-0.5 w-5 shrink-0 overflow-visible\">\n        <line\n          x1={0}\n          y1={1}\n          x2={20}\n          y2={1}\n          stroke={entry.color}\n          strokeWidth={2}\n          strokeDasharray={strokeDash(entry.dash ?? 0)}\n          opacity={off ? 0.35 : 1}\n        />\n      </svg>\n    );\n  }\n  return (\n    <span\n      aria-hidden\n      className=\"h-2.5 w-2.5 shrink-0 rounded-[3px]\"\n      style={{\n        backgroundColor: off ? \"transparent\" : entry.color,\n        boxShadow: `inset 0 0 0 1.5px ${entry.color}`,\n      }}\n    />\n  );\n}\n"],"mappings":";AA8IU,SAaE,KAbF;AAvIV,SAAS,UAAU;AACnB,SAAS,oBAAoB;AAC7B,SAAS,mCAA2D;AAkB7D,MAAM,kBAAmD;AAAA,EAC9D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,SAAS,WAAW,OAAmC;AAC5D,QAAM,IAAI,gBAAgB;AAC1B,SAAO,iBAAkB,KAAK,MAAM,KAAK,IAAI,IAAK,KAAK,CAAC;AAC1D;AAQO,MAAM,YAAY;AASlB,SAAS,aAAa,QAA6B,KAAkC;AAC1F,QAAM,OAAO,IAAI,IAAI,MAAM;AAC3B,MAAI,CAAC,KAAK,OAAO,GAAG,EAAG,MAAK,IAAI,GAAG;AACnC,SAAO;AACT;AAwDO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA,cAAc;AAAA,EACd,aAAa;AAAA,EACb;AAAA,EACA,QAAQ;AACV,GAAsB;AACpB,QAAM,SAAS,aAAa,eAAe,6BAA6B,UAAU;AAClF,MAAI,QAAQ,UAAU,aAAa,IAAI,GAAI,QAAO;AAClD,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,cAAY,OAAO;AAAA,MACnB,WAAW;AAAA,QACT;AAAA,QACA,gBAAgB,aACZ,wCACA;AAAA,QACJ;AAAA,MACF;AAAA,MAEC,kBAAQ,IAAI,CAAC,UAAU;AACtB,cAAM,MAAM,OAAO,IAAI,MAAM,GAAG;AAChC,eACE;AAAA,UAAC;AAAA;AAAA,YAEC,MAAK;AAAA,YAGL,gBAAc,CAAC;AAAA,YACf,SAAS,MAAM,SAAS,MAAM,GAAG;AAAA,YACjC,WAAW;AAAA,cACT;AAAA,cACA;AAAA,cACA,OAAO;AAAA,YACT;AAAA,YAEA;AAAA,kCAAC,cAAW,OAAc,KAAU;AAAA,cACnC,MAAM;AAAA;AAAA;AAAA,UAbF,MAAM;AAAA,QAcb;AAAA,MAEJ,CAAC;AAAA;AAAA,EACH;AAEJ;AASO,SAAS,aAAa,EAAE,UAAU,UAAU,GAAgD;AACjG,SACE,oBAAC,SAAI,WAAW,GAAG,6CAA6C,SAAS,GAAI,UAAS;AAE1F;AASO,SAAS,YAAY,EAAE,OAAO,SAAS,GAA8C;AAC1F,SACE,qBAAC,SAAI,WAAU,2CACb;AAAA,wBAAC,UAAK,WAAU,8EACb,iBACH;AAAA,IACA,oBAAC,SAAI,WAAU,uCAAuC,UAAS;AAAA,KACjE;AAEJ;AAQA,SAAS,WAAW,EAAE,OAAO,IAAI,GAAyC;AACxE,MAAI,MAAM,WAAW,UAAU;AAC7B,WACE,oBAAC,SAAI,eAAW,MAAC,SAAQ,YAAW,WAAU,uCAC5C;AAAA,MAAC;AAAA;AAAA,QACC,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,QAAQ,MAAM;AAAA,QACd,aAAa;AAAA,QACb,iBAAiB,WAAW,MAAM,QAAQ,CAAC;AAAA,QAC3C,SAAS,MAAM,OAAO;AAAA;AAAA,IACxB,GACF;AAAA,EAEJ;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,eAAW;AAAA,MACX,WAAU;AAAA,MACV,OAAO;AAAA,QACL,iBAAiB,MAAM,gBAAgB,MAAM;AAAA,QAC7C,WAAW,qBAAqB,MAAM,KAAK;AAAA,MAC7C;AAAA;AAAA,EACF;AAEJ;","names":[]}

package/dist/components/tooltip.d.ts

@@ -1,8 +1,26 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
 import { AnchorRect } from '../hooks/use-anchored-rect.js';
 
 type TooltipSide = "top" | "bottom" | "left" | "right";
+/**
+ * `extends ComponentPropsWithoutRef<"span">` because the wrapper this renders IS a span,
+ * and a tooltip is the component a caller most often needs to reach past: it sits
+ * between the layout and the control, so a `data-tour` anchor, a test id or an
+ * `aria-label` aimed at the trigger used to be swallowed by it.
+ *
+ * ⚠️ On the empty-label branch there is no wrapper at all, and therefore nothing for
+ * those attributes to land on — see the note in the body.
+ */
+interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
+    label: ReactNode;
+    side?: TooltipSide;
+    className?: string;
+    portal?: boolean;
+    /** Tag the bubble `data-private`, for a label that repeats the user's own data. */
+    redact?: boolean;
+    children: ReactNode;
+}
 /**
  * Hover/focus label for a control.
  *
@@ -26,6 +44,25 @@ type TooltipSide = "top" | "bottom" | "left" | "right";
  * would be a worse `title`, so the emptiness check is here rather than at every call
  * site that could forget it.
  *
+ * ⚠️ **The bubble describes its trigger, which means cloning it.** `role="tooltip"` is
+ * a name for a box, not a relationship — so for as long as nothing referenced the
+ * bubble, the label reached the pointer and nobody else. That is worst on the call
+ * sites that need it most: the kit's icon-only buttons, where the tooltip IS the
+ * label. `aria-describedby` has to sit on the focusable element, which is the
+ * caller's child and not this component's wrapper, so the child is CLONED to carry
+ * it. A description the caller already set is appended to, never replaced — a field's
+ * error text and its hint bubble both describe it. Children that cannot take props (a
+ * fragment, a bare string, several elements) are left exactly as they were.
+ *
+ * ⚠️ **Escape dismisses it (WCAG 1.4.13).** Anything that appears on hover or focus has
+ * to be dismissible without moving the pointer, and a bubble is opaque: it lands over
+ * the row, field or figure you were reading, and the only way out of it used to be to
+ * point somewhere else — which is precisely what you cannot do when what you need to
+ * read is underneath it. The listener is the document's rather than the wrapper's
+ * because the pointer opens this with the keyboard focus somewhere else entirely, and
+ * it is subscribed only while a bubble is actually up: the CSS variant is always
+ * mounted, and a table of forty tooltips must not mean forty keydown listeners.
+ *
  * ⚠️ **Inside a scroll container, use `portal`.** An always-mounted bubble is
  * absolutely positioned, but an absolutely positioned descendant still counts
  * towards its scroll-container ancestor's scrollable overflow — so an invisible
@@ -36,15 +73,7 @@ type TooltipSide = "top" | "bottom" | "left" | "right";
  * until hovered, so it adds no width — and, being outside the container, it also
  * cannot be clipped by it.
  */
-declare function Tooltip({ label, side, className, portal, redact, children, }: {
-    label: ReactNode;
-    side?: TooltipSide;
-    className?: string;
-    portal?: boolean;
-    /** Tag the bubble `data-private`, for a label that repeats the user's own data. */
-    redact?: boolean;
-    children: ReactNode;
-}): react.JSX.Element;
+declare function Tooltip({ label, side, className, portal, redact, children, ...rest }: TooltipProps): react.JSX.Element;
 interface TooltipSize {
     width: number;
     height: number;
@@ -83,4 +112,4 @@ interface TooltipPlacement {
  */
 declare function placeTooltip(r: AnchorRect, side: TooltipSide, size: TooltipSize, viewport: TooltipViewport): TooltipPlacement;
 
-export { Tooltip, type TooltipPlacement, type TooltipSize, type TooltipViewport, placeTooltip };
+export { Tooltip, type TooltipPlacement, type TooltipProps, type TooltipSize, type TooltipViewport, placeTooltip };

package/dist/components/tooltip.js

@@ -1,7 +1,16 @@
+"use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useRef, useState } from "react";
+import {
+  cloneElement,
+  isValidElement,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState
+} from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../lib/cn.js";
+import { useEscapeKey } from "../hooks/use-dismiss.js";
 import { useAnchoredRect } from "../hooks/use-anchored-rect.js";
 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";
 const sidePositionClass = {
@@ -16,7 +25,8 @@ function Tooltip({
   className,
   portal = false,
   redact = false,
-  children
+  children,
+  ...rest
 }) {
   if (isEmptyLabel(label)) return /* @__PURE__ */ jsx(Fragment, { children });
   if (portal) {
@@ -27,26 +37,68 @@ function Tooltip({
         side,
         className,
         redact,
+        ...rest,
         children
       }
     );
   }
-  return /* @__PURE__ */ jsxs("span", { className: cn("relative inline-flex group/tooltip", className), children: [
-    children,
-    /* @__PURE__ */ jsx(
-      "span",
-      {
-        role: "tooltip",
-        "data-private": redact ? "" : void 0,
-        className: cn(
-          TOOLTIP_SURFACE,
-          "pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100",
-          sidePositionClass[side]
-        ),
-        children: label
-      }
-    )
-  ] });
+  return /* @__PURE__ */ jsx(CssTooltip, { label, side, className, redact, ...rest, children });
+}
+function CssTooltip({
+  label,
+  side,
+  className,
+  redact,
+  children,
+  ...rest
+}) {
+  const id = useId();
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+  useEscapeKey(() => setDismissed(true), (hovered || focused) && !dismissed);
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      ...rest,
+      className: cn("relative inline-flex group/tooltip", className),
+      onMouseEnter: () => {
+        setHovered(true);
+        setDismissed(false);
+      },
+      onMouseLeave: () => setHovered(false),
+      onFocus: () => {
+        setFocused(true);
+        setDismissed(false);
+      },
+      onBlur: () => setFocused(false),
+      children: [
+        describedBy(children, dismissed ? void 0 : id),
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            id,
+            role: "tooltip",
+            hidden: dismissed || void 0,
+            "data-private": redact ? "" : void 0,
+            className: cn(
+              TOOLTIP_SURFACE,
+              "pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100",
+              sidePositionClass[side]
+            ),
+            children: label
+          }
+        )
+      ]
+    }
+  );
+}
+function describedBy(children, id) {
+  if (id === void 0 || !isValidElement(children)) return children;
+  const child = children;
+  if (typeof child.type === "symbol") return children;
+  const own = child.props["aria-describedby"];
+  return cloneElement(child, { "aria-describedby": own ? `${own} ${id}` : id });
 }
 function isEmptyLabel(label) {
   return label == null || label === false || typeof label === "string" && label.trim() === "";
@@ -110,11 +162,14 @@ function PortalTooltip({
   side,
   className,
   redact,
-  children
+  children,
+  ...rest
 }) {
   const triggerRef = useRef(null);
   const bubbleRef = useRef(null);
   const [visible, setVisible] = useState(false);
+  const id = useId();
+  useEscapeKey(() => setVisible(false), visible);
   const rect = useAnchoredRect(triggerRef, visible);
   const [room, setRoom] = useState(null);
   useLayoutEffect(() => {
@@ -134,13 +189,14 @@ function PortalTooltip({
     /* @__PURE__ */ jsx(
       "span",
       {
+        ...rest,
         ref: triggerRef,
         className: cn("relative inline-flex", className),
         onMouseEnter: () => setVisible(true),
         onMouseLeave: () => setVisible(false),
         onFocus: () => setVisible(true),
         onBlur: () => setVisible(false),
-        children
+        children: describedBy(children, visible ? id : void 0)
       }
     ),
     visible && point && typeof document !== "undefined" && createPortal(
@@ -148,6 +204,7 @@ function PortalTooltip({
         "span",
         {
           ref: bubbleRef,
+          id,
           role: "tooltip",
           "data-private": redact ? "" : void 0,
           style: placed ? { position: "fixed", left: placed.left, top: placed.top } : {

package/dist/components/tooltip.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/tooltip.tsx"],"sourcesContent":["import { useLayoutEffect, useRef, useState, type ReactNode } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { useAnchoredRect, type AnchorRect } from \"../hooks/use-anchored-rect\";\n\ntype TooltipSide = \"top\" | \"bottom\" | \"left\" | \"right\";\n\n/** The floating bubble itself. Uses the shared surface/border/text tokens so it\n *  reads as part of the app's chrome (like the top bar and cards) rather than the\n *  cold slate pill it used to be.\n *\n *  `w-max` keeps a short label on one line — the old `whitespace-nowrap` did that\n *  too, but it also let a sentence-length label grow without bound, and a bubble\n *  wider than the space beside its trigger gets clipped by whatever overflow\n *  container it sits in. So cap it and let long text wrap instead. The cap tracks\n *  the viewport as well, for narrow screens where 20rem is already most of it.\n *  `side` is a preference rather than an instruction for the PORTALLED variant,\n *  which measures the bubble and turns it round when it would not fit\n *  (Steering Design feedback #126). The CSS-only one never learns its own size,\n *  so there `side` is still the whole of the placement. */\nconst TOOLTIP_SURFACE =\n  \"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\";\n\nconst sidePositionClass: Record<TooltipSide, string> = {\n  top: \"bottom-full left-1/2 -translate-x-1/2 mb-1\",\n  bottom: \"top-full left-1/2 -translate-x-1/2 mt-1\",\n  left: \"right-full top-1/2 -translate-y-1/2 mr-1\",\n  right: \"left-full top-1/2 -translate-y-1/2 ml-1\",\n};\n\n/**\n * Hover/focus label for a control.\n *\n * Two implementations, and the choice matters more than it looks. The default is\n * CSS-only: the bubble is always mounted next to the trigger and fades in on\n * `:hover`, which costs no state and works in a plain render test. The `portal`\n * variant mounts the bubble in `document.body` only while hovered, positioned by\n * measurement.\n *\n * ⚠️ **A bubble that repeats a value has to be redactable.** The consuming app blurs\n * `[data-private]` under a `demo-mode` class on `<html>` — and the portalled bubble is\n * mounted on `document.body`, which is INSIDE that class, so the rule reaches it as\n * long as the bubble is tagged. It is not tagged by default, because most labels are\n * UI strings; pass `redact` on the ones that repeat the user's own data (a truncated\n * payee, an account name, a memo). Getting this wrong is silent: the trigger blurs,\n * the bubble spells the value out on hover.\n *\n * ⚠️ **An empty label renders nothing at all.** `title={payee ?? \"\"}` is an ordinary\n * shape at a call site that reveals truncated text, and the native attribute answers\n * it by showing no tooltip. A component that faithfully rendered an empty bubble\n * would be a worse `title`, so the emptiness check is here rather than at every call\n * site that could forget it.\n *\n * ⚠️ **Inside a scroll container, use `portal`.** An always-mounted bubble is\n * absolutely positioned, but an absolutely positioned descendant still counts\n * towards its scroll-container ancestor's scrollable overflow — so an invisible\n * bubble on a control near the right edge makes the container scroll sideways\n * with nothing to reveal. That is what Keksdose feedback dev#488 reported on the\n * admin roster: 66px of horizontal scroll on a table that fit, 44px of it owed to\n * tooltips nobody could see. The portalled bubble is `position: fixed` and absent\n * until hovered, so it adds no width — and, being outside the container, it also\n * cannot be clipped by it.\n */\nexport function Tooltip({\n  label,\n  side = \"top\",\n  className,\n  portal = false,\n  redact = false,\n  children,\n}: {\n  label: ReactNode;\n  side?: TooltipSide;\n  className?: string;\n  portal?: boolean;\n  /** Tag the bubble `data-private`, for a label that repeats the user's own data. */\n  redact?: boolean;\n  children: ReactNode;\n}) {\n  // No label, no bubble — and no wrapper either, so a conditional tooltip costs the\n  // layout nothing on the branch where it does not apply.\n  if (isEmptyLabel(label)) return <>{children}</>;\n  if (portal) {\n    return (\n      <PortalTooltip\n        label={label}\n        side={side}\n        className={className}\n        redact={redact}\n      >\n        {children}\n      </PortalTooltip>\n    );\n  }\n  return (\n    <span className={cn(\"relative inline-flex group/tooltip\", className)}>\n      {children}\n      <span\n        role=\"tooltip\"\n        data-private={redact ? \"\" : undefined}\n        className={cn(\n          TOOLTIP_SURFACE,\n          \"pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100\",\n          sidePositionClass[side],\n        )}\n      >\n        {label}\n      </span>\n    </span>\n  );\n}\n\n/** \"Would this bubble be blank.\" Only the values a call site actually produces when\n *  it has nothing to say — `\"\"`, `null`, `undefined`, `false` from a `&&` guard. A\n *  numeric `0` is a real label and stays one. */\nfunction isEmptyLabel(label: ReactNode): boolean {\n  return (\n    label == null ||\n    label === false ||\n    (typeof label === \"string\" && label.trim() === \"\")\n  );\n}\n\nconst TOOLTIP_GAP = 4;\n\n/** How close to the viewport edge a bubble may sit. Not zero: a label flush\n *  against the glass reads as clipped even when every character is on screen. */\nconst TOOLTIP_MARGIN = 4;\n\nconst portalTransformBySide: Record<TooltipSide, string> = {\n  right: \"translate(0, -50%)\",\n  left: \"translate(-100%, -50%)\",\n  top: \"translate(-50%, -100%)\",\n  bottom: \"translate(-50%, 0)\",\n};\n\n/** Anchor point (viewport px) for the tooltip on the given side of `r`. Paired\n *  with {@link portalTransformBySide}, which shifts the box onto that point. */\nfunction tooltipAnchor(\n  r: AnchorRect,\n  side: TooltipSide,\n): { left: number; top: number } {\n  switch (side) {\n    case \"right\":\n      return { left: r.right + TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"left\":\n      return { left: r.left - TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"top\":\n      return { left: r.left + r.width / 2, top: r.top - TOOLTIP_GAP };\n    case \"bottom\":\n      return { left: r.left + r.width / 2, top: r.bottom + TOOLTIP_GAP };\n  }\n}\n\nexport interface TooltipSize {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipViewport {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipPlacement {\n  left: number;\n  top: number;\n  /** Which side it ended up on, which need not be the one that was asked for. */\n  side: TooltipSide;\n}\n\nconst opposite: Record<TooltipSide, TooltipSide> = {\n  left: \"right\",\n  right: \"left\",\n  top: \"bottom\",\n  bottom: \"top\",\n};\n\n/** Whether the bubble clears the viewport edge on `side` of the trigger. */\nfunction roomOn(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): boolean {\n  switch (side) {\n    case \"left\":\n      return r.left - TOOLTIP_GAP - size.width >= TOOLTIP_MARGIN;\n    case \"right\":\n      return r.right + TOOLTIP_GAP + size.width <= viewport.width - TOOLTIP_MARGIN;\n    case \"top\":\n      return r.top - TOOLTIP_GAP - size.height >= TOOLTIP_MARGIN;\n    case \"bottom\":\n      return r.bottom + TOOLTIP_GAP + size.height <= viewport.height - TOOLTIP_MARGIN;\n  }\n}\n\nfunction sameRoom(\n  a: { size: TooltipSize; viewport: TooltipViewport },\n  b: { size: TooltipSize; viewport: TooltipViewport },\n): boolean {\n  return (\n    a.size.width === b.size.width &&\n    a.size.height === b.size.height &&\n    a.viewport.width === b.viewport.width &&\n    a.viewport.height === b.viewport.height\n  );\n}\n\nfunction clamp(value: number, low: number, high: number): number {\n  // `high` first, so a bubble taller or wider than the viewport is pinned to the\n  // top-left corner rather than to the bottom-right one — the start of a label\n  // is the half worth keeping.\n  return Math.max(low, Math.min(value, high));\n}\n\n/**\n * Where the bubble actually goes, given how big it turned out to be.\n *\n * Two rules, and they are separate because they fix separate failures.\n *\n * **Turn round when the preferred side has no room.** `side` says which side of\n * the trigger the label reads best on, and on a form near the left edge of the\n * window that side is off the screen — the capped bubble can only wrap, not\n * move, so what the reader gets is a sentence with its first half outside the\n * glass. Flipped only when the *other* side is genuinely better: a trigger in a\n * viewport too narrow for the bubble either way keeps the side it asked for, and\n * the clamp below does what it can.\n *\n * **Then clamp both axes.** The cross axis is the one that needs it — a `top`\n * bubble is centred on the trigger, so a trigger near the left edge pushes half\n * the label off even though the side it is on is right — and clamping the main\n * axis too costs nothing and covers the flip having nowhere to land.\n *\n * Pure, and measured in viewport pixels throughout, so it can be tested without\n * a layout: the caller supplies the trigger's rect, the bubble's own size and\n * the window.\n */\nexport function placeTooltip(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): TooltipPlacement {\n  const chosen =\n    roomOn(r, side, size, viewport) || !roomOn(r, opposite[side], size, viewport)\n      ? side\n      : opposite[side];\n  const point = tooltipAnchor(r, chosen);\n  const box =\n    chosen === \"left\"\n      ? { left: point.left - size.width, top: point.top - size.height / 2 }\n      : chosen === \"right\"\n        ? { left: point.left, top: point.top - size.height / 2 }\n        : chosen === \"top\"\n          ? { left: point.left - size.width / 2, top: point.top - size.height }\n          : { left: point.left - size.width / 2, top: point.top };\n  return {\n    left: clamp(box.left, TOOLTIP_MARGIN, viewport.width - size.width - TOOLTIP_MARGIN),\n    top: clamp(box.top, TOOLTIP_MARGIN, viewport.height - size.height - TOOLTIP_MARGIN),\n    side: chosen,\n  };\n}\n\nfunction PortalTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n}: {\n  label: ReactNode;\n  side: TooltipSide;\n  className?: string;\n  redact?: boolean;\n  children: ReactNode;\n}) {\n  const triggerRef = useRef<HTMLSpanElement | null>(null);\n  const bubbleRef = useRef<HTMLSpanElement | null>(null);\n  const [visible, setVisible] = useState(false);\n  // The measure + scroll/resize-tracking lifecycle is owned by useAnchoredRect;\n  // here we only map the rect to a side-specific anchor point.\n  const rect = useAnchoredRect(triggerRef, visible);\n  // The bubble's own size and the window it has to fit in — neither of which is\n  // knowable in render: the width is whatever the label wrapped to inside the\n  // cap, and reading `window` while rendering is not a pure thing to do. Both\n  // are taken in a LAYOUT effect, so the correction lands before the browser\n  // paints and there is no frame in which the label sits off the screen.\n  const [room, setRoom] = useState<{ size: TooltipSize; viewport: TooltipViewport } | null>(null);\n  useLayoutEffect(() => {\n    const measured = visible ? bubbleRef.current?.getBoundingClientRect() : undefined;\n    // eslint-disable-next-line react-hooks/set-state-in-effect -- a measurement is the one thing a layout effect is for\n    setRoom((previous) => {\n      if (!measured) return null;\n      const next = {\n        size: { width: measured.width, height: measured.height },\n        viewport: { width: window.innerWidth, height: window.innerHeight },\n      };\n      // Only publish what actually CHANGED: every re-measure allocates a fresh\n      // object, and a new object on every scroll event would re-render the\n      // bubble forever.\n      return previous && sameRoom(previous, next) ? previous : next;\n    });\n  }, [visible, rect, label]);\n\n  const point = rect ? tooltipAnchor(rect, side) : null;\n  // Unmeasured on the very first pass, where the anchor point plus the side's\n  // own transform is exactly what this always did. One layout effect later the\n  // size is known and the placement is decided properly.\n  const placed = rect && room ? placeTooltip(rect, side, room.size, room.viewport) : null;\n\n  return (\n    <>\n      <span\n        ref={triggerRef}\n        className={cn(\"relative inline-flex\", className)}\n        onMouseEnter={() => setVisible(true)}\n        onMouseLeave={() => setVisible(false)}\n        onFocus={() => setVisible(true)}\n        onBlur={() => setVisible(false)}\n      >\n        {children}\n      </span>\n      {visible &&\n        point &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <span\n            ref={bubbleRef}\n            role=\"tooltip\"\n            data-private={redact ? \"\" : undefined}\n            style={\n              placed\n                ? { position: \"fixed\", left: placed.left, top: placed.top }\n                : {\n                    position: \"fixed\",\n                    left: point.left,\n                    top: point.top,\n                    transform: portalTransformBySide[side],\n                  }\n            }\n            className={cn(TOOLTIP_SURFACE, \"pointer-events-none z-50\")}\n          >\n            {label}\n          </span>,\n          document.body,\n        )}\n    </>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/tooltip.tsx"],"sourcesContent":["import {\n  cloneElement,\n  isValidElement,\n  useId,\n  useLayoutEffect,\n  useRef,\n  useState,\n  type ComponentPropsWithoutRef,\n  type ReactElement,\n  type ReactNode,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { useEscapeKey } from \"../hooks/use-dismiss\";\nimport { useAnchoredRect, type AnchorRect } from \"../hooks/use-anchored-rect\";\n\ntype TooltipSide = \"top\" | \"bottom\" | \"left\" | \"right\";\n\n/** The floating bubble itself. Uses the shared surface/border/text tokens so it\n *  reads as part of the app's chrome (like the top bar and cards) rather than the\n *  cold slate pill it used to be.\n *\n *  `w-max` keeps a short label on one line — the old `whitespace-nowrap` did that\n *  too, but it also let a sentence-length label grow without bound, and a bubble\n *  wider than the space beside its trigger gets clipped by whatever overflow\n *  container it sits in. So cap it and let long text wrap instead. The cap tracks\n *  the viewport as well, for narrow screens where 20rem is already most of it.\n *  `side` is a preference rather than an instruction for the PORTALLED variant,\n *  which measures the bubble and turns it round when it would not fit\n *  (Steering Design feedback #126). The CSS-only one never learns its own size,\n *  so there `side` is still the whole of the placement. */\nconst TOOLTIP_SURFACE =\n  \"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\";\n\nconst sidePositionClass: Record<TooltipSide, string> = {\n  top: \"bottom-full left-1/2 -translate-x-1/2 mb-1\",\n  bottom: \"top-full left-1/2 -translate-x-1/2 mt-1\",\n  left: \"right-full top-1/2 -translate-y-1/2 mr-1\",\n  right: \"left-full top-1/2 -translate-y-1/2 ml-1\",\n};\n\n/**\n * `extends ComponentPropsWithoutRef<\"span\">` because the wrapper this renders IS a span,\n * and a tooltip is the component a caller most often needs to reach past: it sits\n * between the layout and the control, so a `data-tour` anchor, a test id or an\n * `aria-label` aimed at the trigger used to be swallowed by it.\n *\n * ⚠️ On the empty-label branch there is no wrapper at all, and therefore nothing for\n * those attributes to land on — see the note in the body.\n */\nexport interface TooltipProps extends ComponentPropsWithoutRef<\"span\"> {\n  label: ReactNode;\n  side?: TooltipSide;\n  className?: string;\n  portal?: boolean;\n  /** Tag the bubble `data-private`, for a label that repeats the user's own data. */\n  redact?: boolean;\n  children: ReactNode;\n}\n\n/** What each variant below takes: the resolved `side`, and every span attribute the\n *  caller handed {@link Tooltip}, forwarded to that variant's own wrapper. */\ntype TooltipVariantProps = Omit<TooltipProps, \"side\" | \"portal\"> & { side: TooltipSide };\n\n/**\n * Hover/focus label for a control.\n *\n * Two implementations, and the choice matters more than it looks. The default is\n * CSS-only: the bubble is always mounted next to the trigger and fades in on\n * `:hover`, which costs no state and works in a plain render test. The `portal`\n * variant mounts the bubble in `document.body` only while hovered, positioned by\n * measurement.\n *\n * ⚠️ **A bubble that repeats a value has to be redactable.** The consuming app blurs\n * `[data-private]` under a `demo-mode` class on `<html>` — and the portalled bubble is\n * mounted on `document.body`, which is INSIDE that class, so the rule reaches it as\n * long as the bubble is tagged. It is not tagged by default, because most labels are\n * UI strings; pass `redact` on the ones that repeat the user's own data (a truncated\n * payee, an account name, a memo). Getting this wrong is silent: the trigger blurs,\n * the bubble spells the value out on hover.\n *\n * ⚠️ **An empty label renders nothing at all.** `title={payee ?? \"\"}` is an ordinary\n * shape at a call site that reveals truncated text, and the native attribute answers\n * it by showing no tooltip. A component that faithfully rendered an empty bubble\n * would be a worse `title`, so the emptiness check is here rather than at every call\n * site that could forget it.\n *\n * ⚠️ **The bubble describes its trigger, which means cloning it.** `role=\"tooltip\"` is\n * a name for a box, not a relationship — so for as long as nothing referenced the\n * bubble, the label reached the pointer and nobody else. That is worst on the call\n * sites that need it most: the kit's icon-only buttons, where the tooltip IS the\n * label. `aria-describedby` has to sit on the focusable element, which is the\n * caller's child and not this component's wrapper, so the child is CLONED to carry\n * it. A description the caller already set is appended to, never replaced — a field's\n * error text and its hint bubble both describe it. Children that cannot take props (a\n * fragment, a bare string, several elements) are left exactly as they were.\n *\n * ⚠️ **Escape dismisses it (WCAG 1.4.13).** Anything that appears on hover or focus has\n * to be dismissible without moving the pointer, and a bubble is opaque: it lands over\n * the row, field or figure you were reading, and the only way out of it used to be to\n * point somewhere else — which is precisely what you cannot do when what you need to\n * read is underneath it. The listener is the document's rather than the wrapper's\n * because the pointer opens this with the keyboard focus somewhere else entirely, and\n * it is subscribed only while a bubble is actually up: the CSS variant is always\n * mounted, and a table of forty tooltips must not mean forty keydown listeners.\n *\n * ⚠️ **Inside a scroll container, use `portal`.** An always-mounted bubble is\n * absolutely positioned, but an absolutely positioned descendant still counts\n * towards its scroll-container ancestor's scrollable overflow — so an invisible\n * bubble on a control near the right edge makes the container scroll sideways\n * with nothing to reveal. That is what Keksdose feedback dev#488 reported on the\n * admin roster: 66px of horizontal scroll on a table that fit, 44px of it owed to\n * tooltips nobody could see. The portalled bubble is `position: fixed` and absent\n * until hovered, so it adds no width — and, being outside the container, it also\n * cannot be clipped by it.\n */\nexport function Tooltip({\n  label,\n  side = \"top\",\n  className,\n  portal = false,\n  redact = false,\n  children,\n  ...rest\n}: TooltipProps) {\n  // No label, no bubble — and no wrapper either, so a conditional tooltip costs the\n  // layout nothing on the branch where it does not apply. `...rest` goes with the\n  // wrapper on this branch, which is the documented limit of the pass-through: there is\n  // no element left to put an attribute on.\n  if (isEmptyLabel(label)) return <>{children}</>;\n  if (portal) {\n    return (\n      <PortalTooltip\n        label={label}\n        side={side}\n        className={className}\n        redact={redact}\n        {...rest}\n      >\n        {children}\n      </PortalTooltip>\n    );\n  }\n  // Both variants are separate components so that `Tooltip` itself can keep calling NO\n  // hooks: the empty-label branch above returns before either of them, and a hook after\n  // a conditional return is a hooks-order bug rather than a style violation.\n  return (\n    <CssTooltip label={label} side={side} className={className} redact={redact} {...rest}>\n      {children}\n    </CssTooltip>\n  );\n}\n\n/** The always-mounted variant: the bubble sits next to the trigger and CSS fades it in.\n *\n *  It holds the little state it does for the two things CSS cannot express — which\n *  element to point `aria-describedby` at, and Escape — and not for the fade, which is\n *  still `group-hover`/`group-focus-within` and still costs a render nothing. */\nfunction CssTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const id = useId();\n  const [hovered, setHovered] = useState(false);\n  const [focused, setFocused] = useState(false);\n  const [dismissed, setDismissed] = useState(false);\n  useEscapeKey(() => setDismissed(true), (hovered || focused) && !dismissed);\n  return (\n    <span\n      // `...rest` first: the four handlers below are what decides whether a bubble is\n      // up, and a caller passing an `onFocus` of its own must not replace them.\n      {...rest}\n      className={cn(\"relative inline-flex group/tooltip\", className)}\n      // These four track WHETHER A BUBBLE IS UP. They activate nothing — the only thing\n      // here that can be activated is the caller's child, which keeps every handler it\n      // arrived with — so this wrapper needs no role and no key handling of its own.\n      // `jsx-a11y/no-static-element-interactions` warns about it all the same, as it\n      // already does about the portal variant's identical trigger below; both are left\n      // visible rather than silenced, because a rule this package ratchets should be\n      // argued with in the backlog and not in a disable comment.\n      //\n      // Re-armed by the next hover or focus rather than by an effect watching those\n      // flags: coming back to a trigger is a fresh request for its label, and an effect\n      // would also re-show the bubble under a pointer that never left.\n      onMouseEnter={() => {\n        setHovered(true);\n        setDismissed(false);\n      }}\n      onMouseLeave={() => setHovered(false)}\n      onFocus={() => {\n        setFocused(true);\n        setDismissed(false);\n      }}\n      onBlur={() => setFocused(false)}\n    >\n      {describedBy(children, dismissed ? undefined : id)}\n      <span\n        id={id}\n        role=\"tooltip\"\n        // The `hidden` ATTRIBUTE, not an opacity class: dismissing has to take the\n        // bubble out of the accessibility tree as well as off the screen, or a screen\n        // reader still reads out the description of a bubble the user just closed.\n        hidden={dismissed || undefined}\n        data-private={redact ? \"\" : undefined}\n        className={cn(\n          TOOLTIP_SURFACE,\n          \"pointer-events-none absolute z-50 opacity-0 group-hover/tooltip:opacity-100 group-focus-within/tooltip:opacity-100\",\n          sidePositionClass[side],\n        )}\n      >\n        {label}\n      </span>\n    </span>\n  );\n}\n\n/** Hand `children` the bubble's id as an `aria-describedby`, if it is an element that\n *  can hold one. `id` is undefined while there is no bubble to point at — a dangling\n *  reference describes the trigger as nothing at all, which is worse than silence. */\nfunction describedBy(children: ReactNode, id: string | undefined): ReactNode {\n  if (id === undefined || !isValidElement(children)) return children;\n  const child = children as ReactElement<{ \"aria-describedby\"?: string }>;\n  // Fragments, Suspense and friends are symbol-typed and take no DOM props; cloning one\n  // with an aria attribute warns in development and drops it in production.\n  if (typeof child.type === \"symbol\") return children;\n  const own = child.props[\"aria-describedby\"];\n  return cloneElement(child, { \"aria-describedby\": own ? `${own} ${id}` : id });\n}\n\n/** \"Would this bubble be blank.\" Only the values a call site actually produces when\n *  it has nothing to say — `\"\"`, `null`, `undefined`, `false` from a `&&` guard. A\n *  numeric `0` is a real label and stays one. */\nfunction isEmptyLabel(label: ReactNode): boolean {\n  return (\n    label == null ||\n    label === false ||\n    (typeof label === \"string\" && label.trim() === \"\")\n  );\n}\n\nconst TOOLTIP_GAP = 4;\n\n/** How close to the viewport edge a bubble may sit. Not zero: a label flush\n *  against the glass reads as clipped even when every character is on screen. */\nconst TOOLTIP_MARGIN = 4;\n\nconst portalTransformBySide: Record<TooltipSide, string> = {\n  right: \"translate(0, -50%)\",\n  left: \"translate(-100%, -50%)\",\n  top: \"translate(-50%, -100%)\",\n  bottom: \"translate(-50%, 0)\",\n};\n\n/** Anchor point (viewport px) for the tooltip on the given side of `r`. Paired\n *  with {@link portalTransformBySide}, which shifts the box onto that point. */\nfunction tooltipAnchor(\n  r: AnchorRect,\n  side: TooltipSide,\n): { left: number; top: number } {\n  switch (side) {\n    case \"right\":\n      return { left: r.right + TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"left\":\n      return { left: r.left - TOOLTIP_GAP, top: r.top + r.height / 2 };\n    case \"top\":\n      return { left: r.left + r.width / 2, top: r.top - TOOLTIP_GAP };\n    case \"bottom\":\n      return { left: r.left + r.width / 2, top: r.bottom + TOOLTIP_GAP };\n  }\n}\n\nexport interface TooltipSize {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipViewport {\n  width: number;\n  height: number;\n}\n\nexport interface TooltipPlacement {\n  left: number;\n  top: number;\n  /** Which side it ended up on, which need not be the one that was asked for. */\n  side: TooltipSide;\n}\n\nconst opposite: Record<TooltipSide, TooltipSide> = {\n  left: \"right\",\n  right: \"left\",\n  top: \"bottom\",\n  bottom: \"top\",\n};\n\n/** Whether the bubble clears the viewport edge on `side` of the trigger. */\nfunction roomOn(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): boolean {\n  switch (side) {\n    case \"left\":\n      return r.left - TOOLTIP_GAP - size.width >= TOOLTIP_MARGIN;\n    case \"right\":\n      return r.right + TOOLTIP_GAP + size.width <= viewport.width - TOOLTIP_MARGIN;\n    case \"top\":\n      return r.top - TOOLTIP_GAP - size.height >= TOOLTIP_MARGIN;\n    case \"bottom\":\n      return r.bottom + TOOLTIP_GAP + size.height <= viewport.height - TOOLTIP_MARGIN;\n  }\n}\n\nfunction sameRoom(\n  a: { size: TooltipSize; viewport: TooltipViewport },\n  b: { size: TooltipSize; viewport: TooltipViewport },\n): boolean {\n  return (\n    a.size.width === b.size.width &&\n    a.size.height === b.size.height &&\n    a.viewport.width === b.viewport.width &&\n    a.viewport.height === b.viewport.height\n  );\n}\n\nfunction clamp(value: number, low: number, high: number): number {\n  // `high` first, so a bubble taller or wider than the viewport is pinned to the\n  // top-left corner rather than to the bottom-right one — the start of a label\n  // is the half worth keeping.\n  return Math.max(low, Math.min(value, high));\n}\n\n/**\n * Where the bubble actually goes, given how big it turned out to be.\n *\n * Two rules, and they are separate because they fix separate failures.\n *\n * **Turn round when the preferred side has no room.** `side` says which side of\n * the trigger the label reads best on, and on a form near the left edge of the\n * window that side is off the screen — the capped bubble can only wrap, not\n * move, so what the reader gets is a sentence with its first half outside the\n * glass. Flipped only when the *other* side is genuinely better: a trigger in a\n * viewport too narrow for the bubble either way keeps the side it asked for, and\n * the clamp below does what it can.\n *\n * **Then clamp both axes.** The cross axis is the one that needs it — a `top`\n * bubble is centred on the trigger, so a trigger near the left edge pushes half\n * the label off even though the side it is on is right — and clamping the main\n * axis too costs nothing and covers the flip having nowhere to land.\n *\n * Pure, and measured in viewport pixels throughout, so it can be tested without\n * a layout: the caller supplies the trigger's rect, the bubble's own size and\n * the window.\n */\nexport function placeTooltip(\n  r: AnchorRect,\n  side: TooltipSide,\n  size: TooltipSize,\n  viewport: TooltipViewport,\n): TooltipPlacement {\n  const chosen =\n    roomOn(r, side, size, viewport) || !roomOn(r, opposite[side], size, viewport)\n      ? side\n      : opposite[side];\n  const point = tooltipAnchor(r, chosen);\n  const box =\n    chosen === \"left\"\n      ? { left: point.left - size.width, top: point.top - size.height / 2 }\n      : chosen === \"right\"\n        ? { left: point.left, top: point.top - size.height / 2 }\n        : chosen === \"top\"\n          ? { left: point.left - size.width / 2, top: point.top - size.height }\n          : { left: point.left - size.width / 2, top: point.top };\n  return {\n    left: clamp(box.left, TOOLTIP_MARGIN, viewport.width - size.width - TOOLTIP_MARGIN),\n    top: clamp(box.top, TOOLTIP_MARGIN, viewport.height - size.height - TOOLTIP_MARGIN),\n    side: chosen,\n  };\n}\n\nfunction PortalTooltip({\n  label,\n  side,\n  className,\n  redact,\n  children,\n  ...rest\n}: TooltipVariantProps) {\n  const triggerRef = useRef<HTMLSpanElement | null>(null);\n  const bubbleRef = useRef<HTMLSpanElement | null>(null);\n  const [visible, setVisible] = useState(false);\n  const id = useId();\n  // Escape closes it outright, since this variant's bubble only exists while it is\n  // shown. The next mouseenter/focus brings it back, which is the behaviour WCAG\n  // 1.4.13 asks for: dismissible now, still available when you ask again.\n  useEscapeKey(() => setVisible(false), visible);\n  // The measure + scroll/resize-tracking lifecycle is owned by useAnchoredRect;\n  // here we only map the rect to a side-specific anchor point.\n  const rect = useAnchoredRect(triggerRef, visible);\n  // The bubble's own size and the window it has to fit in — neither of which is\n  // knowable in render: the width is whatever the label wrapped to inside the\n  // cap, and reading `window` while rendering is not a pure thing to do. Both\n  // are taken in a LAYOUT effect, so the correction lands before the browser\n  // paints and there is no frame in which the label sits off the screen.\n  const [room, setRoom] = useState<{ size: TooltipSize; viewport: TooltipViewport } | null>(null);\n  useLayoutEffect(() => {\n    const measured = visible ? bubbleRef.current?.getBoundingClientRect() : undefined;\n    // eslint-disable-next-line react-hooks/set-state-in-effect -- a measurement is the one thing a layout effect is for\n    setRoom((previous) => {\n      if (!measured) return null;\n      const next = {\n        size: { width: measured.width, height: measured.height },\n        viewport: { width: window.innerWidth, height: window.innerHeight },\n      };\n      // Only publish what actually CHANGED: every re-measure allocates a fresh\n      // object, and a new object on every scroll event would re-render the\n      // bubble forever.\n      return previous && sameRoom(previous, next) ? previous : next;\n    });\n  }, [visible, rect, label]);\n\n  const point = rect ? tooltipAnchor(rect, side) : null;\n  // Unmeasured on the very first pass, where the anchor point plus the side's\n  // own transform is exactly what this always did. One layout effect later the\n  // size is known and the placement is decided properly.\n  const placed = rect && room ? placeTooltip(rect, side, room.size, room.viewport) : null;\n\n  return (\n    <>\n      <span\n        // As in `CssTooltip`: the caller's attributes first, the four handlers that run\n        // this component after them. The BUBBLE is deliberately not given them — it is\n        // portalled to `<body>`, and an id or a tour anchor duplicated onto a node that\n        // only exists while hovered would match twice or match nothing.\n        {...rest}\n        ref={triggerRef}\n        className={cn(\"relative inline-flex\", className)}\n        onMouseEnter={() => setVisible(true)}\n        onMouseLeave={() => setVisible(false)}\n        onFocus={() => setVisible(true)}\n        onBlur={() => setVisible(false)}\n      >\n        {describedBy(children, visible ? id : undefined)}\n      </span>\n      {visible &&\n        point &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <span\n            ref={bubbleRef}\n            id={id}\n            role=\"tooltip\"\n            data-private={redact ? \"\" : undefined}\n            style={\n              placed\n                ? { position: \"fixed\", left: placed.left, top: placed.top }\n                : {\n                    position: \"fixed\",\n                    left: point.left,\n                    top: point.top,\n                    transform: portalTransformBySide[side],\n                  }\n            }\n            className={cn(TOOLTIP_SURFACE, \"pointer-events-none z-50\")}\n          >\n            {label}\n          </span>,\n          document.body,\n        )}\n    </>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/treemap.d.ts

@@ -0,0 +1,132 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+/**
+ * One tile.
+ *
+ * `value`, not keksdose's `total`: a treemap's areas are not always money (keksdose
+ * already sizes one by transaction COUNT), and `value` is the word every other chart
+ * in recharts uses for the number a mark is sized by. Migrating is a rename at the
+ * mapping step — `{ id, name, value: row.total }`.
+ */
+interface TreemapNode {
+    /** Stable key, handed back by {@link TreemapProps.onNodeClick} and
+     *  {@link TreemapProps.nodeNote}. Names can collide; ids must not. */
+    id: string;
+    name: string;
+    /** The tile's area. A node whose value is not a positive finite number is NOT
+     *  drawn — an area cannot be negative, and recharts lays a negative size out as
+     *  nonsense rather than refusing it. Saying so is the caller's job: a group that
+     *  vanishes silently between two views of the same data is a bug report. */
+    value: number;
+    /** Overrides the by-index palette colour for this tile — e.g. to paint every child
+     *  in its parent group's colour, so the groups stay legible in one picture. A
+     *  concrete `#rrggbb` keeps the label ink measured; anything else (a CSS var) gets
+     *  `currentColor` ink, because there is nothing to measure. */
+    fill?: string;
+}
+/**
+ * Everything a `<div>` takes reaches the chart's root (`ChartContainer`), so a test id
+ * or a `data-tour` anchor can find it. `children` is the chart's own.
+ */
+interface TreemapProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    data: TreemapNode[];
+    /**
+     * Formats a node's value in the tooltip. Handed the node's SHARE of what is drawn
+     * (0–1) as a second argument, because a tile is read for how big it is relative to
+     * the rest, and "€412.30" alone makes the reader estimate that ratio off the areas.
+     * The share is `undefined` when the drawn total is not positive.
+     *
+     * Default: the bare number through `Intl.NumberFormat` in the runtime's locale. A
+     * host that has a currency or a locale passes this — the kit knows neither.
+     */
+    valueFormatter?: (value: number, share: number | undefined) => ReactNode;
+    /** Chart height in px. Default 320. */
+    height?: number;
+    /** A tile was activated — by click, or by Enter/Space on a focused tile. Setting
+     *  this makes every tile a focusable `role="button"` named by its node name. */
+    onNodeClick?: (id: string, name: string) => void;
+    /**
+     * The node names are the user's own data (payees, not categories): the tile labels
+     * and the whole tooltip bubble get `data-private`, the same attribute the kit's
+     * `Tooltip redact` and `ChartTooltipContent`'s value cell carry, so the host's one
+     * privacy rule reaches them. Off by default — a category name is a label of the app.
+     */
+    redactNames?: boolean;
+    /**
+     * A second, smaller line under a tile's label — one extra figure per node that the
+     * name cannot carry (a year-on-year `+12%`, `new`). Return `undefined` for a node
+     * with nothing to add. Never tagged `data-private`: a ratio reveals no amount.
+     *
+     * ON THE TILE rather than in the tooltip, for two reasons. The tooltip identifies a
+     * node by name or by raw value, so a per-node note would be keyed on an amount (two
+     * nodes of equal size would swap notes). And a tooltip is a pointer affordance: a
+     * phone never hovers, so a figure that only exists on hover does not exist there.
+     */
+    nodeNote?: (id: string) => string | undefined;
+    /**
+     * Draw at most this many tiles (the first N drawable nodes, in the order given —
+     * sort first). Unbounded by default. A tile under ~44x20px has no room for a label,
+     * and a map made of unlabelled rectangles answers nothing; around 24 is where the
+     * smallest tile of a skewed series reaches that floor on a phone-width card. The
+     * caller owns the "N more not shown" line, since it knows how many it passed.
+     */
+    maxTiles?: number;
+    /**
+     * The categorical ramp tiles take by index, as concrete hex. Default: the page's
+     * live `--chart-1…9` tokens (see `useChartTokenHex`). Pass one when the host
+     * already holds the active palette — e.g. `createPaletteStore`'s `useChartHex()` —
+     * so a caller colouring a legend beside the map is guaranteed the same list.
+     */
+    colors?: readonly string[];
+}
+/**
+ * Fit a label to its tile: the text itself when it fits, an ellipsised head when it
+ * does not, `null` when not even three characters would. Without this a long name ran
+ * on across its neighbours and collided with THEIR labels. 0.58em is the average
+ * advance of a UI sans at this weight; it only needs to be close, since the tile keeps
+ * 6px of padding either side. The full name stays in the tooltip.
+ */
+declare function fitLabel(name: string, boxWidth: number, fontSize: number): string | null;
+/** What recharts hands a `content` element for each node, plus the three options the
+ *  chart forwards. Everything optional because recharts clones the element it was
+ *  given and fills the geometry in — the element as written carries only the options. */
+interface TreemapCellProps {
+    depth?: number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    name?: string;
+    fill?: string;
+    id?: string;
+    onNodeClick?: (id: string, name: string) => void;
+    redactNames?: boolean;
+    nodeNote?: (id: string) => string | undefined;
+}
+/**
+ * One tile. Exported so a caller drawing its own recharts `<Treemap>` gets the same
+ * label rules.
+ *
+ * recharts' default cell inherits the chart-level `stroke`, an SVG presentation
+ * attribute that lands on the `<svg>` root and cascades into the label — so the glyphs
+ * were painted with a 1px outline ON TOP of themselves, which reads as blur. This cell
+ * draws its own label with a halo in the TILE colour painted BEHIND the fill
+ * (`paint-order: stroke`), which defeats any inherited stroke and keeps the text solid
+ * where it overlaps a lighter or darker part of its own tile.
+ */
+declare function TreemapCell({ depth, x, y, width, height, name, fill, id, onNodeClick, redactNames, nodeNote, }: TreemapCellProps): react.JSX.Element | null;
+/**
+ * Tile chart: one rectangle per {@link TreemapNode}, sized by `value`, coloured by
+ * index from the chart ramp (or by the node's own `fill`), labelled in whichever of the
+ * kit's two inks measures better against it. Hover shows the name and the formatted
+ * value; `onNodeClick` turns the tiles into buttons.
+ *
+ * Renders nothing when no node has a positive value — an empty box is a hole in the
+ * card, and the caller's own sentence is the better answer there.
+ *
+ * Needs `recharts`, like everything behind `@eifi1/ui-kit/chart`.
+ */
+declare function Treemap({ data, valueFormatter, height, onNodeClick, redactNames, nodeNote, maxTiles, colors, style, ...rest }: TreemapProps): react.JSX.Element | null;
+
+export { Treemap, TreemapCell, type TreemapCellProps, type TreemapNode, type TreemapProps, fitLabel };