@usableapp/cardds 0.7.106 → 0.7.107

package/lint/rules.mjs

@@ -168,7 +168,7 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   for (const m of text.matchAll(/<Screen\b/g)) {
     const end = text.indexOf('</Screen>', m.index);
     const screen = text.slice(m.index, end < 0 ? text.length : end);
-    if (/<Sheet\b/.test(screen) && /<ActionBar\b/.test(screen)) add('screen.bar-with-sheet', 'warn', m.index, 'a Sheet and an ActionBar on one Screen — a screen with a sheet finishes on the sheet\'s CardFoot, no bar.');
+    if (/<Sheet\b/.test(screen) && /<ActionBar\b/.test(screen)) add('screen.bar-with-sheet', 'warn', m.index, 'a Sheet and an ActionBar on one Screen — a screen with a sheet finishes on the sheet\'s Foot, no bar.');
   }
 
   // 4 · focus: cardds places the cursor when these parts come up — an `autoFocus` or a `.focus(` beside them fights it
@@ -246,16 +246,21 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   // a form is never on the ground (Lh 2026-10-18, timebank's ask steps on a bare Page): the control's nearest container written in this file decides.
   // None in the file (a step component's fragment) is not judged here — the file that places it is
   const places = [
-    ...span(/<(?:Sheet|SheetBody|SheetStep|StackSheet|SheetStack|CallSheet|Modal|ModalAsk)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })), // a modal is a surface over the screen too
+    // a Sheet's or a Modal's own children are its rows: content in it stands in its Body (a Modal's answers in its ModalAsk; the one control of a
+    // head, a Dropdown or a Toggle, in its Head). A Body is the sheet's when nothing round it in this file says otherwise; in a Card it is the card's (field-in-card)
+    ...span(/<(?:Sheet|Modal)\b(?![\w.])/g).map((p) => ({ ...p, ground: false, rows: true })),
+    ...span(/<(?:Body|SheetStep|StackSheet|SheetStack|CallSheet|ModalAsk)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })), // a modal is a surface over the screen too
     ...span(/<(?:ActionBarTier|FilterRow|TopBar|AppBar)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })), // a bar's control: a Slider in a control tier, a Dropdown in a filter row or a top bar's actions, a Toggle in an app bar
     ...span(/<(?:Page|Pages|Step|Screen)\b(?![\w.])/g).map((p) => ({ ...p, ground: true })),
     ...cards.map((p) => ({ ...p, ground: false })), // a card round it is field-in-card's finding
   ].sort((a, b) => a.at - b.at);
   // true on a sheet, false on the ground, null when this file cannot tell. A component of this file is where it is placed: the ask steps' <Page>,
-  // in a function rendered inside a <SheetBody> further up the file, slides inside that sheet
+  // in a function rendered inside a <Body> further up the file, slides inside that sheet
   const componentAt = (at) => [...text.slice(0, at).matchAll(/(?:function\s+|const\s+)([A-Z]\w*)/g)].at(-1)?.[1];
