makersclaw 0.1.0 → 0.3.0

package/registry/blocks/org-chart/README.md

@@ -0,0 +1,145 @@
+# OrgChart
+
+Who reports to whom, top down. Give it people as a flat list — each row
+names its manager — and it draws the tree: managers centred over their
+teams, a team with no managers in it as a compact column (twelve cards in
+a row read worse than a list), every line in place.
+
+Teams past the first levels start folded; the chip under a manager says
+how many report to them and, folded, how many are hidden. **Find a
+person** (or press `/`) unfolds the way down to them, centres them and
+lights their chain of managers. A click selects a card; a second click
+(or Enter) opens a details sheet: who they report to, their direct
+reports, the team's size. Cards carry a colour strip by department, with
+a legend on top.
+
+With `onChangeManager`, drag a card onto another to move that person to a
+new manager — shown at once, saved through your callback, undone if it
+fails, with an Undo in the toast.
+
+It is built on `flow-canvas` (which draws it, pans and zooms): this block
+builds the tree, lays it out and owns the keys.
+
+```jsx
+import { OrgChart } from "../components/blocks/org-chart";   // a Makersclaw app ("./blocks/org-chart" from components/)
+import { OrgChart } from "@/components/makersclaw/blocks/org-chart";   // a shadcn project
+```
+
+`OrgChart` is a client component: render it from a `"use client"`
+component. `makersclaw add org-chart` adds `flow-canvas` with it (and its
+npm package, `@xyflow/react`: run `npm install` after). The helpers
+(`buildOrg`, `orgToText`…) are plain functions and work on the server too.
+
+## The data
+
+One row per person, as a table holds them:
+
+```js
+[
+  { id: "p1", name: "Amara Okafor", title: "Chief Executive Officer", department: "Leadership" },
+  { id: "p2", name: "Daniel Reyes", title: "VP Engineering", department: "Engineering", managerId: "p1", avatar: "https://…", email: "daniel@…", location: "Lisbon" },
+]
+```
+
+- `id` — required, unique. `name`, `title` — the card's two lines.
+- `managerId` (or the field named by `managerKey`) — the manager's `id`.
+  Missing, or naming someone not in the list: the person is the top of a
+  tree (several tops sit side by side). A loop of managers is broken, and
+  never hangs the chart.
+- `avatar` — an image URL; without one the card shows initials.
+- `department` (or the field named by `groupBy`) — the card's colour strip
+  and the legend. Colours are the theme's chart hues, given in the order
+  groups first appear.
+- `email`, `location` — shown in the details sheet. Any other field is
+  kept and handed back to your callbacks.
+
+## Props
+
+- `people` — required, the rows above. An empty list shows a friendly
+  empty state.
+- `managerKey` — the field naming the manager (default `"managerId"`).
+- `groupBy` — the field to colour by (default `"department"`), or
+  `(person) => group`; `null` for no colours or legend.
+- `defaultDepth` — how many levels show before teams fold (default `3`:
+  the top, their reports, and theirs).
+- `onChangeManager(person, managerId)` — `async`, return `{ ok: true }` or
+  `{ ok: false, error? }` (a throw counts as failed). Turns on dragging a
+  card onto another (with a mouse; on touch a drag always pans). The move
+  shows at once; a failure puts the person back and says why. Update
+  `people` when it succeeds (the chart keeps the move until you do).
+- `onOpenPerson(person)` — open your own view of a person (a record page,
+  your own Sheet) instead of the built-in details sheet.
+- `renderDetails(person)` — more for the built-in details sheet, under the
+  reports: kit parts (their open deals, a "Message" button).
+- `onSelectionChange(person | null)` — the selected card changed.
+- `height` — px or any CSS length, default `640`. A height class in
+  `className` (`h-dvh`, `h-full`, `flex-1`) replaces it.
+- `label` — the chart's accessible name (default "Org chart").
+- `className` — layout around it (margin, width, height). Never colour.
+
+## Keyboard and pointer
+
+- `/` finds a person. Arrows walk the chart: ↑ to the manager, ↓ into the
+  team (unfolding it), ← → along the team (and across to the next team
+  at the end of a row); in a column ↑ ↓ go up and down it.
+- Space folds or unfolds the selected person's team; Enter opens their
+  details; Home goes to the top; Esc clears the selection; ⇧1 fits the
+  chart to the screen.
+- A plain drag on the canvas pans, pinch or ⌘-scroll zooms, the chip under
+  a manager folds their team. The zoom bar (bottom right) has fit, zoom
+  and a list view for screen readers.
+
+## The helpers
+
+- `buildOrg(people, { managerKey })` → `{ roots, byId }`: each node
+  `{ id, person, parentId, depth, children, total }` (`total`: everyone
+  under them).
+- `chainOf(byId, id)` → the chain of managers, top first, ending with them.
+- `orgToText(people, { managerKey })` — one person a line, indented under
+  their manager, "Daniel Reyes — VP Engineering (10)": for an agent or a
+  search column.
+- `layoutOrg(roots, { collapsed(node), stack = true })` → `{ items,
+  bounds }`: every visible card's box and the line up to its manager.
+- `groupHues(people, key)` → Map(group → hue 1..5), the colours the chart
+  uses (for a Legend or Badge elsewhere).
+
+## Example
+
+```jsx
+// components/TeamChart.jsx — client
+"use client";
+import { useState } from "react";
+import { updateRow } from "../lib/actions";
+import { OrgChart } from "./blocks/org-chart";
+
+export default function TeamChart({ employees }) {
+  const [people, setPeople] = useState(employees);   // rows of public.employees
+  return (
+    <OrgChart
+      people={people}
+      managerKey="manager_id"
+      onChangeManager={async (person, managerId) => {
+        const res = await updateRow({ source: "public.employees", id: person.id, patch: { manager_id: managerId } });
+        if (res.ok) setPeople((list) => list.map((p) => (p.id === person.id ? { ...p, manager_id: managerId } : p)));
+        return res;
+      }}
+      className="h-[calc(100dvh-8rem)]"
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Show a person under two managers (dotted lines, matrix orgs): one
+  manager each.
+- Edit a person's details: open your own form from `onOpenPerson` or put
+  a button in `renderDetails`.
+- Export an image or print.
+- Render on the server: the server shows the people as text until the
+  canvas mounts. For a read-only page that must be rich in the HTML,
+  render `orgToText` yourself.
+
+A chart 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 org-chart` restores them.

