makersclaw 0.2.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

@@ -40,6 +40,14 @@ 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)",

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|sample)\.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/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>
+  );
+}

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

@@ -0,0 +1,149 @@
+"use client";
+
+import { useId, useRef } from "react";
+import Link from "next/link";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+import { usePopoverPosition } from "./popover";
+
+// Breadcrumb — where this page sits: Deals › Acme Corp › Renewal. Items
+// are data; each with an `href` is a next/link (base path applied), the
+// last is the page you are on (aria-current) and is never a link.
+// A client part (a server surface renders it as it is; items are plain
+// data): the "…" that stands in for the middle is a native popover
+// (popovertarget), kept under its button by usePopoverPosition — CSS
+// anchoring where the browser has it, measured where it does not.
+//
+//   items      [{ label, href? }] — first is the root, last is this page
+//   max        how many slots on a wide window before the middle folds
+//              into "…" (default 4, the "…" counts as one); a narrow
+//              window shows first › … › last once there are four or more
+//   separator  chevron (default) · slash
+//
+// Long labels truncate, the full text on hover. Earlier crumbs are capped
+// (max-w-40, 56 on sm+); the current page takes the rest of the row. One item or none: nothing
+// to place the page within, so nothing is drawn.
+
+const SEP = {
+  chevron: <Icon name="chevron-right" size={14} />,
+  slash: <span className="px-0.5">/</span>,
+};
+
+// Shown at one width and not the other: the "…", each crumb, each entry
+// in the popover. Whole class names, so Tailwind sees them.
+const SHOW = {
+  flex: { both: "flex", narrow: "flex sm:hidden", wide: "hidden sm:flex", none: "hidden" },
+  block: { both: "block", narrow: "block sm:hidden", wide: "hidden sm:block", none: "hidden" },
+};
+
+// Every crumb truncates; only the earlier ones carry a cap. The current
+// page is the one worth reading, so it takes whatever the row has left
+// and cuts off only when the row really runs out. It is clamped to one
+// line rather than kept on one (nowrap), so its narrowest size is a
+// letter, not the whole title: a card or grid cell sized by its content
+// still shrinks to the window instead of being pushed wide by the title.
+const CRUMB = "min-w-0 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const CAP = "block max-w-40 truncate sm:max-w-56";
+const REST = "line-clamp-1 [overflow-wrap:anywhere]";
+
+export function Breadcrumb({ items, max = 4, separator = "chevron", label = "Breadcrumb", className }) {
+  const auto = useId();
+  const more = useRef(null);
+  const panel = useRef(null);
+  usePopoverPosition(more, panel, { side: "bottom", align: "start", offset: 4 });
+  const list = (items ?? []).filter(Boolean);
+  if (list.length < 2) return null;
+
+  const id = `crumbs-${auto.replace(/[^a-zA-Z0-9]/g, "")}`;
+  const n = list.length;
+  const keep = Math.max(1, max - 2); // trailing items kept beside the first and the "…"
+  // Middle item i folds on a wide window when there are more than `max`;
+  // on a narrow one every middle item folds once there are four or more
+  // (three fit, truncated).
+  const foldsWide = (i) => n > max && i > 0 && i < n - keep;
+  const foldsNarrow = n > 3;
+  const middle = list.slice(1, -1).map((item, k) => ({ item, i: k + 1 }));
+  const wideFold = middle.some(({ i }) => foldsWide(i));
+  const at = (narrow, wide, display = "flex") => SHOW[display][narrow ? (wide ? "both" : "narrow") : wide ? "wide" : "none"];
+  const sep = (
+    <span aria-hidden="true" className="shrink-0 text-muted-foreground/70">
+      {SEP[separator] ?? SEP.chevron}
+    </span>
+  );
+
+  const crumb = (item, current) =>
+    current || !item.href ? (
+      <span aria-current={current ? "page" : undefined} title={item.label} className={cx(CRUMB, current ? cx(REST, "font-medium text-foreground") : CAP)}>
+        {item.label}
+      </span>
+    ) : (
+      <Link href={item.href} title={item.label} className={cx(CRUMB, CAP, "transition-colors hover:text-foreground")}>
+        {item.label}
+      </Link>
+    );
+
+  return (
+    <nav aria-label={label} className={cx("min-w-0", className)}>
+      <ol className="flex min-w-0 items-center gap-1.5 text-sm text-muted-foreground">
+        <li className="flex min-w-0 items-center">{crumb(list[0], false)}</li>
+
+        {middle.length > 0 ? (
+          <li className={cx("shrink-0 items-center gap-1.5", at(foldsNarrow, wideFold))}>
+            {sep}
+            <button
+              type="button"
+              ref={more}
+              popoverTarget={id}
+              aria-label="Show the full path"
+              title="Show the full path"
+              className="-mx-1 inline-flex h-8 w-8 items-center justify-center rounded-md outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <Icon name="more" size={18} />
+            </button>
+            {/* Keyed by the page, so a client navigation lands with it closed. */}
+            <div
+              key={list[n - 1].href ?? list[n - 1].label}
+              ref={panel}
+              id={id}
+              popover="auto"
+              className="min-w-44 max-w-[calc(100vw-2rem)] rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg"
+            >
+              <ul>
+                {middle.map(({ item, i }) => (
+                  <li key={i} className={at(foldsNarrow, foldsWide(i), "block")}>
+                    {item.href ? (
+                      <Link
+                        href={item.href}
+                        className="flex min-h-10 items-center rounded-sm px-2 text-sm outline-none hover:bg-accent focus-visible:bg-accent"
+                      >
+                        <span className="truncate">{item.label}</span>
+                      </Link>
+                    ) : (
+                      <span className="flex min-h-10 items-center px-2 text-sm text-muted-foreground">
+                        <span className="truncate">{item.label}</span>
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          </li>
+        ) : null}
+
+        {middle.map(({ item, i }) => (
+          <li key={i} className={cx("min-w-0 items-center gap-1.5", at(!foldsNarrow, !foldsWide(i)))}>
+            {sep}
+            {crumb(item, false)}
+          </li>
+        ))}
+
+        {/* The rest of the row, and never less than 10rem (or half a narrow
+            row): long earlier crumbs give way before this page's title. */}
+        <li className="flex min-w-[min(10rem,50%)] flex-1 items-center gap-1.5">
+          {sep}
+          {crumb(list[n - 1], true)}
+        </li>
+      </ol>
+    </nav>
+  );
+}