+  const placeAt = (at) => places.filter((p) => within(at, p)).at(-1);
+  const heads = span(/<Head\b(?![\w.])/g);
   const onSheet = (at, depth = 0) => {
-    const place = places.filter((p) => within(at, p)).at(-1);
+    const place = placeAt(at);
     if (place && !place.ground) return true;
     const name = depth < 5 && componentAt(at);
     if (name) for (const u of text.matchAll(new RegExp(`(?<![\\w$)\\].])<${name}\\b(?![\\w.])`, 'g'))) if (onSheet(u.index, depth + 1)) return true;
@@ -263,16 +268,18 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   };
   for (const c of text.matchAll(/<(Field|Composer|ComposerArea|Pin|Dropdown|Slider|Toggle|Check|ChipPick|Calendar|CalendarWeeks|DayStrip|Day|Picker|Mood|AvatarPick|FileBtn|AddRow|MapPick|Tile)\b(?![\w.])/g)) {
     const kind = c[1] === 'Tile' ? tagAt(text, c.index).match(/\s(pick|upload)\b(?!\s*=\s*\{\s*false)/)?.[1] : null;
-    if (c[1] === 'Tile' && !kind) continue; // a plain or stat Tile is read, not filled
+    if (c[1] === 'Tile' && !kind) continue; // a plain Tile is read, not filled
     const card = innermost(c.index);
     if (!card) {
-      if (onSheet(c.index) === false) add('field-off-sheet', 'error', c.index, `<${kind ? `Tile ${kind}` : c[1]}> on the ground: a form is never on the ground, it sits only on a sheet (Lh 2026-10-18). A Page, Pages, Step or Screen is the base, not a sheet. Put the control on a Sheet's <SheetBody>, in a <SheetStep>, or on a stack sheet — a form over a screen is a <Sheet> in a <SheetStage over dim> (Home/AskSheet).`);
+      const place = placeAt(c.index);
+      if (place?.rows && !heads.some((h) => within(c.index, h) && h.at > place.at)) { add('field-off-sheet', 'error', c.index, `<${kind ? `Tile ${kind}` : c[1]}> straight in a <${text.slice(place.at + 1).match(/^\w+/)[0]}>: a sheet's and a modal's children are its rows, a Head, a Body and a Foot, and the content stands in the Body (Lh 2026-10-21). Put the control in its <Body>.`); continue; }
+      if (onSheet(c.index) === false) add('field-off-sheet', 'error', c.index, `<${kind ? `Tile ${kind}` : c[1]}> on the ground: a form is never on the ground, it sits only on a sheet (Lh 2026-10-18). A Page, Pages, Step or Screen is the base, not a sheet. Put the control in a Sheet's <Body>, in a <SheetStep>, or on a stack sheet — a form over a screen is a <Sheet> in a <SheetStage over dim> (Home/AskSheet).`);
       continue;
     }
     const stack = stacks.filter((s) => card.at >= s.body && card.at < s.end).at(-1);
     if (stack && !cards.some((o) => o !== card && within(card.at, o) && o.at >= stack.body)) continue;
     const name = kind ? `Tile ${kind}` : c[1];
-    add('field-in-card', 'error', c.index, `<${name}> inside a <Card>: the sheet is the paper the member fills in (Lh 2026-10-18) — a card is for reading and pressing buttons. Put the ${name} straight on a Sheet's <SheetBody>, in a <SheetStep>, or on a stack sheet, with no card round it.`);
+    add('field-in-card', 'error', c.index, `<${name}> inside a <Card>: the sheet is the paper the member fills in (Lh 2026-10-18) — a card is for reading and pressing buttons. Put the ${name} straight in a Sheet's <Body>, in a <SheetStep>, or on a stack sheet, with no card round it.`);
   }
 
   // 11 · a worded pager bar: back and next never carry the same signal — the forward Btn (the last) is `primary`, the back one is not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.106",
+  "version": "0.7.107",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",
@@ -59,6 +59,7 @@
     "lint",
     "lib",
     "bin",
+    "scripts/codemod-parts.mjs",
     "css",
     "fonts",
     "cardds.css",

package/scripts/codemod-parts.mjs

@@ -0,0 +1,324 @@
+// The parts of a line, and the head, the body and the foot of a card, a sheet, a stack sheet and a modal replace the parts each whole had of its own (docs/parts-plan.md, Lh 2026-10-21): this
+// rewrites a file's JSX and its `cardds` imports from the retired names to the new, through the TypeScript AST, never by the text of a name. A consumer runs it
+// on its screens after the release; the previews were migrated by it. Later PRs of the program add their rows to RENAMES and RESHAPES.
+//   npx cardds codemod-parts <files…>             rewrite each file in place; a tag it cannot rewrite is printed and left
+//   npx cardds codemod-parts --check <files…>     exit 1 naming every tag and import that still writes a retired name
+// (in this repo also `node scripts/codemod-parts.mjs …`; it reads `typescript` from the project that runs it)
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+
+/** old tag → new tag; `inside` when the rewrite holds only under that parent element (a `CardBody` is the words of a `Card row`) */
+export const RENAMES = {
+  RowLead: { to: 'Lead' },
+  RowBody: { to: 'Words' },
+  RowEnd: { to: 'End' },
+  CardThumb: { to: 'Lead' },
+  CardEnd: { to: 'End' },
+  CardBody: { to: 'Words', inside: { tag: 'Card', attr: 'row' } },
+  SheetBody: { to: 'Body' },
+  ModalBody: { to: 'Body' },
+  CardFoot: { to: 'Foot' },
+};
+
+/** a tag whose props became children: the props the tag drew its head with, and what each is now. `Card` keeps its own props, so only the head's go */
+export const RESHAPES = {
+  CardHead: { to: 'Head', words: { heading: 'title', caption: 'meta', level: 'level' }, end: 'end' },
+  SheetHead: { to: 'Head', adds: 'centre', words: { title: 'title', sub: 'meta' }, lead: 'lead', end: 'trail' },
+  Card: { words: { heading: 'title', caption: 'meta', level: 'level' }, end: 'end', head: true },
+};
+/** a Card's foot props, written as its last child, a `Foot`: `foot` its children, `footLink` its `link`, `footRound` its `round` */
+const FOOT_PROPS = ['foot', 'footLink', 'footRound'];
+const HEAD_PROPS = { Card: ['heading', 'caption', 'end', 'level'], CardHead: ['heading', 'caption', 'end', 'level'], SheetHead: ['lead', 'title', 'sub', 'trail'] };
+const LINE = 140;
+
+const parse = (source, file) => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+const tagName = (el) => (ts.isJsxOpeningElement(el) || ts.isJsxSelfClosingElement(el) || ts.isJsxClosingElement(el)) && ts.isIdentifier(el.tagName) ? el.tagName.text : null;
+const attrName = (a) => (ts.isJsxAttribute(a) && ts.isIdentifier(a.name) ? a.name.text : null);
+const findAttr = (opening, name) => opening.attributes.properties.find((a) => attrName(a) === name);
+const hasAttr = (opening, name) => opening.attributes.properties.some((a) => attrName(a) === name && (!a.initializer || (ts.isJsxExpression(a.initializer) && a.initializer.expression?.kind === ts.SyntaxKind.TrueKeyword)));
+/** the element this tag stands directly in, or null at the top or inside an attribute */
+const parentElement = (el) => {
+  const self = ts.isJsxSelfClosingElement(el) ? el : el.parent;
+  return ts.isJsxElement(self.parent) ? self.parent.openingElement : null;
+};
+const fits = (rule, el) => {
+  if (!rule.inside) return true;
+  const parent = parentElement(el);
+  return !!parent && tagName(parent) === rule.inside.tag && hasAttr(parent, rule.inside.attr);
+};
+const line = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+const openingOf = (n) => (ts.isJsxElement(n) ? n.openingElement : n);
+const headProps = (opening) => (HEAD_PROPS[tagName(opening)] ?? []).filter((p) => findAttr(opening, p));
+
+/** every retired name the file still writes, as a JSX tag, a `cardds` import or a prop that became a child: `{ line, name, write }`, in file order */
+export function check(source, file = 'x.tsx') {
+  const sf = parse(source, file);
+  const out = [];
+  const walk = (n) => {
+    const name = tagName(n);
+    if (name && name in RENAMES && !ts.isJsxClosingElement(n)) out.push({ line: line(sf, n), name, write: RENAMES[name].to });
+    if (name && (name === 'CardHead' || name === 'SheetHead') && !ts.isJsxClosingElement(n)) out.push({ line: line(sf, n), name, write: 'Head' });
+    if (name === 'Card' && (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n))) {
+      for (const p of headProps(n)) out.push({ line: line(sf, n), name: `Card ${p}`, write: '<Head><Words title meta /></Head> as its first child' });
+      for (const p of FOOT_PROPS.filter((f) => findAttr(n, f))) out.push({ line: line(sf, n), name: `Card ${p}`, write: '<Foot round link>…</Foot> as its last child' });
+    }
+    ts.forEachChild(n, walk);
+  };
+  walk(sf);
+  for (const st of sf.statements) {
+    if (!st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    const named = ts.isFunctionDeclaration(st) ? [st.name] : ts.isVariableStatement(st) ? st.declarationList.declarations.map((d) => d.name) : [];
+    for (const id of named) if (id && ts.isIdentifier(id) && STORY.test(id.text)) out.push({ line: line(sf, id), name: id.text, write: storyName(id.text) });
+  }
+  for (const imp of sf.statements.filter(ts.isImportDeclaration)) {
+    const nb = imp.importClause?.namedBindings;
+    if (imp.moduleSpecifier.text !== 'cardds' || !nb || !ts.isNamedImports(nb)) continue;
+    for (const e of nb.elements) {
+      const name = (e.propertyName ?? e.name).text;
+      if (name in RENAMES) out.push({ line: line(sf, e), name: e.name.text, write: RENAMES[name].to });
+      if (name === 'CardHead' || name === 'SheetHead') out.push({ line: line(sf, e), name: e.name.text, write: 'Head' });
+    }
+  }
+  return out.sort((a, b) => a.line - b.line);
+}
+
+const lineIndent = (source, pos) => /^[ \t]*/.exec(source.slice(source.lastIndexOf('\n', pos - 1) + 1))[0];
+const valueOf = (attr, sf) => (attr.initializer ? attr.initializer.getText(sf) : '{true}');
+/** a prop's value as a child: a JSX element stands as it is, anything else in braces */
+function childOf(attr, sf) {
+  const init = attr.initializer;
+  if (!init) return null;
+  const expr = ts.isJsxExpression(init) ? init.expression : init;
+  if (!expr) return null;
+  const jsx = ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr) || ts.isJsxFragment(expr);
+  return jsx ? expr.getText(sf) : `{${expr.getText(sf)}}`;
+}
+/** `parts` laid on one line when they fit, else one to a line under `indent` */
+function lay(open, parts, close, indent) {
+  const one = `${open}${parts.join('')}${close}`;
+  if (one.length + indent.length <= LINE && !one.includes('\n')) return one;
+  return `${open}\n${parts.map((p) => `${indent}  ${p}`).join('\n')}\n${indent}${close}`;
+}
+/** the words the head's props draw, as one `<Words … />`, or null when none was given */
+function wordsOf(opening, rule, sf) {
+  const props = Object.entries(rule.words).map(([from, to]) => [to, findAttr(opening, from)]).filter(([, a]) => a);
+  if (!props.some(([to]) => to === 'title' || to === 'meta')) return null;
+  return `<Words ${props.map(([to, a]) => `${to}=${valueOf(a, sf)}`).join(' ')} />`;
+}
+/** the opening tag's text without the props that became children (each removed with the space before it) */
+function without(source, opening, names, sf) {
+  const cuts = names.map((n) => findAttr(opening, n)).filter(Boolean).map((a) => [a.getFullStart(), a.end]).sort((a, b) => b[0] - a[0]);
+  let text = source.slice(opening.getStart(sf), opening.end);
+  const base = opening.getStart(sf);
+  for (const [from, to] of cuts) text = text.slice(0, from - base) + text.slice(to - base);
+  return text;
+}
+
+/** the innermost head-shaped element that still writes the old props, as an edit: `{ pos, end, text }`, or null */
+function reshape(source, sf, el) {
+  const opening = openingOf(el), name = tagName(opening);
+  const rule = RESHAPES[name];
+  if (!rule) return null;
+  const used = headProps(opening);
+  if (name === 'CardHead' && !used.length && ts.isJsxSelfClosingElement(el) === false) {
+    return { rename: true };
+  }
+  if (rule.head && !used.length) return footOf(source, sf, el);
+  const indent = lineIndent(source, opening.getStart(sf));
+  const words = wordsOf(opening, rule, sf);
+  const endAttr = findAttr(opening, rule.end);
+  const end = endAttr ? childOf(endAttr, sf) : null;
+  const lead = rule.lead && findAttr(opening, rule.lead) ? childOf(findAttr(opening, rule.lead), sf) : null;
+  const moved = Object.keys(rule.words).concat(rule.end, rule.lead ?? []);
+  const rest = (without(source, opening, moved, sf)).replace(/\s*\/>$/, '>').replace(/\s*\n\s*>$/, '>').replace(/^<(\w+)\s+>$/, '<$1>').replace(/^<(\w+)/, (m, tag) => `<${rule.to ?? tag}${rule.adds ? ` ${rule.adds}` : ''}`);
+  if (rule.head && !words && !end) {
+    const was = source.slice(opening.getStart(sf), opening.end);
+    return { pos: opening.getStart(sf), end: opening.end, text: ts.isJsxSelfClosingElement(el) ? was.replace(new RegExp(`\\s*\\b(${moved.join('|')})=(\\{[^}]*\\}|"[^"]*")`, 'g'), '') : rest };
+  }
+  if (rule.head) {
+    const head = lay('<Head>', [words, end].filter(Boolean), '</Head>', `${indent}  `);
+    if (ts.isJsxSelfClosingElement(el)) return { pos: el.getStart(sf), end: el.end, text: `${rest}\n${indent}  ${head}\n${indent}</Card>` };
+    return { pos: opening.getStart(sf), end: opening.end, text: `${rest}\n${indent}  ${head}` };
+  }
+  if (ts.isJsxSelfClosingElement(el)) {
+    const open = rest;
+    return { pos: el.getStart(sf), end: el.end, text: lay(open, [lead, words, end].filter(Boolean), '</Head>', indent) };
+  }
+  const front = [lead, words].filter(Boolean);
+  const inner = source.slice(opening.end, el.closingElement.getStart(sf));
+  if (!inner.includes('\n')) return { pos: el.getStart(sf), end: el.end, text: lay(rest, [...front, inner.trim(), end].filter(Boolean), '</Head>', indent) };
+  const edits = [{ pos: opening.getStart(sf), end: opening.end, text: front.length ? `${rest}\n${indent}  ${front.join(`\n${indent}  `)}` : rest }];
+  edits.push({ pos: el.closingElement.getStart(sf), end: el.closingElement.end, text: `${end ? `  ${end}\n${indent}` : ''}</Head>` });
+  return { edits };
+}
+
+/** a node's text with its lines after the first moved as far as its first one moves, to stand at column `to` */
+function moved(node, sf, text, to) {
+  const by = to - sf.getLineAndCharacterOfPosition(node.getStart(sf)).character;
+  return text.replace(/\n( *)/g, (m, sp) => `\n${' '.repeat(Math.max(0, sp.length + by))}`);
+}
+/** what a Card's `foot` held, as the Foot's children standing at column `to`: a fragment's children each as it is, anything else as one child */
+function footChildren(attr, sf, to) {
+  const expr = attr.initializer && ts.isJsxExpression(attr.initializer) ? attr.initializer.expression : null;
+  if (expr && ts.isJsxFragment(expr)) return expr.children.filter((c) => !(ts.isJsxText(c) && !c.getText(sf).trim())).map((c) => moved(c, sf, c.getText(sf).trim(), to));
+  const child = childOf(attr, sf);
+  if (!child) return [];
+  return [expr && (ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr)) ? moved(expr, sf, child, to) : child];
+}
+/** a Card that still writes its foot with props, as an edit that drops them and writes a `<Foot>` as its last child (`footRound` alone drew no foot: it only goes) */
+function footOf(source, sf, el) {
+  const opening = openingOf(el);
+  const used = FOOT_PROPS.filter((p) => findAttr(opening, p));
+  if (!used.length) return null;
+  const indent = lineIndent(source, opening.getStart(sf));
+  const self = ts.isJsxSelfClosingElement(el);
+  const rest = without(source, opening, used, sf).replace(/\s*\/>$/, '>').replace(/\s*\n\s*>$/, '>');
+  const fa = findAttr(opening, 'foot'), la = findAttr(opening, 'footLink'), ra = findAttr(opening, 'footRound');
+  if (!fa && !la) return { pos: opening.getStart(sf), end: opening.end, text: self ? rest.replace(/>$/, ' />') : rest };
+  const round = !ra ? '' : hasAttr(opening, 'footRound') ? ' round' : ` round=${valueOf(ra, sf)}`;
+  const attrs = `${round}${la ? ` link=${valueOf(la, sf)}` : ''}`;
+  const kids = fa ? footChildren(fa, sf, indent.length + 4) : [];
+  const foot = kids.length ? lay(`<Foot${attrs}>`, kids, '</Foot>', `${indent}  `) : `<Foot${attrs} />`;
+  if (self) return { pos: el.getStart(sf), end: el.end, text: `${rest}\n${indent}  ${foot}\n${indent}</Card>` };
+  const inner = source.slice(opening.end, el.closingElement.getStart(sf));
+  if (!inner.includes('\n')) return { pos: el.getStart(sf), end: el.end, text: lay(rest, [inner.trim(), foot].filter(Boolean), '</Card>', indent) };
+  return { edits: [{ pos: opening.getStart(sf), end: opening.end, text: rest }, { pos: el.closingElement.getStart(sf), end: el.closingElement.getStart(sf), text: `  ${foot}\n${indent}` }] };
+}
+
+/** the file rewritten: `source` after, `tags` rewritten, `imports` rewritten, and `left`, the tags no rule fits (`{ line, name, why }`) */
+export function rewrite(source, file = 'x.tsx') {
+  let tags = 0, imports = 0;
+  const left = [];
+  let text = source;
+  for (let pass = 0; pass < 12; pass++) {
+    const r = once(text, file);
+    if (r.source === text) { left.splice(0, left.length, ...r.left); break; }
+    tags += r.tags;
+    text = r.source;
+    if (pass === 11) throw new Error(`codemod-parts: ${file} still changing after 12 passes`);
+  }
+  const fin = fixImports(text, file);
+  for (const name of fin.clash) left.push({ line: 1, name, why: `the file declares its own ${name}, which the import would shadow: rename it` });
+  const stories = renameStories(fin.source, file);
+  return { source: stories.source, tags, imports: fin.imports, stories: stories.count, left };
+}
+
+/** one pass: the renames of RENAMES, then the innermost reshape that overlaps no other edit */
+function once(source, file) {
+  const sf = parse(source, file);
+  const edits = [];
+  const left = [];
+  const walk = (n) => {
+    const name = tagName(n);
+    if (name && name in RENAMES) {
+      const rule = RENAMES[name];
+      const opening = ts.isJsxClosingElement(n) ? n.parent.openingElement : n;
+      if (fits(rule, opening)) edits.push({ pos: n.tagName.getStart(sf), end: n.tagName.end, text: rule.to });
+      else if (!ts.isJsxClosingElement(n)) left.push({ line: line(sf, n), name, why: `not in a <${rule.inside.tag} ${rule.inside.attr}>` });
+    }
+    ts.forEachChild(n, walk);
+  };
+  walk(sf);
+  if (edits.length) return { source: apply(source, edits), tags: edits.length, left };
+  const found = [];
+  const reshapes = (n) => {
+    if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)) {
+      const r = reshape(source, sf, n);
+      if (r) found.push({ node: n, r });
+    }
+    ts.forEachChild(n, reshapes);
+  };
+  reshapes(sf);
+  const inner = found.filter(({ node }) => !found.some((o) => o.node !== node && o.node.getStart(sf) >= node.getStart(sf) && o.node.end <= node.end));
+  const out = [];
+  for (const { node, r } of inner) {
+    if (r.rename) { const el = node; out.push({ pos: el.openingElement.tagName.getStart(sf), end: el.openingElement.tagName.end, text: 'Head' }, { pos: el.closingElement.tagName.getStart(sf), end: el.closingElement.tagName.end, text: 'Head' }); }
+    else out.push(...(r.edits ?? [r]));
+  }
+  return { source: apply(source, out), tags: inner.length, left };
+}
+
+const apply = (source, edits) => {
+  let out = source;
+  for (const e of edits.sort((a, b) => b.pos - a.pos)) out = out.slice(0, e.pos) + e.text + out.slice(e.end);
+  return out;
+};
+
+/** a story named for a part it showed (`CardHeadTop`, `SheetHeadLeadTrail`, `SheetBodyScrolls`, `CardFootRound`) is named for the one part (`HeadTop`,
+ *  `HeadLeadTrail`, `BodyScrolls`, `FootRound`), wherever the file says it */
+const STORY = /^(CardHead|SheetHead|SheetBody|CardFoot)(?=[A-Z])/;
+const storyName = (name) => name.replace(STORY, (m) => ({ SheetBody: 'Body', CardFoot: 'Foot' })[m] ?? 'Head');
+function renameStories(source, file) {
+  const sf = parse(source, file);
+  const names = new Set();
+  for (const st of sf.statements) {
+    if (!st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    if (ts.isFunctionDeclaration(st) && st.name && STORY.test(st.name.text)) names.add(st.name.text);
+    if (ts.isVariableStatement(st)) for (const d of st.declarationList.declarations) if (ts.isIdentifier(d.name) && STORY.test(d.name.text)) names.add(d.name.text);
+  }
+  if (!names.size) return { source, count: 0 };
+  const edits = [];
+  const walk = (n) => { if (ts.isIdentifier(n) && names.has(n.text)) edits.push({ pos: n.getStart(sf), end: n.end, text: storyName(n.text) }); ts.forEachChild(n, walk); };
+  walk(sf);
+  return { source: apply(source, edits), count: names.size };
+}
+
+/** the names between the braces, wrapped under 140 columns when the import was written over lines */
+function importList(names, wrapped) {
+  if (!wrapped) return `{ ${names.join(', ')} }`;
+  const rows = [''];
+  for (const n of names) { const row = rows[rows.length - 1]; if (row && row.length + n.length > LINE - 6) rows.push(n); else rows[rows.length - 1] = row ? `${row}, ${n}` : n; }
+  return `{\n${rows.map((r) => `  ${r},`).join('\n')}\n}`;
+}
+
+/** the `cardds` import after the tags changed: a retired name replaced by its new one in place, `Head` and `Words` added where a tag now needs them, a name no tag writes any more dropped */
+function fixImports(source, file) {
+  const sf = parse(source, file);
+  const used = new Set();
+  const walk = (n) => { const name = tagName(n); if (name && !ts.isJsxClosingElement(n)) used.add(name); ts.forEachChild(n, walk); };
+  walk(sf);
+  const edits = [];
+  let imports = 0;
+  for (const imp of sf.statements.filter(ts.isImportDeclaration)) {
+    const nb = imp.importClause?.namedBindings;
+    if (imp.moduleSpecifier.text !== 'cardds' || !nb || !ts.isNamedImports(nb)) continue;
+    const names = [];
+    const add = (t) => { if (!names.includes(t)) names.push(t); };
+    for (const e of nb.elements) {
+      const name = (e.propertyName ?? e.name).text;
+      const retired = !e.propertyName && (name in RENAMES || name === 'CardHead' || name === 'SheetHead') && !used.has(name);
+      if (!retired) { add(e.getText(sf)); continue; }
+      const to = name in RENAMES ? RENAMES[name].to : 'Head';
+      add(to);
+      if (to === 'Head' && used.has('Words')) add('Words');
+    }
+    for (const part of ['Head', 'Words', 'Foot']) if (used.has(part) && !names.includes(part)) names.push(part);
+    if (names.join(', ') === nb.elements.map((e) => e.getText(sf)).join(', ')) continue;
+    imports++;
+    edits.push({ pos: nb.getStart(sf), end: nb.end, text: importList(names, nb.getText(sf).includes('\n')) });
+  }
+  const declared = new Set(sf.statements.flatMap((st) => (ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && st.name ? [st.name.text] : ts.isVariableStatement(st) ? st.declarationList.declarations.flatMap((d) => (ts.isIdentifier(d.name) ? [d.name.text] : [])) : []));
+  return { source: apply(source, edits), imports, clash: ['Head', 'Words', 'Body', 'Foot'].filter((n) => used.has(n) && declared.has(n)) };
+}
+
+/** the command: rewrite each file in place, or with `--check` name what still writes a retired name; the exit code */
+export function main(args) {
+  const checking = args.includes('--check');
+  const files = args.filter((a) => a !== '--check');
+  if (!files.length) { console.error('usage: npx cardds codemod-parts [--check] <files…>'); return 2; }
+  let failed = false;
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8');
+    if (checking) {
+      for (const { line, name, write } of check(source, file)) { failed = true; console.log(`${file}:${line}: ${name} is retired, write ${write}`); }
+      continue;
+    }
+    const { source: out, tags, imports, stories, left } = rewrite(source, file);
+    if (out !== source) { writeFileSync(file, out); console.log(`${file}: ${tags} tag${tags === 1 ? '' : 's'}, ${imports} import${imports === 1 ? '' : 's'}${stories ? `, ${stories} stor${stories === 1 ? 'y' : 'ies'}` : ''}`); }
+    for (const { line, name, why } of left) { failed = true; console.log(`${file}:${line}: <${name}> left as it is, ${why}`); }
+  }
+  return failed ? 1 : 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) process.exit(main(process.argv.slice(2)));

package/dist/cards/CardFoot.d.ts

@@ -1,15 +0,0 @@
-import type { ComponentProps, ReactNode } from 'react';
-export interface CardFootProps extends ComponentProps<'div'> {
-    /** a SMALL LINK under the buttons, centred on its own short row (a `Link sm` — "details for developers") — the same as an
-     *  ActionBar's ctaLink (Lh 2026-09-23). It never takes a share of the buttons' line */
-    link?: ReactNode;
-    /** a foot of a few ROUND buttons (`IconBtn`, a size `lg` / `xl` for the big ones): they keep their own size instead of sharing the line, and
-     *  stand as ONE group in the middle of the foot, a fixed gap apart (wider than the Btns' — `--card-foot-gap` sets it). The Btn foot is
-     *  unchanged: this is the other foot, for a few big round answers */
-    round?: boolean;
-}
-/** CardFoot — the card's action buttons on one line: one takes the width, up to four share it evenly. Btns only in the row; a small
- *  link goes in `link`, under it. A `Btn form` keeps its own size here: as wide as its words, centred — for a foot whose one button
- *  should not fill the card. With `round` it is the foot of a few round `IconBtn`s (`size="xl"`, one `primary` with a word, the others
- *  with icons): one centred group, a fixed gap between them. */
-export declare function CardFoot({ link, round, className, children, ...rest }: CardFootProps): import("react").JSX.Element;

package/dist/cards/CardFoot.js

@@ -1,9 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cx } from '../cx.js';
-/** CardFoot — the card's action buttons on one line: one takes the width, up to four share it evenly. Btns only in the row; a small
- *  link goes in `link`, under it. A `Btn form` keeps its own size here: as wide as its words, centred — for a foot whose one button
- *  should not fill the card. With `round` it is the foot of a few round `IconBtn`s (`size="xl"`, one `primary` with a word, the others
- *  with icons): one centred group, a fixed gap between them. */
-export function CardFoot({ link, round, className, children, ...rest }) {
-    return (_jsxs("div", { className: cx('card__foot', link != null && 'card__foot--link', round && 'card__foot--round', className), ...rest, children: [children, link != null && _jsx("div", { className: "card__foot-link", children: link })] }));
-}