package/registry/blocks/org-chart/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "org-chart",
+  "title": "OrgChart",
+  "description": "An org chart on flow-canvas: people laid out top down from a flat list (each names a manager), managers centred over their teams, a team with no managers in it as a compact column, every line drawn for you. Teams fold past the first levels behind a chip that says how many are hidden; search finds a person, unfolds the way to them, centres them and lights their chain of managers; a card opens a details sheet (reports to, direct reports, team size). Colour strips and a legend by department. Optional: drag a card onto another to change someone's manager (async { ok }, optimistic, with Undo). Keyboard throughout.",
+  "useWhen": "A screen that shows who reports to whom: a team or company directory's chart, an account's buying committee as a hierarchy, a reporting line to check before a reorg. Not for a free-form map of people and notes (account-map, flow-canvas), a plain list of people (data-table), or a tree of ideas (mind-map).",
+  "tags": ["org chart", "organization", "organisation", "hierarchy", "reporting line", "manager", "team", "people", "directory", "tree", "reports", "reorg", "canvas"],
+  "exports": ["OrgChart", "buildOrg", "layoutOrg", "chainOf", "orgToText", "groupHues"],
+  "files": ["index.js", "org-chart.jsx", "person.jsx", "org.js"],
+  "requires": ["flow-canvas"]
+}

package/registry/blocks/org-chart/demo.jsx

