makersclaw 0.1.0 → 0.3.0

package/registry/blocks/flow-canvas/index.js

@@ -0,0 +1,41 @@
+// The FlowCanvas block — `makersclaw add flow-canvas`. Fixed: compose it
+// through its props (README.md beside this file). The board helpers are
+// plain functions and work anywhere, the server included. The canvas
+// blocks built on this one (account-map, process-map, journey-map,
+// idea-board…) import it, never @xyflow/react directly.
+export { FlowCanvas, useFlowCanvas } from "./flow-canvas";
+export { useCanvas } from "./context";
+export { NodeShell, NodeHandles, EditableText } from "./nodes";
+export { Palette, StickySwatch, ColorDot, ShapeGlyph } from "./chrome";
+export { colorClasses } from "./theme";
+export {
+  GRID,
+  COLORS,
+  STICKY_COLORS,
+  COLOR_NAMES,
+  SHAPES,
+  emptyBoard,
+  createNode,
+  createEdge,
+  cleanBoard,
+  readBoard,
+  boardToText,
+  boardToMarkdown,
+  describeNode,
+  nodeText,
+  autoLayout,
+  alignNodes,
+  distributeNodes,
+  duplicateNodes,
+  removeNodes,
+  frameContents,
+  frameOf,
+  nodeRect,
+  boardBounds,
+  snapPoint,
+  snapToCell,
+  fitFontSize,
+  historyInit,
+  historyReducer,
+  starterTemplates,
+} from "./board";

package/registry/blocks/flow-canvas/nodes.jsx

