@usableapp/cardds 0.7.72 → 0.7.73

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.73 — 2026-10-08
+
+### Added
+- **`StampBook bare`: the album page with no ground** (Lh 2026-10-08) — three stamps across, lying on what holds the book and as large as it allows: each stamp is the whole width of its third, a small gap between. `<StampBook bare places={12}>`. The free `places` are still drawn. For the name, give the `Stamp` its `name` (it is drawn inside the stamp) and leave `StampCell label` out. The grounded page is as before.
+- **`AvatarStack more`: the count that trails the stack, unframed and large** (Lh 2026-10-08) — `<AvatarStack more="+9">`: plain title-size words after the heads, readable at arm's length. Before → after: `<Avatar size="sm" on>+9</Avatar>` as the last child (a small accent round — still there, unchanged) → `more="+9"` when the number must be seen.
+- **An `AvatarStack` holds `Stamp`s** — a `<Stamp bare>` in a stack has a width of its own (as tall as an `sm` avatar) and overlaps a little, like the heads. Before: the app had to set the stamp's width by hand.
+- **The catalog says what a component is FOR** (Lh 2026-10-08) — each component has a role: what it represents (a person, a number, words…; for a control, the kind of data it carries), whether it shows one thing or a group (in brief, in detail), and what the member can do with it (pick · act · write · navigate, or nothing). `npx cardds get <Name>` prints it; `npx cardds list` groups by it; `npx cardds find` asks by it in any language: `npx cardds find --represents person --shape group [--interact pick|none] [words…]`. Over MCP, `find_components` takes `represents`, `shape`, `interact`. A screen already drawn matches when its parts together cover what was asked.
+
+### Changed
+- **`npx cardds find` that matches nothing answers with one line** — a hint to ask in English words or by the axes; it used to list every screen.
+- **`npx cardds scaffold <id> --html` warns when the still picture is not the layout** — a screen with a `Sheet`, a `Step`, a `Modal`, a `Menu`… is placed by JavaScript when it runs, so its static HTML starts with a comment saying so (and the CLI says it on stderr): use the tsx there. `--css <href>` sets where `cardds.css` is from the file's place.
+- **`npx cardds list` output** — `{ name, group, shape, interact, represents }` per component (`--json`); it was `{ name, group }`. The catalog lists only what the package exports (`PostCorner`, `FormNote` are gone from it).
+
+### Fixed
+- **`npx cardds … --root` takes an absolute path** — it was joined to the working folder and found no catalog.
+- **`npx cardds … --root` (and the MCP pointed at a checkout) no longer blanks that checkout's running gallery** — the catalog's build shared the dev server's dependency cache.
+
 ## 0.7.72 — 2026-10-08
 
 ### Added

package/README.md

@@ -142,10 +142,12 @@ A session asked for a prototype need not read `src/`: the package ships a catalo
 `npm run build`) of every component — props, slots — and every story with its code and its rendered HTML. Ask it first:
 
 ```bash
-npx cardds find <words…>        # the screens already drawn, then components, then what is used with them (no match → every screen)
+npx cardds find [words…] [--represents person] [--shape group] [--interact pick|none]
+                                # by the AXES first (docs/roles.md: what it stands for · one or a group · what the member can do), words second;
+                                # the screens already drawn, then components, then what is used with them (nothing → a hint, not a list)
 npx cardds scaffold <id>        # a whole file from a screen: tsx (the code) or --html (a static document linking cardds.css)
-npx cardds get <Name> [--html]  # one component: props (a ReactNode prop is a slot) + variations with code
-npx cardds list                 # every name and group, nothing more
+npx cardds get <Name> [--html]  # one component: its role, props (a ReactNode prop is a slot) + variations with code
+npx cardds list                 # every name by what it is for: one · group-brief · group-detail, the show-only first, then by what the member can do
 npx cardds check <dir>          # the rules, before a screen is called done
 ```
 