package/dist/cards/CardHead.d.ts

@@ -1,21 +0,0 @@
-import { type ComponentProps, type ReactNode } from 'react';
-export interface CardHeadProps extends ComponentProps<'div'> {
-    /** the heading (a string becomes an h2 at level `t-h2`) — wraps freely, as many lines as the words need */
-    heading?: ReactNode;
-    /** the muted line under the heading (a date, a subtitle) */
-    caption?: ReactNode;
-    /** the contextual thing at the far right: a chip, an IconBtn (more), a Link, a small Ring, an Avatar, a Badge (a count in a stack head) */
-    end?: ReactNode;
-    /** top-align a genuinely tall multi-line title with its control */
-    top?: boolean;
-    /** the heading level to render the string heading with (h2 default; h1 for the one-feature page) */
-    level?: 'h1' | 'h2' | 'display';
-    /** 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

@@ -1,39 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useContext } from 'react';
-import { cx } from '../cx.js';
-import { Text } from '../type/Text.js';
-import { StackHeadCtx } from '../sheets/stackCard.js';
-const onTitleKey = (e) => {
-    if (e.key !== 'Enter' && e.key !== ' ')
-        return;
-    e.preventDefault();
-    e.currentTarget.click();
-};
-/** the stack's title is the keyboard's way in. The heading renders the tab stop and, when the sheet measured it long, `.is-long`. Nothing sets either on the node afterwards */
-function markTitle(node, tab, long) {
-    if (!isValidElement(node))
-        return node;
-    const el = node;
-    const level = el.type === Text ? el.props.level : null;
-    const intrinsic = typeof el.type === 'string' && /^h[1-3]$/.test(el.type);
-    if (level !== 'h1' && level !== 'h2' && level !== 'display' && !intrinsic)
-        return node;
-    return cloneElement(el, {
-        ...(long ? { className: cx(el.props.className, 'is-long') } : {}),
-        ...(tab != null ? {
-            tabIndex: tab,
-            onKeyDown: (e) => { el.props.onKeyDown?.(e); if (!e.defaultPrevented)
-                onTitleKey(e); },
-        } : {}),
-    });
-}
-/**
- * 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';
-    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: cx(`t-${level}`, long && 'is-long'), tabIndex: tab ?? undefined, onKeyDown: tab != null ? onTitleKey : undefined, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), tab == null && !long ? children : Children.map(children, (c) => markTitle(c, tab, !!long)), end] }));
-}

package/dist/cards/Stat.d.ts

@@ -1,19 +0,0 @@
-import type { ComponentProps } from 'react';
-export interface StatProps extends ComponentProps<'div'> {
-    /** takes the remaining row space beside a Ring */
-    grow?: boolean;
-    /** centred: the one number of a sheet or a stage, under a centred Avatar */
-    centre?: boolean;
-}
-/** Stat — an inline stat block: a label, a big `Text level="stat"` number, a caption; StatRows put a Delta beside the label. */
-export declare function Stat({ grow, centre, className, ...rest }: StatProps): import("react").JSX.Element;
-export interface StatRowProps extends ComponentProps<'div'> {
-}
-/** StatRow — label left, Delta (or caption) right, inside a Stat. */
-export declare function StatRow({ className, ...rest }: StatRowProps): import("react").JSX.Element;
-export interface DeltaProps extends ComponentProps<'span'> {
-    /** a drop: painted in the signal colour */
-    neg?: boolean;
-}
-/** Delta — the small "+7.5%" pill beside a stat label. */
-export declare function Delta({ neg, className, ...rest }: DeltaProps): import("react").JSX.Element;

