makersclaw 0.1.0 → 0.3.0

package/registry/blocks/spreadsheet/types.js

@@ -0,0 +1,473 @@
+// The column-type registry: what each kind of column holds, how it reads
+// and writes text, sorts and filters. Plain functions — no React, so they
+// run on the server, in a test, in csv-import. How a type is DRAWN and
+// EDITED lives in cells.jsx, keyed by `editor` below.
+//
+// A type is:
+//   label     what a person calls it ("Currency")
+//   icon      a kit glyph for the header
+//   align     start · end (numbers line up on the right)
+//   width     the default column width, px
+//   editor    how it is edited in a cell: text · number · date · select ·
+//             person · toggle (flips in place) · rating · url · none
+//   empty(v)  true when the cell holds nothing
+//   parse(text, col, ctx) → { value } | { error } — typed or pasted text in.
+//             A select may add `create: [{ value, label }]` (options that
+//             do not exist yet)
+//   toText(v, col, ctx)  the text a copy puts on the clipboard and an
+//             edit starts from ("1250.5", "2026-09-23", "Won, Lost")
+//   format(v, col, ctx)  the text a cell shows ("$1,250.50", "Sep 23, 2026")
+//   compare(a, b, col, ctx) the sort order; empties always sort last
+//   filters   the conditions the Filter panel offers: [{ id, label, arg,
+//             test(v, arg, col, ctx) }] — `arg` names the value control:
+//             text · number · date · option · options · person · none
+//
+// `ctx` is { people, locale, currency }: what a type reads beyond its own
+// column (the person list, the reader's locale).
+
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+
+const isBlank = (v) => v == null || v === "" || (Array.isArray(v) && v.length === 0);
+const str = (v) => (v == null ? "" : String(v));
+const lc = (v) => str(v).toLowerCase();
+
+// ── numbers ─────────────────────────────────────────────────────────────
+
+/** "$1,250.50", "(300)", "1 250,5", "-12" → a number, or null for blank,
+ *  or NaN when it is not one. */
+export function parseNumberText(text) {
+  let s = str(text).trim();
+  if (!s) return null;
+  let neg = false;
+  if (/^\(.*\)$/.test(s)) {
+    neg = true;
+    s = s.slice(1, -1);
+  }
+  s = s.replace(/[\s ]/g, "").replace(/^[^\d.,+-]+|[^\d.,]+$/g, "");
+  if (s.startsWith("-")) {
+    neg = !neg;
+    s = s.slice(1);
+  } else if (s.startsWith("+")) s = s.slice(1);
+  // A comma is a decimal point only when it is the one separator and two
+  // or fewer digits follow it ("12,5"); else it groups thousands.
+  const commas = (s.match(/,/g) || []).length;
+  const dots = (s.match(/\./g) || []).length;
+  if (commas === 1 && dots === 0 && /,\d{1,2}$/.test(s)) s = s.replace(",", ".");
+  else if (dots > 1 && commas <= 1) s = s.replace(/\./g, "").replace(",", ".");
+  else s = s.replace(/,/g, "");
+  if (!/^\d*\.?\d+$|^\d+\.$/.test(s)) return NaN;
+  const n = Number(s);
+  return neg ? -n : n;
+}
+
+function numberFormat(col, ctx, currency) {
+  const digits = col?.precision ?? (currency ? 2 : undefined);
+  const opts = currency
+    ? { style: "currency", currency: col?.currency || ctx?.currency || "USD", minimumFractionDigits: digits, maximumFractionDigits: digits }
+    : { maximumFractionDigits: digits ?? 2, minimumFractionDigits: col?.precision ?? 0 };
+  return cachedFormat("n", ctx?.locale, opts, () => new Intl.NumberFormat(ctx?.locale, opts), () => new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }));
+}
+
+// Building an Intl formatter costs far more than using one, and a sort or
+// a search formats every cell: one per locale and options, kept.
+const FORMATS = new Map();
+function cachedFormat(kind, locale, opts, make, fallback) {
+  const key = `${kind}|${locale ?? ""}|${JSON.stringify(opts)}`;
+  let f = FORMATS.get(key);
+  if (!f) {
+    try {
+      f = make();
+    } catch {
+      f = fallback();
+    }
+    FORMATS.set(key, f);
+  }
+  return f;
+}
+
+const numberCompare = (a, b) => a - b;
+
+const NUMBER_FILTERS = [
+  { id: "eq", label: "=", arg: "number", test: (v, a) => v === a },
+  { id: "ne", label: "≠", arg: "number", test: (v, a) => v !== a },
+  { id: "gt", label: ">", arg: "number", test: (v, a) => v > a },
+  { id: "lt", label: "<", arg: "number", test: (v, a) => v < a },
+  { id: "gte", label: "≥", arg: "number", test: (v, a) => v >= a },
+  { id: "lte", label: "≤", arg: "number", test: (v, a) => v <= a },
+];
+
+// ── dates ───────────────────────────────────────────────────────────────
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const pad = (n) => String(n).padStart(2, "0");
+
+function validDay(y, m, d) {
+  if (!(y >= 1000 && y <= 9999 && m >= 1 && m <= 12 && d >= 1)) return null;
+  const last = new Date(Date.UTC(y, m, 0)).getUTCDate();
+  return d <= last ? `${y}-${pad(m)}-${pad(d)}` : null;
+}
+
+/** Text → "YYYY-MM-DD", null for blank, or undefined when it is no day.
+ *  ISO first, then 9/23/2026 (or 23/9/2026 with order "dmy", or when the
+ *  first number cannot be a month), then "Sep 23, 2026" / "23 Sep 2026". */
+export function parseDateText(text, order = "mdy") {
+  const s = str(text).trim();
+  if (!s) return null;
+  let m = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T\s].*)?$/.exec(s);
+  if (m) return validDay(+m[1], +m[2], +m[3]) ?? undefined;
+  m = /^(\d{1,2})[/.-](\d{1,2})[/.-](\d{2}|\d{4})$/.exec(s);
+  if (m) {
+    let [a, b] = [+m[1], +m[2]];
+    const y = m[3].length === 2 ? 2000 + +m[3] : +m[3];
+    if (order === "dmy" || a > 12) [a, b] = [b, a];
+    return validDay(y, a, b) ?? undefined;
+  }
+  m = /^([a-z]{3,})\.?\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4})$/i.exec(s);
+  if (m) {
+    const mo = MONTHS.indexOf(m[1].slice(0, 3).toLowerCase());
+    return mo < 0 ? undefined : validDay(+m[3], mo + 1, +m[2]) ?? undefined;
+  }
+  m = /^(\d{1,2})(?:st|nd|rd|th)?\s+([a-z]{3,})\.?,?\s+(\d{4})$/i.exec(s);
+  if (m) {
+    const mo = MONTHS.indexOf(m[2].slice(0, 3).toLowerCase());
+    return mo < 0 ? undefined : validDay(+m[3], mo + 1, +m[1]) ?? undefined;
+  }
+  return undefined;
+}
+
+function formatDay(v, ctx) {
+  if (!v) return "";
+  const [y, m, d] = String(v).split("-").map(Number);
+  if (!y || !m || !d) return str(v);
+  const opts = { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" };
+  const fmt = cachedFormat("d", ctx?.locale, opts, () => new Intl.DateTimeFormat(ctx?.locale, opts), () => new Intl.DateTimeFormat(undefined, opts));
+  return fmt.format(new Date(Date.UTC(y, m - 1, d)));
+}
+
+// ── options (select, multi-select) ──────────────────────────────────────
+
+const optionsOf = (col) => col?.options ?? [];
+export const optionOf = (col, value) => optionsOf(col).find((o) => o.value === value);
+const labelOf = (col, value) => optionOf(col, value)?.label ?? str(value);
+
+/** A new option's value from its label: "Closed won" → "closed-won". */
+export function optionValue(label, taken = []) {
+  const base = lc(label).trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "option";
+  let v = base;
+  for (let i = 2; taken.includes(v); i++) v = `${base}-${i}`;
+  return v;
+}
+
+// Hues 1–5 cycle through new options, so a created one is never grey.
+function nextHue(col, extra = 0) {
+  return ((optionsOf(col).length + extra) % 5) + 1;
+}
+
+function matchOption(col, text) {
+  const t = lc(text).trim();
+  return optionsOf(col).find((o) => lc(o.label) === t || lc(o.value) === t);
+}
+
+function parseOptions(text, col, multiple) {
+  const s = str(text).trim();
+  if (!s) return { value: multiple ? [] : null };
+  const parts = multiple ? s.split(/\s*[,;\n]\s*/).filter(Boolean) : [s];
+  const value = [];
+  const create = [];
+  for (const p of parts) {
+    const hit = matchOption(col, p) ?? create.find((c) => lc(c.label) === lc(p));
+    if (hit) {
+      if (!value.includes(hit.value)) value.push(hit.value);
+      continue;
+    }
+    if (col?.allowNew === false) return { error: `“${p}” is not one of the options` };
+    const o = { value: optionValue(p, [...optionsOf(col).map((x) => x.value), ...create.map((x) => x.value)]), label: p, hue: nextHue(col, create.length) };
+    create.push(o);
+    value.push(o.value);
+  }
+  return create.length ? { value: multiple ? value : value[0], create } : { value: multiple ? value : value[0] };
+}
+
+const optionRank = (col, v) => {
+  const i = optionsOf(col).findIndex((o) => o.value === v);
+  return i < 0 ? Infinity : i;
+};
+
+// ── people ──────────────────────────────────────────────────────────────
+
+const personOf = (ctx, id) => (ctx?.people ?? []).find((p) => p.id === id);
+const personName = (ctx, id) => personOf(ctx, id)?.name ?? str(id);
+const asList = (v) => (Array.isArray(v) ? v : isBlank(v) ? [] : [v]);
+
+function parsePeople(text, col, ctx) {
+  const s = str(text).trim();
+  if (!s) return { value: col?.multiple ? [] : null };
+  const parts = col?.multiple ? s.split(/\s*[,;\n]\s*/).filter(Boolean) : [s];
+  const ids = [];
+  for (const p of parts) {
+    const t = lc(p);
+    const hit = (ctx?.people ?? []).find((x) => lc(x.name) === t || lc(x.email) === t || lc(x.id) === t || lc(x.name).split(" ")[0] === t);
+    if (!hit) return { error: `No one called “${p}”` };
+    if (!ids.includes(hit.id)) ids.push(hit.id);
+  }
+  return { value: col?.multiple ? ids : ids[0] };
+}
+
+// ── the registry ────────────────────────────────────────────────────────
+
+const TEXT_FILTERS = [
+  { id: "contains", label: "contains", arg: "text", test: (v, a) => lc(v).includes(lc(a)) },
+  { id: "not-contains", label: "does not contain", arg: "text", test: (v, a) => !lc(v).includes(lc(a)) },
+  { id: "is", label: "is", arg: "text", test: (v, a) => lc(v).trim() === lc(a).trim() },
+];
+
+export const COLUMN_TYPES = {
+  text: {
+    label: "Text",
+    icon: "type",
+    align: "start",
+    width: 220,
+    editor: "text",
+    parse: (t) => ({ value: str(t) }),
+    toText: (v) => str(v),
+    format: (v) => str(v),
+    compare: (a, b) => collator.compare(str(a), str(b)),
+    filters: TEXT_FILTERS,
+  },
+  number: {
+    label: "Number",
+    icon: "hash",
+    align: "end",
+    width: 120,
+    editor: "number",
+    parse: (t) => {
+      const n = parseNumberText(t);
+      return Number.isNaN(n) ? { error: "That is not a number" } : { value: n };
+    },
+    toText: (v) => (typeof v === "number" ? String(v) : str(v)),
+    format: (v, col, ctx) => (typeof v === "number" ? numberFormat(col, ctx, false).format(v) : str(v)),
+    compare: numberCompare,
+    filters: NUMBER_FILTERS,
+  },
+  currency: {
+    label: "Currency",
+    icon: "dollar",
+    align: "end",
+    width: 130,
+    editor: "number",
+    parse: (t) => {
+      const n = parseNumberText(t);
+      return Number.isNaN(n) ? { error: "That is not an amount" } : { value: n };
+    },
+    toText: (v) => (typeof v === "number" ? String(v) : str(v)),
+    format: (v, col, ctx) => (typeof v === "number" ? numberFormat(col, ctx, true).format(v) : str(v)),
+    compare: numberCompare,
+    filters: NUMBER_FILTERS,
+  },
+  date: {
+    label: "Date",
+    icon: "calendar",
+    align: "start",
+    width: 140,
+    editor: "date",
+    parse: (t, col) => {
+      const d = parseDateText(t, col?.dateOrder);
+      return d === undefined ? { error: "That is not a date — try 2026-09-23" } : { value: d };
+    },
+    toText: (v) => str(v),
+    format: (v, col, ctx) => formatDay(v, ctx),
+    compare: (a, b) => (a < b ? -1 : a > b ? 1 : 0),
+    filters: [
+      { id: "is", label: "is", arg: "date", test: (v, a) => v === a },
+      { id: "before", label: "is before", arg: "date", test: (v, a) => v < a },
+      { id: "after", label: "is after", arg: "date", test: (v, a) => v > a },
+    ],
+  },
+  select: {
+    label: "Single select",
+    icon: "chevron-down",
+    align: "start",
+    width: 150,
+    editor: "select",
+    parse: (t, col) => parseOptions(t, col, false),
+    toText: (v, col) => (isBlank(v) ? "" : labelOf(col, v)),
+    format: (v, col) => (isBlank(v) ? "" : labelOf(col, v)),
+    compare: (a, b, col) => optionRank(col, a) - optionRank(col, b) || collator.compare(str(a), str(b)),
+    filters: [
+      { id: "any", label: "is any of", arg: "options", test: (v, a) => asList(a).includes(v) },
+      { id: "none", label: "is none of", arg: "options", test: (v, a) => !asList(a).includes(v) },
+    ],
+  },
+  "multi-select": {
+    label: "Multiple select",
+    icon: "tag",
+    align: "start",
+    width: 200,
+    editor: "select",
+    multiple: true,
+    parse: (t, col) => parseOptions(t, col, true),
+    toText: (v, col) => asList(v).map((x) => labelOf(col, x)).join(", "),
+    format: (v, col) => asList(v).map((x) => labelOf(col, x)).join(", "),
+    compare: (a, b, col) => optionRank(col, asList(a)[0]) - optionRank(col, asList(b)[0]) || asList(a).length - asList(b).length,
+    filters: [
+      { id: "any", label: "has any of", arg: "options", test: (v, a) => asList(v).some((x) => asList(a).includes(x)) },
+      { id: "all", label: "has all of", arg: "options", test: (v, a) => asList(a).every((x) => asList(v).includes(x)) },
+      { id: "none", label: "has none of", arg: "options", test: (v, a) => !asList(v).some((x) => asList(a).includes(x)) },
+    ],
+  },
+  person: {
+    label: "Person",
+    icon: "user",
+    align: "start",
+    width: 170,
+    editor: "person",
+    parse: parsePeople,
+    toText: (v, col, ctx) => asList(v).map((id) => personName(ctx, id)).join(", "),
+    format: (v, col, ctx) => asList(v).map((id) => personName(ctx, id)).join(", "),
+    compare: (a, b, col, ctx) => collator.compare(personName(ctx, asList(a)[0]), personName(ctx, asList(b)[0])),
+    filters: [
+      { id: "any", label: "is any of", arg: "person", test: (v, a) => asList(v).some((x) => asList(a).includes(x)) },
+      { id: "none", label: "is none of", arg: "person", test: (v, a) => !asList(v).some((x) => asList(a).includes(x)) },
+    ],
+  },
+  checkbox: {
+    label: "Checkbox",
+    icon: "square-check",
+    align: "center",
+    width: 96,
+    editor: "toggle",
+    // A checkbox is never "empty": unchecked is a value.
+    empty: () => false,
+    parse: (t) => {
+      const s = lc(t).trim();
+      if (["true", "yes", "y", "1", "x", "✓", "✔", "checked", "on", "done"].includes(s)) return { value: true };
+      if (["false", "no", "n", "0", "", "unchecked", "off"].includes(s)) return { value: false };
+      return { error: "Use yes or no" };
+    },
+    toText: (v) => (v ? "true" : "false"),
+    format: (v) => (v ? "Yes" : "No"),
+    compare: (a, b) => Number(Boolean(b)) - Number(Boolean(a)),
+    filters: [
+      { id: "checked", label: "is checked", arg: "none", test: (v) => Boolean(v) },
+      { id: "unchecked", label: "is not checked", arg: "none", test: (v) => !v },
+    ],
+  },
+  url: {
+    label: "Link",
+    icon: "link",
+    align: "start",
+    width: 200,
+    editor: "url",
+    parse: (t) => {
+      const s = str(t).trim();
+      if (!s) return { value: "" };
+      if (/\s/.test(s) || !/[.:]/.test(s)) return { error: "That does not look like a link" };
+      return { value: s };
+    },
+    toText: (v) => str(v),
+    format: (v) => str(v).replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, ""),
+    compare: (a, b) => collator.compare(str(a), str(b)),
+    filters: TEXT_FILTERS,
+  },
+  rating: {
+    label: "Rating",
+    icon: "star",
+    align: "start",
+    width: 130,
+    editor: "rating",
+    empty: (v) => !v,
+    parse: (t, col) => {
+      const s = str(t).trim();
+      if (!s) return { value: 0 };
+      const stars = (s.match(/[★⭐*]/g) || []).length;
+      const n = stars && stars === s.replace(/\s/g, "").length ? stars : Number(s);
+      const max = col?.max ?? 5;
+      if (!Number.isInteger(n) || n < 0 || n > max) return { error: `Use a whole number from 0 to ${max}` };
+      return { value: n };
+    },
+    toText: (v) => (v ? String(v) : ""),
+    format: (v, col) => (v ? `${v} of ${col?.max ?? 5}` : ""),
+    compare: (a, b) => (a || 0) - (b || 0),
+    filters: [
+      { id: "gte", label: "is at least", arg: "number", test: (v, a) => (v || 0) >= a },
+      { id: "lte", label: "is at most", arg: "number", test: (v, a) => (v || 0) <= a },
+      { id: "eq", label: "is", arg: "number", test: (v, a) => (v || 0) === a },
+    ],
+  },
+};
+
+// Every type also filters on emptiness.
+const EMPTY_FILTERS = [
+  { id: "empty", label: "is empty", arg: "none", test: (v, a, col, ctx, type) => type.empty(v) },
+  { id: "not-empty", label: "is not empty", arg: "none", test: (v, a, col, ctx, type) => !type.empty(v) },
+];
+
+/** The type a column has: `custom` (the Spreadsheet's `types` prop)
+ *  first, then the built-ins; an unknown name reads as text. Missing
+ *  functions fall back to text's, so a custom type may be small. */
+export function typeOf(col, custom) {
+  const name = col?.type ?? "text";
+  const key = custom ?? NONE;
+  let byName = CACHE.get(key);
+  if (!byName) CACHE.set(key, (byName = new Map()));
+  let t = byName.get(name);
+  if (t) return t;
+  const own = custom?.[name] ? { ...(COLUMN_TYPES[name] ?? {}), ...custom[name] } : COLUMN_TYPES[name] ?? COLUMN_TYPES.text;
+  t = { ...COLUMN_TYPES.text, empty: isBlank, ...own, name };
+  t.allFilters = [...(own.filters ?? COLUMN_TYPES.text.filters), ...(name === "checkbox" ? [] : EMPTY_FILTERS)];
+  byName.set(name, t);
+  return t;
+}
+
+// One resolved type per (custom registry, name): typeOf runs per cell.
+const NONE = {};
+const CACHE = new WeakMap();
+
+export { isBlank };
+
+/** Parse `text` for `col`; a blank cell is always fine (an empty value). */
+export function parseCell(text, col, ctx, custom) {
+  const t = typeOf(col, custom);
+  try {
+    return t.parse(text, col, ctx);
+  } catch {
+    return { error: "That value does not fit here" };
+  }
+}
+
+/** A value moved to a column of another type: through its text. What
+ *  does not parse becomes empty. */
+export function convertValue(value, from, to, ctx, custom) {
+  const text = typeOf(from, custom).toText(value, from, ctx);
+  const r = parseCell(text, to, ctx, custom);
+  return "error" in r ? typeOf(to, custom).parse("", to, ctx).value ?? null : r.value;
+}
+
+/** Guess a column type from sample text values (csv-import uses it):
+ *  checkbox, currency, number, date, url, select (few distinct values),
+ *  multi-select (comma lists of few distinct parts), else text. Most
+ *  values (four in five) must fit, so a few bad cells in an import are
+ *  flagged to fix instead of turning the whole column into text. */
+export function guessType(values) {
+  const vals = values.map((v) => str(v).trim()).filter(Boolean);
+  if (vals.length === 0) return "text";
+  const need = Math.max(1, Math.ceil(vals.length * 0.8));
+  const most = (fn) => vals.filter(fn).length >= need;
+  const isNum = (v) => {
+    const n = parseNumberText(v);
+    return n !== null && !Number.isNaN(n);
+  };
+  if (vals.every((v) => /^(true|false|yes|no|y|n|x|✓)$/i.test(v))) return "checkbox";
+  if (most(isNum)) return vals.some((v) => /[$€£¥₹]|^[A-Z]{3}\s?[\d.,]/.test(v)) ? "currency" : "number";
+  if (most((v) => /\d/.test(v) && parseDateText(v) !== undefined)) return "date";
+  if (most((v) => /^(https?:\/\/|www\.)\S+$/i.test(v))) return "url";
+  const distinct = new Set(vals.map((v) => v.toLowerCase()));
+  if (vals.some((v) => v.includes(",")) && vals.every((v) => v.length <= 80)) {
+    const all = vals.flatMap((v) => v.split(/\s*,\s*/)).map((p) => p.toLowerCase());
+    const parts = new Set(all);
+    // Parts that repeat across cells ("SaaS, B2B" … "B2B"): tags, not prose.
+    if (parts.size <= 12 && parts.size < all.length) return "multi-select";
+  }
+  if (vals.length >= 4 && distinct.size <= Math.min(12, Math.ceil(vals.length / 2)) && vals.every((v) => v.length <= 40)) return "select";
+  return "text";
+}

