makersclaw 0.8.0 → 0.8.2

package/registry/blocks/sum-bar/demo.jsx

@@ -0,0 +1,110 @@
+"use client";
+
+// SumBar in every state — the gallery's and the smoke test's surface. Not
+// installed into apps: `makersclaw add sum-bar` lays index.js, sum-bar.jsx and
+// sum-model.js only.
+//   A project's score   two reds, the sum below both caps; then a cap that
+//                       bites (the sum 56, held at 49); then one red holding a
+//                       74.
+//   Nothing taken off   a full bar.
+//   Pressable           onSelect: every cut is a button, one selected.
+//   Sizes, legend       sm, md, lg; the legend; the receipt turned off.
+//   Odd input           a negative cost, a cost past the total, text for a
+//                       cost, a zero total.
+//   Narrow and wide     a 320 px container and a wide one.
+//   Loading, failed.
+import { useState } from "react";
+import { SumBar } from "../components/blocks/sum-bar";
+
+const BANDS = [
+  { from: 0, to: 50, tone: "danger", label: "off track" },
+  { from: 50, to: 75, tone: "warning", label: "at risk" },
+  { from: 75, to: 100, tone: "success", label: "on track" },
+];
+const POSTS = [
+  { at: 74, label: "cap 74 · one red" },
+  { at: 49, label: "cap 49 · two reds" },
+];
+const SIGNALS = [
+  { id: "schedule", label: "Schedule", cost: 22, tone: "danger" },
+  { id: "budget", label: "Budget", cost: 25, tone: "danger" },
+  { id: "late", label: "Late work", cost: 5, tone: "warning" },
+  { id: "blocked", label: "Blocked", cost: 8, tone: "warning" },
+  { id: "activity", label: "Activity", cost: 0 },
+  { id: "client", label: "Client", cost: 5, tone: "warning" },
+];
+const CAPPED = [
+  { id: "schedule", label: "Schedule", cost: 14, tone: "danger" },
+  { id: "budget", label: "Budget", cost: 8, tone: "warning" },
+  { id: "late", label: "Late work", cost: 8, tone: "warning" },
+  { id: "blocked", label: "Blocked", cost: 10, tone: "danger" },
+  { id: "activity", label: "Activity", cost: 4, tone: "warning" },
+];
+const ONE_RED = [
+  { id: "blocked", label: "Blocked", cost: 8, tone: "danger" },
+  { id: "client", label: "Client", cost: 0 },
+];
+
+function Section({ title, note, children }) {
+  return (
+    <section className="grid min-w-0 gap-2">
+      <h2 className="text-sm font-semibold">{title}</h2>
+      {note ? <p className="text-xs text-muted-foreground">{note}</p> : null}
+      {children}
+    </section>
+  );
+}
+
+export default function Demo() {
+  const [on, setOn] = useState("budget");
+  return (
+    <div className="grid min-w-0 gap-8 p-4">
+      <Section title="Two reds: the sum is below both caps" note="100 − 22 − 25 − 5 − 8 − 0 − 5 = 35. The caps change nothing here.">
+        <SumBar label="Website rebuild, score sheet" size="lg" parts={SIGNALS} result={35} posts={POSTS} bands={BANDS} unit="points" />
+      </Section>
+
+      <Section title="A cap that bites" note="The sum is 56; two reds hold it at 49. The stretch between is dotted.">
+        <SumBar label="Online banking help centre, score sheet" size="lg" parts={CAPPED} result={49} posts={POSTS} bands={BANDS} />
+      </Section>
+
+      <Section title="One red holding a 74" note="Only 8 points lost, yet the cap says 74.">
+        <SumBar label="Mortgage calculator copy, score sheet" parts={ONE_RED} result={74} posts={POSTS} bands={BANDS} />
+      </Section>
+
+      <Section title="Nothing taken off">
+        <SumBar label="Launch campaign, score sheet" parts={[{ id: "a", label: "Schedule", cost: 0 }, { id: "b", label: "Budget", cost: 0 }]} posts={POSTS} bands={BANDS} />
+        <SumBar label="No parts at all" parts={[]} />
+      </Section>
+
+      <Section title="Pressable" note="Every cut is a button. The pressed one is ringed.">
+        <SumBar label="Press a cut" parts={SIGNALS} result={35} selected={on} onSelect={(p) => setOn(p.id)} bands={BANDS} legend />
+        <p className="text-xs text-muted-foreground">Pressed: {SIGNALS.find((p) => p.id === on)?.label}</p>
+      </Section>
+
+      <Section title="Sizes, no receipt" note="sm and md under a title, without the written sum.">
+        <SumBar size="sm" label="Small" parts={CAPPED} result={49} receipt={false} />
+        <SumBar size="md" label="Medium" parts={CAPPED} result={49} receipt={false} />
+      </Section>
+
+      <Section title="Small cuts" note="Under 5% wide: the cost is in the tooltip and the receipt.">
+        <SumBar label="Small cuts" parts={[{ id: "a", label: "Late", cost: 3, tone: "warning" }, { id: "b", label: "Blocked", cost: 2, tone: "warning" }, { id: "c", label: "Client", cost: 1 }]} bands={BANDS} />
+      </Section>
+
+      <Section title="Odd input" note="A negative cost, a cost past the total, text for a cost, a zero total.">
+        <SumBar label="Odd costs" parts={[{ id: "a", label: "Negative", cost: -5 }, { id: "b", label: "Text", cost: "12" }, { id: "c", label: "Past the total", cost: 400, tone: "danger" }, { id: "d", label: "Nothing", cost: "n/a" }]} />
+        <SumBar label="Zero total" total={0} parts={[{ id: "a", label: "A", cost: 10 }]} />
+      </Section>
+
+      <Section title="Narrow (a 320 px container)">
+        <div className="w-80 max-w-full">
+          <SumBar label="Narrow" parts={SIGNALS} result={35} posts={POSTS} bands={BANDS} legend />
+        </div>
+      </Section>
+
+      <Section title="Loading, failed">
+        <SumBar label="Loading" status="loading" />
+        <SumBar label="Failed" status="failed" error="The check could not be read." onRetry={() => {}} />
+      </Section>
+    </div>
+  );
+}

