@usableapp/cardds 0.7.107 → 0.7.108

package/scripts/codemod-parts.mjs

@@ -1,9 +1,13 @@
-// 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
+// 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 (Lh 2026-10-21, the inner parts): 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.
+// on its screens after the release; the previews were migrated by it. It also moves the `Row` props 0.7.106 retired (`title`, `meta`, `lead`, `leadIcon`,
+// `body`, `end`, `endValue`, `endCaption`) into the line's children, which the 0.7.107 version left; a screen migrated with that version is checked again.
 //   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
+//   npx cardds codemod-parts --check <files…>     exit 1 naming every tag, prop, import and type that still writes a retired name
 // (in this repo also `node scripts/codemod-parts.mjs …`; it reads `typescript` from the project that runs it)
+// A part a tag now needs is imported once, on the file's value import (`import type { … }` only has its type names renamed, `CardFootProps` → `FootProps`).
+// A Card's `foot={cond ? x : undefined}` (or `: null`, or `cond && x`) keeps its condition, `{cond ? <Foot>{x}</Foot> : null}`, so no empty foot is drawn;
+// a `foot={value}` is written `<Foot>{value}</Foot>` as it is: the script cannot know whether `value` may be undefined, and the consumer reads that line.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
@@ -21,15 +25,28 @@ export const RENAMES = {
   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 */
+/** 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;
+ *  a `Row` keeps its own too, and the props that drew its line (ROW_PROPS) 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 },
+  Row: { line: 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'] };
+/** a Row's props of 0.7.105, each written as a child in this order (the 0.7.106 table): `lead` and `end` stand bare, the rest become a Lead, a Words, an End */
+const ROW_PROPS = {
+  lead: 'its lead as the first child', leadIcon: '<Lead icon /> first', title: '<Words title meta /> after the lead', meta: '<Words title meta /> after the lead',
+  body: '<Words title meta>…</Words> after the lead', endValue: '<End value caption /> after the words', endCaption: '<End value caption /> after the words', end: 'its end as the last child',
+};
+/** the new tag a retired tag is written as, or null */
+const retiredTo = (name) => (name in RENAMES ? RENAMES[name].to : RESHAPES[name]?.to ?? null);
+/** a retired tag's props type → the part's (`CardFootProps` → `FootProps`) */
+const TYPE_RENAMES = Object.fromEntries(Object.keys({ ...RENAMES, ...RESHAPES }).filter(retiredTo).map((n) => [`${n}Props`, `${retiredTo(n)}Props`]));
+/** the parts a reshape writes, imported where the file's tags now need them */
+const PARTS = ['Head', 'Words', 'Foot', 'Lead', 'End'];
 const LINE = 140;
 
 const parse = (source, file) => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
@@ -50,6 +67,7 @@ const fits = (rule, el) => {
 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));
+const rowProps = (opening) => Object.keys(ROW_PROPS).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') {
@@ -57,12 +75,14 @@ export function check(source, file = 'x.tsx') {
   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 && retiredTo(name) && !ts.isJsxClosingElement(n)) out.push({ line: line(sf, n), name, write: retiredTo(name) });
     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' });
     }
+    if (name === 'Row' && (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n))) {
+      for (const p of rowProps(n)) out.push({ line: line(sf, n), name: `Row ${p}`, write: ROW_PROPS[p] });
+    }
     ts.forEachChild(n, walk);
   };
   walk(sf);
@@ -76,8 +96,8 @@ export function check(source, file = 'x.tsx') {
     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' });
+      const to = retiredTo(name) ?? TYPE_RENAMES[name];
+      if (to) out.push({ line: line(sf, e), name: e.name.text, write: to });
     }
   }
   return out.sort((a, b) => a.line - b.line);
@@ -85,14 +105,18 @@ export function check(source, file = 'x.tsx') {
 
 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) {
+/** a prop's value, the expression or string it holds, or null when it has none (`<Card foot>`) */
+function exprOf(attr) {
   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)}}`;
+  return ts.isJsxExpression(init) ? init.expression ?? null : init;
+}
+/** an expression as a child: a JSX element stands as it is, anything else in braces */
+const asChild = (expr, sf) => (ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr) || ts.isJsxFragment(expr) ? expr.getText(sf) : `{${expr.getText(sf)}}`);
+/** a prop's value as a child, or null */
+function childOf(attr, sf) {
+  const expr = exprOf(attr);
+  return expr ? asChild(expr, sf) : null;
 }
 /** `parts` laid on one line when they fit, else one to a line under `indent` */
 function lay(open, parts, close, indent) {
@@ -120,6 +144,7 @@ function reshape(source, sf, el) {
   const opening = openingOf(el), name = tagName(opening);
   const rule = RESHAPES[name];
   if (!rule) return null;
+  if (rule.line) return rowOf(source, sf, el);
   const used = headProps(opening);
   if (name === 'CardHead' && !used.length && ts.isJsxSelfClosingElement(el) === false) {
     return { rename: true };
@@ -159,12 +184,19 @@ function moved(node, sf, text, to) {
   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];
+function footChildren(expr, sf, to) {
+  if (!expr) return [];
+  if (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));
+  return [ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr) ? moved(expr, sf, asChild(expr, sf), to) : asChild(expr, sf)];
+}
+/** a `foot` written under a condition, `cond ? x : undefined`, `cond ? x : null` or `cond && x`: the condition's text and `x`; a plain value has no `when` */
+function footCondition(expr, sf) {
+  if (!expr) return { shown: null };
+  if (ts.isConditionalExpression(expr) && (expr.whenFalse.kind === ts.SyntaxKind.NullKeyword || (ts.isIdentifier(expr.whenFalse) && expr.whenFalse.text === 'undefined'))) {
+    return { when: (foot) => `{${expr.condition.getText(sf)} ? ${foot} : null}`, shown: expr.whenTrue };
+  }
+  if (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) return { when: (foot) => `{${expr.left.getText(sf)} && ${foot}}`, shown: expr.right };
+  return { shown: expr };
 }
 /** 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) {
@@ -178,14 +210,42 @@ function footOf(source, sf, el) {
   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} />`;