@@ -0,0 +1,392 @@
+"use client";
+
+// The built-in node types — sticky, shape, text, frame, card, image — and
+// the two pieces a block's own node types are made from:
+//
+//   NodeShell     the chrome every node wears: the selection box, the four
+//                 connection dots that show on hover, the resize handles,
+//                 the lock mark, and the whole-card drop target while a
+//                 connector is being dragged. Wrap your node's body in it.
+//   EditableText  words that edit in place, laid out the same way shown and
+//                 edited so nothing jumps when a double-click starts typing.
+//
+// Colours are token names in the node's data (theme.js turns them into
+// classes); nothing here holds a colour of its own.
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { Handle, NodeResizer, Position } from "@xyflow/react";
+import { Badge, Icon, Image, cx } from "../../ui";
+import { TEXT_SIZE_PX, fitFontSize } from "./board";
+import { useCanvas } from "./context";
+import { EDGE, FILL, SOLID, STROKE, TINT, WASH, tone } from "./theme";
+
+// The dots sit just outside each side, so they never cover the words.
+const DOT =
+  "size-3! min-w-0! min-h-0! rounded-full! border-2! border-primary! bg-background! opacity-0 transition-[opacity,scale] duration-150 motion-reduce:transition-none " +
+  "hover:scale-125 group-hover/node:opacity-100 [[data-connecting=true]_&]:opacity-100 [[data-tool=connector]_&]:opacity-100";
+const SIDES = [
+  [Position.Top, "top", "-top-2!"],
+  [Position.Right, "right", "-right-2!"],
+  [Position.Bottom, "bottom", "-bottom-2!"],
+  [Position.Left, "left", "-left-2!"],
+];
+// While a connector is in the air (or the connector tool is on), the whole
+// card is one big invisible handle: drop anywhere on it to connect.
+const BODY =
+  "absolute! inset-0! top-0! left-0! size-full! min-w-0! min-h-0! [transform:none]! rounded-none! border-0! bg-transparent! opacity-0! z-10";
+
+/** The four connection dots. NodeShell draws them; a node that does not
+ *  use NodeShell must draw these, or connectors cannot reach it. */
+export function NodeHandles() {
+  return SIDES.map(([pos, id, place]) => <Handle key={id} type="source" id={id} position={pos} className={cx(DOT, place)} />);
+}
+
+/**
+ * The chrome around a node. Props:
+ *   id, selected   from the node's props (React Flow passes them)
+ *   locked         data.locked: no resize, a lock mark when selected
+ *   resizable      true (default) · false; minWidth/minHeight (default
+ *                  40/30), keepAspectRatio
+ *   autoHeight     the node's height follows its content (text, cards)
+ *   handles        false: nothing connects to this node
+ *   ring           false: no selection box (draw your own)
+ *   className      the body's layout (never colour)
+ */
+export function NodeShell({
+  id,
+  selected,
+  locked = false,
+  resizable = true,
+  minWidth = 40,
+  minHeight = 30,
+  keepAspectRatio = false,
+  autoHeight = false,
+  handles = true,
+  ring = true,
+  className,
+  children,
+}) {
+  const { api, tool, readOnly, connecting } = useCanvas();
+  return (
+    <div className={cx("group/node relative", autoHeight ? "w-full" : "size-full", className)}>
+      {children}
+      {ring ? (
+        <span
+          aria-hidden="true"
+          className={cx(
+            "pointer-events-none absolute -inset-1 rounded-md transition-shadow duration-150 motion-reduce:transition-none",
+            selected ? "ring-2 ring-primary" : "ring-0 group-hover/node:ring-1 group-hover/node:ring-primary/50",
+          )}
+        />
+      ) : null}
+      {resizable && !readOnly ? (
+        <NodeResizer
+          isVisible={Boolean(selected) && !locked}
+          minWidth={minWidth}
+          minHeight={minHeight}
+          keepAspectRatio={keepAspectRatio}
+          onResizeEnd={() => api?.commit("resize", [id])}
+        />
+      ) : null}
+      {handles && !readOnly ? <NodeHandles /> : null}
+      {handles && !readOnly && (connecting || tool === "connector") ? <Handle type="source" id="body" position={Position.Top} className={BODY} /> : null}
+      {locked && selected ? (
+        <span className="pointer-events-none absolute -top-3 -right-3 grid size-6 place-items-center rounded-full border border-border bg-background text-muted-foreground shadow-sm">
+          <Icon name="lock" size={12} label="Locked" />
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Words that edit in place. Shown and edited in the same box, with the
+ * same classes, so starting to type moves nothing.
+ *   value, editing          the words; true while being edited
+ *   onChange(text)          every keystroke (update the node's data)
+ *   onDone()                Esc, a click away, Enter (singleLine), ⌘Enter
+ *   placeholder             shown while empty (and while editing)
+ *   singleLine              Enter finishes (a title, a label)
+ *   label                   the field's accessible name
+ */
+export function EditableText({ value, editing, onChange, onDone, placeholder, singleLine = false, label, className, style }) {
+  const ref = useRef(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!editing || !el) return;
+    el.innerText = value ?? "";
+    el.focus({ preventScroll: true });
+    // The caret at the end of the words, not the start.
+    const range = document.createRange();
+    range.selectNodeContents(el);
+    range.collapse(false);
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+    // Only when editing starts: typing must not reset the caret.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editing]);
+
+  if (!editing) {
+    return (
+      <div className={className} style={style}>
+        {value ? value : placeholder ? <span className="text-muted-foreground">{placeholder}</span> : null}
+      </div>
+    );
+  }
+  return (
+    // raw: a contentEditable box, not the kit's Textarea — the words keep
+    // the exact size, place and wrapping they have on the card while they
+    // are typed (a field would add its own border, padding and height).
+    <div
+      ref={ref}
+      role="textbox"
+      aria-label={label}
+      aria-multiline={!singleLine}
+      contentEditable="plaintext-only"
+      suppressContentEditableWarning
+      data-placeholder={placeholder ?? ""}
+      className={cx(
+        className,
+        "nodrag nopan nowheel cursor-text select-text outline-none",
+        "empty:before:text-muted-foreground empty:before:content-[attr(data-placeholder)]",
+      )}
+      style={style}
+      onInput={(e) => onChange?.(e.currentTarget.innerText.replace(/\n$/, ""))}
+      onPaste={(e) => {
+        // Plain text only, in browsers without plaintext-only.
+        e.preventDefault();
+        const text = e.clipboardData.getData("text/plain");
+        document.execCommand("insertText", false, singleLine ? text.replace(/\s*\n\s*/g, " ") : text);
+      }}
+      onKeyDown={(e) => {
+        e.stopPropagation();
+        if (e.nativeEvent.isComposing) return;
+        if (e.key === "Escape" || (e.key === "Enter" && (singleLine || e.metaKey || e.ctrlKey))) {
+          e.preventDefault();
+          e.currentTarget.blur();
+        }
+      }}
+      onBlur={() => onDone?.()}
+      onPointerDown={(e) => e.stopPropagation()}
+    />
+  );
+}
+
+// Editing helpers shared by the built-in nodes.
+function useWords(id, key = "text") {
+  const { api, editingNode, readOnly } = useCanvas();
+  const editing = !readOnly && editingNode === id;
+  return {
+    editing,
+    onChange: (text) => api?.updateNodeData(id, { [key]: text }, { commit: false }),
+    onDone: () => api?.stopEditing(id),
+  };
+}
+
+// ── sticky ───────────────────────────────────────────────────────────────
+
+export function StickyNode({ id, data, selected, width, height }) {
+  const w = width ?? 200;
+  const h = height ?? 200;
+  const words = useWords(id);
+  const hasMeta = Boolean(data?.meta);
+  const size = fitFontSize(data?.text, w - 28, h - 28 - (hasMeta ? 18 : 0), { max: Math.min(30, Math.round(h / 5)) });
+  const badge = data?.badge != null && data.badge !== "" ? data.badge : null;
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} minWidth={80} minHeight={80}>
+      <div className="relative size-full overflow-hidden rounded-sm bg-card shadow-md transition-[box-shadow,translate] duration-150 group-hover/node:shadow-lg motion-reduce:transition-none">
+        <div aria-hidden="true" className={cx("absolute inset-0", tone(TINT, data?.color, "warning"))} />
+        <div className={cx("relative flex size-full items-center justify-center px-3.5", hasMeta ? "pt-3.5 pb-7" : "py-3.5")}>
+          <EditableText
+            {...words}
+            value={data?.text}
+            label="Sticky note"
+            placeholder={selected || words.editing ? "Type something" : ""}
+            className="max-h-full w-full overflow-hidden text-center leading-tight break-words whitespace-pre-wrap text-foreground"
+            style={{ fontSize: size }}
+          />
+        </div>
+        {badge !== null ? (
+          <Badge variant="soft" className="absolute top-2 right-2 tabular-nums">
+            {badge}
+          </Badge>
+        ) : null}
+        {hasMeta ? <span className="absolute right-3 bottom-2 left-3 truncate text-2xs text-muted-foreground">{data.meta}</span> : null}
+      </div>
+    </NodeShell>
+  );
+}
+
+// ── shape ────────────────────────────────────────────────────────────────
+
+function Outline({ kind, w, h, className }) {
+  const i = 1;
+  if (kind === "ellipse") return <ellipse cx={w / 2} cy={h / 2} rx={w / 2 - i} ry={h / 2 - i} className={className} />;
+  if (kind === "diamond") return <polygon points={`${w / 2},${i} ${w - i},${h / 2} ${w / 2},${h - i} ${i},${h / 2}`} className={className} />;
+  const r = kind === "pill" ? (h - 2 * i) / 2 : Math.min(10, h / 6);
+  return <rect x={i} y={i} width={w - 2 * i} height={h - 2 * i} rx={r} className={className} />;
+}
+
+export function ShapeNode({ id, data, selected, width, height }) {
+  const w = width ?? 160;
+  const h = height ?? 100;
+  const kind = data?.shape ?? "rect";
+  const words = useWords(id);
+  // A diamond's words live in its middle; an ellipse's a little inside.
+  const inset = kind === "diamond" ? { x: w * 0.22, y: h * 0.22 } : kind === "ellipse" ? { x: w * 0.12, y: h * 0.12 } : { x: 12, y: 8 };
+  const max = TEXT_SIZE_PX[data?.textSize] ?? TEXT_SIZE_PX.md;
+  const size = fitFontSize(data?.text, w - inset.x * 2, h - inset.y * 2, { max, min: 10 });
+  const color = data?.color ?? "muted";
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} minWidth={40} minHeight={30}>
+      {/* raw: the outline is geometry on a canvas (a diamond, an ellipse), which no kit part draws. */}
+      <svg width={w} height={h} className="absolute inset-0 overflow-visible drop-shadow-sm" aria-hidden="true">
+        <Outline kind={kind} w={w} h={h} className="fill-card" />
+        <Outline
+          kind={kind}
+          w={w}
+          h={h}
+          className={cx(tone(FILL, color), tone(STROKE, color), "[stroke-width:1.5] transition-[fill,stroke] duration-150 motion-reduce:transition-none")}
+        />
+      </svg>
+      <div className="relative flex size-full items-center justify-center" style={{ padding: `${inset.y}px ${inset.x}px` }}>
+        <EditableText
+          {...words}
+          value={data?.text}
+          label={`${kind} text`}
+          placeholder={words.editing ? "Type something" : ""}
+          className="max-h-full w-full overflow-hidden text-center font-medium leading-tight break-words whitespace-pre-wrap text-foreground"
+          style={{ fontSize: size }}
+        />
+      </div>
+    </NodeShell>
+  );
+}
+
+// ── text ─────────────────────────────────────────────────────────────────
+
+const ALIGN = { left: "text-left", center: "text-center", right: "text-right" };
+
+export function TextNode({ id, data, selected, height }) {
+  const words = useWords(id);
+  const size = TEXT_SIZE_PX[data?.textSize] ?? TEXT_SIZE_PX.md;
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} autoHeight={!height} minWidth={60} minHeight={20}>
+      <EditableText
+        {...words}
+        value={data?.text}
+        label="Text"
+        placeholder={words.editing ? "Type something" : "Empty text"}
+        className={cx(
+          "w-full px-1 py-0.5 leading-snug break-words whitespace-pre-wrap text-foreground",
+          ALIGN[data?.align] ?? ALIGN.left,
+          (data?.textSize === "lg" || data?.textSize === "xl") && "font-semibold tracking-tight",
+        )}
+        style={{ fontSize: size }}
+      />
+    </NodeShell>
+  );
+}
+
+// ── frame ────────────────────────────────────────────────────────────────
+
+export function FrameNode({ id, data, selected }) {
+  const words = useWords(id, "title");
+  const color = data?.color;
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} minWidth={120} minHeight={80} ring={false}>
+      <div
+        aria-hidden="true"
+        className={cx(
+          "absolute inset-0 rounded-lg border-2 transition-colors duration-150 motion-reduce:transition-none",
+          color ? cx(tone(WASH, color), tone(EDGE, color)) : "border-border bg-card/70",
+          selected ? "border-primary!" : "",
+        )}
+      />
+      {/* The edges take the pointer (drag the frame by its edge); the inside does not. */}
+      <span aria-hidden="true" className="pointer-events-auto absolute inset-x-0 -top-1 h-2" />
+      <span aria-hidden="true" className="pointer-events-auto absolute inset-x-0 -bottom-1 h-2" />
+      <span aria-hidden="true" className="pointer-events-auto absolute inset-y-0 -left-1 w-2" />
+      <span aria-hidden="true" className="pointer-events-auto absolute inset-y-0 -right-1 w-2" />
+      <div className="pointer-events-auto absolute -top-8 left-0 flex max-w-full items-center gap-1.5 rounded-md px-1 py-1 text-sm font-medium text-muted-foreground transition-colors duration-150 hover:text-foreground">
+        {color ? <span aria-hidden="true" className={cx("size-2.5 shrink-0 rounded-full", tone(SOLID, color))} /> : <Icon name="frame" size={14} />}
+        <EditableText {...words} singleLine value={data?.title} label="Frame title" placeholder="Untitled frame" className="min-w-8 truncate" />
+      </div>
+    </NodeShell>
+  );
+}
+
+// ── card ─────────────────────────────────────────────────────────────────
+
+/** The card a block fills: `renderCard(node, ctx)` on FlowCanvas draws its
+ *  inside (kit parts: Avatar, Badge…); without it, a title and a body. */
+export function CardNode({ id, type, data, selected, width, height }) {
+  const { renderCard, api } = useCanvas();
+  const words = useWords(id, "title");
+  const node = { id, type, data: data ?? {}, width, height };
+  const inner = renderCard
+    ? renderCard(node, {
+        selected: Boolean(selected),
+        editing: words.editing,
+        update: (patch) => api?.updateNodeData(id, patch),
+        api,
+      })
+    : undefined;
+  const custom = inner !== undefined && inner !== null;
+  // A card the app draws has no words of ours to edit: hand editing back.
+  useEffect(() => {
+    if (custom && words.editing) api?.stopEditing(id);
+  }, [custom, words.editing, api, id]);
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} autoHeight={!height} minWidth={140} minHeight={60}>
+      <div
+        className={cx(
+          "w-full overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm transition-shadow duration-150 group-hover/node:shadow-md motion-reduce:transition-none",
+          height ? "h-full" : "",
+        )}
+      >
+        {data?.color ? <div aria-hidden="true" className={cx("h-1", tone(SOLID, data.color))} /> : null}
+        {custom ? (
+          inner
+        ) : (
+          <div className="grid gap-1 p-3">
+            <div className="flex items-start gap-2">
+              {data?.icon ? <Icon name={data.icon} size={16} className="mt-0.5 shrink-0 text-muted-foreground" /> : null}
+              <EditableText
+                {...words}
+                singleLine
+                value={data?.title}
+                label="Card title"
+                placeholder="Untitled"
+                className="min-w-0 flex-1 text-sm font-medium leading-snug break-words"
+              />
+              {data?.badge ? <Badge variant="soft">{data.badge}</Badge> : null}
+            </div>
+            {data?.body ? <p className="text-sm leading-snug text-muted-foreground break-words whitespace-pre-wrap">{data.body}</p> : null}
+          </div>
+        )}
+      </div>
+    </NodeShell>
+  );
+}
+
+// ── image ────────────────────────────────────────────────────────────────
+
+export function ImageNode({ id, data, selected }) {
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} keepAspectRatio minWidth={60} minHeight={40}>
+      <div className="size-full overflow-hidden rounded-md bg-card shadow-md">
+        <Image src={data?.src || undefined} alt={data?.alt ?? ""} fit="cover" rounded="md" loading="eager" className="size-full" draggable={false} />
+      </div>
+    </NodeShell>
+  );
+}
+
+export const BUILT_IN_NODES = {
+  sticky: StickyNode,
+  shape: ShapeNode,
+  text: TextNode,
+  frame: FrameNode,
+  card: CardNode,
+  image: ImageNode,
+};

