makersclaw 0.8.0 → 0.8.2

package/registry/blocks/suggestion/suggestion.jsx

@@ -0,0 +1,436 @@
+"use client";
+
+// A value the agent proposes, drawn in pencil: dashed while it is a
+// proposal, solid once kept (the app kit, D15; grown in the CRM as
+// field-suggestion, 0.7.0). Five shapes, one idea — the source is always
+// shown, and a person keeps or drops it:
+//
+//   FieldSuggestion   under a field, with what it holds now
+//   InlineSuggestion  found in place: a dashed chip in the cell it would fill
+//   TextSuggestion    a span of text struck, its replacement beside it
+//   Pencil            the dashed frame for a whole record ("pencil to ink")
+//   SuggestionGroup   the head over several: Keep all, Drop all
+//
+// The verbs are props (Keep/Drop, Apply/Dismiss, Accept/Decline). A keep
+// calls your callback, which runs the app's own declared action, so a
+// keep is the same write the agent would make. Props in, callbacks out;
+// the block never reads a database. Tokens only.
+
+import { useState } from "react";
+import { Button, Icon, IconButton, cx } from "../../ui";
+
+/** "her email signature, Sat 12 Sep" from { from, at }. `at` is a
+ *  "YYYY-MM-DD" day (or anything Date reads); `format(date)` words it,
+ *  default "Sat 12 Sep". */
+export function suggestionSource({ from, at } = {}, format) {
+  if (!from && !at) return "";
+  let when = "";
+  if (at) {
+    const d = typeof at === "string" && /^\d{4}-\d{2}-\d{2}$/.test(at) ? new Date(`${at}T12:00:00Z`) : new Date(at);
+    if (!Number.isNaN(d.getTime())) {
+      when = format ? format(d) : d.toLocaleDateString("en-GB", { weekday: "short", day: "numeric", month: "short", timeZone: "UTC" }).replace(",", "");
+    }
+  }
+  return [from, when].filter(Boolean).join(", ");
+}
+
+const FRAME = {
+  pencil: "border-[1.5px] border-dashed border-foreground/35 bg-card",
+  kept: "border-[1.5px] border-solid border-success/60 bg-card",
+  failed: "border-[1.5px] border-dashed border-destructive/60 bg-card",
+};
+
+/** The dashed frame for any proposal: a kicker ("A NEW DEAL"), a title,
+ *  the reason, your content, your actions. `state` "pencil" (default),
+ *  "kept" (solid) or "failed" (with `error`). */
+export function Pencil({ kicker, title, reason, state = "pencil", error, actions, label, className, children }) {
+  return (
+    <section
+      aria-label={label ?? (typeof title === "string" ? `Suggested: ${title}` : "A suggestion")}
+      className={cx("grid grid-cols-1 min-w-0 gap-2 rounded-lg p-3", FRAME[state] ?? FRAME.pencil, className)}
+    >
+      {kicker ? <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">{kicker}</p> : null}
+      {title ? <div className="min-w-0 text-[15px] font-semibold leading-snug">{title}</div> : null}
+      {children}
+      {reason ? <p className="text-sm text-muted-foreground">{reason}</p> : null}
+      {state === "failed" && error ? (
+        <p role="alert" className="text-sm text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {actions ? <div className="flex flex-wrap items-center gap-2">{actions}</div> : null}
+    </section>
+  );
+}
+
+/**
+ * One proposed value for one field.
+ *
+ *   label      the field's name ("Job title")
+ *   current    what it holds now; empty → "empty now"
+ *   value      the proposed value (text or a node)
+ *   source     { from, at } or a string: where it came from
+ *   onKeep()   async → { ok } | { ok: false, error }
+ *   onDrop()   async → { ok } | { ok: false, error }
+ *   compact    icon Keep/Drop at the row's end (a list of several)
+ *   showLabel  false when the field's label is drawn by you above it
+ *   keepLabel · dropLabel · keptLabel   the verbs ("Apply", "Dismiss", "Applied")
+ */
+export function FieldSuggestion({
+  label,
+  current,
+  value,
+  source,
+  onKeep,
+  onDrop,
+  compact = false,
+  showLabel = true,
+  keepLabel = "Keep",
+  dropLabel = "Drop",
+  keptLabel = "Kept",
+  formatDate,
+  className,
+}) {
+  const [busy, setBusy] = useState(null);
+  const [state, setState] = useState("pencil");
+  const [error, setError] = useState(null);
+  const from = typeof source === "string" ? source : suggestionSource(source, formatDate);
+  const empty = current == null || current === "";
+
+  async function run(which, fn) {
+    if (!fn || busy) return;
+    setBusy(which);
+    setError(null);
+    let r;
+    try {
+      r = await fn();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy(null);
+    if (r && r.ok === false) {
+      setState("failed");
+      setError(r.error || `Couldn't ${(which === "keep" ? keepLabel : dropLabel).toLowerCase()} it. Try again.`);
+      return;
+    }
+    setState(which === "keep" ? "kept" : "dropped");
+  }
+
+  if (state === "dropped") return null;
+  const name = typeof label === "string" ? label.toLowerCase() : "this";
+  return (
+    <div className={cx("@container grid grid-cols-1 min-w-0 gap-1", className)}>
+      {showLabel && label ? (
+        <p className="text-xs text-muted-foreground">
+          {label}
+          {state === "kept" ? ` · ${keptLabel.toLowerCase()}` : empty ? " · empty now" : ` · now ${typeof current === "string" ? current : ""}`}
+        </p>
+      ) : null}
+      <div
+        role="group"
+        aria-label={`Suggested ${name}`}
+        className={cx(
+          "grid min-w-0 gap-2 rounded-md px-3 py-2",
+          // Side by side from 22rem of its own width; under it the
+          // buttons go below the value. Compact icons always fit beside.
+          compact ? "grid-cols-[minmax(0,1fr)_auto] items-center gap-3" : "grid-cols-1 @[22rem]:grid-cols-[minmax(0,1fr)_auto] @[22rem]:items-center @[22rem]:gap-3",
+          FRAME[state] ?? FRAME.pencil,
+        )}
+      >
+        <div className="grid grid-cols-1 min-w-0 gap-0.5">
+          {compact && label ? <span className="text-xs text-muted-foreground">{label}</span> : null}
+          <span className="min-w-0 break-words text-sm font-semibold">{value}</span>
+          {from ? <span className="text-xs text-muted-foreground">{from}</span> : null}
+          {state === "failed" && error ? (
+            <span role="alert" className="text-xs text-destructive">
+              {error}
+            </span>
+          ) : null}
+        </div>
+        {state === "kept" ? (
+          <span className="inline-flex items-center gap-1 text-xs font-medium text-success">
+            <Icon name="check" size={14} />
+            {keptLabel}
+          </span>
+        ) : compact ? (
+          <span className="flex items-center gap-1">
+            <IconButton icon="check" size="sm" variant="secondary" label={`${keepLabel} ${name}`} disabled={Boolean(busy)} onClick={() => run("keep", onKeep)} />
+            <IconButton icon="x" size="sm" label={`${dropLabel} ${name}`} disabled={Boolean(busy)} onClick={() => run("drop", onDrop)} />
+          </span>
+        ) : (
+          <span className="flex flex-wrap items-center gap-1">
+            <Button size="sm" variant="primary" loading={busy === "keep"} disabled={Boolean(busy)} onClick={() => run("keep", onKeep)} aria-label={`${keepLabel} ${name}`}>
+              {keepLabel}
+            </Button>
+            <Button size="sm" variant="quiet" loading={busy === "drop"} disabled={Boolean(busy)} onClick={() => run("drop", onDrop)} aria-label={`${dropLabel} ${name}`}>
+              {dropLabel}
+            </Button>
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** The header for several suggestions on one record: what was found and
+ *  where from, Keep all and Drop all. */
+export function SuggestionGroup({ title, description, count, onKeepAll, onDropAll, keepAllLabel, dropAllLabel = "Drop all", className, children }) {
+  const [busy, setBusy] = useState(null);
+  const [error, setError] = useState(null);
+  async function run(which, fn) {
+    if (!fn || busy) return;
+    setBusy(which);
+    setError(null);
+    let r;
+    try {
+      r = await fn();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy(null);
+    if (r && r.ok === false) setError(r.error || "That didn't work. Try again.");
+  }
+  return (
+    <div className={cx("grid grid-cols-1 min-w-0 gap-3", className)}>
+      <div role="status" className={cx("flex min-w-0 flex-wrap items-center gap-3 rounded-lg px-4 py-3", FRAME.pencil)}>
+        <Icon name="sparkles" className="text-muted-foreground" />
+        <div className="grid min-w-0 flex-1 basis-56 grid-cols-1 gap-0.5">
+          <p className="text-sm font-semibold">{title}</p>
+          {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
+          {error ? (
+            <p role="alert" className="text-sm text-destructive">
+              {error}
+            </p>
+          ) : null}
+        </div>
+        <span className="flex flex-wrap items-center gap-2">
+          {onKeepAll ? (
+            <Button size="sm" variant="primary" loading={busy === "keep"} disabled={Boolean(busy)} onClick={() => run("keep", onKeepAll)}>
+              {keepAllLabel ?? (count ? `Keep all ${count}` : "Keep all")}
+            </Button>
+          ) : null}
+          {onDropAll ? (
+            <Button size="sm" variant="quiet" loading={busy === "drop"} disabled={Boolean(busy)} onClick={() => run("drop", onDropAll)}>
+              {dropAllLabel}
+            </Button>
+          ) : null}
+        </span>
+      </div>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Found in place: the proposed value inside the cell or field it would
+ * fill, as a small dashed chip in the agent's tone, with where it came
+ * from and a tick to keep and a cross to drop (0.7.0, the CRM's v2
+ * signature). Same callbacks as FieldSuggestion.
+ *
+ *   value      the proposed value
+ *   source     { from, at } or a string ("her email signature, Sat 12 Sep")
+ *   label      the field's name, for the buttons ("Keep job title")
+ *   onKeep() · onDrop()   async → { ok } | { ok: false, error }
+ *   keepLabel · dropLabel  the verbs the buttons say to a reader
+ */
+export function InlineSuggestion({ value, source, label, onKeep, onDrop, keepLabel = "Keep", dropLabel = "Drop", formatDate, className }) {
+  const [busy, setBusy] = useState(null);
+  const [state, setState] = useState("pencil");
+  const [error, setError] = useState(null);
+  const from = typeof source === "string" ? source : suggestionSource(source, formatDate);
+  const name = typeof label === "string" ? label.toLowerCase() : "this";
+  async function run(which, fn) {
+    if (!fn || busy) return;
+    setBusy(which);
+    setError(null);
+    let r;
+    try {
+      r = await fn();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy(null);
+    if (r && r.ok === false) {
+      setState("failed");
+      setError(r.error || "That didn't work. Try again.");
+      return;
+    }
+    setState(which === "keep" ? "kept" : "dropped");
+  }
+  if (state === "dropped") return null;
+  return (
+    <span
+      role="group"
+      aria-label={`Suggested ${name}: ${typeof value === "string" ? value : ""}`}
+      title={error ?? (from ? `Found by the agent: ${from}` : undefined)}
+      className={cx(
+        "inline-flex h-[22px] min-w-0 max-w-full items-center gap-1.5 whitespace-nowrap rounded-[4px] border border-dashed pl-[7px] pr-[3px] align-middle text-[13px] text-foreground",
+        state === "kept" ? "border-solid border-success" : state === "failed" ? "border-destructive" : "border-info",
+        className,
+      )}
+    >
+      <span className="min-w-0 truncate">{value}</span>
+      {from ? <span className="min-w-0 truncate text-[11.5px] text-muted-foreground">{from}</span> : null}
+      {state === "kept" ? (
+        <Icon name="check" size={12} className="shrink-0 text-success" label="Kept" />
+      ) : (
+        <>
+          <button
+            type="button"
+            aria-label={`${keepLabel} ${name}`}
+            disabled={Boolean(busy)}
+            onClick={(e) => {
+              e.stopPropagation();
+              run("keep", onKeep);
+            }}
+            className="grid grid-cols-1 size-[18px] shrink-0 place-items-center rounded-[3px] text-success outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            <Icon name="check" size={12} />
+          </button>
+          <button
+            type="button"
+            aria-label={`${dropLabel} ${name}`}
+            disabled={Boolean(busy)}
+            onClick={(e) => {
+              e.stopPropagation();
+              run("drop", onDrop);
+            }}
+            className="grid grid-cols-1 size-[18px] shrink-0 place-items-center rounded-[3px] text-muted-foreground outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            <Icon name="x" size={12} />
+          </button>
+        </>
+      )}
+      {state === "failed" && error ? <span className="sr-only" role="alert">{error}</span> : null}
+    </span>
+  );
+}
+
+/** "Looking…" in the agent's tone, where a value is still being found. */
+export function Looking({ children = "Looking…", className }) {
+  return (
+    <span className={cx("inline-flex items-center gap-[5px] text-[13px] text-info motion-safe:animate-pulse", className)}>
+      <Icon name="sparkles" size={12} />
+      {children}
+    </span>
+  );
+}
+
+/**
+ * A change to a span of text, as an editor's proof mark: the old words
+ * struck, the new beside them, why, and where from (Writing Review's proof
+ * marks; Notes, Landing Page Reviewer). Kept, the new words stand alone in
+ * a solid frame; dropped, it goes.
+ *
+ *   before     the words now (struck); empty for an insertion
+ *   after      the words proposed; empty for a cut
+ *   lead · tail  a few words around the span, muted, so it reads in place
+ *   reason     why, one line ("“your” is the owner's, “you're” is “you are”")
+ *   source     { from, at } or a string: what it leans on (a style guide, a page)
+ *   onKeep() · onDrop()   async → { ok } | { ok: false, error }
+ *   keepLabel · dropLabel · keptLabel   default "Keep", "Drop", "Kept"
+ */
+export function TextSuggestion({
+  before,
+  after,
+  lead,
+  tail,
+  reason,
+  source,
+  onKeep,
+  onDrop,
+  keepLabel = "Keep",
+  dropLabel = "Drop",
+  keptLabel = "Kept",
+  formatDate,
+  className,
+}) {
+  const [busy, setBusy] = useState(null);
+  const [state, setState] = useState("pencil");
+  const [error, setError] = useState(null);
+  const from = typeof source === "string" ? source : suggestionSource(source, formatDate);
+  const cut = after == null || after === "";
+  const insert = before == null || before === "";
+
+  async function run(which, fn) {
+    if (!fn || busy) return;
+    setBusy(which);
+    setError(null);
+    let r;
+    try {
+      r = await fn();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy(null);
+    if (r && r.ok === false) {
+      setState("failed");
+      setError(r.error || `Couldn't ${(which === "keep" ? keepLabel : dropLabel).toLowerCase()} it. Try again.`);
+      return;
+    }
+    setState(which === "keep" ? "kept" : "dropped");
+  }
+
+  if (state === "dropped") return null;
+  const kept = state === "kept";
+  const what = cut ? "Cut" : insert ? "Add" : "Change";
+  return (
+    <div
+      role="group"
+      aria-label={`Suggested ${what.toLowerCase()}${typeof after === "string" && after ? `: ${after}` : ""}`}
+      className={cx("@container grid grid-cols-1 min-w-0 gap-2 rounded-md px-3 py-2 text-sm", FRAME[state] ?? FRAME.pencil, className)}
+    >
+      <p className="min-w-0 break-words leading-relaxed">
+        {lead ? <span className="text-muted-foreground">{lead}</span> : null}
+        {kept ? (
+          cut ? null : <span className="font-semibold">{after}</span>
+        ) : (
+          <>
+            {insert ? null : (
+              <del className="text-muted-foreground decoration-foreground decoration-[1.5px]">
+                <span className="sr-only">Remove: </span>
+                {before}
+              </del>
+            )}
+            {!insert && !cut ? (
+              <Icon name="arrow-right" size={12} className="mx-1 inline-block align-[-0.1em] text-muted-foreground" />
+            ) : null}
+            {cut ? null : (
+              <ins className="font-semibold no-underline">
+                <span className="sr-only">Add: </span>
+                {after}
+              </ins>
+            )}
+          </>
+        )}
+        {tail ? <span className="text-muted-foreground">{tail}</span> : null}
+      </p>
+      {reason && !kept ? <p className="text-xs text-muted-foreground">{reason}</p> : null}
+      {from && !kept ? <p className="text-xs text-muted-foreground">{from}</p> : null}
+      {state === "failed" && error ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {kept ? (
+        <span className="inline-flex items-center gap-1 text-xs font-medium text-success">
+          <Icon name="check" size={14} />
+          {keptLabel}
+        </span>
+      ) : onKeep || onDrop ? (
+        <span className="flex flex-wrap items-center gap-1">
+          {onKeep ? (
+            <Button size="sm" variant="primary" loading={busy === "keep"} disabled={Boolean(busy)} onClick={() => run("keep", onKeep)}>
+              {keepLabel}
+            </Button>
+          ) : null}
+          {onDrop ? (
+            <Button size="sm" variant="quiet" loading={busy === "drop"} disabled={Boolean(busy)} onClick={() => run("drop", onDrop)}>
+              {dropLabel}
+            </Button>
+          ) : null}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/sum-bar/README.md

@@ -0,0 +1,122 @@
+# SumBar
+
+A total with its parts cut out of it, so a number can be checked, not trusted.
+
+A health score of 35 says little. "100, less 22 for the schedule, 25 for the
+budget, 5 late, 8 blocked, 5 quiet client" says everything. This block draws
+that sum to scale:
+
+- **The bar** runs from 0 to the total (100). What is left is solid, with its
+  number in it.
+- **Each part is a hatched block cut from the top end downward**, in the tone
+  of its part (`warning`, `danger`, `info`, `neutral`), its cost written in it
+  and its name under it. A part can be pressed.
+- **A rule that holds the result down** (a cap) is a **post** standing on the
+  bar with a flag above it. When the cap bites, the stretch between the sum
+  and the result is dotted and the receipt says so.
+- **Bands** under the bar name the ranges (off track, at risk, on track).
+- **The receipt** writes the sum out: `100 − 22 − 25 − 5 − 8 − 0 − 5 = 35`,
+  or `100 − 44 = 56, held at 49`.
+
+It draws a result the app has already worked out. It scores nothing and
+changes no number. For a total split into shares use the kit's `Distribution`;
+for progress against a clock use `pace-bar`.
+
+Born in a project monitor's score sheet ("57% done, 88% of the time gone" is
+`pace-bar`; the 35 it costs is this). Fits any app that scores out of 100 and
+must show its working.
+
+```jsx
+import { SumBar, receiptOf, resultOf, sumWords } from "../components/blocks/sum-bar";   // a Makersclaw app ("./blocks/sum-bar" from components/)
+import { SumBar } from "@/components/makersclaw/blocks/sum-bar";   // a shadcn project
+```
+
+A client component. No other block, no npm package. Positions are percentages
+of the total, so a server render and a browser render agree.
+
+## Props
+
+- `total`: the whole (default `100`).
+- `parts`: `[{ id, label, cost, tone, note }]`, taken off in the order given,
+  from the top end of the bar. `cost` is a number (0 or more; anything else
+  counts as 0). A part that costs nothing is no block on the bar but is a term
+  in the receipt. `tone`: `neutral` (default), `info`, `warning`, `danger`.
+- `result`: the number after a rule held it down. Left out, it is the total
+  less the costs. Lower than that, the difference is "held" (dotted).
+- `posts`: `[{ at, label, tone }]`: a dashed post at `at` (0 to the total),
+  with a flag above. `tone: "danger"` draws it in the danger colour.
+- `bands`: `[{ from, to, tone, label }]`: a thin coloured strip under the bar
+  and a label centred under each band. `tone`: `success`, `warning`, `danger`,
+  `info`, `neutral`.
+- `selected`, `onSelect(part)`: with `onSelect` every cut is a button; the
+  selected one is ringed. Without it the cuts are read-only.
+- `size`: `sm` (24 px), `md` (36 px, default), `lg` (48 px).
+- `names`: the names under the cuts (default `true`). They show from 32rem of
+  the block's own width, and only under cuts wide enough to hold a name.
+- `legend`: a list of every part and its cost under the bar (default `false`).
+- `receipt`: the written sum (default `true`).
+- `unit`: appended to the receipt (`"points"`). `noun`: what a screen reader
+  calls one unit (default `"point"`).
+- `label`: what a screen reader calls the whole (default "Score sheet").
+- `status`: `ready` (default), `loading` (a skeleton), `failed` (a danger
+  notice with `error` and a Try again when `onRetry` is given).
+- `className`: layout around it. Never colour.
+
+## The sums (plain functions, no React)
+
+- `resultOf({ total, parts, result })` → `{ total, lost, kept, result, held, raised }`
+- `cutsOf({ total, parts })` → each part with `from`, `to`, `leftPct`, `widthPct`, `cut`
+- `postsOf({ total, posts })`, `bandsOf({ total, bands })`: placed, out-of-range ones dropped
+- `receiptOf({ total, parts, result, unit })` → `{ …resultOf, terms, text }`
+- `sumWords({ total, parts, result, posts, noun })`: the whole bar in a sentence
+- `costOf(value)`, `totalOf(total)`, `lostOf(parts)`, `labelledCuts(cuts, minPct)`
+
+## Example
+
+```jsx
+// A project's score: 100 less what each signal cost, held at 49 by two reds.
+<SumBar
+  label="Website rebuild, score sheet"
+  parts={[
+    { 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" },
+  ]}
+  result={35}
+  posts={[{ at: 74, label: "cap 74 · one red" }, { at: 49, label: "cap 49 · two reds" }]}
+  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" },
+  ]}
+  unit="points"
+  onSelect={(part) => scrollToSignal(part.id)}
+/>
+```
+
+## States drawn in the demo
+
+- **Nothing taken off**: a full solid bar, the receipt `100 = 100`.
+- **One part, many parts**, a part that costs nothing (in the receipt, not on
+  the bar).
+- **Held by a rule**: the sum above the result, the dotted stretch, the receipt
+  "held at 49".
+- **Posts and bands**; **pressable** (a selected part, arrow keys by Tab).
+- **Very small cuts** (under 5% wide: no cost written in the block, still in the
+  tooltip and the receipt).
+- **Odd input**: a negative cost, a cost past the total, text for a cost, a
+  zero total.
+- **Narrow** (a 320 px container: names under the cuts give way to the legend
+  you ask for), **wide**, **loading**, **failed**.
+
+## Notes for the app that places it
+
+- Colour is a signal. Tone a cut `danger` or `warning` only when its signal is
+  in the red or a warning; a neutral cut is a cost that is not a problem.
+- Never rely on tone alone: the cost is written in the cut, in the tooltip and
+  in the receipt.
+- Put the same numbers in words beside it (the rows of the sum). The bar is a
+  picture of them.

package/registry/blocks/sum-bar/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "sum-bar",
+  "title": "SumBar",
+  "description": "A total with its parts cut out of it, drawn to scale. The bar runs from 0 to the total (100 by default); what is left is solid with its number, each part's cost is a hatched block cut from the top end downward in the tone of its part (warning, danger, info, neutral) with its cost written in it and its name under it, and a part can be pressed. When a rule holds the result below the sum, the stretch between them is dotted and says so. Posts stand on the bar where a rule applies (a cap at 74, a cap at 49), each with a flag above. Coloured bands under the bar name the ranges (off track under 50, at risk to 75, on track). Under it the sum is written out so no number is taken on trust: \"100 − 22 − 25 − 5 − 8 − 0 − 5 = 35\", or \"100 − 44 = 56, held at 49\". Positions are percentages, so it draws the same on the server; a screen reader hears the whole bar as one sentence; loading, failed and nothing-taken-off are drawn; the sums (resultOf, cutsOf, postsOf, bandsOf, receiptOf, sumWords) are exported as plain functions.",
+  "useWhen": "Any screen where a number is a total with things taken off it and the member should be able to check the arithmetic: a health score of 100 points less what each signal cost, a risk score, a quote's price less its discounts, a budget less what each line spent, a credit balance less each charge, a grade out of 100 less each lost mark. It draws a result the app has already worked out and changes no number. Not a total split into shares (Distribution, breakdown), progress against a clock (pace-bar), a meter against a limit (Meter), or a time series (chart).",
+  "tags": ["sum", "score", "total", "points", "cost", "deduction", "receipt", "arithmetic", "cap", "ceiling", "threshold", "health", "risk", "budget", "breakdown", "waterfall", "bar", "hatched"],
+  "exports": ["SumBar", "bandsOf", "costOf", "cutsOf", "labelledCuts", "lostOf", "postsOf", "receiptOf", "resultOf", "sumWords", "totalOf"],
+  "files": ["index.js", "sum-bar.jsx", "sum-model.js"],
+  "requires": []
+}