package/bin/cardds.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // `npx cardds init` — set a project up the ONE way (Lh 2026-09-29): the project's theme.css, the check script, the ESLint rules.
 // `npx cardds check [dir…]` — the rules of lint/rules.mjs over the project's source; exit 1 on an error.
-// `npx cardds list | get <Name> | find <words…> | scaffold [id]` — the component catalog (lib/catalog.mjs) for an AI session; `npx cardds mcp` serves the same over MCP.
+// `npx cardds list | get <Name> | find [words…] [--represents a,b] [--shape s] [--interact k|none] | scaffold [id]` — the component catalog (lib/catalog.mjs) for an AI session; `npx cardds mcp` serves the same over MCP.
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkSource } from '../lint/rules.mjs';
 import * as catalog from '../lib/catalog.mjs';
@@ -70,15 +70,26 @@ import them, never copy their markup: the behaviour lives in the component. Gall
   return 0;
 }
 
+// the exports beside the components that are not components (docs/roles.md rows `a function, not a component`…): shape `—` and nothing to tell them from a structural part, so they are named
+const HELPERS = new Set(['applyMask', 'slideTo', 'useLayer', 'useLayers', 'useOptionalLayer', 'registerIcons', 'LayerHistory']);
 const one = (text) => text.replace(/\s+/g, ' ').trim();
 const indent = (text, by = '    ') => text.replace(/^(?=.)/gm, by);
 
 // each catalog command: the function's result as compact text (--json prints the result itself)
 const asText = {
-  list: (groups) => Object.entries(Object.groupBy(groups, (c) => c.group)).map(([g, cs]) => `${g}: ${cs.map((c) => c.name).join(' ')}`).join('\n'),
+  list: (components) => {
+    const named = (c) => (c.represents.length ? `${c.name} (${c.represents.join('·')})` : c.name);
+    const row = (label, cs) => (cs.length ? [`  ${label}${cs.map(named).join(' ')}`] : []);
+    const section = (shape, cs) => shape === '—'
+      ? [...row('helpers: ', cs.filter((c) => HELPERS.has(c.name))), ...row('structure: ', cs.filter((c) => !HELPERS.has(c.name)))]
+      : [...row('show      ', cs.filter((c) => !c.interact)), ...catalog.KINDS.flatMap((k) => row(k.padEnd(10), cs.filter((c) => c.interact && c.interact.includes(k))))];
+    return catalog.SHAPES.map((shape) => [shape, components.filter((c) => c.shape === shape)])
+      .filter(([, cs]) => cs.length).flatMap(([shape, cs]) => [shape, ...section(shape, cs)]).join('\n');
+  },
   get: (c, { html }) => [
     `${c.name} (${c.group})${c.element ? ` — forwards the <${c.element}> attributes` : ''}`,
     one(c.description),
+    ...(c.role ? [`role: represents ${[c.role.represents, c.role.count, c.role.density, c.role.job].flat().join(' · ')}${c.role.standsInFor.length ? `; stands in for: ${c.role.standsInFor.map((s) => (s.condition ? `${s.name} (${s.condition})` : s.name)).join('; ')}` : ''}`] : []),
     '\nprops',
     ...c.props.map((p) => `  ${p.name}${p.optional ? '?' : ''}: ${p.type}${p.slot ? '  [slot]' : ''}${p.description ? ` — ${one(p.description)}` : ''}`),
     `\nvariations (${c.variations.length})`,
@@ -86,27 +97,32 @@ const asText = {
     ...(c.alsoUsedIn ? [`\nalso used in: ${c.alsoUsedIn.join(' ')}\n(--all prints their code too)`] : []),
   ].join('\n'),
   find: (r) => [
-    ...(r.fallback ? [`nothing matches "${r.query}" — ${r.hint}. Every screen already drawn:\n${r.results.map((x) => x.id).join(' ')}`] : r.results.map((x) => `${x.kind === 'screen' ? 'screen    ' : 'component '}${x.id ?? x.name} — ${x.summary}`)),
+    ...(r.fallback ? [`nothing matches "${r.query}" — ${r.hint} (${r.screens} screens drawn)`]
+      : r.results.length ? r.results.map((x) => `${x.kind === 'screen' ? 'screen    ' : 'component '}${x.id ?? x.name}${x.role ? ` [${[...x.role.represents, x.role.shape, x.role.interact ? x.role.interact.join('+') : 'show'].join('·')}]` : ''} — ${x.summary}`) : [r.hint]),
     ...(r.usedTogether?.length ? [`\nused together: ${r.usedTogether.map((u) => `${u.name} (${u.stories})`).join(' ')}`] : []),
   ].join('\n'),
-  scaffold: (r) => typeof r === 'string' ? r.trimEnd() : r.map((x) => `${x.id} — ${x.summary}`).join('\n'),
+  scaffold: (r) => typeof r === 'string' ? r.trimEnd() : r.html ? r.html.trimEnd() : r.map((x) => `${x.id} — ${x.summary}`).join('\n'),
 };
 
 function ask(cmd, argv) {
   const flag = (name) => { const i = argv.indexOf(name); return i >= 0 && argv.splice(i, 1).length > 0; };
   const at = argv.indexOf('--root');
-  const root = at >= 0 ? join(cwd, argv.splice(at, 2)[1] ?? '') : undefined;
+  const root = at >= 0 ? resolve(cwd, argv.splice(at, 2)[1] ?? '') : undefined;
   const cssAt = argv.indexOf('--css'), css = cssAt >= 0 ? argv.splice(cssAt, 2)[1] : undefined;
+  const option = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv.splice(i, 2)[1] : undefined; };
+  const commas = (v) => v?.split(',').map((x) => x.trim()).filter(Boolean);
+  const axes = cmd === 'find' ? { represents: commas(option('--represents')), shape: option('--shape'), interact: ((v) => (v === 'none' ? false : commas(v)))(option('--interact')) } : undefined;
   const json = flag('--json'), html = flag('--html'), all = flag('--all');
   if (cmd === 'mcp') return import('../lib/mcp.mjs').then((m) => m.serve({ root }));
   const cat = catalog.load({ root });
   const q = argv.join(' ');
-  const result = cmd === 'list' ? catalog.list(cat) : cmd === 'get' ? catalog.get(cat, q, { html, all }) : cmd === 'find' ? catalog.find(cat, q) : catalog.scaffold(cat, q || undefined, { format: html ? 'html' : 'tsx', css });
+  const result = cmd === 'list' ? catalog.list(cat) : cmd === 'get' ? catalog.get(cat, q, { html, all }) : cmd === 'find' ? catalog.find(cat, q, axes) : catalog.scaffold(cat, q || undefined, { format: html ? 'html' : 'tsx', css });
   if (result.error) { console.error(`cardds ${cmd}: ${result.error}${result.closest ? ` — closest: ${result.closest.join(', ')}` : ''}`); return 1; }
+  if (result.warning && !json) console.error(`cardds scaffold: ${result.warning}`);
   console.log(json ? JSON.stringify(result) : asText[cmd](result, { html }));
   return 0;
 }
 
 const code = cmd === 'check' ? check(args) : cmd === 'init' ? init() : ['list', 'get', 'find', 'scaffold', 'mcp'].includes(cmd) ? await ask(cmd, args)
