@eifi1/ui-kit 0.51.7 → 0.52.0

package/dist/components/treemap-layout.js

@@ -0,0 +1,126 @@
+"use client";
+const PHI = (1 + Math.sqrt(5)) / 2;
+const BAND = 20;
+const FRAME_MARGIN = 3;
+const BODY_SHARE = 1 / PHI;
+function groupBody(box, scale) {
+  const band = BAND * scale;
+  const margin = Math.min(FRAME_MARGIN, Math.floor(box.width / 4), Math.floor(box.height / 4));
+  const banded = box.width >= 44 * scale && box.height - band - margin >= box.height * BODY_SHARE;
+  const top = banded ? band : margin;
+  return {
+    banded,
+    body: {
+      x: box.x + margin,
+      y: box.y + top,
+      width: Math.max(0, box.width - 2 * margin),
+      height: Math.max(0, box.height - top - margin)
+    }
+  };
+}
+function worst(area, min, max, side, ratio) {
+  const along = side * side;
+  const across = area * area;
+  if (across === 0 || min === 0) return Infinity;
+  return Math.max(along * max * ratio / across, across / (along * min * ratio));
+}
+function squarify(weights, rect, ratio = PHI) {
+  const out = weights.map(() => ({ x: rect.x, y: rect.y, width: 0, height: 0 }));
+  const sum = weights.reduce((acc, w) => acc + Math.max(0, w), 0);
+  if (!(sum > 0) || rect.width <= 0 || rect.height <= 0) return out;
+  const areas = weights.map((w) => Math.max(0, w) * rect.width * rect.height / sum);
+  let { x, y, width, height } = rect;
+  let i = 0;
+  while (i < areas.length) {
+    const side = Math.min(width, height);
+    let rowArea = 0;
+    let min = Infinity;
+    let max = 0;
+    let best = Infinity;
+    let j = i;
+    while (j < areas.length) {
+      const a = areas[j];
+      const score = worst(rowArea + a, Math.min(min, a), Math.max(max, a), side, ratio);
+      if (j > i && score > best) break;
+      rowArea += a;
+      min = Math.min(min, a);
+      max = Math.max(max, a);
+      best = score;
+      j += 1;
+    }
+    const last = j === areas.length;
+    if (side === width) {
+      const thick = last ? height : rowArea / width;
+      let at = x;
+      for (let k = i; k < j; k++) {
+        const len = k === j - 1 ? x + width - at : areas[k] / rowArea * width;
+        out[k] = { x: at, y, width: len, height: thick };
+        at += len;
+      }
+      y += thick;
+      height -= thick;
+    } else {
+      const thick = last ? width : rowArea / height;
+      let at = y;
+      for (let k = i; k < j; k++) {
+        const len = k === j - 1 ? y + height - at : areas[k] / rowArea * height;
+        out[k] = { x, y: at, width: thick, height: len };
+        at += len;
+      }
+      x += thick;
+      width -= thick;
+    }
+    i = j;
+  }
+  return out;
+}
+function snap(b) {
+  const x = Math.round(b.x);
+  const y = Math.round(b.y);
+  return { x, y, width: Math.round(b.x + b.width) - x, height: Math.round(b.y + b.height) - y };
+}
+const ROUNDS = 8;
+function layoutTreemap(nodes, width, height, scale) {
+  const total = nodes.reduce((acc, n) => acc + n.size, 0);
+  const frames = /* @__PURE__ */ new Map();
+  let placed = /* @__PURE__ */ new Map();
+  for (let round = 0; round < ROUNDS; round++) {
+    const framed = [...frames.values()].reduce((acc, a) => acc + a, 0);
+    const spare = width * height - framed;
+    const density = total > 0 ? (spare > 0 ? spare : width * height) / total : 0;
+    const need = (n) => n.children ? (frames.get(n.path) ?? 0) + n.children.reduce((acc, c) => acc + need(c), 0) : n.size * density;
+    let moved = 0;
+    placed = /* @__PURE__ */ new Map();
+    const place = (list, rect) => {
+      const boxes = squarify(
+        list.map((n) => need(n)),
+        rect
+      );
+      list.forEach((n, i) => {
+        const box = snap(boxes[i]);
+        if (!n.children) {
+          placed.set(n.path, { box });
+          return;
+        }
+        const { banded, body } = groupBody(box, scale);
+        placed.set(n.path, { box, body, banded });
+        const frame = box.width * box.height - body.width * body.height;
+        moved = Math.max(moved, Math.abs(frame - (frames.get(n.path) ?? 0)));
+        frames.set(n.path, frame);
+        place(n.children, body);
+      });
+    };
+    place(nodes, { x: 0, y: 0, width, height });
+    if (moved < 1) break;
+  }
+  return placed;
+}
+export {
+  BAND,
+  BODY_SHARE,
+  FRAME_MARGIN,
+  groupBody,
+  layoutTreemap,
+  squarify
+};
+//# sourceMappingURL=treemap-layout.js.map