package/registry/blocks/stat-cards/README.md

@@ -0,0 +1,173 @@
+# Stat cards
+
+The few numbers at the top of a dashboard, each with its name and what
+changed. Four shapes over one list of items: a bordered `strip`; `cards`,
+one per number, with a change in the corner or after the value, a "from"
+value, a status dot and a goal meter, a sparkline, a "View more" footer;
+`usage`, one tile per amount against its limit, as a bar or a ring, a
+split by kind with what is free, a warning line near the cap, an action
+along the foot and a limit the founder can change; and a plain `list` of
+values with their change. Loading, empty and error states are built in.
+
+```jsx
+import { StatCards } from "../components/blocks/stat-cards";   // a Makersclaw app ("./blocks/stat-cards" from components/)
+import { StatCards } from "@/components/makersclaw/blocks/stat-cards";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the numbers in the server surface (README §4). A sparkline is drawn
+by the free `chart` block, so `makersclaw add stat-cards` lays that one
+too.
+
+## The data
+
+One item per number, already formatted where it is shown as text:
+
+```js
+{
+  id: "mrr",                  // key; default the label
+  label: "Monthly recurring revenue",
+  value: "$48.6K",            // a string you formatted, or a number (gets thousands separators)
+  unit: "ms",                 // after the value, smaller and muted
+  sublabel: "ORBT",           // after the label, muted: a ticker, a region code
+  delta: 5.2,                 // a percent; or Delta's props: { value, suffix, display, label, invert }
+  invert: true,               // lower is better (churn, cost): down turns green
+  previous: "$46.2K",         // shown after the value as "from $46.2K"
+  caption: "Paid plans only", // a muted line under the value
+  status: "warning",          // a dot and a word at the top right: success · warning · danger · info,
+                              // or { tone, label: "Needs attention" }
+  goal: { value: 3, max: 5, label: "Goals achieved" },   // a thin meter in the status tone
+  trend: [12, 14, 13, 17],    // a sparkline under the value (numbers, oldest first)
+  trendLabel: "MRR, last 16 weeks",   // what a screen reader hears for it
+  trendTone: "chart-2",       // default: green when the change is good, red when bad
+  href: "/revenue",           // a "View more →" footer link; or onSelect(item) for a button
+  linkLabel: "View region",
+}
+```
+
+In `usage`, an item is an amount against a limit:
+
+```js
+{
+  id: "egress",
+  label: "Egress",
+  used: 188,                  // a number, in the limit's unit
+  limit: 200,                 // the cap; null means none ("/ Unlimited"); left out, no limit is shown
+  unit: "GB",
+  value: "188 GB",            // how `used` reads; default the number and the unit
+  limitText: "$150 budget",   // how the limit reads; default the number and the unit
+  suffix: "this month",       // after the value when there is no limit
+  format: (n) => `$${n}`,     // every number shown, default thousands separators
+  parts: [{ label: "Writes", value: 7410000 }, { label: "Reads", value: 2410000 }],
+                              // a split bar with a legend in place of the meter; with a
+                              // limit, the rest shows as "Free" (restLabel)
+  note: "Past 200 GB is billed per GB.",   // a line under the bar: warning near the cap
+  noteTone: "muted",          // override: muted · success · warning · danger · info
+  delta: 9.5,                 // a badge beside the label
+  thresholds: [{ at: 75, tone: "warning" }],   // default: warning at warnAt
+  action: { label: "Upgrade", icon: "zap", onSelect: (item) => … },   // a button along the foot
+  editable: false,            // no "Change limit" button on this tile
+  limitLabel: "Change budget", limitPrefix: "$",   // this tile's limit button and field
+  meter: "ring",              // this tile's shape, over the block's `meter`
+}
+```
+
+Over the limit the bar stays full and turns red; a reader hears "over by".
+
+## Props
+
+- `items` — the numbers, as above. Required.
+- `variant` — `"strip"` (default) · `"cards"` · `"usage"` · `"list"`.
+- `columns` — how many across from `lg` up, 1 to 4; default the number of
+  items, at most 4. Cards and usage tiles are one column on a phone and
+  two from `sm`; a strip is two on a phone.
+- `title` · `description` · `actions` — a header over the numbers
+  ("Plan usage", "You are on the Team plan. Compare plans", a button).
+- `label` — the group's name for a screen reader when there is no title.
+
+Stats (`strip`, `cards`, `list`)
+
+- `deltaPlacement` — `"inline"` (after the value) or `"corner"` (at the
+  label's right). Default corner in a strip, inline elsewhere. A tile with
+  a `status` keeps its change inline.
+- `deltaVariant` — `"text"` or `"badge"` (a tinted pill). Default badge
+  in a list, text elsewhere.
+- `size` — the value's size: `"sm"` · `"md"` (default in a strip) · `"lg"`
+  (default in cards).
+- `linkLabel` — the footer link's words, default `"View more"`.
+
+Usage
+
+- `meter` — `"bar"` (default) or `"ring"`, for every tile without its own
+  `meter`. A tile with `parts` is always a split bar.
+- `format(n)` — every number shown, unless a tile has its own.
+- `warnAt` — the percent of the limit where the bar and the note turn
+  warning, default 90.
+- `onLimitChange(item, limit)` — adds a "Change limit" button to each tile
+  (not those with `editable: false`). It opens a dialog with the limit in
+  a number field; Save calls this with the new number. Return (or resolve
+  to) `{ ok: false, error }`, or throw, and the dialog stays open and says
+  why; anything else closes it. The block does not change the number on
+  screen: pass the new `limit` back in `items`.
+- `limitLabel` — the button's and dialog's words, default `"Change limit"`.
+- `limitHint` — the dialog's description, default the current limit and
+  what is used.
+
+States
+
+- `loading` — skeleton tiles in the shape of the variant; `loadingCount`
+  of them (default 4).
+- `error` — a danger notice above the numbers (they still show, if any);
+  `onRetry` adds a Retry button to it.
+- `emptyTitle` · `emptyBody` · `emptyAction` — when `items` is empty.
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/Overview.jsx — client: the numbers the server read
+"use client";
+import { StatCards } from "./blocks/stat-cards";
+import { updateRow } from "../lib/actions";
+
+export default function Overview({ kpis, usage }) {
+  return (
+    <div className="grid gap-6">
+      <StatCards
+        items={[
+          { id: "mrr", label: "MRR", value: kpis.mrr, delta: kpis.mrrChange, trend: kpis.mrrWeeks, href: "/revenue" },
+          { id: "churn", label: "Logo churn", value: kpis.churn, delta: kpis.churnChange, invert: true },
+          { id: "trials", label: "Active trials", value: kpis.trials, previous: kpis.trialsLastWeek, delta: kpis.trialsChange },
+        ]}
+        variant="cards"
+      />
+      <StatCards
+        variant="usage"
+        title="Plan usage"
+        items={usage.map((u) => ({ id: u.id, label: u.name, used: u.used, limit: u.limit, unit: u.unit }))}
+        onLimitChange={(item, limit) => updateRow({ source: "public.quotas", id: item.id, patch: { limit } })}
+        limitLabel="Change budget"
+      />
+    </div>
+  );
+}
+```
+
+## What it will not do
+
+- Fetch or compute: numbers come in formatted, changes already worked out.
+- Draw a chart worth reading on its own: that is the `chart` block.
+- Score one subject against thresholds with an overall status, or list
+  many meters under a shared summary: those are other blocks.
+- Colour a number for decoration: tones are for status (a change's
+  direction, a tile near its cap, a status dot).
+
+A tile it cannot be is your own component in `components/`, built from
+the kit's `Stat`, `Meter` and `Distribution` — not an edit to this block.
+Its files are fixed: `npm run check` refuses a change, and `makersclaw add
+stat-cards` restores them.
+
+## Credits
+
+Ported from blocks.so's stats (https://github.com/ephraimduncan/blocks,
+MIT): a rewrite on the Makersclaw kit, not their code.

package/registry/blocks/stat-cards/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "stat-cards",
+  "title": "Stat cards",
+  "description": "A row of key numbers, each with its name and its change: one bordered strip, or a card each with a change in the corner or after the value, a \"from\" value, a status dot and a goal meter, a sparkline, a \"View more\" footer; or a usage tile per amount against its limit (a bar or a ring, a split by kind with what is free, a warning line near the cap, an action and a limit the founder can change); or a plain list of values with their change. Loading, empty and error states.",
+  "useWhen": "The few numbers at the top of a dashboard or a report: revenue, users, conversion, spend against budget, seats and storage against a plan. Not for a trend worth reading on its own (a chart), many rows of records (a table), or one subject scored against thresholds (a scorecard).",
+  "tags": ["stats", "kpi", "metrics", "numbers", "dashboard", "overview", "delta", "change", "trend", "sparkline", "usage", "limit", "quota", "plan", "budget", "goal", "status", "ring", "meter"],
+  "exports": ["StatCards"],
+  "files": ["index.js", "stat-cards.jsx", "usage.jsx"],
+  "requires": ["chart"]
+}