+  const { when, shown } = footCondition(fa ? exprOf(fa) : null, sf);
+  const kids = footChildren(shown, sf, indent.length + 4);
+  const drawn = kids.length ? lay(`<Foot${attrs}>`, kids, '</Foot>', `${indent}  `) : `<Foot${attrs} />`;
+  const foot = when ? when(drawn) : drawn;
   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}` }] };
 }
 
+/** a Row that still draws its line with props, as an edit that drops them and writes the line's children in order: lead · words · its own children · end */
+function rowOf(source, sf, el) {
+  const opening = openingOf(el);
+  const used = rowProps(opening);
+  if (!used.length) return null;
+  const indent = lineIndent(source, opening.getStart(sf));
+  const at = (p) => findAttr(opening, p);
+  const attrs = (pairs) => pairs.filter(([from]) => at(from)).map(([from, to]) => ` ${to}=${valueOf(at(from), sf)}`).join('');
+  const words = attrs([['title', 'title'], ['meta', 'meta']]), body = at('body') ? childOf(at('body'), sf) : null;
+  const ends = attrs([['endValue', 'value'], ['endCaption', 'caption']]);
+  const front = [
+    at('leadIcon') && `<Lead icon=${valueOf(at('leadIcon'), sf)} />`,
+    at('lead') && childOf(at('lead'), sf),
+    (words || body) && (body ? `<Words${words}>${body}</Words>` : `<Words${words} />`),
+  ].filter(Boolean);
+  const back = [ends && `<End${ends} />`, at('end') && childOf(at('end'), sf)].filter(Boolean);
+  const rest = without(source, opening, used, sf).replace(/\s*\/>$/, '>').replace(/\s*\n\s*>$/, '>').replace(/^<Row\s+>$/, '<Row>');
+  if (ts.isJsxSelfClosingElement(el)) return { pos: el.getStart(sf), end: el.end, text: lay(rest, [...front, ...back], '</Row>', indent) };
+  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(), ...back], '</Row>', indent) };
+  return { edits: [
+    { pos: opening.getStart(sf), end: opening.end, text: front.length ? `${rest}\n${indent}  ${front.join(`\n${indent}  `)}` : rest },
+    { pos: el.closingElement.getStart(sf), end: el.closingElement.getStart(sf), text: back.map((b) => `  ${b}\n${indent}`).join('') },
+  ] };
+}
+
 /** 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;
@@ -272,34 +332,53 @@ function importList(names, wrapped) {
   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 */
+/** the `cardds` imports after the tags changed: a retired name replaced by its new one in place, a part added to the value import where a tag now needs it,
+ *  a name no tag writes any more dropped; an `import type` only has its retired type names renamed, and a file with no value import gets one after it */
 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;
+  let imports = 0, values = 0, last = null;
+  const types = new Map();
+  const typeSpec = (e, name) => {
+    if (e.propertyName) return e.getText(sf);
+    if (TYPE_RENAMES[name]) types.set(name, TYPE_RENAMES[name]);
+    return `${e.isTypeOnly ? 'type ' : ''}${TYPE_RENAMES[name] ?? name}`;
+  };
   for (const imp of sf.statements.filter(ts.isImportDeclaration)) {
     const nb = imp.importClause?.namedBindings;
     if (imp.moduleSpecifier.text !== 'cardds' || !nb || !ts.isNamedImports(nb)) continue;
+    last = imp;
+    const typeOnly = !!imp.importClause.isTypeOnly;
     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 (typeOnly || e.isTypeOnly) { add(typeSpec(e, name)); continue; }
+      const retired = !e.propertyName && retiredTo(name) && !used.has(name);
       if (!retired) { add(e.getText(sf)); continue; }
-      const to = name in RENAMES ? RENAMES[name].to : 'Head';
+      const to = retiredTo(name);
       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 (!typeOnly) { values++; for (const part of PARTS) 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')) });
   }
+  if (types.size) {
+    const rename = (n) => { if (ts.isIdentifier(n) && types.has(n.text)) edits.push({ pos: n.getStart(sf), end: n.end, text: types.get(n.text) }); ts.forEachChild(n, rename); };
+    for (const st of sf.statements) if (!ts.isImportDeclaration(st)) rename(st);
+  }
+  const needed = PARTS.filter((part) => used.has(part));
+  if (last && !values && needed.length) {
+    imports++;
+    edits.push({ pos: last.end, end: last.end, text: `\nimport ${importList(needed, false)} from ${last.moduleSpecifier.getText(sf)}${source[last.end - 1] === ';' ? ';' : ''}` });
+  }
   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)) };
+  return { source: apply(source, edits), imports, clash: [...PARTS, 'Body'].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 */