-  : (console.log('usage: cardds init | check [dir…] | list | get <Name> [--html] | find <words…> | scaffold [id] [--html [--css <href>]] | mcp   (list get find scaffold mcp: --root <path> --json)'), cmd ? 2 : 0);
+  : (console.log('usage: cardds init | check [dir…] | list | get <Name> [--html] | find [words…] [--represents a,b] [--shape s] [--interact k|none] | scaffold [id] [--html [--css <href>]] | mcp   (list get find scaffold mcp: --root <path> --json)'), cmd ? 2 : 0);
 process.exitCode = code;  // not process.exit: a big answer piped to a reader is cut off by an exit before it is flushed

package/css/people.css

@@ -50,6 +50,12 @@
 .avatar-stack { display: inline-flex; align-items: center; }
 .avatar-stack > .avatar { box-shadow: 0 0 0 var(--sp-1) var(--card-bg, var(--surface)); }
 .avatar-stack > .avatar + .avatar { margin-left: calc(-1 * var(--sp-3)); }
+/* stamps in the stack: a Stamp is as wide as its column, and an inline row has none — so it brings one, as tall as an sm head (4:5) and a little overlapped, like the heads
+   <span class="avatar-stack"><span class="stamp stamp--bare">…</span><span class="stamp stamp--bare">…</span><span class="avatar-stack__more">+9</span></span> */
+.avatar-stack > .stamp { --_stack-w: calc(var(--avatar-sm) * 4 / 5); flex: none; width: var(--avatar-stack-stamp-w, var(--_stack-w)); margin-inline: 0; }
+.avatar-stack > .stamp + .stamp { margin-left: calc(-1 * var(--sp-2)); }
+/* more: the count that trails the stack — plain words on the ground, title size so it reads at arm's length (the accent "+7" avatar is the small, framed way) */
+.avatar-stack__more { margin-left: var(--avatar-stack-more-gap, var(--sp-3)); font: var(--avatar-stack-more-font, var(--type-title)); color: var(--avatar-stack-more-ink, inherit); white-space: nowrap; }
 
 /* ---- avatar chooser: big heads with name + role under, scrolls sideways ----
    <div class="avatar-pick"><button class="avatar-pick__item"><span class="avatar avatar--lg avatar--add">+</span><span class="avatar-pick__name">Add</span><span class="avatar-pick__role">member</span></button>…</div> */