package/dist/components/treemap-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/treemap-layout.ts"],"sourcesContent":["// Where `Treemap` draws each node — a pure function of the nodes, the chart's size and the\n// text size, with no recharts in it (0.52 code review of treemap.tsx, findings 1 and 8).\n//\n// recharts lays nested data out itself, edge to edge, and 0.52 first made the groups' room\n// afterwards: a group's cell took its band and margin out of its rectangle and each child's\n// cell SQUEEZED the rectangle recharts gave it into what was left. Two faults followed.\n// A fixed 23px is a different share of every group, so a €100 tile in a 61px group was\n// drawn at two thirds of a €100 tile in a 300px one — in a chart whose one promise is that\n// area is share. And the squeeze ran through a cache the group's cell wrote during render\n// for its children's cells to read, which held only because recharts renders a group\n// before its children.\n//\n// So the layout is made here, up front: squarified as recharts does it, with each group\n// asking for its tiles' area PLUS its frame's, and its tiles laid out in its body. A\n// frame's area depends on the rectangle it gets, so the layout is run again with each\n// group's frame as measured until no frame moves by a pixel — two or three rounds.\n\nexport interface Box {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\n/** What the layout needs of a node: its key, its value, and a group's nodes. */\nexport interface LayoutNode {\n  path: string;\n  size: number;\n  children?: readonly LayoutNode[];\n}\n\n/** A node as drawn: its rectangle, and for a group the body its nodes fill and whether\n *  its band is drawn. Whole pixels, on shared edges, so neighbours meet without a seam. */\nexport interface Placed {\n  box: Box;\n  body?: Box;\n  banded?: boolean;\n}\n\nconst PHI = (1 + Math.sqrt(5)) / 2;\n\n/**\n * A group's band, in px at Normal, × the text size's scale: the 20px floor a tile keeps\n * for its own name, so the group's name sits in it as a tile's does in a tile.\n */\nexport const BAND = 20;\n/**\n * The frame's margin round its body, in px. Each tile keeps its 2px gutter, half of it\n * inside the tile, so 3 leaves one pixel of the frame's own colour between the group's\n * gutter and its tiles' — the frame reads as one outline round the group, not as a gutter\n * that happens to be wider.\n */\nexport const FRAME_MARGIN = 3;\n/**\n * The least of a group's height its body keeps under the band: 1/φ. At Normal that is a\n * group of 61px (20 band + 3 margin = 0.382 of it), whose body of 38px still holds a\n * tile's name and its second line (the note's 36px floor) — so a single row of tiles under\n * the band keeps both. A smaller group draws no band, and its name is in its tiles'\n * accessible names and its tooltip rather than over their area. Since the frame's area is\n * given to the group (above), this bounds the frame's share of the picture, not the tiles'.\n */\nexport const BODY_SHARE = 1 / PHI;\n\n/** A group drawn at `box`: whether it has the room for its band (see {@link BODY_SHARE};\n *  and 44px across, the floor of a word), and the body its nodes are drawn into. */\nexport function groupBody(box: Box, scale: number): { banded: boolean; body: Box } {\n  const band = BAND * scale;\n  const margin = Math.min(FRAME_MARGIN, Math.floor(box.width / 4), Math.floor(box.height / 4));\n  const banded = box.width >= 44 * scale && box.height - band - margin >= box.height * BODY_SHARE;\n  const top = banded ? band : margin;\n  return {\n    banded,\n    body: {\n      x: box.x + margin,\n      y: box.y + top,\n      width: Math.max(0, box.width - 2 * margin),\n      height: Math.max(0, box.height - top - margin),\n    },\n  };\n}\n\n/** The worst aspect ratio in a row of `area` along `side`, against the target `ratio`. */\nfunction worst(area: number, min: number, max: number, side: number, ratio: number): number {\n  const along = side * side;\n  const across = area * area;\n  if (across === 0 || min === 0) return Infinity;\n  return Math.max((along * max * ratio) / across, across / (along * min * ratio));\n}\n\n/**\n * Bruls, Huizing and van Wijk's squarified layout, as recharts runs it: `weights` share\n * out `rect` in order, a row at a time along its shorter side, and a row closes when the\n * next node would make its worst tile further from φ:1 (recharts' default ratio). Returns\n * one rectangle per weight, in order, in fractional pixels.\n */\nexport function squarify(weights: readonly number[], rect: Box, ratio = PHI): Box[] {\n  const out: Box[] = weights.map(() => ({ x: rect.x, y: rect.y, width: 0, height: 0 }));\n  const sum = weights.reduce((acc, w) => acc + Math.max(0, w), 0);\n  if (!(sum > 0) || rect.width <= 0 || rect.height <= 0) return out;\n  const areas = weights.map((w) => (Math.max(0, w) * rect.width * rect.height) / sum);\n  let { x, y, width, height } = rect;\n  let i = 0;\n  while (i < areas.length) {\n    const side = Math.min(width, height);\n    let rowArea = 0;\n    let min = Infinity;\n    let max = 0;\n    let best = Infinity;\n    let j = i;\n    while (j < areas.length) {\n      const a = areas[j]!;\n      const score = worst(rowArea + a, Math.min(min, a), Math.max(max, a), side, ratio);\n      if (j > i && score > best) break;\n      rowArea += a;\n      min = Math.min(min, a);\n      max = Math.max(max, a);\n      best = score;\n      j += 1;\n    }\n    // The last row takes what is left, so rounding never leaves a sliver unpainted.\n    const last = j === areas.length;\n    if (side === width) {\n      // A row along the top, as wide as the space.\n      const thick = last ? height : rowArea / width;\n      let at = x;\n      for (let k = i; k < j; k++) {\n        const len = k === j - 1 ? x + width - at : (areas[k]! / rowArea) * width;\n        out[k] = { x: at, y, width: len, height: thick };\n        at += len;\n      }\n      y += thick;\n      height -= thick;\n    } else {\n      // A column at the left, as tall as the space.\n      const thick = last ? width : rowArea / height;\n      let at = y;\n      for (let k = i; k < j; k++) {\n        const len = k === j - 1 ? y + height - at : (areas[k]! / rowArea) * height;\n        out[k] = { x, y: at, width: thick, height: len };\n        at += len;\n      }\n      x += thick;\n      width -= thick;\n    }\n    i = j;\n  }\n  return out;\n}\n\n/** Whole pixels on the EDGES: neighbours share an edge, so they round it alike. */\nfunction snap(b: Box): Box {\n  const x = Math.round(b.x);\n  const y = Math.round(b.y);\n  return { x, y, width: Math.round(b.x + b.width) - x, height: Math.round(b.y + b.height) - y };\n}\n\n/** The rounds the frames get to settle; three is usual, more only when a band switches. */\nconst ROUNDS = 8;\n\n/**\n * Every node of `nodes` placed in a `width` × `height` chart, by path.\n *\n * Each tile's area is its value's share of what is left for tiles once the frames have\n * theirs — the same density in every group and at the top. A group asks for its tiles'\n * area and its own frame's (band and margin, as {@link groupBody} measures them on the\n * rectangle it got last round), so its body holds exactly its tiles.\n */\nexport function layoutTreemap(\n  nodes: readonly LayoutNode[],\n  width: number,\n  height: number,\n  scale: number,\n): Map<string, Placed> {\n  const total = nodes.reduce((acc, n) => acc + n.size, 0);\n  const frames = new Map<string, number>();\n  let placed = new Map<string, Placed>();\n  for (let round = 0; round < ROUNDS; round++) {\n    const framed = [...frames.values()].reduce((acc, a) => acc + a, 0);\n    const spare = width * height - framed;\n    // Frames that would take the whole chart (a tiny chart of many groups) leave nothing\n    // to share; the tiles then take the density they would have without frames.\n    const density = total > 0 ? (spare > 0 ? spare : width * height) / total : 0;\n    const need = (n: LayoutNode): number =>\n      n.children ? (frames.get(n.path) ?? 0) + n.children.reduce((acc, c) => acc + need(c), 0) : n.size * density;\n    let moved = 0;\n    placed = new Map();\n    const place = (list: readonly LayoutNode[], rect: Box) => {\n      const boxes = squarify(\n        list.map((n) => need(n)),\n        rect,\n      );\n      list.forEach((n, i) => {\n        const box = snap(boxes[i]!);\n        if (!n.children) {\n          placed.set(n.path, { box });\n          return;\n        }\n        const { banded, body } = groupBody(box, scale);\n        placed.set(n.path, { box, body, banded });\n        const frame = box.width * box.height - body.width * body.height;\n        moved = Math.max(moved, Math.abs(frame - (frames.get(n.path) ?? 0)));\n        frames.set(n.path, frame);\n        place(n.children, body);\n      });\n    };\n    place(nodes, { x: 0, y: 0, width, height });\n    if (moved < 1) break;\n  }\n  return placed;\n}\n"],"mappings":"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","names":[]}