@@ -0,0 +1,94 @@
+"use client";
+
+// OrgChart — the gallery's and the smoke test's surface. Not installed
+// into apps.
+//   Company   a 38-person company: five departments, teams folded past
+//             the third level, search, details. Moving people on or off,
+//             and a failing save, behind switches.
+//   Empty     no people yet.
+import { useState } from "react";
+import { Switch, TabPanel, Tabs } from "../components/ui";
+import { OrgChart } from "../components/blocks/org-chart";
+
+const TEAM = [
+  { id: "p1", name: "Amara Okafor", title: "Chief Executive Officer", department: "Leadership", location: "London", email: "amara@northwind.test" },
+  { id: "p2", name: "Daniel Reyes", title: "VP Engineering", department: "Engineering", managerId: "p1", location: "Lisbon" },
+  { id: "p3", name: "Priya Raman", title: "Head of Product", department: "Product", managerId: "p1", location: "London" },
+  { id: "p4", name: "Tomás Novak", title: "VP Sales", department: "Sales", managerId: "p1", location: "Berlin" },
+  { id: "p5", name: "Grace Liu", title: "Head of Operations", department: "Operations", managerId: "p1", location: "London" },
+
+  { id: "p6", name: "Sofia Marchetti", title: "Engineering Manager, Platform", department: "Engineering", managerId: "p2" },
+  { id: "p7", name: "Kwame Mensah", title: "Engineering Manager, Apps", department: "Engineering", managerId: "p2" },
+  { id: "p8", name: "Hannah Weber", title: "Staff Engineer", department: "Engineering", managerId: "p2" },
+  { id: "p9", name: "Leo Tanaka", title: "Senior Engineer", department: "Engineering", managerId: "p6" },
+  { id: "p10", name: "Isla Murphy", title: "Engineer", department: "Engineering", managerId: "p6" },
+  { id: "p11", name: "Ravi Iyer", title: "Site Reliability Engineer", department: "Engineering", managerId: "p6" },
+  { id: "p12", name: "Chloé Martin", title: "Senior Engineer", department: "Engineering", managerId: "p7" },
+  { id: "p13", name: "Mateo Silva", title: "Engineer", department: "Engineering", managerId: "p7" },
+  { id: "p14", name: "Yuki Sato", title: "Mobile Engineer", department: "Engineering", managerId: "p7" },
+  { id: "p15", name: "Noah Fischer", title: "Engineer", department: "Engineering", managerId: "p7" },
+
+  { id: "p16", name: "Elena Popescu", title: "Senior Product Designer", department: "Product", managerId: "p3" },
+  { id: "p17", name: "Omar Haddad", title: "Product Manager", department: "Product", managerId: "p3" },
+  { id: "p18", name: "Freya Lindqvist", title: "Product Designer", department: "Product", managerId: "p3" },
+  { id: "p19", name: "Samuel Adeyemi", title: "User Researcher", department: "Product", managerId: "p3" },
+
+  { id: "p20", name: "Lucía Fernández", title: "Sales Manager, EMEA", department: "Sales", managerId: "p4" },
+  { id: "p21", name: "Ethan Brooks", title: "Sales Manager, North America", department: "Sales", managerId: "p4" },
+  { id: "p22", name: "Mia Kowalski", title: "Sales Engineer", department: "Sales", managerId: "p4" },
+  { id: "p23", name: "Jonas Berg", title: "Account Executive", department: "Sales", managerId: "p20" },
+  { id: "p24", name: "Aisha Khan", title: "Account Executive", department: "Sales", managerId: "p20" },
+  { id: "p25", name: "Pierre Dubois", title: "Sales Development Rep", department: "Sales", managerId: "p20" },
+  { id: "p26", name: "Olivia Grant", title: "Account Executive", department: "Sales", managerId: "p21" },
+  { id: "p27", name: "Marcus Hill", title: "Account Executive", department: "Sales", managerId: "p21" },
+  { id: "p28", name: "Zoe Campbell", title: "Sales Development Rep", department: "Sales", managerId: "p21" },
+  { id: "p29", name: "Diego Alvarez", title: "Sales Development Rep", department: "Sales", managerId: "p21" },
+
+  { id: "p30", name: "Nadia Petrova", title: "Finance Lead", department: "Operations", managerId: "p5" },
+  { id: "p31", name: "Ben Carter", title: "People Partner", department: "Operations", managerId: "p5" },
+  { id: "p32", name: "Hiroshi Mori", title: "Customer Support Lead", department: "Operations", managerId: "p5" },
+  { id: "p33", name: "Fatima Zahra", title: "Support Specialist", department: "Operations", managerId: "p32" },
+  { id: "p34", name: "Liam O'Connor", title: "Support Specialist", department: "Operations", managerId: "p32" },
+  { id: "p35", name: "Ana Costa", title: "Support Specialist", department: "Operations", managerId: "p32" },
+  { id: "p36", name: "Theo Laurent", title: "Accountant", department: "Operations", managerId: "p30" },
+  { id: "p37", name: "Maya Cohen", title: "Recruiter", department: "Operations", managerId: "p31" },
+  { id: "p38", name: "Sven Olsen", title: "Office Manager", department: "Operations", managerId: "p5" },
+];
+
+export default function OrgChartDemo() {
+  const [people, setPeople] = useState(TEAM);
+  const [movable, setMovable] = useState(true);
+  const [failing, setFailing] = useState(false);
+  const [tab, setTab] = useState("company");
+
+  const move = async (person, managerId) => {
+    await new Promise((r) => setTimeout(r, 450));
+    if (failing) return { ok: false, error: "The HR system didn't answer." };
+    setPeople((list) => list.map((p) => (p.id === person.id ? { ...p, managerId } : p)));
+    return { ok: true };
+  };
+
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="Examples"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "company", label: "Company" },
+          { key: "empty", label: "Empty" },
+        ]}
+      />
+      <TabPanel tab="company" value={tab} className="grid gap-4">
+        <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
+          <Switch label="Drag to change a manager" checked={movable} onChange={(e) => setMovable(e.target.checked)} />
+          <Switch label="Moves fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} />
+        </div>
+        <OrgChart people={people} onChangeManager={movable ? move : undefined} label="Northwind org chart" height={640} />
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <OrgChart people={[]} label="Empty org chart" height={320} />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/org-chart/index.js

@@ -0,0 +1,7 @@
+// The OrgChart block — `makersclaw add org-chart`. Fixed: compose it
+// through its props (README.md beside this file). Built on flow-canvas
+// (it draws, pans and zooms; this block builds the tree, lays it out and
+// owns the keys). The helpers in org.js are plain functions and run
+// anywhere, the server included.
+export { OrgChart } from "./org-chart";
+export { buildOrg, layoutOrg, chainOf, orgToText, groupHues } from "./org";