package/css/stamp.css

@@ -150,6 +150,10 @@
   color: var(--stamp-cell-on-ink, var(--on-accent));
 }
 .stamp-cell__on > .icon { width: 70%; height: 70%; }
+/* --bare: no ground, no padding — the stamps lie on what holds the book and fill it: three across, each the whole width of its third (the Stamp's own cap is lifted), the gap the least that still keeps three apart (the shadow's room), the row gap the same. The name is the Stamp's own; free places still draw.
+   <div class="stamp-book stamp-book--bare"> */
+.stamp-book--bare { gap: var(--stamp-book-bare-gap, var(--sp-2)); padding: 0; border-radius: 0; background: none; }
+.stamp-book--bare :is(.stamp, .stamp-place) { max-width: none; }
 /* --strip: ONE line of small stamps that scrolls sideways — the tray a member picks from. No ground. */
 .stamp-book--strip {
   --_strip: calc(var(--tap) * 1.5);

package/dist/actions/Chip.d.ts

@@ -9,7 +9,9 @@ export interface ChipProps extends ComponentProps<'span'> {
     dot?: 'a' | 'b' | DotTone;
     /** the element: span (default), a link, or a button */
     as?: 'span' | 'a' | 'button';
+    /** makes the chip a link (an `a`) */
     href?: string;
+    /** the chip's words */
     children?: ReactNode;
 }
 /** Chip — a status or attribute tag (with an optional signal Dot), or a small tap target; `on` when it is the live one. For a choice use ChipPick (`sign` for the +/× interest picker). */
@@ -303,10 +305,15 @@ export interface ChipPickProps extends Omit<ComponentProps<'label'>, 'onChange'>
     type?: 'radio' | 'checkbox';
     /** the +/× at the end: an interest / filter chip on a row, hugging its word (was ChipToggle) */
     sign?: boolean;
+    /** the input's name: the radios of one choice share it (that is what makes them one group); a checkbox's is its form field */
     name?: string;
+    /** what the input reports when this chip is picked */
     value?: string;
+    /** CONTROLLED: picked. The app owns it — pair it with `onChange` */
     checked?: boolean;
+    /** UNCONTROLLED: picked on arrival; the input then keeps its own */
     defaultChecked?: boolean;
+    /** the native input's change event: the chip was picked, or (checkbox) toggled */
     onChange?: React.ChangeEventHandler<HTMLInputElement>;
 }
 /** ChipPick — a chip that is a choice: full-width in a ChipGrid (9:00 · 9:30 · …), or `sign` on a ChipRow (+ off, × on — the

package/dist/actions/Dropdown.d.ts

@@ -35,6 +35,7 @@ export interface MenuProps extends Omit<ComponentProps<'div'>, 'popover' | 'onCh
     value?: string;
     /** …or the value it starts with */
     defaultValue?: string;