package/dist/cards/Stat.js

@@ -1,14 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { cx } from '../cx.js';
-/** Stat — an inline stat block: a label, a big `Text level="stat"` number, a caption; StatRows put a Delta beside the label. */
-export function Stat({ grow, centre, className, ...rest }) {
-    return _jsx("div", { className: cx('stat', grow && 'grow', centre && 'stat--centre', className), ...rest });
-}
-/** StatRow — label left, Delta (or caption) right, inside a Stat. */
-export function StatRow({ className, ...rest }) {
-    return _jsx("div", { className: cx('stat__row', className), ...rest });
-}
-/** Delta — the small "+7.5%" pill beside a stat label. */
-export function Delta({ neg, className, ...rest }) {
-    return _jsx("span", { className: cx('delta', neg && 'delta--neg', className), ...rest });
-}

package/dist/sheets/SheetBody.d.ts

@@ -1,5 +0,0 @@
-import { type ComponentProps } from 'react';
-export interface SheetBodyProps extends ComponentProps<'div'> {
-}
-/** SheetBody — everything under a Sheet's head: the one thing that scrolls; its scroll padding keeps a focused control above the cut. Content never goes straight into the Sheet. */
-export declare function SheetBody({ className, ...rest }: SheetBodyProps): import("react").JSX.Element;

