makersclaw 0.2.0 → 0.3.1

package/registry/blocks/data-table/model.js

@@ -0,0 +1,169 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+// The table's arithmetic, apart from its drawing: controlled-or-not
+// state, and the pure pipeline rows go through (search → facets → sort →
+// page). Pure functions, so a block built on DataTable (report-table)
+// reads the same answers the table draws.
+
+/** One piece of state that is the caller's when `value` is given, else
+ *  the block's own. `onChange` is called either way. */
+export function useControllable(value, defaultValue, onChange) {
+  const controlled = value !== undefined;
+  const [own, setOwn] = useState(defaultValue);
+  const current = controlled ? value : own;
+  const latest = useRef(current);
+  latest.current = current;
+  const set = useCallback(
+    (next) => {
+      const v = typeof next === "function" ? next(latest.current) : next;
+      latest.current = v;
+      if (!controlled) setOwn(v);
+      onChange?.(v);
+    },
+    [controlled, onChange],
+  );
+  return [current, set];
+}
+
+const isBlank = (v) => v === null || v === undefined || v === "";
+
+/** What a column holds for a row, for sorting. */
+export function sortValueOf(column, row) {
+  return column.sortValue ? column.sortValue(row) : row?.[column.key];
+}
+
+/** What a column says for a row, for the search. */
+export function searchTextOf(column, row) {
+  const v = column.searchValue ? column.searchValue(row) : sortValueOf(column, row);
+  if (isBlank(v)) return "";
+  if (v instanceof Date) return v.toISOString();
+  return typeof v === "object" ? "" : String(v);
+}
+
+/** The value a facet groups a row under (always a string key). */
+export function facetValueOf(facet, row) {
+  const v = facet.value ? facet.value(row) : row?.[facet.key];
+  return isBlank(v) ? "" : String(v);
+}
+
+function compare(a, b) {
+  // Blanks sort last in either direction (the caller flips only non-blanks).
+  if (a instanceof Date) a = a.getTime();
+  if (b instanceof Date) b = b.getTime();
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/** Rows ordered by `sort` ([{ key, dir: "asc" | "desc" }], first wins). */
+export function sortRows(rows, sort, columns) {
+  const keys = (sort ?? []).map((s) => ({ ...s, column: columns.find((c) => c.key === s.key) })).filter((s) => s.column);
+  if (keys.length === 0) return rows;
+  return rows
+    .map((row, i) => ({ row, i }))
+    .sort((x, y) => {
+      for (const { column, dir } of keys) {
+        const a = sortValueOf(column, x.row);
+        const b = sortValueOf(column, y.row);
+        const ba = isBlank(a);
+        const bb = isBlank(b);
+        if (ba || bb) {
+          if (ba && bb) continue;
+          return ba ? 1 : -1;
+        }
+        const c = compare(a, b);
+        if (c !== 0) return dir === "desc" ? -c : c;
+      }
+      return x.i - y.i; // stable
+    })
+    .map((x) => x.row);
+}
+
+/** Rows whose searchable columns contain every word of `query`. */
+export function searchRows(rows, query, columns) {
+  const words = String(query ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return rows;
+  const searchable = columns.filter((c) => c.searchable !== false);
+  return rows.filter((row) => {
+    const text = searchable.map((c) => searchTextOf(c, row)).join(" \u0001 ").toLowerCase();
+    return words.every((w) => text.includes(w));
+  });
+}
+
+/** Rows that match every facet's chosen values (`filters`: { key: [v…] }).
+ *  `except` leaves one facet out — its own counts are taken that way. */
+export function filterRows(rows, filters, facets, except) {
+  const active = (facets ?? []).filter((f) => f.key !== except && (filters?.[f.key] ?? []).length > 0);
+  if (active.length === 0) return rows;
+  return rows.filter((row) => active.every((f) => filters[f.key].map(String).includes(facetValueOf(f, row))));
+}
+
+/** A facet's options with how many rows each would show, counted over
+ *  the rows the search and the OTHER facets leave. */
+export function facetOptions(facet, rows, filters, facets, query, columns) {
+  const pool = filterRows(searchRows(rows, query, columns), filters, facets, facet.key);
+  const counts = new Map();
+  for (const row of pool) {
+    const v = facetValueOf(facet, row);
+    counts.set(v, (counts.get(v) ?? 0) + 1);
+  }
+  const given = facet.options?.map((o) => (typeof o === "object" ? { ...o, value: String(o.value) } : { value: String(o), label: String(o) }));
+  const all = given ?? [...new Set(rows.map((r) => facetValueOf(facet, r)))].sort((a, b) => compare(a, b)).map((v) => ({ value: v, label: v || "None" }));
+  return all.map((o) => ({ ...o, count: o.count ?? counts.get(o.value) ?? 0 }));
+}
+
+/** Rows through search, facets and sort — the whole of client mode. */
+export function processRows(rows, { query, filters, facets, sort, columns }) {
+  return sortRows(filterRows(searchRows(rows, query, columns), filters, facets), sort, columns);
+}
+
+/** The next sort after a press on `key`: plain press sorts by it alone
+ *  (asc → desc → off); with `add` it joins or cycles within the list. */
+export function nextSort(sort, key, add) {
+  const now = sort ?? [];
+  const at = now.find((s) => s.key === key);
+  const cycled = !at ? { key, dir: "asc" } : at.dir === "asc" ? { key, dir: "desc" } : null;
+  if (!add) return cycled ? [cycled] : [];
+  if (!at) return [...now, cycled];
+  return cycled ? now.map((s) => (s.key === key ? cycled : s)) : now.filter((s) => s.key !== key);
+}
+
+/** The value `groupBy` (a key or `(row) => value`) files a row under. */
+export function groupValueOf(groupBy, row) {
+  const v = typeof groupBy === "function" ? groupBy(row) : row?.[groupBy];
+  return isBlank(v) ? "" : v;
+}
+
+/** The string a group is known by (its React key, its place in `order`). */
+export function groupKeyOf(value) {
+  return value instanceof Date ? value.toISOString() : String(value ?? "");
+}
+
+/** Rows filed under `groupBy`: [{ key, value, rows }]. Rows keep their
+ *  order inside a group (sort first, then group: a sort orders rows
+ *  within their groups and never moves a group). `order` places the
+ *  groups: an array of group values (those listed first, in that order;
+ *  the rest by first appearance in `rows`) or a compare function over
+ *  two group values. */
+export function groupRows(rows, groupBy, order) {
+  if (groupBy === undefined || groupBy === null || groupBy === false) return null;
+  const map = new Map();
+  for (const row of rows ?? []) {
+    const value = groupValueOf(groupBy, row);
+    const key = groupKeyOf(value);
+    let g = map.get(key);
+    if (!g) map.set(key, (g = { key, value, rows: [] }));
+    g.rows.push(row);
+  }
+  const groups = [...map.values()];
+  if (typeof order === "function") return groups.sort((a, b) => order(a.value, b.value));
+  if (!Array.isArray(order)) return groups;
+  const rank = new Map();
+  for (const v of order) if (!rank.has(groupKeyOf(v))) rank.set(groupKeyOf(v), rank.size);
+  return groups
+    .map((g, i) => ({ g, i }))
+    .sort((x, y) => (rank.get(x.g.key) ?? rank.size + x.i) - (rank.get(y.g.key) ?? rank.size + y.i))
+    .map((x) => x.g);
+}

package/registry/blocks/diagram/README.md

@@ -0,0 +1,108 @@
+# Diagram
+
+Draws a diagram from [Mermaid](https://mermaid.js.org) text — flowcharts,
+sequence diagrams, class and state diagrams, entity relationships, Gantt
+charts, pies, mind maps, timelines, git graphs and the rest — in the
+workspace theme. Nodes are soft tints of the primary and the chart hues on
+the card, lines are muted, text is the theme's own face and ink, and it
+follows light and dark.
+
+It opens fitted to its frame. Zoom with the pill in the corner, with
+Cmd/Ctrl+scroll (or a trackpad pinch) at the pointer, with two fingers on
+a phone, or by double-clicking (Shift to zoom out); drag to move. A plain
+scroll still scrolls the page. The Source tab shows the text with line
+numbers; the ⋯ menu copies the source or the SVG and downloads the SVG.
+
+A mistake says which line and what Mermaid expected, and shows the lines
+around it. When an earlier version drew, that drawing stays up (dimmed)
+under the message, so a diagram being written live never blanks out.
+
+It is Mermaid (MIT) underneath. Mermaid needs concrete colours, so the
+block reads each token from the page at run time (`--color-card`,
+`--color-primary`, `--color-chart-1…5`, `--color-muted-foreground`…),
+mixes the tints, and hands them to Mermaid as its theme; when the
+workspace theme or light/dark changes it reads them again and redraws.
+
+```jsx
+import { Diagram } from "../components/blocks/diagram";   // a Makersclaw app ("./blocks/diagram" from components/)
+import { Diagram } from "@/components/makersclaw/blocks/diagram";   // a shadcn project
+```
+
+`Diagram` is a client component: render it from a `"use client"`
+component. `makersclaw add diagram` adds `mermaid` (pinned, exact) to
+package.json: run `npm install` after. It loads with the page (no
+`import()`); the drawing happens after the first render, and until then —
+on the server — the frame shows the Mermaid text.
+
+## Props
+
+- `source` — the Mermaid text. Required (an empty string shows "No
+  diagram yet"). Change it and the diagram redraws a moment after the
+  last change, so it can follow someone typing.
+- `title` — the frame's heading. Without it: the diagram's own `title`
+  line, else its kind ("Flowchart", "Sequence diagram"…).
+- `label` — what a screen reader calls the diagram (default: the title
+  and kind). Say what it shows: "Order flow from cart to delivery".
+- `height` — a fixed canvas height (px number or CSS length). Without it
+  the canvas is as tall as the drawing at the frame's width, between
+  `minHeight` (160) and `maxHeight` (560).
+- `look` — `"classic"` (default), `"neo"` (Mermaid's newer, lighter
+  shapes) or `"handDrawn"` (a sketchy line, for early ideas).
+- `toolbar` — `true` (default): the heading, Diagram/Source and the ⋯
+  menu. `false` leaves the canvas and its zoom pill only.
+- `onRender(result)` — after each drawing: `{ ok: true, svg }` or
+  `{ ok: false, error: { line, message, detail } }`. Pair it with a
+  `code-editor` to mark the line: `diagnostics={[{ line, message }]}`.
+- `className` — the frame's classes.
+
+### Keys
+
+On the focused canvas: `+` / `-` zoom · `0` fit · `1` actual size ·
+arrows move (Shift for bigger steps).
+
+## The helpers
+
+Plain functions, on the server too.
+
+- `diagramKind(source)` → `"Flowchart"`, `"Gantt chart"`… or null.
+- `diagramTitle(source)` → its `title`, or null.
+- `describeError(error, source)` → `{ line, message, detail }` for a
+  Mermaid error.
+- `mermaidTheme(palette, { fontFamily })` → Mermaid `themeVariables`
+  from `{ card, foreground, primary, "chart-1"…, … }` hex colours.
+
+## Example
+
+```jsx
+"use client";
+import { Diagram } from "../components/blocks/diagram";
+
+const ONBOARDING = `flowchart LR
+  signup([Sign-up]) --> verify{Email verified?}
+  verify -- yes --> workspace[Create workspace]
+  verify -- no --> remind[Send reminder] --> verify
+  workspace --> invite[Invite team] --> done([First project])`;
+
+export function OnboardingFlow() {
+  return <Diagram title="Onboarding" source={ONBOARDING} label="Onboarding flow from sign-up to first project" />;
+}
+```
+
+A live editor, with the mistake marked in the text:
+
+```jsx
+const [text, setText] = useState(ONBOARDING);
+const [problem, setProblem] = useState([]);
+<CodeEditor value={text} onChange={setText} diagnostics={problem} />
+<Diagram source={text} onRender={(r) => setProblem(r.ok || !r.error.line ? [] : [{ line: r.error.line, message: r.error.detail ?? r.error.message }])} />
+```
+
+## What it will not do
+
+- It draws; it does not edit. People change a diagram by changing its
+  text (put a `code-editor` beside it).
+- No clicks or links inside the drawing: Mermaid runs in its strict
+  mode, so `click` lines and HTML in labels are dropped.
+- Colours in the text (`style`, `classDef … fill:#…`) are Mermaid's,
+  not the theme's; leave them out and the theme paints everything.
+- PNG export is not built in; Download SVG is.

package/registry/blocks/diagram/block.json

@@ -0,0 +1,13 @@
+{
+  "name": "diagram",
+  "title": "Diagram",
+  "description": "Draws Mermaid text (flowcharts, sequence, class, state, ER, Gantt, pie, mind maps, timelines, git graphs…) in the workspace theme: the tokens are read from the page at run time and handed to Mermaid, so nodes, lines, text and chart colours are the theme's and follow light/dark. Zoom and pan (buttons, Cmd/Ctrl+scroll, pinch, drag, keys), fit to view, a Source tab with line numbers, copy the source or the SVG, download SVG. A mistake shows its line and Mermaid's words, and keeps the last drawing that worked. On the server the frame shows the Mermaid text.",
+  "useWhen": "A screen shows a diagram written as text: a process or decision flow an agent wrote, a sequence of API calls, a data model, a project timeline, an org or system sketch in docs, a mind map. Not for a board people arrange by hand (flow-canvas), freehand drawing (sketch-canvas), or charts of numbers (chart).",
+  "tags": ["diagram", "mermaid", "flowchart", "sequence diagram", "er diagram", "gantt", "mind map", "timeline", "state diagram", "class diagram", "svg", "zoom", "docs", "architecture"],
+  "exports": ["Diagram", "diagramKind", "diagramTitle", "describeError", "mermaidTheme"],
+  "files": ["index.js", "diagram.jsx", "mermaid.js", "palette.js", "source.js"],
+  "requires": [],
+  "dependencies": {
+    "mermaid": "12.0.0"
+  }
+}

package/registry/blocks/diagram/demo.jsx

@@ -0,0 +1,113 @@
+"use client";
+
+// Diagram four ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Flow       a lead-routing flowchart, fitted to its frame.
+//   Sequence   a checkout's calls between services.
+//   Plan       a launch plan as a Gantt chart.
+//   Live       type Mermaid, watch it draw; break it to see the mistake
+//              marked while the last good drawing stays up.
+import { useState } from "react";
+import { Field, TabPanel, Tabs, Textarea } from "../components/ui";
+import { Diagram } from "../components/blocks/diagram";
+
+const LEAD_ROUTING = `flowchart LR
+  form([Demo request]) --> enrich[Enrich company]
+  enrich --> size{Employees}
+  size -- "under 50" --> self[Self-serve trial]
+  size -- "50 to 500" --> ae[Account executive]
+  size -- "over 500" --> ent[Enterprise team]
+  ae --> meeting[Book intro call]
+  ent --> meeting
+  self --> nurture[Nurture emails]
+  meeting --> crm[(CRM)]
+  nurture --> crm`;
+
+const CHECKOUT = `sequenceDiagram
+  autonumber
+  actor Buyer
+  participant Shop as Storefront
+  participant Pay as Payments
+  participant Stock as Inventory
+  Buyer->>Shop: Place order
+  Shop->>Stock: Reserve items
+  Stock-->>Shop: Reserved
+  Shop->>Pay: Charge card
+  alt card accepted
+    Pay-->>Shop: Paid
+    Shop-->>Buyer: Order confirmed
+  else card declined
+    Pay-->>Shop: Declined
+    Shop->>Stock: Release items
+    Shop-->>Buyer: Try another card
+  end
+  Note over Shop,Stock: Reservations expire after 15 minutes`;
+
+const LAUNCH = `gantt
+  title Spring launch
+  dateFormat YYYY-MM-DD
+  axisFormat %b %d
+  section Product
+    Beta feedback      :done, beta, 2026-03-02, 10d
+    Pricing page       :active, price, after beta, 6d
+    Release            :milestone, rel, 2026-03-27, 0d
+  section Marketing
+    Launch post        :post, 2026-03-16, 8d
+    Customer webinar   :crit, web, 2026-03-24, 3d
+  section Sales
+    Enablement         :enable, 2026-03-12, 7d`;
+
+const STARTER = `flowchart TD
+  idea[Idea] --> spec[Write a one-pager]
+  spec --> review{Team agrees?}
+  review -- yes --> build[Build it]
+  review -- not yet --> spec`;
+
+function LiveDemo() {
+  const [text, setText] = useState(STARTER);
+  const [status, setStatus] = useState(null);
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <Field
+        id="diagram-live-text"
+        label="Mermaid"
+        hint="Try adding a line: build --> ship[Ship it]"
+        error={status && !status.ok ? `${status.error.message}. ${status.error.detail ?? ""}` : undefined}
+      >
+        <Textarea id="diagram-live-text" value={text} onChange={(e) => setText(e.target.value)} rows={10} invalid={status ? !status.ok : false} className="font-mono" spellCheck={false} />
+      </Field>
+      <Diagram source={text} title="Your diagram" onRender={setStatus} minHeight={240} />
+    </div>
+  );
+}
+
+export default function DiagramDemo() {
+  const [tab, setTab] = useState("flow");
+  return (
+    <div className="mx-auto w-full max-w-4xl">
+      <Tabs
+        aria-label="Examples"
+        tabs={[
+          { key: "flow", label: "Flow" },
+          { key: "sequence", label: "Sequence" },
+          { key: "plan", label: "Plan" },
+          { key: "live", label: "Live" },
+        ]}
+        value={tab}
+        onChange={setTab}
+      />
+      <TabPanel tab="flow" value={tab}>
+        <Diagram title="Lead routing" source={LEAD_ROUTING} label="Lead routing: demo requests routed by company size to self-serve, an account executive or the enterprise team" />
+      </TabPanel>
+      <TabPanel tab="sequence" value={tab}>
+        <Diagram title="Checkout" source={CHECKOUT} />
+      </TabPanel>
+      <TabPanel tab="plan" value={tab}>
+        <Diagram source={LAUNCH} />
+      </TabPanel>
+      <TabPanel tab="live" value={tab}>
+        <LiveDemo />
+      </TabPanel>
+    </div>
+  );
+}