package/registry/blocks/sum-bar/index.js

@@ -0,0 +1,5 @@
+// The SumBar block — `makersclaw add sum-bar`. Fixed: compose it through its
+// props (README.md beside this file). The model's helpers are plain
+// functions; they work on the server too.
+export { SumBar } from "./sum-bar";
+export { bandsOf, costOf, cutsOf, labelledCuts, lostOf, postsOf, receiptOf, resultOf, sumWords, totalOf } from "./sum-model";

package/registry/blocks/sum-bar/sum-bar.jsx

@@ -0,0 +1,209 @@
+"use client";
+
+import { Button, Notice, Skeleton, cx } from "../../ui";
+import { bandsOf, cutsOf, labelledCuts, postsOf, receiptOf, resultOf, sumWords } from "./sum-model";
+
+// A total with its parts cut out of it. The bar runs from 0 to the total;
+// what is left is solid, each part's cost is a hatched block cut from the
+// top end downward, and a post stands where a rule holds the result down (a
+// cap). Under it, the sum written out so no number is taken on trust.
+//
+// Props in, one callback out (`onSelect`); the block imports only React and
+// the kit, reads no data and works nothing out beyond placing what it is
+// given. Positions are percentages, so the server draws what the browser
+// draws. README.md beside this file lists every prop.
+
+// Literal class names, so Tailwind sees every one of them.
+const CUT = {
+  neutral: "border-border text-muted-foreground bg-muted",
+  info: "border-info text-info bg-info/10",
+  warning: "border-warning text-warning bg-warning/10",
+  danger: "border-destructive text-destructive bg-destructive/10",
+};
+const BAND = { success: "bg-success", warning: "bg-warning", danger: "bg-destructive", info: "bg-info", neutral: "bg-muted-foreground" };
+const SIZE = { sm: "h-6", md: "h-9", lg: "h-12" };
+
+const HATCH = { backgroundImage: "repeating-linear-gradient(135deg, currentColor 0 1px, transparent 1px 5px)" };
+const DOTS = { backgroundImage: "repeating-linear-gradient(90deg, currentColor 0 2px, transparent 2px 6px)" };
+
+const say = (n) => (Number.isInteger(n) ? String(n) : String(Math.round(n * 1000) / 1000));
+
+/**
+ * The bar.
+ *
+ * Props: `total` (100), `parts` `[{ id, label, cost, tone?, note? }]` (taken
+ * off in the order given, from the top end), `result` (the number after a
+ * rule held it down; default total minus the costs), `posts` `[{ at, label,
+ * tone? }]`, `bands` `[{ from, to, tone, label? }]`, `selected`, `onSelect(part)`,
+ * `size` (sm | md | lg), `names` (the names under the cuts, default true),
+ * `legend` (a list of the parts under the bar), `receipt` (the written sum,
+ * default true), `unit`, `noun`, `label`, `status`, `error`, `onRetry`,
+ * `className`.
+ */
+export function SumBar({
+  total = 100,
+  parts,
+  result,
+  posts,
+  bands,
+  selected,
+  onSelect,
+  size = "md",
+  names = true,
+  legend = false,
+  receipt = true,
+  unit = "",
+  noun = "point",
+  label = "Score sheet",
+  status = "ready",
+  error,
+  onRetry,
+  className,
+}) {
+  if (status === "loading") {
+    return (
+      <div role="status" aria-label={`${label}, loading`} className={cx("grid gap-2", className)}>
+        <Skeleton className={cx("w-full", SIZE[size] ?? SIZE.md)} />
+        <Skeleton className="h-3 w-2/3" />
+      </div>
+    );
+  }
+  if (status === "failed") {
+    return (
+      <Notice
+        tone="danger"
+        className={className}
+        action={
+          onRetry ? (
+            <Button size="sm" onClick={onRetry}>
+              Try again
+            </Button>
+          ) : undefined
+        }
+      >
+        {error || "The sum could not be read."}
+      </Notice>
+    );
+  }
+
+  const r = resultOf({ total, parts, result });
+  const cuts = cutsOf({ total, parts });
+  const pins = postsOf({ total: r.total, posts });
+  const strips = bandsOf({ total: r.total, bands });
+  const named = names ? labelledCuts(cuts) : [];
+  const keptPct = Math.round((Math.min(r.kept, r.result) / r.total) * 100000) / 1000;
+  const resultPct = Math.round((r.result / r.total) * 100000) / 1000;
+  const sum = receiptOf({ total, parts, result, unit });
+  const inside = resultPct >= 12;
+  const words = sumWords({ total, parts, result, posts, noun });
+
+  return (
+    <div role="group" aria-label={label} className={cx("@container grid min-w-0 gap-2", className)}>
+      <div className="relative min-w-0 pt-6">
+        {pins.map((p) => (
+          <span
+            key={`post-label-${p.index}`}
+            aria-hidden="true"
+            className={cx("absolute top-0 left-(--at) -translate-x-1/2 whitespace-nowrap text-[11px] font-semibold leading-none", p.tone === "danger" ? "text-destructive" : "text-muted-foreground")}
+            style={{ "--at": `${p.pct}%` }}
+          >
+            {p.label}
+          </span>
+        ))}
+        <div className={cx("relative overflow-hidden rounded-[4px] border border-border bg-muted", SIZE[size] ?? SIZE.md)} role="img" aria-label={words}>
+          {resultPct > 0 ? (
+            <span aria-hidden="true" className="absolute inset-y-0 left-0 w-(--w) bg-foreground" style={{ "--w": `${Math.min(keptPct, resultPct)}%` }} />
+          ) : null}
+          {r.held > 0 ? (
+            <span
+              aria-hidden="true"
+              title={`Held down by a rule: ${say(r.kept)} on the sum, ${say(r.result)} after it`}
+              className="absolute inset-y-0 left-(--at) w-(--width) text-muted-foreground"
+              style={{ ...DOTS, "--at": `${resultPct}%`, "--width": `${Math.round((r.held / r.total) * 100000) / 1000}%` }}
+            />
+          ) : null}
+          {inside ? (
+            <span aria-hidden="true" className="absolute inset-y-0 left-2 flex items-center text-sm font-semibold tabular-nums text-background">
+              {say(r.result)}
+            </span>
+          ) : null}
+          {cuts
+            .filter((c) => c.cut)
+            .map((c) => {
+              const tone = CUT[c.tone] ?? CUT.neutral;
+              const on = selected != null && c.id === selected;
+              const className = cx("absolute inset-y-0 left-(--at) w-(--width) overflow-hidden border-x outline-none focus-visible:ring-2 focus-visible:ring-ring", tone, on && "ring-2 ring-ring");
+              const style = { "--at": `${c.leftPct}%`, "--width": `${c.widthPct}%` };
+              const inner = (
+                <>
+                  <span aria-hidden="true" className="absolute inset-0 opacity-60" style={HATCH} />
+                  {c.widthPct >= 5 ? <span className="relative flex h-full items-center justify-center text-[11px] font-semibold tabular-nums text-foreground">−{say(c.cost)}</span> : null}
+                </>
+              );
+              return onSelect ? (
+                <button key={c.id ?? c.index} type="button" aria-label={`${c.label ?? "Part"}, took ${say(c.cost)}`} aria-pressed={on} title={`${c.label ?? "Part"} took ${say(c.cost)}`} className={className} style={style} onClick={() => onSelect(c)}>
+                  {inner}
+                </button>
+              ) : (
+                <span key={c.id ?? c.index} title={`${c.label ?? "Part"} took ${say(c.cost)}`} className={className} style={style}>
+                  {inner}
+                </span>
+              );
+            })}
+          {pins.map((p) => (
+            <span key={`post-${p.index}`} aria-hidden="true" className={cx("absolute inset-y-0 left-(--at) w-0 border-l-2 border-dashed", p.tone === "danger" ? "border-destructive" : "border-muted-foreground")} style={{ "--at": `${p.pct}%` }} />
+          ))}
+          {!inside && resultPct > 0 ? (
+            <span aria-hidden="true" className="absolute inset-y-0 left-(--at) ml-1.5 flex items-center text-sm font-semibold tabular-nums" style={{ "--at": `${resultPct}%` }}>
+              {say(r.result)}
+            </span>
+          ) : null}
+        </div>
+        {strips.length ? (
+          <div className="relative mt-1 h-1.5 overflow-hidden rounded-[2px]" aria-hidden="true">
+            {strips.map((b) => (
+              <span key={b.index} className={cx("absolute inset-y-0 left-(--at) w-(--width)", BAND[b.tone] ?? BAND.neutral)} style={{ "--at": `${b.leftPct}%`, "--width": `${b.widthPct}%` }} />
+            ))}
+          </div>
+        ) : null}
+        {strips.some((b) => b.label) ? (
+          <div className="relative mt-1 h-4 text-[11px] text-muted-foreground" aria-hidden="true">
+            {strips.map((b) =>
+              b.label ? (
+                <span key={b.index} className="absolute top-0 left-(--at) -translate-x-1/2 whitespace-nowrap" style={{ "--at": `${b.leftPct + b.widthPct / 2}%` }}>
+                  {b.label}
+                </span>
+              ) : null,
+            )}
+          </div>
+        ) : null}
+        {named.length ? (
+          <div className="relative mt-1 hidden h-4 text-[11px] text-muted-foreground @lg:block" aria-hidden="true">
+            {named.map((c) => (
+              <span key={c.id ?? c.index} className="absolute top-0 left-(--at) -translate-x-1/2 whitespace-nowrap" style={{ "--at": `${c.leftPct + c.widthPct / 2}%` }}>
+                {c.label}
+              </span>
+            ))}
+          </div>
+        ) : null}
+      </div>
+      {legend && cuts.length ? (
+        <ul className="m-0 grid list-none gap-1 p-0 text-xs @md:grid-cols-2">
+          {cuts.map((c) => (
+            <li key={c.id ?? c.index} className="flex min-w-0 items-baseline gap-2">
+              <span className="truncate">{c.label}</span>
+              <span className="ml-auto shrink-0 tabular-nums text-muted-foreground">{c.cost > 0 ? `−${say(c.cost)}` : "0"}</span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {receipt ? (
+        <p className="m-0 text-xs tabular-nums text-muted-foreground">
+          <span className="font-medium text-foreground">{sum.text}</span>
+          {sum.held > 0 ? <span> · a rule holds it down by {say(sum.held)}</span> : null}
+          {sum.raised > 0 ? <span> · a rule lifts it by {say(sum.raised)}</span> : null}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/sum-bar/sum-model.js

@@ -0,0 +1,126 @@
+// sum-bar: the arithmetic. Plain functions, no React, no clock: they work on
+// the server and in a test.
+//
+// A SUM starts at a total (100) and takes costs off it, one per part. What is
+// left is the result. A rule may hold the result down (a cap): then the result
+// is lower than total minus the costs, and the stretch between the two is
+// "held". The block draws what the app has already worked out; these helpers
+// only place it and say it.
+
+/** A cost: a finite number, never below 0. Anything else counts as 0. */
+export function costOf(value) {
+  const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+const round = (n) => Math.round(n * 1000) / 1000;
+const clampPct = (n) => Math.min(100, Math.max(0, n));
+
+/** The total as a positive number (default 100). */
+export function totalOf(total) {
+  const n = Number(total);
+  return Number.isFinite(n) && n > 0 ? n : 100;
+}
+
+/** Everything the parts cost, together. */
+export function lostOf(parts) {
+  return round((parts ?? []).reduce((sum, p) => sum + costOf(p?.cost), 0));
+}
+
+/**
+ * What is left once the costs are off, and what the result is:
+ * `kept` = total minus the costs (never below 0), `result` = the app's own
+ * number when it gives one (a cap held it down), else `kept`.
+ * `held` is how far a rule pushed the result below `kept`.
+ */
+export function resultOf({ total, parts, result }) {
+  const whole = totalOf(total);
+  const lost = lostOf(parts);
+  const kept = Math.max(0, round(whole - lost));
+  const given = typeof result === "number" && Number.isFinite(result) ? Math.min(Math.max(result, 0), whole) : null;
+  const final = given == null ? kept : round(given);
+  return { total: whole, lost, kept, result: final, held: final < kept ? round(kept - final) : 0, raised: final > kept ? round(final - kept) : 0 };
+}
+
+/**
+ * Each part's place on the bar. The costs are cut out from the total
+ * downward, in the order the parts are given: the first part sits at the top
+ * end. A part that would run below 0 is cut short there. Percentages of the
+ * total.
+ */
+export function cutsOf({ total, parts }) {
+  const whole = totalOf(total);
+  let top = whole;
+  const out = [];
+  for (const [index, p] of (parts ?? []).entries()) {
+    const cost = costOf(p?.cost);
+    const low = Math.max(0, top - cost);
+    out.push({
+      ...p,
+      index,
+      cost,
+      from: round(low),
+      to: round(top),
+      leftPct: round(clampPct((low / whole) * 100)),
+      widthPct: round(clampPct(((top - low) / whole) * 100)),
+      cut: cost > 0,
+    });
+    top = low;
+  }
+  return out;
+}
+
+/** A post's place (a cap, a threshold) as a percentage. Posts out of range are dropped. */
+export function postsOf({ total, posts }) {
+  const whole = totalOf(total);
+  return (posts ?? [])
+    .map((p, index) => ({ ...p, index, at: Number(p?.at) }))
+    .filter((p) => Number.isFinite(p.at) && p.at >= 0 && p.at <= whole)
+    .map((p) => ({ ...p, pct: round(clampPct((p.at / whole) * 100)) }));
+}
+
+/** The coloured bands under the bar (off track, at risk, on track), as percentages. */
+export function bandsOf({ total, bands }) {
+  const whole = totalOf(total);
+  return (bands ?? [])
+    .map((b, index) => ({ ...b, index, from: Number(b?.from), to: Number(b?.to) }))
+    .filter((b) => Number.isFinite(b.from) && Number.isFinite(b.to) && b.to > b.from)
+    .map((b) => {
+      const from = Math.max(0, b.from);
+      const to = Math.min(whole, b.to);
+      return { ...b, leftPct: round(clampPct((from / whole) * 100)), widthPct: round(clampPct(((to - from) / whole) * 100)) };
+    })
+    .filter((b) => b.widthPct > 0);
+}
+
+const num = (n) => (Number.isInteger(n) ? String(n) : String(round(n)));
+
+/**
+ * The receipt, as a sum anyone can check: "100 − 22 − 25 − 5 − 8 − 0 − 5 = 35".
+ * Every part is a term, a part that cost nothing included. When a rule held
+ * the result down: "100 − 44 = 56, held at 49".
+ */
+export function receiptOf({ total, parts, result, unit = "" }) {
+  const r = resultOf({ total, parts, result });
+  const list = parts ?? [];
+  const terms = list.map((p) => ({ id: p?.id ?? p?.label, label: p?.label ?? "", cost: costOf(p?.cost) }));
+  const sum = [num(r.total), ...terms.map((t) => `− ${num(t.cost)}`)].join(" ");
+  const text = r.held > 0 ? `${r.total} − ${num(r.lost)} = ${num(r.kept)}, held at ${num(r.result)}` : list.length ? `${sum} = ${num(r.result)}` : `${num(r.total)} = ${num(r.result)}`;
+  return { ...r, terms, text: unit ? `${text} ${unit}` : text };
+}
+
+/** The whole bar in a sentence for a screen reader. */
+export function sumWords({ total, parts, result, posts, noun = "point" }) {
+  const r = resultOf({ total, parts, result });
+  const list = (parts ?? []).filter((p) => costOf(p?.cost) > 0);
+  const plural = (n) => (n === 1 ? noun : `${noun}s`);
+  const took = list.length ? ` ${list.map((p) => `${p.label ?? "A part"} took ${num(costOf(p.cost))}`).join(", ")}.` : " Nothing was taken off.";
+  const held = r.held > 0 ? ` A rule holds it at ${num(r.result)} where the sum is ${num(r.kept)}.` : "";
+  const pins = (posts ?? []).filter((p) => p?.label).map((p) => `${p.label} at ${num(Number(p.at))}`);
+  return `${num(r.result)} of ${num(r.total)} ${plural(r.total)}.${took}${held}${pins.length ? ` Posts: ${pins.join(", ")}.` : ""}`;
+}
+
+/** Which of the parts to show a name under, when the bar is too short for all of them. */
+export function labelledCuts(cuts, minPct = 7) {
+  return cuts.filter((c) => c.cut && c.widthPct >= minPct);
+}

package/registry/blocks/tier-map/README.md

@@ -0,0 +1,217 @@
+# TierMap
+
+Cards in tiers, from a flat list where each item names its parent.
+
+The first tier is the tops. Press a card and the cards under it open as the
+next tier beneath, joined to it by elbow lines. Press it again and they close.
+**One layer opens at a time**: opening a card closes what was open beside it.
+A card with something under it says how many ("6 serving it") and whether it
+is open.
+
+Items that sit under nothing and are not tops are shown together in an
+*unparented* group, with a note and a slot for an action. Items marked `ghost`
+(drafts: counted nowhere yet) are drawn dashed in a group of their own, and a
+draft can serve another draft.
+
+It draws a structure the app has already worked out. It moves nothing between
+parents and collects nothing. For a person-and-manager chart you pan and zoom
+use `org-chart`; for a free map of ideas `mind-map`; for nodes and edges you
+draw `flow-canvas`; for a table with rows that expand `data-table`.
+
+Born in a goals tracker, on the screen "How goals fit": company goals in the
+first tier, the team goals that serve them beneath. The same block holds
+initiatives under goals, work under a roadmap theme, an account's
+sub-accounts, a strategy map.
+
+```jsx
+import { TierMap } from "../components/blocks/tier-map";   // a Makersclaw app ("./blocks/tier-map" from components/)
+import { TierMap } from "@/components/makersclaw/blocks/tier-map";   // a shadcn project
+```
+
+A client component. No other block and no npm package. The lines are CSS only:
+each tier is a grid of equal columns and the lines are placed in percent of
+its width, so nothing is measured, there is no observer, and the server draws
+what the browser draws. The helpers (`buildTierModel`, `openPath`,
+`togglePath`, `neighbour`, `elbowOf`...) are plain functions and work on the
+server too.
+
+## The data
+
+One row per card, as a table holds them:
+
+```js
+[
+  { id: "c1", title: "Reach $1M in annual revenue", kicker: "Company", by: <Avatar name="Dana" size="xs" />, value: 0.62, tone: "warning", foot: "6 teams serve it" },
+  { id: "s1", parent: "c1", title: "Close the enterprise gap", kicker: "Sales", value: 0.58 },
+  { id: "g1", ghost: true, title: "Grow MRR to $80k", kicker: "Draft" },
+]
+```
+
+- `id` required, unique (a repeat is ignored). Numbers are read as text.
+- `parent` the parent's `id`. Missing, empty, itself, or **an id that is not in
+  the list**: the card has no parent. A **loop** of parents (a names b, b names
+  a) is broken at the card that comes first in the list, which becomes
+  parentless, and never hangs the map.
+- `title` the card's heading. Long words break; nothing overflows.
+- `kicker` the small line above the title ("Sales", "Sub-account").
+- `mark` a node before the kicker (the app's status mark: a `StatusDot`, an
+  icon).
+- `by` a node at the card's top right (an `Avatar`). It sits inside the
+  card's button, so it must not be interactive.
+- `value` 0 to 1: a bar with its percent. Missing, `null` or not a number: no
+  bar. A draft never has one.
+- `tone` the bar's colour, **a status only**: `ink` (default) · `quiet` · `info`
+  · `success` · `warning` · `danger` · `auto` (ink, and success when full).
+- `foot` one muted line at the card's foot.
+- `ghost` `true`: a draft. Dashed, no bar, never in the tiers, never counted.
+  A draft under a draft is drawn under it; a draft under a real card shows
+  `Serves <that card's title>`.
+- `href` the card is also a link (the app's record page).
+- Any other key is kept and handed back to `onSelect` and `renderCard`.
+
+Where a card goes:
+
+| It is | and it goes |
+| --- | --- |
+| a top (named in `tops`, or by default a real card with no parent and kids) | the first tier |
+| under a top, or under a card in the tiers | the tier beneath its parent when that card is open |
+| real, and not reachable from any top | the unparented group |
+| `ghost` | the drafts group |
+
+A card named in `tops` is drawn as a top and nowhere else, even if it names a
+parent. A real card whose parent is a draft is unparented.
+
+## Props
+
+- `items` required. The rows above. With none, `empty` shows.
+- `tops` ids drawn as the first tier, in that order. Default: the real cards
+  with no parent that have kids. Name them yourself to show a top that has
+  nothing under it yet.
+- `topsLabel` the heading over the first tier ("Company · Q3 2026"). A node.
+- `label` the map's name for a reader. Default "Tiers".
+- `childrenLabel` the words after the count on a card with kids: a string
+  ("serving it" gives "6 serving it") or `(count) => text`. Default "below".
+- `openWord` said after the count while a card is open. Default "open".
+- `open` the open path, controlled: an array of ids, **one per tier** (a top,
+  then one of its kids, then one of theirs). An id that cannot be open there
+  ends the path at that point.
+- `defaultOpen` the same, uncontrolled (the initial path). Default none.
+- `onOpenChange(ids)` called with the new path when a card opens or closes.
+- `onSelect(item)` makes a card's title and body a button that selects it (open
+  the record); the count and the chevron then open the tier. Without it the
+  whole card opens the tier, and a card with nothing under it does nothing.
+- `selected` the id marked as current.
+- `unparentedLabel` the group's heading. Default "Not under anything"; the
+  count is added ("Serves nothing · 1"). The group is drawn only when there is
+  something in it.
+- `unparentedNote` a node beside the cards: the note and the action, as you
+  compose them ("Serves nothing: is it work the company needs, or work nobody
+  asked for?" and a Button "Link to a company goal").
+- `ghostLabel` the drafts group's heading. Default "Drafts".
+- `ghostNote` a node under that heading.
+- `servesLabel` the word before the parent's title on a draft that serves a
+  real card. Default "Serves"; `""` leaves the line out.
+- `renderCard(item, state)` replaces the default card. Return nothing (`null`)
+  to keep the default for that card. `state` is `{ id, item, open, selected,
+  count, tier, ghost, serves, pressable, select, toggle, holderProps,
+  primaryProps, toggleProps }`. Spread `holderProps` on your root,
+  `primaryProps` on the element that takes the focus, and `toggleProps` (null
+  when the card has nothing under it) on the button that opens the tier; the
+  arrow keys, the roving focus and the tier lines depend on them.
+- `loading` three placeholder cards.
+- `error` the words for a failure (a string or a node). Pass plain words:
+  the block shows them as given. With `onRetry`, a Try again button.
+- `empty` a node shown when there are no items. Default: "Nothing to map yet".
+- `className` layout: width and margin. Never colour.
+
+`TierCard` is exported too, for a `renderCard` that wants the default card in
+some cases. Helpers, pure and without React: `buildTierModel(items, { tops })`,
+`openPath(model, ids)`, `togglePath(model, path, id)`, `pathTo(model, id)`
+(the ids to open so that a card is on screen), `tiersOf`, `neighbour`,
+`siblingsOf`, `elbowOf`, `centreOf`, `barOf`, `toneOf`, `countText`, `fitKey`,
+`thresholdRem`.
+
+## Example
+
+```jsx
+const [path, setPath] = useState(["c1"]);
+
+<TierMap
+  label="How goals fit"
+  items={goals}                          // [{ id, parent, title, kicker, by, value, tone, ghost }]
+  tops={companyGoalIds}
+  topsLabel="Company · Q3 2026"
+  childrenLabel={(n) => `${n} serving it`}
+  open={path}
+  onOpenChange={setPath}
+  selected={goalId}
+  onSelect={(goal) => router.push(`?goal=${goal.id}`)}
+  unparentedLabel="Serves nothing"
+  unparentedNote={
+    <>
+      <p>Is it work the company needs, or work nobody asked for?</p>
+      <Button size="sm" onClick={linkIt}>Link to a company goal</Button>
+    </>
+  }
+  ghostLabel="Q4 2026 drafts · aligned already"
+/>
+
+// Open the parents of a goal a link points at:
+import { buildTierModel, pathTo } from "../components/blocks/tier-map";
+const path = pathTo(buildTierModel(goals, { tops: companyGoalIds }), goalId);
+```
+
+## Keys
+
+Cards are buttons (a link when they have an `href`), with one tab stop for the
+whole map; the arrows move inside it.
+
+- Left and right: the card beside, in the same tier. Home and End: the first
+  and the last.
+- Down: into the first card under this one (opening it first if it is closed).
+- Up: to the parent.
+- Escape: close this card's tier; on a card that is not open, close its
+  parent's tier and move to the parent.
+- Enter and Space press the focused button: select the card, or open its tier.
+
+## Layout
+
+Everything follows the block's own width (container queries), never the
+window's. A tier sits in **one row of equal columns** when the container has
+11 rem for each of its cards (and for each card of the tiers above it, so a
+tier never sits in a row under one that stacks); cards are at most 26 rem wide
+and centred in their column, and an elbow runs from the open card across to
+each card under it. A tier of more than eight cards always stacks.
+
+Below that, the tier **stacks**: cards go one under another, full width, and
+the cards under an open card hang from a line down their left. In between
+(the parent in a row, its kids too many for one), the line leaves the parent
+and runs left to that rail.
+
+## States drawn
+
+- **Empty**, **one top with nothing under it**, **many tops**, **one open**.
+- **A deep path**: three tiers open, controlled or not.
+- **Very long titles, kickers, feet and names**: they wrap or truncate; no
+  card grows past its column.
+- **Narrow** (a 320 px container): tiers stack, cards full width, a rail.
+- **Wide** (past 1000 px): a tier of six in one row with its elbows.
+- **Unparented group** with its note and action; **drafts group** where a draft
+  serves a draft and one serves a real card.
+- **A loop of parents** (broken), **a parent that is not in the list**, a card
+  that names itself.
+- **Read-only** (no `onSelect`): a card only opens its tier.
+- **Loading**, **failed** (with Try again).
+- Reduced motion: the chevron does not turn.
+
+## Notes for the app that places it
+
+- **Colour is a signal.** The bar is ink unless the goal is behind (warning,
+  danger) or done (success). Work out the status yourself; the block has no
+  words for "behind" and no thresholds.
+- Put the numbers in words as well: `foot` is the place ("Own key results 82%").
+- The count on a card is the cards drawn under it. A draft is never counted.
+- Keep the open path in the address (`?open=c1,s1`) if a member should be able
+  to send the page; `pathTo` gives the path for a card a link points at.
+- It does not fetch. Give it every item of the map at once; a list of hundreds
+  is fine, only the open tiers are drawn.