makersclaw 0.1.0 → 0.3.0

package/src/install.mjs

@@ -147,6 +147,7 @@ function lay(dir, tpl, before) {
   }
 
   const blocks = {};
+  const blockDeps = {};
   const known = loadBlocks();
   for (const [name, from] of Object.entries(before.manifest?.blocks ?? {})) {
     if (!existsSync(join(dir, BLOCK_DIR, name))) {
@@ -170,6 +171,20 @@ function lay(dir, tpl, before) {
       pins[f.to] = hash;
     }
     blocks[name] = v;
+    Object.assign(blockDeps, block.dependencies);
+  }
+
+  // The blocks' npm packages, at the versions this release pins them to
+  // (block.json `dependencies`): a block's files and its packages move
+  // together, or an update would lay files the installed package cannot run.
+  if (Object.keys(blockDeps).length && existsSync(join(dir, "package.json"))) {
+    const path = join(dir, "package.json");
+    const { out, changes } = mergePackage(readJson(path, {}), { dependencies: blockDeps });
+    if (changes.length) {
+      writeJson(path, out);
+      if (!written.includes("package.json")) written.push("package.json");
+      pkg = [...pkg, ...changes];
+    }
   }
 
   for (const p of Object.keys(before.pins)) {
@@ -446,6 +461,9 @@ export function diff(dir) {
   const pkgPath = join(dir, "package.json");
   const tplPkg = tpl.files.find((f) => f.class === "merged");
   const pkg = existsSync(pkgPath) && tplPkg ? mergePackage(readJson(pkgPath), readJson(tplPkg.from)).changes : [];
+  // …and the installed blocks' npm packages, which update lays with them.
+  const blockDeps = Object.assign({}, ...Object.keys(manifest.blocks ?? {}).map((n) => known.find((b) => b.name === n)?.dependencies ?? {}));
+  if (existsSync(pkgPath) && Object.keys(blockDeps).length) pkg.push(...mergePackage(readJson(pkgPath), { dependencies: blockDeps }).changes);
   return {
     from: manifest.version,
     to: v,

package/src/shadcn.mjs

@@ -0,0 +1,171 @@
+// The free kit and blocks as a shadcn registry, so any Next.js + shadcn
+// project can install them with the CLI it already has:
+//
+//   npx shadcn@latest add https://cdn.jsdelivr.net/npm/makersclaw@<version>/r/board.json
+//
+// Two kinds of item:
+//   core      the kit (components/ui) and the parts (components/parts),
+//             plus what a stock shadcn theme lacks: the success, warning
+//             and info colours, the text-2xs size, and four CSS rules
+//   <block>   one block, which lists core as a registry dependency, so
+//             `add board` brings the kit along the first time
+//
+// Where it lands: components/makersclaw/{ui,parts,blocks/<name>} — the
+// same relative shape as a Makersclaw app's components/, so every import
+// inside the kit and the blocks (../../ui, ../../parts, ./sample) is
+// relative and resolves unchanged; nothing needs rewriting, and nothing
+// collides with the project's own components/ui. The files are served by
+// jsDelivr straight from the npm tarball (`r/` is built at `npm pack`).
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { PKG_ROOT, loadBlocks, loadTemplate, packageInfo } from "./registry.mjs";
+
+const ITEM_SCHEMA = "https://ui.shadcn.com/schema/registry-item.json";
+const INDEX_SCHEMA = "https://ui.shadcn.com/schema/registry.json";
+/** Under the project's components folder: @components/ is the CLI's
+ *  placeholder for it, and what follows is kept as written. */
+export const SHADCN_ROOT = "@components/makersclaw";
+
+/** Where the built registry is served from: this version's own files on
+ *  jsDelivr, so a block's dependency on core names exactly its kit. */
+export function defaultBase(version = packageInfo().version) {
+  return `https://cdn.jsdelivr.net/npm/makersclaw@${version}/r`;
+}
+
+// What a stock shadcn theme lacks and the kit uses. Tailwind's own
+// green/amber/blue at 600 on light and 400 on dark — status colours,
+// readable on either ground.
+const CSS_VARS = {
+  theme: {
+    "text-2xs": "0.6875rem",
+    "text-2xs--line-height": "1rem",
+    // The chart block's series colours. A shadcn theme already defines
+    // --chart-1…5 (light and dark); this only makes sure the utilities
+    // (fill-chart-1, stroke-chart-2…) read them.
+    "color-chart-1": "var(--chart-1)",
+    "color-chart-2": "var(--chart-2)",
+    "color-chart-3": "var(--chart-3)",
+    "color-chart-4": "var(--chart-4)",
+    "color-chart-5": "var(--chart-5)",
+  },
+  light: {
+    success: "oklch(0.627 0.194 149.214)",
+    warning: "oklch(0.666 0.179 58.318)",
+    info: "oklch(0.546 0.245 262.881)",
+  },
+  dark: {
+    success: "oklch(0.792 0.209 151.711)",
+    warning: "oklch(0.828 0.189 84.429)",
+    info: "oklch(0.707 0.165 254.624)",
+  },
+};
+
+// The rules the kit leans on (the template's app/globals.css): tabular
+// numbers, the native dialog and popover the Sheet and the Menu sit on,
+// and the boundary where a depiction stops wearing the theme.
+const CSS = {
+  "@layer base": {
+    "[data-nums]": { "font-variant-numeric": "tabular-nums" },
+    dialog: { color: "inherit" },
+    "dialog::backdrop": { background: "color-mix(in oklab, var(--background) 70%, transparent)" },
+    "[popover]": { color: "inherit", margin: "0", padding: "0", border: "0", background: "transparent" },
+  },
+  "@layer components": {
+    "[data-depiction]": {
+      isolation: "isolate",
+      "color-scheme": "light",
+      font: '16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Apple Color Emoji", "Segoe UI Emoji", sans-serif',
+      "letter-spacing": "normal",
+      "word-spacing": "normal",
+      "text-align": "start",
+      color: "CanvasText",
+    },
+    '[data-depiction][data-scheme="dark"]': { "color-scheme": "dark" },
+  },
+};
+
+const README_URL = "https://www.npmjs.com/package/makersclaw";
+
+function coreItem() {
+  const tpl = loadTemplate("next");
+  const files = tpl.files
+    .filter((f) => /^components\/(?:ui|parts)\//.test(f.path))
+    .map((f) => ({
+      path: `templates/next/files/${f.path}`,
+      type: "registry:ui",
+      target: `${SHADCN_ROOT}/${f.path.slice("components/".length)}`,
+      content: readFileSync(f.from, "utf8"),
+    }));
+  return {
+    $schema: ITEM_SCHEMA,
+    name: "core",
+    type: "registry:ui",
+    title: "Makersclaw kit",
+    description:
+      "The kit every Makersclaw block is built from — Button, Field, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction — " +
+      "and the parts bound to data (RecordSwitcher, useFixture). Native elements under the project's own theme tokens.",
+    files,
+    cssVars: CSS_VARS,
+    css: CSS,
+    docs: `Installed to components/makersclaw/ui and components/makersclaw/parts. Import: import { Button } from "@/components/makersclaw/ui". Needs Next.js 15+, React 19 and Tailwind v4. ${README_URL}`,
+  };
+}
+
+function blockItem(block, base, version) {
+  const files = block.files.map((f) => ({
+    path: `registry/blocks/${block.name}/${basename(f.from)}`,
+    type: "registry:component",
+    target: `${SHADCN_ROOT}/blocks/${block.name}/${basename(f.from)}`,
+    content: readFileSync(f.from, "utf8"),
+  }));
+  if (block.readme) {
+    // Beside the code, where the developer and their assistant will look.
+    files.push({
+      path: `registry/blocks/${block.name}/README.md`,
+      type: "registry:file",
+      target: `${SHADCN_ROOT}/blocks/${block.name}/README.md`,
+      content: readFileSync(block.readme, "utf8"),
+    });
+  }
+  return {
+    $schema: ITEM_SCHEMA,
+    name: block.name,
+    type: "registry:block",
+    title: block.title,
+    description: block.description,
+    registryDependencies: [`${base}/core.json`, ...block.requires.map((r) => `${base}/${r}.json`)],
+    dependencies: Object.entries(block.dependencies ?? {}).map(([name, range]) => `${name}@${range}`),
+    files,
+    categories: block.tags,
+    docs:
+      `Installed to components/makersclaw/blocks/${block.name}. ` +
+      `Import: import { ${block.exports.join(", ")} } from "@/components/makersclaw/blocks/${block.name}". ` +
+      `Props and an example: components/makersclaw/blocks/${block.name}/README.md. ` +
+      `Makersclaw builds whole apps from these blocks: https://makersclaw.com`,
+    meta: { makersclaw: { version, useWhen: block.useWhen } },
+  };
+}
+
+/** Every item, with its files' content, and the index shadcn's `list` and
+ *  `search` read (the same items, without content). */
+export function buildRegistry({ base = defaultBase(), version = packageInfo().version } = {}) {
+  const items = [coreItem(), ...loadBlocks().map((b) => blockItem(b, base, version))];
+  const index = {
+    $schema: INDEX_SCHEMA,
+    name: "makersclaw",
+    homepage: "https://makersclaw.com",
+    items: items.map(({ $schema, ...item }) => ({ ...item, files: item.files.map(({ content, ...f }) => f) })),
+  };
+  return { base, version, items, index };
+}
+
+/** Write r/<name>.json for every item and r/registry.json. */
+export function writeRegistry(outDir = join(PKG_ROOT, "r"), opts = {}) {
+  const built = buildRegistry(opts);
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  for (const item of built.items) writeFileSync(join(outDir, `${item.name}.json`), `${JSON.stringify(item, null, 2)}\n`);
+  writeFileSync(join(outDir, "registry.json"), `${JSON.stringify(built.index, null, 2)}\n`);
+  return { ...built, outDir };
+}

package/templates/next/files/README.md

@@ -129,28 +129,162 @@ rarely does. `npm run check` refuses a raw `<select>`, `<dialog>`,
 `<svg>`, `role="tab"`, `popover` or `window.confirm()` outside the kit.
 
 ```jsx
-import { Button, IconButton, Card, Field, Input, Textarea, Select, Switch, Checkbox,
-         Sheet, Confirm, Tabs, TabPanel, Menu, Notice, Badge, Kicker, Empty, Icon, cx }
+import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGroup,
+         Field, Input, TimeInput, Textarea, Select, Switch, Checkbox, RadioGroup, Radio, Rating,
+         InputGroup, PasswordInput, InputOTP, Slider, Image, FileInput, FileDrop, fileMatches, Combobox, Command, CommandDialog, Calendar, DatePicker, DateInput, DATE_PRESETS,
+         parseDate, isDateString, toDateString, todayString, addDays, addMonths,
+         startOfMonth, endOfMonth, dayOfWeek, formatDate, firstDayOfWeek,
+         Card, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
+         Sheet, Confirm, Tabs, TabPanel, Menu, ContextMenu, Popover, Tooltip, HoverCard,
+         Breadcrumb, Pagination, Collapsible, Accordion, Carousel, ScrollArea,
+         ResizablePanelGroup, ResizablePanel, ResizableHandle,
+         Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption,
+         Spinner, Skeleton, Progress, Separator, Kbd, KbdGroup, AspectRatio,
+         Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
+         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx }
   from "../components/ui";           // "./ui" from a component
 import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../components/parts";
 ```
 
 - `Button` — `variant` primary (one per surface) · secondary · quiet ·
-  danger · link; `size` md (44px) · sm; `icon="plus"`; `href` for a link.
-  `IconButton` for an icon alone (`label` required).
+  danger · link (inline text: no padding or height, wraps and truncates
+  with its sentence; `size="inherit"` takes the sentence's size;
+  `tone="muted"` for a secondary link) · nav (a full-width navigation row, start-aligned, normal
+  weight, filled by `aria-current="page"`); `size` md (44px) · sm;
+  `align` center · start; `icon="plus"`; `href` for a link.
+  `IconButton` for an icon alone (`label` required). `loading` while its
+  action runs: a spinner, the same width, `aria-busy`, disabled.
 - `Field` wraps `Input`, `Textarea`, `Select`, `Switch`, `Checkbox` with
   its label, hint and error. `Select` with empty `options` renders a
-  muted line, never a disabled dropdown.
+  muted line, never a disabled dropdown. `TimeInput` — a time of day
+  ("HH:MM"; `min max step`), the kit's clock in place of the browser's.
+- `Rating` — stars: read-only `value` of `max` (halves drawn, "4.5 out
+  of 5" to a reader), or with `onChange` a radio-group input; `size`, `label`.
+- `InputGroup` — an input with `icon`, `prefix` ("https://"), `suffix`
+  ("USD"), `kbd` and an `action` button (copy, search, show password);
+  one border, focus ring and `invalid` for the whole group; `multiline`
+  is the chat composer (a growing textarea, `minRows` `maxRows`, `tools`
+  and the action in a bar under it, `above` for attached files).
+  `PasswordInput` — the password field with a show/hide toggle
+  (`autoComplete` passes through; "new-password" on sign-up).
+  `Textarea autoGrow` grows with its text the same way. `InputOTP` —
+  a one-time code in boxes (`length` or `groups={[3, 3]}`, `digitsOnly`,
+  `onComplete(code)`, `invalid`; paste and SMS autofill fill every box).
+  `Slider` — a number, or a range with `value={[low, high]}`; `min max
+  step`, `showValue` + `format`. A number someone will type is an Input.
+- `Combobox` — pick one or many from a searchable list (`options` with
+  `icon`, `description`, `group`, `count` at the right; `multiple` →
+  chips; `creatable`; `open` + `onOpenChange` or `defaultOpen`;
+  `onSearch` async; `clearable`; in a `Field` by `id`; a bottom sheet on a
+  phone). `searchable={false}` is the rich Select (icons, descriptions)
+  — a plain list of words stays the native `Select`. `Command` — a
+  searchable list of actions (`items` with `icon`, `shortcut`, `keywords`,
+  `group`, `onSelect`); `CommandDialog hotkey="k"` is the ⌘K palette.
 - `Sheet` — the one overlay, a rail beside the work (`side="end"`), a
-  dialog (`center`) or a bottom sheet; on a narrow window every side
-  becomes a bottom sheet. `Confirm` is the "delete this?" case.
+  navigation drawer (`start`), a dialog (`center`) or a bottom sheet; on a narrow window every side
+  becomes a bottom sheet; `bare` + `label` for a panel that draws its own
+  top (no header, flush body). `Confirm` is the "delete this?" case;
+  `consequences`, `requireText` and `acknowledge` hold it until met.
+- `Image src alt ratio fit rounded` — a picture of a thing (thumbnail,
+  cover): Skeleton while it loads, a glyph when it fails, lazy, `alt`
+  required. Never a raw `<img>`; a face is an `Avatar`.
+- `FileInput onFiles accept multiple` (a Button that opens the picker;
+  only a `label` → an IconButton) and `FileDrop` (a drop zone, `label`
+  `hint` `size` sm · md; a drop is filtered by `accept`, the rest go to
+  `onReject`). Never a raw `<input type="file">`.
 - `Tabs` + `TabPanel` — views of ONE thing (a record's notes | history).
   Never for the app's surfaces; those are the shell's nav.
-- `Menu` — the "…" of a row. Empty `items` render nothing: a menu is
-  earned by having actions.
-- `Card`, `Notice` (tone neutral · info · success · warning · danger),
-  `Badge`, `Kicker` (the small line above a heading), `Empty` (a filter
+- `Menu` — the "…" of a row, a View or Account dropdown. `items` are
+  data: actions (`icon`, `tone`, `shortcut`, `description`), `{ group,
+  items }`, `{ type: "separator" }`, `{ type: "checkbox", checked,
+  onCheckedChange }`, `{ type: "radio", value, onValueChange, options }`
+  (choices keep it open) and submenus `{ label, items }`; `side` +
+  `align`; `size` sm (36px, default) · md (44px trigger). Empty `items` render nothing: a menu is earned by having
+  actions. `ContextMenu` opens the same `items` on a region's right-click,
+  long press or Shift+F10 — a shortcut, never the only door.
+- `Popover` (a panel beside its `trigger`; `side`, `align`, `width`;
+  flips at the window's edge; `open` + `onOpenChange` or uncontrolled),
+  `Tooltip` (a short text `label` on hover or keyboard focus; never on
+  touch, so it only repeats what is visible) and `HoverCard` (a preview
+  of what a link points at; may hold links). `usePopoverPosition` is the
+  placement alone, for a floating part of your own.
+- `DatePicker` (a field that opens a Calendar; `mode` single · range,
+  `presets`, `clearable`, `min max disabled`; in a `Field` with the same
+  `id`), `Calendar` (the grid inline; `mode` single · multiple · range,
+  `numberOfMonths`, `captionLayout` dropdown · none (you show and move a
+  controlled `month`), `showWeekNumbers`, `weekStartsOn`, `marked` with
+  `emphasizeMarked` and `onlyMarked`) and
+  `DateInput` (a typed date with the Calendar a button away). Dates are
+  `"YYYY-MM-DD"` strings in and out — never a Date — and `addDays`,
+  `addMonths`, `formatDate`… do the arithmetic.
+- `RadioGroup` (`options` or `<Radio>` children, each with a
+  `description`; `variant` list · card; `orientation`; in a `Field` with
+  the same `id`), `Toggle` (`pressed` + `onPressedChange`, aria-pressed),
+  `ToggleGroup` (the segmented control; `type` single · multiple) and
+  `ButtonGroup` (buttons, icon buttons and a `Menu` joined into one
+  piece; `ButtonGroupSeparator` between primary or quiet ones).
+- `Avatar name src size shape status` (initials while loading and when
+  the image fails) and `AvatarGroup people max` ("+N" past `max`);
+  `Breadcrumb items={[{ label, href }]}` (last is this page; the middle
+  folds into "…"; the current page takes the rest of the row); `Pagination page pageCount` with `hrefFor(page)` or
+  `onPageChange` (compact on a phone; `pageSize` + `onPageSizeChange`).
+- `Collapsible` (title, meta, `open` + `onOpenChange` or `defaultOpen`;
+  `variant` plain · outline · flush for edge-to-edge rows inside a Card;
+  `chevron` down · right, the disclosure triangle that turns down)
+  and `Accordion` (`items`, `type` single · multiple) — show and hide,
+  never a raw `<details>`. `Item` / `ItemGroup` — the list row (media or
+  icon, title, description, meta, actions; `href` or `onClick` makes the
+  whole row the target; `aria-current`, `onClick`, `target`, `rel` reach
+  that link or button). `Table` + `TableHeader`, `TableBody`, `TableRow`
+  (`selected`), `TableHead` (`sort` + `onSort`; `sortIndex` when several
+  are sorted), `TableCell` (`numeric`)
+  — a table that scrolls inside itself on a phone.
+- `Card` (`padding` md · sm · none — none for a table or rows that run
+  to the border, never `p-0!`; `titleSize` md · lg for a 20px title),
+  `Notice` (tone neutral · info · success · warning · danger),
+  `Badge` (tone neutral · primary · success · warning · danger · info;
+  `variant` label — small caps · soft — the case as written, every tone
+  tinted, primary too · outline — the case as written, a hairline, no
+  fill · code — a version tag or a commit hash in the mono face; `hue`
+  1..5 for a KIND of thing — a platform, a content type — never a state:
+  tone is status, hue is category), `Kicker` (the small line above a heading), `Empty` (a filter
   or search with no matches — not the landing state, that is the fixture).
+- `Spinner` (size sm · md · lg), `Skeleton` (shape line · circle · rect,
+  sized by className), `Progress` (`value` of `max`, no value for
+  indeterminate; tone; `label`) — waiting, never a hand-drawn loader.
+- `Steps steps={[{ label, description, status, meta }]}` (or `current`)
+  — where a staged job has got: `variant` dots · bar (rollout phases);
+  status complete · current · pending · failed · skipped; `orientation`
+  horizontal · vertical; `pulse`; `label` + `valueText`;
+  `hideStepLabels` for bare dots (still pass every label: it is what a
+  reader hears); `onSelect`
+  only when a step opens something. Never a hand-drawn stepper.
+- `Stat label value unit caption tone delta invert size` (sm · md · lg)
+  in a `StatGroup` (the 2–4 summary strip; card · divided · bare);
+  `Delta value suffix invert` (coloured by sign; zero is neutral);
+  `StatusDot tone pulse label`; `Legend items={[{ tone, label, count }]}`;
+  `Meter value max unit target thresholds` (a role=meter; over the limit
+  turns danger; `direction` higher · lower picks the tone against the
+  target; `valueTone`; `targetMark={false}`; tone `muted` for a plain
+  grey share) — numbers and states, never a hand-drawn tile or bar.
+  `Delta hideValue` is the arrow alone; `StatusDot` and Legend items take
+  `hue` (1..5) for a category. `Distribution segments={[{ label, value,
+  tone, hue }]} legend label size` (thin · md) — parts of one whole as
+  one stacked bar, a hue per segment, a tone for sentiment. `Swatch color
+  label size` — a colour that comes from data; the only inline colour.
+- `Separator` (horizontal · vertical; `decorative={false}` for a real
+  one), `Kbd` / `KbdGroup keys={["⌘", "K"]}`, `AspectRatio ratio="video"`
+  (its child fills it), `ScrollArea` (a bounded scroller with themed
+  scrollbars, `fade`, keyboard-focusable while it overflows; `ref` is the
+  scrolling element, for a list that sets its own scrollTop).
+- `toast("Saved")`, `toast.success/.error/.info/.warning(title, {
+  description, action, duration })`, `toast.promise(p, { loading,
+  success, error })` — nothing to mount; `<Toaster position />` only to
+  move the stack. A toast is never the only record of an error.
+- `Carousel label itemsPerView` (scroll-snap; 1 on a phone; dots ·
+  counter; `loop`, `autoplay` only when asked), `ResizablePanelGroup`
+  + `ResizablePanel defaultSize minSize` + `ResizableHandle grip`
+  (`storageKey` remembers; a horizontal group stacks below md).
 - `Icon name="…"` — one sprite, `ICON_NAMES` lists it. Missing one? Add
   the glyph to `components/ui/icon.jsx`; never an `<svg>` in a surface.
 - `RecordSwitcher` — pick a saved record or make a new one. With nothing

package/templates/next/files/app/globals.css

@@ -100,6 +100,41 @@
     border: 0;
     background: transparent;
   }
+
+  /* Status tones when the preset does not pin them (@theme below reads
+     these). The plain fallbacks there are for a dark canvas and read faint
+     on a light one, so a light page gets darker ones: by color-scheme (the
+     preset's), through light-dark(), where the browser has it; by
+     data-theme=light where it does not. Every one reads at 4.5:1 or more
+     as text on the Daylight background and card. */
+  [data-theme=light] {
+    --scheme-success: #15703a;
+    --scheme-warning: #9a4a06;
+    --scheme-info: #1d4ed8;
+    --scheme-destructive: #c01c1c;
+  }
+  @supports (color: light-dark(red, red)) {
+    :root,
+    [data-theme] {
+      --scheme-success: light-dark(#15703a, #4ade80);
+      --scheme-warning: light-dark(#9a4a06, #ffbd38);
+      --scheme-info: light-dark(#1d4ed8, #60a5fa);
+      --scheme-destructive: light-dark(#c01c1c, #fb2c36);
+    }
+  }
+
+  /* Chart series 2-5, derived with relative colour (oklch(from …)), which
+     Chrome before 119 and Safari before 16.4 lack. Set only where it
+     parses; elsewhere @theme falls back to plain colours that still stay
+     apart, rather than to no colour at all. */
+  @supports (color: oklch(from red l c h)) {
+    :root {
+      --chart-derived-2: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 144));
+      --chart-derived-3: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 288));
+      --chart-derived-4: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 72));
+      --chart-derived-5: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 216));
+    }
+  }
 }
 
 /* The boundary where the workspace theme stops: a depiction (README §3c),
@@ -150,16 +185,32 @@
   --color-accent: var(--accent, color-mix(in srgb, var(--midground-base) 12%, var(--background-base)));
   --color-accent-foreground: var(--accent-foreground, var(--midground-base));
 
-  --color-destructive: var(--destructive, #fb2c36);
+  --color-destructive: var(--destructive, var(--scheme-destructive, #fb2c36));
   --color-destructive-foreground: var(--destructive-foreground, #ffffff);
-  --color-success: var(--success, #4ade80);
-  --color-warning: var(--warning, #ffbd38);
-  --color-info: var(--info, #60a5fa);
+  --color-success: var(--success, var(--scheme-success, #4ade80));
+  --color-warning: var(--warning, var(--scheme-warning, #ffbd38));
+  --color-info: var(--info, var(--scheme-info, #60a5fa));
 
   --color-border: var(--border, color-mix(in srgb, var(--midground-base) 15%, transparent));
   --color-input: var(--input, color-mix(in srgb, var(--midground-base) 15%, transparent));
   --color-ring: var(--ring, var(--midground-base));
 
+  /* Chart series (fill-chart-1, stroke-chart-2, bg-chart-3…), for the chart
+     block: several colours that must stay apart in every theme. A preset
+     (or a shadcn theme) may pin --chart-N. Otherwise chart-1 is the primary
+     and the others turn its hue round the wheel, 144° a step so neighbours
+     never sit close, keeping its lightness (the primary already reads on
+     this canvas) with a floor on chroma so a grey or pastel theme still
+     gets colours. Not success/warning/info: those are status, and a theme's
+     primary is often one of them (amber, mint, blue). The turn is worked
+     out in the base layer (--chart-derived-N); the hex after it is for a
+     browser without relative colour. */
+  --color-chart-1: var(--chart-1, var(--primary, var(--midground-base)));
+  --color-chart-2: var(--chart-2, var(--chart-derived-2, #14b8a6));
+  --color-chart-3: var(--chart-3, var(--chart-derived-3, #a78bfa));
+  --color-chart-4: var(--chart-4, var(--chart-derived-4, #f472b6));
+  --color-chart-5: var(--chart-5, var(--chart-derived-5, #38bdf8));
+
   --radius-sm: calc(var(--theme-radius) - 4px);
   --radius-md: calc(var(--theme-radius) - 2px);
   --radius-lg: var(--theme-radius);

package/templates/next/files/check/run.mjs

@@ -48,7 +48,7 @@ const STATIC_ONLY = process.argv.includes("--static");
 // update` lays both folders again.
 // Exact names AND extensions: Next resolves .js before .jsx, so a
 // components/ui/depiction.js beside depiction.jsx would win unseen.
-const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:button|depiction|field|icon|menu|notice|sheet|tabs)\.jsx|parts\/index\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
+const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
 
 // The pins: sha256 of every fixed file, written by `makersclaw init` and
 // `makersclaw add` (check/pins.json). Read first, because a BLOCK is
@@ -209,11 +209,11 @@ const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`
   const RULES = [
     [/<select\b/, "Select from components/ui, or RecordSwitcher from components/parts", files],
     [/<dialog\b/, "Sheet or Confirm from components/ui", files],
-    [/<details\b/, "Menu or Sheet from components/ui", files],
+    [/<details\b/, "Collapsible or Accordion from components/ui", files],
     [/role=["']tab(?:list)?["']/, "Tabs from components/ui", files],
     [/role=["']menu(?:item)?["']/, "Menu from components/ui", files],
     [/role=["']dialog["']/, "Sheet from components/ui", files],
-    [/\bpopover=/, "Menu from components/ui", files],
+    [/\bpopover=/, "Popover, Tooltip, HoverCard or Menu from components/ui", files],
     [/window\.confirm\(/, "Confirm from components/ui", files],
     [/<svg\b/, "Icon from components/ui (add a glyph there if it is missing)", appFiles],
   ];

package/templates/next/files/components/parts/fixture.jsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import { markSample } from "../../lib/sample";
+import { markSample } from "./sample";
 import { Button, Notice } from "../ui";
 
 // The worked example, never persisted. A surface opens populated (README

package/templates/next/files/components/parts/sample.js

@@ -0,0 +1,15 @@
+// Pure: importable from either side. The parts use it in the browser
+// (fixture.jsx); lib/sample.js re-exports it for server code (lib/data.js).
+// It lives beside the parts, not in lib/, so the parts travel as one folder
+// — into an app's components/parts, or a shadcn project's
+// components/makersclaw/parts — and import nothing outside it but the kit.
+
+/** Sample rows get stable ids and a `_sample: true` marker, so a surface
+ *  can label them until real rows exist and refuse to edit them. */
+export function markSample(sample, idColumn = "id") {
+  return (sample ?? []).map((r, i) => ({
+    ...r,
+    [idColumn]: r[idColumn] ?? `sample-${i + 1}`,
+    _sample: true,
+  }));
+}

package/templates/next/files/components/ui/avatar.jsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Avatar — a person's face, or their initials while it loads and when it
+// fails. The initials are always drawn; the image lays over them only
+// once it has loaded, so a slow, missing or broken `src` never shows a
+// hole or the browser's broken-image glyph. No name either: a user icon.
+//
+//   name     "Jane Cooper" → JC; also the accessible name
+//   src      the image; optional
+//   size     xs (24px) · sm (32px) · md (40px) · lg (56px)
+//   shape    round · square (a company, a bot, a workspace)
+//   status   online · away · busy · offline — a dot, named to a reader
+//   label    overrides what a screen reader says
+//
+// AvatarGroup below is the overlapping stack with "+N" after `max`.
+
+const SIZES = {
+  xs: { box: "h-6 w-6 text-2xs", dot: "h-1.5 w-1.5", icon: 12, overlap: "-space-x-1.5" },
+  sm: { box: "h-8 w-8 text-xs", dot: "h-2 w-2", icon: 14, overlap: "-space-x-2" },
+  md: { box: "h-10 w-10 text-sm", dot: "h-2.5 w-2.5", icon: 18, overlap: "-space-x-2.5" },
+  lg: { box: "h-14 w-14 text-lg", dot: "h-3.5 w-3.5", icon: 24, overlap: "-space-x-3" },
+};
+
+const SHAPES = { round: "rounded-full", square: "rounded-md" };
+
+// Colour is the signal: the status tones are the workspace's status tokens.
+const STATUS = {
+  online: { dot: "bg-success", say: "online" },
+  away: { dot: "bg-warning", say: "away" },
+  busy: { dot: "bg-destructive", say: "busy" },
+  offline: { dot: "bg-muted-foreground", say: "offline" },
+};
+
+/** "Jane Cooper" → "JC", "jane@acme.com" → "J", "Priya" → "P". First and
+ *  last word, by code point, so an accented or non-Latin name survives. */
+function initials(name) {
+  const words = String(name ?? "").split("@")[0].trim().split(/[\s._-]+/).filter(Boolean);
+  if (words.length === 0) return "";
+  const first = Array.from(words[0])[0] ?? "";
+  const last = words.length > 1 ? Array.from(words[words.length - 1])[0] ?? "" : "";
+  return (first + last).toUpperCase();
+}
+
+export function Avatar({ name, src, size = "md", shape = "round", status, label, className }) {
+  const s = SIZES[size] ?? SIZES.md;
+  const round = SHAPES[shape] ?? SHAPES.round;
+  const st = STATUS[status];
+  const img = useRef(null);
+  // Both hold the src they are about, so a new src starts fresh unreset.
+  const [loaded, setLoaded] = useState(null);
+  const [failed, setFailed] = useState(null);
+
+  // A server-rendered <img> can load or fail before React is listening.
+  useEffect(() => {
+    const i = img.current;
+    if (!i || !src || !i.complete) return;
+    if (i.naturalWidth > 0) setLoaded(src);
+    else setFailed(src);
+  }, [src]);
+
+  const text = initials(name);
+  const said = label ?? ([name, st?.say].filter(Boolean).join(", ") || undefined);
+  const showImg = src && failed !== src;
+
+  return (
+    <span
+      role={said ? "img" : undefined}
+      aria-label={said}
+      aria-hidden={said ? undefined : true}
+      title={name || undefined}
+      className={cx("relative inline-flex shrink-0 select-none", round, s.box, className)}
+    >
+      <span className={cx("relative flex h-full w-full items-center justify-center overflow-hidden bg-muted font-medium text-muted-foreground", round)}>
+        {/* Hidden, not removed, once the image is in: a transparent PNG must not show letters through it. */}
+        <span aria-hidden="true" className={cx("inline-flex leading-none", loaded === src && showImg && "invisible")}>
+          {text || <Icon name="user" size={s.icon} />}
+        </span>
+        {showImg ? (
+          <img
+            ref={img}
+            src={src}
+            alt=""
+            onLoad={() => setLoaded(src)}
+            onError={() => setFailed(src)}
+            className={cx("absolute inset-0 h-full w-full object-cover", loaded === src ? "opacity-100" : "opacity-0")}
+          />
+        ) : null}
+      </span>
+      {st ? (
+        <span
+          aria-hidden="true"
+          className={cx(
+            "absolute rounded-full ring-2 ring-background",
+            shape === "square" ? "-bottom-0.5 -right-0.5" : "bottom-0 right-0",
+            s.dot,
+            st.dot,
+          )}
+        />
+      ) : null}
+    </span>
+  );
+}
+
+/** Faces overlapping, the first `max` of `people`, then "+N" naming the
+ *  rest on hover and to a reader. No status dots: the next face covers
+ *  them. Empty `people` renders nothing.
+ *
+ *    people   [{ name, src? }]
+ *    max      how many faces before "+N" (default 4)
+ */
+export function AvatarGroup({ people, max = 4, size = "sm", shape = "round", label, className }) {
+  const list = (people ?? []).filter(Boolean);
+  if (list.length === 0) return null;
+  const s = SIZES[size] ?? SIZES.sm;
+  const round = SHAPES[shape] ?? SHAPES.round;
+  const shown = list.slice(0, Math.max(1, max));
+  const rest = list.slice(shown.length);
+  const restNames = rest.map((p) => p.name).filter(Boolean).join(", ");
+
+  return (
+    <div role="group" aria-label={label ?? `${list.length} people`} className={cx("flex items-center", s.overlap, className)}>
+      {shown.map((p, i) => (
+        <Avatar key={i} name={p.name} src={p.src} size={size} shape={shape} className="ring-2 ring-background" />
+      ))}
+      {rest.length > 0 ? (
+        <span
+          role="img"
+          aria-label={`and ${rest.length} more${restNames ? `: ${restNames}` : ""}`}
+          title={restNames || undefined}
+          className={cx("relative inline-flex shrink-0 items-center justify-center bg-muted font-medium text-muted-foreground ring-2 ring-background", round, s.box)}
+        >
+          <span data-nums aria-hidden="true" className="leading-none">+{rest.length}</span>
+        </span>
+      ) : null}
+    </div>
+  );
+}