+    /** a MenuItem was picked (a value menu): the item's `value` */
     onChange?: (value: string) => void;
     /** the trigger sits at the far right: the panel grows leftwards */
     end?: boolean;

package/dist/actions/Fab.d.ts

@@ -1,8 +1,11 @@
 import type { ComponentProps } from 'react';
 import { type IconName } from '../type/Icon.js';
 export interface FabProps extends ComponentProps<'button'> {
+    /** the accessible name — required, the button has no text */
     label: string;
+    /** the icon (default plus); children replace it */
     icon?: IconName;
+    /** filled accent (default true); `invert={false}` for a plain one */
     invert?: boolean;
 }
 /** Fab — the square floating action at the bottom-right of a stage or screen (above the bar): an IconBtn with the fab's place. */

package/dist/actions/IconBtnGroup.d.ts

@@ -8,6 +8,7 @@ export interface IconBtnGroupProps extends Omit<ComponentProps<'div'>, 'onChange
     select?: 'one' | 'many';
     /** which are on — each child IconBtn names itself with its own `value` */
     value?: Picked;
+    /** UNCONTROLLED: which are on at first, in the same shape as `value`; the group then keeps its own. Pair of `value` */
     defaultValue?: Picked;
     /** asks the app: `one` → the pressed value · `many` → the new list */
     onChange?: (value: Picked) => void;

package/dist/cardds.css

@@ -3099,6 +3099,12 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .avatar-stack { display: inline-flex; align-items: center; }
 .avatar-stack > .avatar { box-shadow: 0 0 0 var(--sp-1) var(--card-bg, var(--surface)); }
 .avatar-stack > .avatar + .avatar { margin-left: calc(-1 * var(--sp-3)); }
+/* stamps in the stack: a Stamp is as wide as its column, and an inline row has none — so it brings one, as tall as an sm head (4:5) and a little overlapped, like the heads
+   <span class="avatar-stack"><span class="stamp stamp--bare">…</span><span class="stamp stamp--bare">…</span><span class="avatar-stack__more">+9</span></span> */
+.avatar-stack > .stamp { --_stack-w: calc(var(--avatar-sm) * 4 / 5); flex: none; width: var(--avatar-stack-stamp-w, var(--_stack-w)); margin-inline: 0; }
+.avatar-stack > .stamp + .stamp { margin-left: calc(-1 * var(--sp-2)); }
+/* more: the count that trails the stack — plain words on the ground, title size so it reads at arm's length (the accent "+7" avatar is the small, framed way) */
+.avatar-stack__more { margin-left: var(--avatar-stack-more-gap, var(--sp-3)); font: var(--avatar-stack-more-font, var(--type-title)); color: var(--avatar-stack-more-ink, inherit); white-space: nowrap; }
 
 /* ---- avatar chooser: big heads with name + role under, scrolls sideways ----
    <div class="avatar-pick"><button class="avatar-pick__item"><span class="avatar avatar--lg avatar--add">+</span><span class="avatar-pick__name">Add</span><span class="avatar-pick__role">member</span></button>…</div> */
@@ -4048,6 +4054,10 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   color: var(--stamp-cell-on-ink, var(--on-accent));
 }
 .stamp-cell__on > .icon { width: 70%; height: 70%; }
