makersclaw 0.1.0 → 0.3.0

package/registry/blocks/menubar/menubar.jsx

@@ -0,0 +1,199 @@
+"use client";
+
+import { useId, useRef, useState } from "react";
+import { Icon, Menu, MenuPanel, cx, panelClass, usePopoverPosition } from "../../ui";
+
+// Menubar — a desktop app's File · Edit · View · Help. Each top-level
+// menu is a trigger and the kit's MenuPanel (the same panel, keys and
+// `items` as Menu), opened as an auto popover: the browser closes the
+// others when one opens, and does the light dismiss and Escape.
+//
+// The WAI-ARIA menubar pattern: the bar is one Tab stop (roving
+// tabindex); ArrowLeft/Right move along it, and when a menu is open they
+// open the neighbour instead; ArrowDown, Enter or Space open a menu at its
+// first item, ArrowUp at its last. Once a menu is open, hovering another
+// trigger switches to it. Escape closes and puts focus back on the
+// trigger. Below `md` the bar is one menu button whose menus unfold as
+// submenus in place — Menu already does that on a phone.
+
+const ITEMS = '[role^="menuitem"]:not([disabled])';
+
+// Only this panel's items, not a submenu's inside it.
+function own(panel) {
+  return panel ? [...panel.querySelectorAll(ITEMS)].filter((n) => n.closest('[role="menu"]') === panel) : [];
+}
+
+const focus = (n) => n?.focus({ preventScroll: true });
+
+export function Menubar({ menus, label = "Menu bar", menuLabel = "Menu", className }) {
+  const id = useId();
+  const live = (menus ?? []).filter((m) => m && (m.items ?? []).some(Boolean));
+  const [active, setActive] = useState(0);
+  const [open, setOpen] = useState(-1);
+  const triggers = useRef([]);
+  const panels = useRef([]);
+  const start = useRef("first");
+
+  if (live.length === 0) return null;
+  const n = live.length;
+  const tabStop = Math.min(active, n - 1);
+  const isOpen = (i) => Boolean(panels.current[i]?.matches(":popover-open"));
+  const openNow = () => live.findIndex((_, i) => isOpen(i));
+
+  function focusStart(i) {
+    const nodes = own(panels.current[i]);
+    if (start.current === "first") focus(nodes[0]);
+    else if (start.current === "last") focus(nodes[nodes.length - 1]);
+    start.current = "first";
+  }
+
+  // Open menu i; an open sibling closes (auto popovers). `from` is where
+  // focus goes: its first item, its last, or "none" — stay on the trigger.
+  function show(i, from = "first") {
+    const p = panels.current[i];
+    if (!p) return;
+    setActive(i);
+    start.current = from;
+    if (from === "none") focus(triggers.current[i]);
+    if (isOpen(i)) focusStart(i);
+    else p.showPopover();
+  }
+
+  function hide(i) {
+    focus(triggers.current[i]);
+    if (isOpen(i)) panels.current[i].hidePopover();
+  }
+
+  function onToggle(i, e) {
+    // A submenu's toggle bubbles here; it is not this menu's.
+    if (e.target !== e.currentTarget) return;
+    if (e.newState === "open") {
+      setOpen(i);
+      setActive(i);
+      focusStart(i);
+    } else {
+      setOpen((o) => (o === i ? -1 : o));
+      const a = document.activeElement;
+      if (!a || a === document.body || panels.current[i]?.contains(a)) focus(triggers.current[i]);
+    }
+  }
+
+  function onTriggerKey(i, e) {
+    const k = e.key;
+    if (k === "ArrowRight" || k === "ArrowLeft") {
+      const j = (i + (k === "ArrowRight" ? 1 : -1) + n) % n;
+      if (openNow() >= 0) show(j, "first");
+      else focus(triggers.current[j]);
+    } else if (k === "Home") focus(triggers.current[0]);
+    else if (k === "End") focus(triggers.current[n - 1]);
+    else if (k === "ArrowDown") show(i, "first");
+    else if (k === "ArrowUp") show(i, "last");
+    else return; // Enter and Space click the trigger, which toggles its menu
+    e.preventDefault();
+  }
+
+  // Keys the open panel does not use itself: ArrowRight on an item with
+  // no submenu, ArrowLeft outside a submenu — the neighbours.
+  function onPanelKey(i, e) {
+    if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
+    e.preventDefault();
+    show((i + (e.key === "ArrowRight" ? 1 : -1) + n) % n, "first");
+  }
+
+  return (
+    <div className={className}>
+      <div role="menubar" aria-label={label} aria-orientation="horizontal" className="hidden h-10 w-fit max-w-full items-center gap-1 rounded-md border border-border bg-background p-1 shadow-xs md:flex">
+        {live.map((m, i) => (
+          <Top
+            key={m.key ?? `${i}-${m.label}`}
+            menu={m}
+            triggerId={`${id}t${i}`}
+            panelId={`${id}m${i}`}
+            tabIndex={i === tabStop ? 0 : -1}
+            expanded={open === i}
+            triggerRef={(el) => (triggers.current[i] = el)}
+            panelRef={(el) => (panels.current[i] = el)}
+            onFocus={() => setActive(i)}
+            onPointerEnter={(e) => {
+              if (e.pointerType !== "mouse") return;
+              const o = openNow();
+              if (o >= 0 && o !== i) show(i, "none");
+            }}
+            onPointerDown={() => (start.current = "first")}
+            onTriggerKey={(e) => onTriggerKey(i, e)}
+            onPanelKey={(e) => onPanelKey(i, e)}
+            onToggle={(e) => onToggle(i, e)}
+            onExit={() => hide(i)}
+          />
+        ))}
+      </div>
+      <div className="md:hidden">
+        <Menu
+          items={live.map((m) => ({ label: m.label, icon: m.icon, items: m.items }))}
+          label={menuLabel}
+          align="start"
+          trigger={
+            <>
+              <Icon name="menu" />
+              <span>{menuLabel}</span>
+            </>
+          }
+          className="h-11 border border-border bg-background px-3 font-medium shadow-xs"
+        />
+      </div>
+    </div>
+  );
+}
+
+// One top-level menu: its trigger and its panel. A component of its own
+// because each panel keeps itself beside its trigger with a hook.
+function Top({ menu, triggerId, panelId, tabIndex, expanded, triggerRef, panelRef, onFocus, onPointerEnter, onPointerDown, onTriggerKey, onPanelKey, onToggle, onExit }) {
+  const btn = useRef(null);
+  const pop = useRef(null);
+  usePopoverPosition(btn, pop, { side: "bottom", align: "start", offset: 6 });
+
+  return (
+    <div role="none" onKeyDown={(e) => (e.target === btn.current ? onTriggerKey(e) : onPanelKey(e))}>
+      {/* raw: a menubar item — role=menuitem, a roving tabindex and its
+          panel's popoverTarget, drawn flat like Menu's own trigger; Button
+          is a form control's look. */}
+      <button
+        ref={(el) => {
+          btn.current = el;
+          triggerRef(el);
+        }}
+        id={triggerId}
+        type="button"
+        role="menuitem"
+        popoverTarget={panelId}
+        aria-haspopup="menu"
+        aria-expanded={expanded}
+        aria-controls={panelId}
+        tabIndex={tabIndex}
+        onFocus={onFocus}
+        onPointerEnter={onPointerEnter}
+        onPointerDown={onPointerDown}
+        className={cx(
+          "inline-flex h-8 select-none items-center rounded-sm px-3 text-sm font-medium outline-none",
+          "hover:bg-accent focus-visible:bg-accent focus-visible:ring-2 focus-visible:ring-ring aria-expanded:bg-accent aria-expanded:text-accent-foreground",
+        )}
+      >
+        {menu.label}
+      </button>
+      <MenuPanel
+        id={panelId}
+        items={menu.items}
+        labelledBy={triggerId}
+        panelRef={(el) => {
+          pop.current = el;
+          panelRef(el);
+        }}
+        popover="auto"
+        onToggle={onToggle}
+        onExit={onExit}
+        onClose={onExit}
+        className={panelClass("auto", "min-w-52 max-h-[calc(100vh-1rem)] overflow-y-auto p-1")}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,206 @@
+# MindMap
+
+A mind map you can build without touching the mouse. One centre topic,
+main branches balanced on both sides of it, each branch a tidy tree in its
+own colour. **Tab** adds a subtopic, **Enter** the next topic, typing
+renames, the arrows walk the map. The layout is automatic: topics never
+need dragging into place, and the map re-balances as it grows.
+
+A bar on top holds undo and redo, the save state, the selected topic's
+actions (add, colour, fold, delete) and a Map / Outline switch. The
+Outline view is the map as a nested list — the reading of it for a screen
+reader, and a quick way to jump to a topic.
+
+It is built on `flow-canvas` (which draws it, pans and zooms): this block
+owns the tree, the layout and the keys.
+
+```jsx
+import { MindMap } from "../components/blocks/mind-map";   // a Makersclaw app ("./blocks/mind-map" from components/)
+import { MindMap } from "@/components/makersclaw/blocks/mind-map";   // a shadcn project
+```
+
+`MindMap` is a client component: render it from a `"use client"`
+component. `makersclaw add mind-map` adds `flow-canvas` with it (and its
+npm package, `@xyflow/react`: run `npm install` after). The tree helpers
+(`mindMapToText`, `outlineToMindMap`, `layoutMindMap`…) are plain
+functions and work on the server too.
+
+## The data
+
+A map is one tree of topics. Store it as it comes out of `onChange` (one
+`jsonb` column), and keep `mindMapToText(map)` beside it for search and
+agents.
+
+```js
+{
+  id: "root", text: "Relay 2.0 launch",
+  children: [
+    { id: "why", text: "Why now", side: "right", children: [
+      { id: "why-1", text: "Churn up 3 pts" },
+    ] },
+    { id: "risks", text: "Risks", side: "left", color: "chart-4", collapsed: true, children: [ … ] },
+  ],
+}
+```
+
+- `id` — any string, unique in the map. `text` — the words (a newline is
+  allowed). `children` — the subtopics, in order.
+- `collapsed: true` — the branch is folded; the map shows how many topics
+  it hides.
+- `color` — a colour **token**, never a colour value: `"chart-2"` …
+  `"chart-5"`, `"chart-1"` (the theme's own), `"warning"`, `"success"`,
+  `"info"`, `"destructive"`. Subtopics inherit their branch's. A main
+  branch with none takes the next of `colors`.
+- `side` — `"left"` or `"right"`, main branches only. Missing, the map
+  splits the branches to balance the two sides; the first change pins
+  them, so adding a branch never flips the others across the centre.
+- Anything else on a topic (`note`, your own keys) is kept as it is.
+
+`normalizeMap(anything)` cleans what it is given: missing or repeated ids,
+`title`/`label` for `text`, `topics`/`items` for `children`, an outline
+string, or nothing (a fresh map). The component runs it on `value`.
+
+## Props
+
+- `value` — the map, controlled. A new `value` that is not what the map
+  last sent through `onChange` replaces it (loading another record); that
+  replacement can be undone. Pass back exactly what `onChange` gave you.
+- `defaultValue` — the starting map, uncontrolled. With neither, a centre
+  topic called "Central topic" and the first-run card.
+- `onChange(map)` — the whole tree after a change settles (debounced by
+  `changeDelay`; typing is saved as it goes). Selection, folding in
+  read-only mode, panning and zooming never call it.
+- `onSave(map)` — `async`, returns `{ ok: true }` or `{ ok: false,
+  error? }` (a throw counts as failed). Called right after `onChange`. The
+  bar shows "Saving…", "Saved", or the error with Retry. A failure keeps
+  the map as it is on screen (nothing typed is thrown away); Retry sends
+  it again.
+- `changeDelay` — ms of quiet before `onChange` / `onSave` (default 400).
+- `readOnly` — `false` (default). `true`: no editing; the arrows still
+  walk the map, Space folds and unfolds (not saved), the Outline view and
+  copying work.
+- `colors` — the branch palette, token names (default `BRANCH_COLORS`:
+  chart-2, 3, 4, 5, 1). The colour picker offers these plus warning,
+  success, info and destructive.
+- `templates` — what the first-run card offers: `[{ id, label, icon?,
+  description?, map }]`, `map` a tree or a function returning one (default
+  `mindMapTemplates()`: Project plan, Brainstorm, Meeting notes). `[]` for
+  none.
+- `placeholder` — what an empty topic shows while it is typed (default
+  "New topic").
+- `height` — px or any CSS length, default `600`. A height class in
+  `className` (`h-dvh`, `h-full`, `flex-1`) replaces it.
+- `label` — the map's accessible name (default "Mind map").
+- `onSelectionChange(topic | null)` — the selected topic changed (a side
+  panel with its notes).
+- `className` — layout around it (margin, width, height). Never colour.
+
+## Keyboard
+
+With a topic selected (click one, or press an arrow):
+
+| Key | Does |
+| --- | --- |
+| Tab | add a subtopic and type it |
+| Enter / Shift+Enter | add the next topic below / above |
+| Space, F2, or just type | rename |
+| Delete / Backspace | delete the topic and its branch (a toast offers Undo) |
+| ← → ↑ ↓ | walk the map: outwards to a child, inwards to the parent, up and down the column |
+| ⌥↑ / ⌥↓ | move the topic up or down among its siblings |
+| Shift+Tab | move the topic up a level |
+| ⌘↑ / ⌘↓ | fold / unfold the branch |
+| ⌘D | duplicate the branch |
+| ⌘C / ⌘X / ⌘V | copy or cut a branch as an outline; paste an outline (from notes, a doc, an agent) as subtopics |
+| ⌘Z / ⇧⌘Z | undo / redo |
+| Home | the centre |
+| Esc | clear the selection |
+| ⇧1 | fit the map to the screen |
+| ? | the shortcuts sheet |
+
+While typing a topic: **Enter** finishes it and starts the next one (on
+an empty one it steps out a level, so a run of topics never needs the
+mouse), **Tab** finishes it and starts a subtopic (on an empty one it
+moves in a level), **Backspace** on an empty topic removes it and goes
+back to the one before, **Esc** finishes. Shift+Enter is a new line.
+
+With the mouse: click selects, double-click renames, the **+** at a
+topic's end adds a subtopic, the chip at a branch's end folds it (folded,
+it shows the count it hides), and dragging a topic onto another moves its
+branch there. A plain drag on the empty canvas pans; pinch or ⌘-scroll
+zooms. On a touch screen a drag always pans; tap selects, double-tap
+renames, and the bar's buttons add.
+
+## The helpers
+
+Plain functions over a tree; each returns a new tree and leaves the old
+one as it was.
+
+- Read: `findTopic(map, id)`, `pathTo(map, id)` → `[root, …, topic]`,
+  `parentOf(map, id)`, `countTopics(topic)` (everything under it).
+- Change: `updateTopic(map, id, patch)`, `insertTopic(map, parentId,
+  topic, index?)`, `insertSibling(map, id, topic, { before })`,
+  `removeTopic(map, id)`, `moveTopic(map, id, parentId, index?)` (refused
+  into its own branch), `shiftTopic(map, id, ±1)`, `indentTopic`,
+  `outdentTopic`, `duplicateTopic(map, id)` → `{ root, id }`,
+  `setAllCollapsed(map, on)`, `createTopic(text)`.
+- Text: `mindMapToText(map)` (an indented outline, for an agent or search),
+  `mindMapToMarkdown(map)` (a heading and a nested list),
+  `outlineToMindMap(text)` and `outlineToTopics(text)` (bullets, numbers,
+  headings, tabs or spaces — what an agent writes).
+- Layout: `layoutMindMap(map, { measure?, colors? })` → `{ items, bounds }`
+  (every visible topic's box, side, depth, colour and the line to its
+  parent), `mindMapToBoard(map)` (the same as a flow-canvas board).
+- `mindMapTemplates()`, `BRANCH_COLORS`.
+
+## Example
+
+```jsx
+// components/PlanMap.jsx — client
+"use client";
+import { useState } from "react";
+import { updateRow } from "../lib/actions";
+import { MindMap, mindMapToText } from "./blocks/mind-map";
+
+export default function PlanMap({ plan }) {
+  const [map, setMap] = useState(plan.map);   // jsonb, may be null
+  return (
+    <MindMap
+      value={map ?? undefined}
+      defaultValue={{ text: plan.name }}
+      onChange={setMap}
+      onSave={(m) => updateRow({ source: "public.plans", id: plan.id, patch: { map: m, map_text: mindMapToText(m) } })}
+      label={`${plan.name} map`}
+      className="h-[calc(100dvh-8rem)]"
+    />
+  );
+}
+```
+
+An agent's outline, straight onto a map:
+
+```jsx
+const map = outlineToMindMap(`# Hiring plan
+- Roles
+  - Founding engineer
+  - Designer
+- Sourcing
+  - Referrals
+  - Communities`);
+<MindMap defaultValue={map} onSave={save} />
+```
+
+## What it will not do
+
+- Free placement: topics sit where the layout puts them (drag moves a
+  branch to another topic, not to a spot). For free boards use
+  `flow-canvas` or `whiteboard`.
+- Cross-links between branches, images or icons on topics.
+- Collaborate live: saves are last-write-wins.
+- Export an image.
+- Render the map on the server: the server shows it as text until the
+  canvas mounts. For a read-only page that must be rich in the HTML,
+  render `mindMapToMarkdown` yourself.
+
+A map it cannot be is your own component in `components/` — not an edit
+to this block. Its files are fixed: `npm run check` refuses a change, and
+`makersclaw add mind-map` restores them.

package/registry/blocks/mind-map/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "mind-map",
+  "title": "MindMap",
+  "description": "A mind map you can build without the mouse, on flow-canvas: a centre topic with main branches balanced on both sides, each branch a tidy auto-laid-out tree in its own chart hue. Tab adds a subtopic, Enter the next topic, typing renames, arrows walk the map, ⌘↑/⌘↓ fold a branch (a folded one shows how many it hides), ⌥↑/⌥↓ reorder, Shift+Tab moves up a level; drag a topic onto another to move its branch. Undo/redo, a colour per branch, an Outline view, copy a branch as an outline and paste an outline as topics, starter templates. The map is plain JSON (a tree of topics); saves are async callbacks answering { ok }.",
+  "useWhen": "A screen for thinking in a tree: brainstorming around one idea, planning a project, breaking a goal down, notes from a meeting, a topic outline an agent drafted. Not for free-form boards with stickies and arrows (flow-canvas, whiteboard), a people hierarchy (org-chart), or a process with steps (process-map).",
+  "tags": ["mind map", "mindmap", "brainstorm", "tree", "outline", "ideas", "topics", "branches", "planning", "xmind", "mindnode", "keyboard", "canvas", "map"],
+  "exports": ["MindMap", "BRANCH_COLORS", "normalizeMap", "createTopic", "findTopic", "updateTopic", "insertTopic", "removeTopic", "moveTopic", "layoutMindMap", "mindMapToBoard", "mindMapToText", "mindMapToMarkdown", "outlineToMindMap", "outlineToTopics", "mindMapTemplates"],
+  "files": ["index.js", "mind-map.jsx", "topic.jsx", "tree.js"],
+  "requires": ["flow-canvas"]
+}

package/registry/blocks/mind-map/demo.jsx

@@ -0,0 +1,103 @@
+"use client";
+
+// MindMap two ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Launch plan   a product launch, broken down: five branches on both
+//                 sides, one folded. Read-only and a failing save behind
+//                 switches; what an agent reads (the outline) beside it.
+//   Blank         a new map: the first-run card and the templates.
+import { useState } from "react";
+import { Card, Switch, TabPanel, Tabs } from "../components/ui";
+import { MindMap, mindMapToText } from "../components/blocks/mind-map";
+
+const LAUNCH = {
+  id: "root",
+  text: "Relay 2.0 launch",
+  children: [
+    {
+      id: "why",
+      text: "Why now",
+      children: [
+        { id: "why-1", text: "Churn up 3 pts after the price change" },
+        { id: "why-2", text: "Two rivals ship sync this quarter" },
+      ],
+    },
+    {
+      id: "audience",
+      text: "Who it's for",
+      children: [
+        { id: "aud-1", text: "Ops leads at 50–200 person teams", children: [{ id: "aud-1a", text: "Interview 8 by May 20" }] },
+        { id: "aud-2", text: "Agencies running client workspaces" },
+      ],
+    },
+    {
+      id: "scope",
+      text: "Scope",
+      children: [
+        { id: "scope-1", text: "Offline sync" },
+        { id: "scope-2", text: "Shared inbox v2" },
+        { id: "scope-3", text: "Audit log export" },
+      ],
+    },
+    {
+      id: "gtm",
+      text: "Go to market",
+      children: [
+        { id: "gtm-1", text: "Launch post + changelog", children: [{ id: "gtm-1a", text: "Draft by Priya" }, { id: "gtm-1b", text: "Review with Tomás" }] },
+        { id: "gtm-2", text: "Webinar, June 4" },
+        { id: "gtm-3", text: "Email the 1,240 trial users" },
+      ],
+    },
+    {
+      id: "risks",
+      text: "Risks",
+      collapsed: true,
+      children: [
+        { id: "risk-1", text: "Sync conflicts on flaky networks" },
+        { id: "risk-2", text: "Support load in week one" },
+        { id: "risk-3", text: "Pricing page not ready" },
+      ],
+    },
+  ],
+};
+
+export default function MindMapDemo() {
+  const [map, setMap] = useState(LAUNCH);
+  const [readOnly, setReadOnly] = useState(false);
+  const [failing, setFailing] = useState(false);
+  const [tab, setTab] = useState("launch");
+
+  const save = async () => {
+    await new Promise((r) => setTimeout(r, 500));
+    return failing ? { ok: false, error: "Couldn't reach the server" } : { ok: true };
+  };
+
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="Examples"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "launch", label: "Launch plan" },
+          { key: "blank", label: "Blank" },
+        ]}
+      />
+      <TabPanel tab="launch" value={tab} className="grid gap-4">
+        <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
+          <Switch label="Read-only" checked={readOnly} onChange={(e) => setReadOnly(e.target.checked)} />
+          <Switch label="Saves fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} />
+        </div>
+        <div className="grid gap-4 xl:grid-cols-[minmax(0,1fr)_18rem]">
+          <MindMap value={map} onChange={setMap} onSave={save} readOnly={readOnly} label="Relay 2.0 launch" height={620} />
+          <Card title="What an agent reads" padding="sm" className="max-xl:hidden">
+            <pre className="max-h-[34rem] overflow-auto text-xs leading-5 whitespace-pre-wrap text-muted-foreground">{mindMapToText(map)}</pre>
+          </Card>
+        </div>
+      </TabPanel>
+      <TabPanel tab="blank" value={tab}>
+        <MindMap defaultValue={{ text: "Q3 planning" }} onSave={save} label="Q3 planning" height={560} />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/mind-map/index.js

@@ -0,0 +1,31 @@
+// The MindMap block — `makersclaw add mind-map`. Fixed: compose it through
+// its props (README.md beside this file). Built on flow-canvas (it draws,
+// pans and zooms; this block owns the tree, the layout and the keys). The
+// tree helpers are plain functions and run anywhere, the server included.
+export { MindMap } from "./mind-map";
+export {
+  BRANCH_COLORS,
+  normalizeMap,
+  createTopic,
+  findTopic,
+  pathTo,
+  parentOf,
+  countTopics,
+  updateTopic,
+  insertTopic,
+  insertSibling,
+  removeTopic,
+  moveTopic,
+  shiftTopic,
+  indentTopic,
+  outdentTopic,
+  duplicateTopic,
+  setAllCollapsed,
+  layoutMindMap,
+  mindMapToBoard,
+  mindMapToText,
+  mindMapToMarkdown,
+  outlineToMindMap,
+  outlineToTopics,
+  mindMapTemplates,
+} from "./tree";