package/dist/sheets/SheetBody.js

@@ -1,9 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useContext } from 'react';
-import { cx } from '../cx.js';
-import { StackPullCtx } from './stackCard.js';
-/** SheetBody — everything under a Sheet's head: the one thing that scrolls; its scroll padding keeps a focused control above the cut. Content never goes straight into the Sheet. */
-export function SheetBody({ className, ...rest }) {
-    const pulling = useContext(StackPullCtx);
-    return _jsx("div", { className: cx('sheet__body', pulling && 'is-refreshing', className), ...rest });
-}

package/dist/sheets/SheetHead.d.ts

@@ -1,15 +0,0 @@
-import type { ComponentProps, ReactNode } from 'react';
-export interface SheetHeadProps extends Omit<ComponentProps<'div'>, 'title'> {
-    /** the round button on the left (an IconBtn sm) */
-    lead?: ReactNode;
-    /** the centred title */
-    title: ReactNode;
-    /** the caption under the title */
-    sub?: ReactNode;
-    /** the round button on the right */
-    trail?: ReactNode;
-    /** the sheet measured this title as wider than its line, so it runs sideways */
-    long?: boolean;
-}
-/** SheetHead — the stage sheet's three-column head: round button · centred title + sub · round button. A step sheet uses a CardHead instead. */
-export declare function SheetHead({ lead, title, sub, trail, long, className, ...rest }: SheetHeadProps): import("react").JSX.Element;

package/dist/sheets/SheetHead.js

@@ -1,6 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cx } from '../cx.js';
-/** SheetHead — the stage sheet's three-column head: round button · centred title + sub · round button. A step sheet uses a CardHead instead. */
-export function SheetHead({ lead, title, sub, trail, long, className, ...rest }) {
-    return (_jsxs("div", { className: cx('sheet__head', className), ...rest, children: [lead ?? _jsx("span", {}), _jsxs("div", { children: [_jsx("h2", { className: cx('sheet__title', long && 'is-long'), children: title }), sub != null && _jsx("span", { className: "sheet__sub", children: sub })] }), trail ?? _jsx("span", {})] }));
-}