+/* --bare: no ground, no padding — the stamps lie on what holds the book and fill it: three across, each the whole width of its third (the Stamp's own cap is lifted), the gap the least that still keeps three apart (the shadow's room), the row gap the same. The name is the Stamp's own; free places still draw.
+   <div class="stamp-book stamp-book--bare"> */
+.stamp-book--bare { gap: var(--stamp-book-bare-gap, var(--sp-2)); padding: 0; border-radius: 0; background: none; }
+.stamp-book--bare :is(.stamp, .stamp-place) { max-width: none; }
 /* --strip: ONE line of small stamps that scrolls sideways — the tray a member picks from. No ground. */
 .stamp-book--strip {
   --_strip: calc(var(--tap) * 1.5);

package/dist/cards/Card.d.ts

@@ -23,6 +23,7 @@ export interface CardProps extends ComponentProps<'article'> {
     band?: boolean;
     /** the element: article (default), a when it links, label when it wraps an input, div/section */
     as?: 'article' | 'div' | 'a' | 'label' | 'section' | 'li';
+    /** the link's target, for `as="a"` */
     href?: string;
     /** THE HEAD, filled in place: the heading (wraps freely) — the card writes its CardHead first. For a head of your own shape
      *  (a chip before the words, a tile badge) write `<CardHead>` as the first child instead, and leave these out */
@@ -911,6 +912,7 @@ export declare function Card({ tone, paper, sm, row, cover, fold, centre, band,
         colorRendering?: import("csstype").Property.ColorRendering | undefined;
         glyphOrientationVertical?: import("csstype").Property.GlyphOrientationVertical | undefined;
     } | undefined;
+    /** the link's target, for `as="a"` */
     href?: string;
     key?: import("react").Key | null | undefined;
     defaultChecked?: boolean | undefined;

package/dist/cards/CardHead.d.ts

@@ -13,4 +13,9 @@ export interface CardHeadProps extends ComponentProps<'div'> {
     /** the sheet measured this title as wider than its line, so the heading runs sideways */
     long?: boolean;
 }
+/**
+ * CardHead — the card's head: the heading on the left takes the room, the contextual info hugs the far right.
+ * Use `heading` (+ `caption`) and `end` for the standard head, or pass children for a custom one
+ * (the FIRST child takes the room). Flat markup: no wrapper element, no <p> — the caption is a span on a row of its own (card.css). Never put buttons here — they go in the CardFoot.
+ */
 export declare function CardHead({ heading, caption, end, top, level, long, className, children, ...rest }: CardHeadProps): import("react").JSX.Element;

package/dist/cards/CardHead.js

@@ -3,11 +3,6 @@ import { Children, cloneElement, isValidElement, useContext } from 'react';
 import { cx } from '../cx.js';
 import { Text } from '../type/Text.js';
 import { StackHeadCtx } from '../sheets/stackCard.js';
-/**
- * CardHead — the card's head: the heading on the left takes the room, the contextual info hugs the far right.
- * Use `heading` (+ `caption`) and `end` for the standard head, or pass children for a custom one
- * (the FIRST child takes the room). Flat markup: no wrapper element, no <p> — the caption is a span on a row of its own (card.css). Never put buttons here — they go in the CardFoot.
- */
 const onTitleKey = (e) => {
     if (e.key !== 'Enter' && e.key !== ' ')
         return;
@@ -32,6 +27,11 @@ function markTitle(node, tab, long) {
         } : {}),
     });
 }
+/**
+ * CardHead — the card's head: the heading on the left takes the room, the contextual info hugs the far right.
+ * Use `heading` (+ `caption`) and `end` for the standard head, or pass children for a custom one
+ * (the FIRST child takes the room). Flat markup: no wrapper element, no <p> — the caption is a span on a row of its own (card.css). Never put buttons here — they go in the CardFoot.
+ */
 export function CardHead({ heading, caption, end, top, level = 'h2', long, className, children, ...rest }) {
     const tab = useContext(StackHeadCtx);
     const H = level === 'h1' ? 'h1' : 'h2';