package/dist/components/treemap.d.ts

@@ -1,6 +1,9 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { type ChartEdges } from "./chart-edge.js";
 import { type Direction } from "../lib/direction.js";
 import { type ChartHeight } from "./chart-height.js";
+import { type LabelOverride } from "../i18n/kit-labels.js";
+import { type TreemapLabels } from "./treemap-labels.js";
 /**
  * One tile.
  *
@@ -11,13 +14,19 @@ import { type ChartHeight } from "./chart-height.js";
  */
 export interface TreemapNode {
     /** Stable key, handed back by {@link TreemapProps.onNodeClick} and
-     *  {@link TreemapProps.nodeNote}. Names can collide; ids must not. */
+     *  {@link TreemapProps.nodeNote}. Names can collide; ids must not among a group's own
+     *  nodes (or the top's). A group and a tile inside it may share one — chain 12 and shop
+     *  12 from two tables — and `onNodeClick`'s `groups` tells them apart (0.52). */
     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. */
+     *  vanishes silently between two views of the same data is a bug report.
+     *
+     *  A GROUP's own `value` is not read: its area is its drawn children's together. Pass
+     *  that sum — the field stays required so that every reader of a `TreemapNode[]` keeps
+     *  a `number`. */
     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
@@ -25,42 +34,122 @@ export interface TreemapNode {
      *  does `CHART_ROLES.other` (`var(--chart-muted)`), the colour for a "rest" bucket,
      *  which should not wrap round to a hue the reader matches to a real node;
      *  anything else (another var, a `color-mix()`) gets `currentColor` ink, because
-     *  there is nothing to measure — set `labelColor` then. */
+     *  there is nothing to measure — set `labelColor` then.
+     *
+     *  On a group, the colour of every tile inside it that sets none (0.52): keksdose's
+     *  "hue = chain" is a `fill` per chain. A group left without one takes the ramp by its
+     *  index, as a tile does, and hands that down; its frame is drawn in the page's own
+     *  colours whatever it is. */
     fill?: string;
     /** The label's ink, for a `fill` the kit cannot measure (a `var()` or `color-mix()`):
      *  keksdose's recency plot fills with `color-mix(in srgb, var(--chart-1) N%,
      *  transparent)`, where `currentColor` put dark page text on full-strength indigo
-     *  (~1.5:1). Wins over the measured ink when given. */
+     *  (~1.5:1). Wins over the measured ink when given. A tile that takes its group's
+     *  `fill` takes the group's `labelColor` with it; one with a `fill` of its own, or one
+     *  that `shade` turns into another colour, is measured again. */
     labelColor?: string;
+    /**
+     * The tile's colour strength, 0–1 (0.52): its `fill` mixed into the card's colour
+     * (`--bg-surface`) as a concrete hex, `1` the full hue. For a second, ordered quantity
+     * on top of the hue — keksdose's recency steps (1, 0.78, 0.55) over the chain's hue —
+     * without a `color-mix()`: the result is measured like any hex, so the label ink stays
+     * automatic and no `labelColor` is needed. keksdose found a tile under ~0.55 stops
+     * reading as its hue and passes for the muted "other" (#642).
+     *
+     * Only a fill the kit can measure is shaded (a hex, a bare `var(--chart-N)` or another
+     * bare token), and only on a page that declares `--bg-surface` as a hex; anything else
+     * keeps its full hue. On a group, the default for its tiles, as `fill` is.
+     */
+    shade?: number;
+    /**
+     * Makes this node a GROUP (0.52, keksdose dev #642: "Is there already a distinction
+     * between shop and chain?"): a labelled frame, its name in a band along the top, its
+     * tiles laid out inside it by the map's own layout, each at its share of the whole
+     * picture (see "Groups: a frame round their tiles"). Groups nest. A group with nothing
+     * drawable inside is not drawn; an empty array is a tile.
+     *
+     * The frame is in the page's colours (the well, `--bg-surface-2`, under
+     * `--text-primary`, at least 7.4:1 in every preset and contrast), and under More
+     * contrast it is outlined in `--chart-ink` as a pale tile is. Its band is drawn only
+     * where the group has the room for it — see `TreemapCell`.
+     */
+    children?: readonly TreemapNode[];
 }
 /**
  * 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.
+ *
+ * The root is a `role="figure"` (0.52, refactor audit 2026-10-30, DSP-5): name it with
+ * `aria-label` ("Spending by category"), and say what it shows with {@link
+ * TreemapProps.description}.
  */
 export interface TreemapProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
-    data: TreemapNode[];
+    data: readonly 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.
+     * A tile's and a group's accessible name (`labels.tile`, `labels.group`, 0.52) says the
+     * value too, asked of the formatter as the tooltip asks it, share and all, and its text
+     * is used; markup is said as the bare number. The name says the share itself, so a
+     * formatter that writes it into its text has it said twice.
+     *
+     * Default: the bare number through `Intl.NumberFormat` in the provider's locale (0.52,
+     * DOC-10: before, the runtime's). A host with a currency passes this — the kit knows
+     * none.
      */
     valueFormatter?: (value: number, share: number | undefined) => ReactNode;
+    /**
+     * What the map SHOWS, in a sentence — "Rent is three fifths of the month." — the
+     * figure's accessible description (0.52, DSP-5). Not drawn; a caption the eye should
+     * read too belongs in the page.
+     */
+    description?: string;
+    /** Per-map strings over `<UiKitProvider labels={{ treemap }}>`. */
+    labels?: LabelOverride<TreemapLabels>;
     /** Chart height: a CSS length (`"20rem"`, `"min(20rem, 50dvh)"`), a Tailwind class,
      *  or px. Default `"20rem"` — 320 px at Normal, growing with the text size like the
      *  labels in the tiles (0.32, docs/text-size-harmonization.md §10.10). */
     height?: ChartHeight;
-    /** 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;
+    /**
+     * A tile was activated — by click, or by Enter/Space on a focused tile. Setting this
+     * makes every tile a `role="button"`.
+     *
+     * Either way every tile is reachable (0.52, DSP-5): ONE tab stop for the map, the
+     * arrows (←/→ along the reading direction, ↓/↑), Home and End between tiles in the
+     * order given, each named "name: value (share)" (`labels.tile`) — a `role="img"` to read
+     * when nothing listens, as PieChart's slices. Before, a map nobody clicked was nothing
+     * to a screen reader, and a clickable tile said its name alone, one tab stop each.
+     *
+     * In a map with groups (`TreemapNode.children`, 0.52) the walk is the data's own order,
+     * depth first: a group's frame, then its tiles, then the next group. A frame is named
+     * by `labels.group` ("Interspar, group: €1,240 (40%)"), a tile inside one by
+     * `labels.inGroup` round its own name ("Rankweil: €412 (12%), in Interspar"). Only
+     * tiles reach this callback (a frame reaches `onGroupClick`); a tile inside a group is
+     * handed a third argument, the ids of its groups, outermost first. Optional in the type,
+     * so a forwarder calling this with two arguments still type-checks — and absent for a
+     * tile at the top, so a flat map calls it exactly as before.
+     */
+    onNodeClick?: (id: string, name: string, groups?: readonly string[]) => void;
+    /**
+     * A group's frame was activated — by click on its band or margin, or by Enter/Space on
+     * the focused frame (0.52). Setting this makes every frame a `role="button"`; without it
+     * a frame is a `role="img"`, still a stop of the map's keyboard so its total is heard.
+     * `groups` as for {@link TreemapProps.onNodeClick}: the groups round this one, passed
+     * only for a group inside another.
+     */
+    onGroupClick?: (id: string, name: string, groups?: readonly 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.
+     *
+     * Every tile is tagged as a whole too, clickable or not (0.52): its accessible name
+     * (`labels.tile`) says the name and the value, in an attribute a host's redaction
+     * reaches only through the tag.
      */
     redactNames?: boolean;
     /**
@@ -72,6 +161,8 @@ export interface TreemapProps extends Omit<ComponentPropsWithoutRef<"div">, "chi
      * 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.
+     *
+     * Asked for tiles only: a group's band holds its name and nothing else.
      */
     nodeNote?: (id: string) => string | undefined;
     /**
@@ -80,6 +171,9 @@ export interface TreemapProps extends Omit<ComponentPropsWithoutRef<"div">, "chi
      * 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.
+     *
+     * With groups, the tiles are counted across them in the order given, depth first; a
+     * group left with none is not drawn, and a group's frame is not a tile.
      */
     maxTiles?: number;
     /**
@@ -109,8 +203,9 @@ export interface TreemapProps extends Omit<ComponentPropsWithoutRef<"div">, "chi
      */
     edges?: TreemapEdges;
 }
-/** {@link TreemapProps.edges}. */
-export type TreemapEdges = "auto" | "uniform" | "contrast";
+/** {@link TreemapProps.edges}. The switch itself is chart-edge's `useEdgesInForce`,
+ *  which SeriesChart's bars and areas follow too since 0.52 (DSP-18). */
+export type TreemapEdges = ChartEdges;
 /**
  * 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
@@ -133,14 +228,28 @@ export interface TreemapCellProps {
     /** See {@link TreemapNode.labelColor}; recharts hands each node's fields to its cell. */
     labelColor?: string;
     id?: string;
-    onNodeClick?: (id: string, name: string) => void;
+    /** Called with `groups` as its third argument when the cell has any; see
+     *  {@link TreemapProps.onNodeClick}. */
+    onNodeClick?: (id: string, name: string, groups?: readonly string[]) => void;
+    /** A group's cell's click; see {@link TreemapProps.onGroupClick}. */
+    onGroupClick?: (id: string, name: string, groups?: readonly string[]) => void;
+    /** The ids of the groups round the node, outermost first. `Treemap` puts it on every
+     *  node it hands recharts; a cell drawn in a caller's own map has it if the data does. */
+    groups?: readonly string[];
+    /** The node's place in the tree, which `Treemap` puts on every node it hands recharts:
+     *  its key in the map's keyboard, where an id may repeat between a group and a tile. */
+    path?: string;
+    /** Filled in by recharts for a GROUP: the nodes laid out inside it. A cell with
+     *  children draws a frame, not a tile (0.52). */
+    children?: readonly object[] | null;
     redactNames?: boolean;
     nodeNote?: (id: string) => string | undefined;
     /** The page's reading direction, which `Treemap` reads off its own root. In `rtl`
      *  the label stands in the tile's top RIGHT corner and is shaped right-to-left, so a
      *  clipped name ends in its ellipsis on the reading end. Default `ltr`. */
     dir?: Direction;
-    /** See {@link TreemapProps.edges}. Default `auto`. */
+    /** See {@link TreemapProps.edges}. Default `auto`. Read by a cell drawn on its own; a
+     *  `Treemap` hands its tiles its own `edges`. */
     edges?: TreemapEdges;
 }
 /**
@@ -153,17 +262,31 @@ export interface TreemapCellProps {
  * 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.
+ *
+ * Inside a `Treemap` it is one stop of the map's keyboard, named with its value and
+ * share (0.52); drawn on its own it is a stop only as a button (`onNodeClick`), named by
+ * `name`.
+ *
+ * A node with `children` is a GROUP (0.52): the cell draws a frame in the well's colour
+ * (`--bg-surface-2`), with the group's name in a band along its top where the group has
+ * the room (61px at Normal, treemap-layout's `BODY_SHARE`). Inside a `Treemap` its tiles are laid out
+ * in the frame's body; in a caller's own nested recharts `<Treemap>` they are drawn where
+ * recharts lays them, over the frame — only `Treemap` makes the room.
  */
-export declare function TreemapCell({ depth, x, y, width, height, name, fill, labelColor, id, onNodeClick, redactNames, nodeNote, dir, edges: edgesProp, }: TreemapCellProps): import("react").JSX.Element | null;
+export declare function TreemapCell(props: TreemapCellProps): import("react").JSX.Element;
 /**
  * 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.
+ * value; every tile is a keyboard stop named with its value and share (see
+ * `onNodeClick`), and `onNodeClick` turns the tiles into buttons.
+ *
+ * A node with `children` is a group (0.52): a labelled frame with its tiles inside, in
+ * its colour unless they set their own — see {@link TreemapNode.children}.
  *
  * 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`.
  */
-export declare function Treemap({ data, valueFormatter, height, onNodeClick, redactNames, nodeNote, maxTiles, colors, edges, style, ...rest }: TreemapProps): import("react").JSX.Element | null;
+export declare function Treemap({ data, valueFormatter, height, onNodeClick, onGroupClick, redactNames, nodeNote, maxTiles, colors, edges, description, labels: labelsProp, style, ...rest }: TreemapProps): import("react").JSX.Element | null;