package/registry/blocks/flow-canvas/theme.js

@@ -0,0 +1,174 @@
+// React Flow in the workspace theme — the one place its look is mapped.
+//
+// React Flow paints itself from CSS variables (--xy-background-pattern-
+// color, --xy-selection-border…) and a few fixed rules in its stylesheet
+// (@xyflow/react/dist/style.css, imported by flow-canvas.jsx). Each one is
+// pointed at a token here, as Tailwind arbitrary properties on the flow's
+// root. Every class ends in `!`: the library's stylesheet is unlayered, and
+// an unlayered rule beats any Tailwind utility (those live in @layer
+// utilities) whatever its specificity; `!important` inside a layer is the
+// one thing that outranks it. Our own nodes and connectors draw with
+// token classes directly (nodes.jsx, edges.jsx), so the library's node and
+// edge colours are never seen.
+export const THEME = [
+  // the canvas: the page's background with dots in the muted ink
+  "[--xy-background-color:transparent]!",
+  "[--xy-background-pattern-color:var(--color-muted-foreground)]!",
+  "[&_.react-flow__background]:opacity-35!",
+  // the marquee, and the box around a multi-selection
+  "[&_.react-flow__selection]:bg-primary/8!",
+  "[&_.react-flow__selection]:border!",
+  "[&_.react-flow__selection]:border-solid!",
+  "[&_.react-flow__selection]:border-primary/70!",
+  "[&_.react-flow__selection]:rounded-sm!",
+  "[&_.react-flow__nodesselection-rect]:bg-transparent!",
+  "[&_.react-flow__nodesselection-rect]:border!",
+  "[&_.react-flow__nodesselection-rect]:border-dashed!",
+  "[&_.react-flow__nodesselection-rect]:border-primary/60!",
+  "[&_.react-flow__nodesselection-rect]:rounded-sm!",
+  // the line drawn while a connector is being dragged out
+  "[&_.react-flow__connection-path]:stroke-primary!",
+  "[&_.react-flow__connection-path]:[stroke-width:2]!",
+  // cursors that match the tool (flow-canvas.jsx sets data-tool on the root)
+  "[&_.react-flow__pane.selection]:cursor-default!",
+  "[&_.react-flow__node.draggable]:cursor-default!",
+  "[&_.react-flow__node.draggable.dragging]:cursor-grabbing!",
+  "data-[tool=hand]:[&_.react-flow__pane]:cursor-grab!",
+  "data-[tool=hand]:[&_.react-flow__pane.dragging]:cursor-grabbing!",
+  "data-[tool=hand]:[&_.react-flow__node]:cursor-grab!",
+  "data-[tool=place]:[&_.react-flow__pane]:cursor-crosshair!",
+  "data-[tool=text]:[&_.react-flow__pane]:cursor-text!",
+  "data-[tool=connector]:[&_.react-flow__node]:cursor-crosshair!",
+  // keyboard focus on a card: a visible ring (the library turns it off)
+  "[&_.react-flow__node:focus-visible]:outline-2!",
+  "[&_.react-flow__node:focus-visible]:outline-offset-4!",
+  "[&_.react-flow__node:focus-visible]:outline-ring!",
+  "[&_.react-flow__node:focus-visible]:[outline-style:solid]!",
+  // frames: only their title and edge take the pointer, so a double-click
+  // or a marquee inside one lands on the canvas (nodes.jsx)
+  "[&_.react-flow__node-frame]:pointer-events-none!",
+  // the resize handles on a selected card
+  "[&_.react-flow__resize-control.handle]:size-2.5!",
+  "[&_.react-flow__resize-control.handle]:rounded-xs!",
+  "[&_.react-flow__resize-control.handle]:border-primary!",
+  "[&_.react-flow__resize-control.handle]:bg-background!",
+  "[&_.react-flow__resize-control.handle]:pointer-events-auto!",
+  "[&_.react-flow__resize-control.line]:border-primary/0!",
+  "[&_.react-flow__resize-control.line]:pointer-events-auto!",
+  "[&_.react-flow__resize-control.line.left]:w-2!",
+  "[&_.react-flow__resize-control.line.right]:w-2!",
+  "[&_.react-flow__resize-control.line.top]:h-2!",
+  "[&_.react-flow__resize-control.line.bottom]:h-2!",
+  // the minimap: a card with the board in muted ink
+  "[--xy-minimap-background-color:var(--color-card)]!",
+  "[--xy-minimap-node-background-color:var(--color-muted-foreground)]!",
+  "[--xy-minimap-mask-background-color:var(--color-muted)]!",
+  "[&_.react-flow__minimap]:rounded-lg!",
+  "[&_.react-flow__minimap]:border!",
+  "[&_.react-flow__minimap]:border-border!",
+  "[&_.react-flow__minimap]:shadow-md!",
+  "[&_.react-flow__minimap]:overflow-hidden!",
+  "[&_.react-flow__minimap-node]:opacity-50!",
+  "[&_.react-flow__minimap-mask]:opacity-70!",
+  // React Flow's credit: kept (they ask for it), in the muted ink
+  "[&_.react-flow__attribution]:bg-transparent!",
+  "[&_.react-flow__attribution_a]:text-muted-foreground!",
+  // panels: ours sit in the corners with our own spacing
+  "[&_.react-flow__panel]:m-3!",
+].join(" ");
+
+// Colour TOKENS → classes, written out whole so Tailwind generates them. A
+// board stores the token name ("chart-3", "warning"); these turn it into
+// paint. A sticky is the card surface with the hue laid over it, so it
+// reads the same on a light or a dark workspace.
+export const TINT = {
+  warning: "bg-warning/35",
+  "chart-1": "bg-chart-1/25",
+  "chart-2": "bg-chart-2/30",
+  "chart-3": "bg-chart-3/30",
+  "chart-4": "bg-chart-4/30",
+  "chart-5": "bg-chart-5/30",
+  success: "bg-success/30",
+  info: "bg-info/30",
+  destructive: "bg-destructive/25",
+  muted: "bg-muted",
+};
+/** A full-strength dot of the colour: the palette's swatches. */
+export const SOLID = {
+  warning: "bg-warning",
+  "chart-1": "bg-chart-1",
+  "chart-2": "bg-chart-2",
+  "chart-3": "bg-chart-3",
+  "chart-4": "bg-chart-4",
+  "chart-5": "bg-chart-5",
+  success: "bg-success",
+  info: "bg-info",
+  destructive: "bg-destructive",
+  muted: "bg-muted-foreground/40",
+};
+/** Shapes (svg): a tinted fill over the card surface, the hue as the edge. */
+export const FILL = {
+  warning: "fill-warning/35",
+  "chart-1": "fill-chart-1/25",
+  "chart-2": "fill-chart-2/30",
+  "chart-3": "fill-chart-3/30",
+  "chart-4": "fill-chart-4/30",
+  "chart-5": "fill-chart-5/30",
+  success: "fill-success/30",
+  info: "fill-info/30",
+  destructive: "fill-destructive/25",
+  muted: "fill-muted",
+};
+export const STROKE = {
+  warning: "stroke-warning",
+  "chart-1": "stroke-chart-1",
+  "chart-2": "stroke-chart-2",
+  "chart-3": "stroke-chart-3",
+  "chart-4": "stroke-chart-4",
+  "chart-5": "stroke-chart-5",
+  success: "stroke-success",
+  info: "stroke-info",
+  destructive: "stroke-destructive",
+  muted: "stroke-border",
+};
+/** A frame's faint wash of its colour (none: the plain card surface). */
+export const WASH = {
+  warning: "bg-warning/8",
+  "chart-1": "bg-chart-1/8",
+  "chart-2": "bg-chart-2/8",
+  "chart-3": "bg-chart-3/8",
+  "chart-4": "bg-chart-4/8",
+  "chart-5": "bg-chart-5/8",
+  success: "bg-success/8",
+  info: "bg-info/8",
+  destructive: "bg-destructive/8",
+  muted: "bg-muted/60",
+};
+/** A frame's edge in its colour. */
+export const EDGE = {
+  warning: "border-warning/60",
+  "chart-1": "border-chart-1/60",
+  "chart-2": "border-chart-2/60",
+  "chart-3": "border-chart-3/60",
+  "chart-4": "border-chart-4/60",
+  "chart-5": "border-chart-5/60",
+  success: "border-success/60",
+  info: "border-info/60",
+  destructive: "border-destructive/60",
+  muted: "border-border",
+};
+/** An unknown token falls back to this. */
+export const tone = (map, token, fallback = "muted") => map[token] ?? map[fallback];
+
+/** Every class for one colour token, for a block's own node types:
+ *  colorClasses("chart-3").tint → "bg-chart-3/30". */
+export function colorClasses(token) {
+  return {
+    tint: tone(TINT, token),
+    solid: tone(SOLID, token),
+    fill: tone(FILL, token),
+    stroke: tone(STROKE, token),
+    wash: tone(WASH, token),
+    edge: tone(EDGE, token),
+  };
+}