@pantheon-systems/pds-toolkit-react 2.0.0-alpha.37 → 2.0.0-alpha.39

package/codemods/v1-to-v2/transforms/css-class-removals.js

@@ -0,0 +1,192 @@
+/**
+ * Codemod: css-class-removals
+ *
+ * Handles removed PDS CSS utility classes in JSX className attributes.
+ * Driven entirely by cssClasses.removals in mappings.json.
+ *
+ * Three kinds of change:
+ *
+ * 1. Direct renames — replacement is another class name:
+ *    pds-button--navbar   → pds-button--subtle
+ *    pds-ts-9xl           → pds-ts-8xl
+ *    Replaced automatically.
+ *
+ * 2. Safe removals — replacement text says "no class needed":
+ *    pds-typography--product → removed (product context is now the default)
+ *    Removed automatically.
+ *
+ * 3. Flag only — replacement requires manual styling work with design tokens:
+ *    pds-color-bg-brand, pds-color-fg-brand, pds-lead-text*, pds-quote-text*
+ *    Left in place; a warning is printed so the developer can find and fix
+ *    these manually. Removing them silently would break visible styles with
+ *    no clear path forward.
+ *
+ * Usage:
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/css-class-removals.js \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * No --only flag — CSS utility classes apply to any element globally.
+ */
+
+const path = require('path');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Extract the first pds-* class name from a replacement string, if present.
+// Strips CSS custom property references (var(--pds-*)) first so that token
+// names mentioned in prose explanations aren't mistaken for class names.
+function extractReplacementClass(replacement) {
+	if (!replacement) return null;
+	const cleaned = replacement.replace(/var\(--[^)]+\)/g, '');
+	const match = cleaned.match(/\bpds-[a-z0-9-]+/);
+	return match ? match[0] : null;
+}
+
+// Classify each removal entry into one of three buckets.
+function buildLookups() {
+	// { oldClass: newClass } — rename automatically
+	const renames = {};
+	// Set of class names to remove unconditionally
+	const removals = new Set();
+	// Set of class names to flag with a warning (no safe auto-fix)
+	const flags = new Set();
+
+	for (const entry of mappings.cssClasses.removals) {
+		const { old: oldClass, replacement } = entry;
+		if (!oldClass) continue;
+
+		const replacementClass = extractReplacementClass(replacement);
+		if (replacementClass) {
+			renames[oldClass] = replacementClass;
+		} else if (
+			replacement &&
+			/no class needed|no replacement/i.test(replacement)
+		) {
+			removals.add(oldClass);
+		} else {
+			flags.add(oldClass);
+		}
+	}
+
+	return { renames, removals, flags };
+}
+
+const { renames: RENAMES, removals: REMOVALS, flags: FLAGS } = buildLookups();
+
+// Process a space-separated class string.
+// Returns { result, changed, flagged[] }
+function processClasses(classString, filePath) {
+	let changed = false;
+	const flagged = [];
+
+	const result = classString
+		.split(/(\s+)/)
+		.map((token) => {
+			if (/^\s+$/.test(token) || token === '') return token;
+
+			if (RENAMES[token]) {
+				changed = true;
+				return RENAMES[token];
+			}
+			if (REMOVALS.has(token)) {
+				changed = true;
+				return null; // will be filtered out
+			}
+			if (FLAGS.has(token)) {
+				flagged.push(token);
+			}
+			return token;
+		})
+		.filter((token) => token !== null)
+		.join('');
+
+	// Normalise any double-spaces left by removed tokens
+	const normalised = result.replace(/  +/g, ' ').trim();
+	const didChange = changed || normalised !== classString.trim();
+
+	return { result: normalised, changed: didChange, flagged };
+}
+
+module.exports = function transform(file, api) {
+	const j = api.jscodeshift;
+	const root = j(file.source);
+
+	const allFlagged = []; // { file, class } pairs for the summary warning
+	let changed = false;
+
+	root
+		.find(j.JSXAttribute, { name: { name: 'className' } })
+		.forEach((nodePath) => {
+			const { value } = nodePath.node;
+			if (!value) return;
+
+			// className="pds-button--navbar foo"
+			if (value.type === 'StringLiteral') {
+				const {
+					result,
+					changed: c,
+					flagged,
+				} = processClasses(value.value, file.path);
+				if (c) {
+					nodePath.node.value = j.stringLiteral(result);
+					changed = true;
+				}
+				flagged.forEach((cls) => allFlagged.push(cls));
+				return;
+			}
+
+			if (value.type !== 'JSXExpressionContainer') return;
+			const { expression } = value;
+
+			// className={'pds-button--navbar'}
+			if (expression.type === 'StringLiteral') {
+				const {
+					result,
+					changed: c,
+					flagged,
+				} = processClasses(expression.value, file.path);
+				if (c) {
+					value.expression = j.stringLiteral(result);
+					changed = true;
+				}
+				flagged.forEach((cls) => allFlagged.push(cls));
+				return;
+			}
+
+			// className={`pds-button--navbar ${x}`}
+			if (expression.type === 'TemplateLiteral') {
+				expression.quasis.forEach((quasi) => {
+					const {
+						result,
+						changed: c,
+						flagged,
+					} = processClasses(quasi.value.raw, file.path);
+					if (c) {
+						quasi.value.raw = result;
+						quasi.value.cooked = result;
+						changed = true;
+					}
+					flagged.forEach((cls) => allFlagged.push(cls));
+				});
+			}
+		});
+
+	// Emit warnings for classes that need manual attention
+	if (allFlagged.length > 0) {
+		const unique = [...new Set(allFlagged)];
+		process.stderr.write(
+			`\n⚠  ${file.path}\n` +
+				unique
+					.map(
+						(cls) =>
+							`   ${cls} — removed in v2, no direct replacement. See migration guide.`,
+					)
+					.join('\n') +
+				'\n',
+		);
+	}
+
+	return changed ? root.toSource() : undefined;
+};
+
+module.exports.parser = 'tsx';

package/codemods/v1-to-v2/transforms/css-class-renames.js

@@ -0,0 +1,114 @@
+/**
+ * Codemod: css-class-renames
+ *
+ * Renames PDS CSS utility classes in JSX className attributes.
+ * Driven entirely by cssClasses.renames in mappings.json.
+ *
+ * Usage:
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/css-class-renames.js \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Handles:
+ *   - String literals:       className="pds-overline-text foo"
+ *   - Expression containers: className={'pds-overline-text'}
+ *   - Template literals:     className={`pds-overline-text ${styles.x}`}
+ *
+ * Does not handle:
+ *   - CSS/SCSS files — run a find-and-replace over those separately.
+ *   - Dynamic class names built at runtime (e.g. computed from variables).
+ *
+ * No --only flag: CSS utility classes can appear on any element (including
+ * native HTML), so there is no meaningful component-level scope to filter by.
+ * This transform is safe to run globally.
+ */
+
+const path = require('path');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Build lookup: { 'oldClass': 'newClass' }
+function buildRenamesLookup() {
+	const lookup = {};
+	for (const entry of mappings.cssClasses.renames) {
+		if (entry.old && entry.new) lookup[entry.old] = entry.new;
+	}
+	return lookup;
+}
+
+const RENAMES = buildRenamesLookup();
+
+// Replace class names in a space-separated class string.
+// Splits on whitespace and does exact token matching, so 'pds-overline-text'
+// won't incorrectly mangle 'pds-overline-text--sm'.
+function renameClasses(classString) {
+	let changed = false;
+	const result = classString
+		.split(/(\s+)/)
+		.map((token) => {
+			// Preserve whitespace tokens unchanged
+			if (/^\s+$/.test(token) || token === '') return token;
+			const renamed = RENAMES[token];
+			if (renamed) {
+				changed = true;
+				return renamed;
+			}
+			return token;
+		})
+		.join('');
+	return { result, changed };
+}
+
+module.exports = function transform(file, api) {
+	const j = api.jscodeshift;
+	const root = j(file.source);
+
+	if (Object.keys(RENAMES).length === 0) return;
+
+	let changed = false;
+
+	root
+		.find(j.JSXAttribute, { name: { name: 'className' } })
+		.forEach((nodePath) => {
+			const { value } = nodePath.node;
+			if (!value) return;
+
+			// className="pds-overline-text foo"
+			if (value.type === 'StringLiteral') {
+				const { result, changed: c } = renameClasses(value.value);
+				if (c) {
+					nodePath.node.value = j.stringLiteral(result);
+					changed = true;
+				}
+				return;
+			}
+
+			if (value.type !== 'JSXExpressionContainer') return;
+			const { expression } = value;
+
+			// className={'pds-overline-text'}
+			if (expression.type === 'StringLiteral') {
+				const { result, changed: c } = renameClasses(expression.value);
+				if (c) {
+					value.expression = j.stringLiteral(result);
+					changed = true;
+				}
+				return;
+			}
+
+			// className={`pds-overline-text ${styles.x}`}
+			if (expression.type === 'TemplateLiteral') {
+				expression.quasis.forEach((quasi) => {
+					const { result, changed: c } = renameClasses(quasi.value.raw);
+					if (c) {
+						quasi.value.raw = result;
+						quasi.value.cooked = result;
+						changed = true;
+					}
+				});
+			}
+		});
+
+	return changed ? root.toSource() : undefined;
+};
+
+module.exports.parser = 'tsx';

package/codemods/v1-to-v2/transforms/icon-name-updates.js

@@ -0,0 +1,124 @@
+/**
+ * Codemod: icon-name-updates
+ *
+ * Rewrites removed icon names to their v2 equivalents on any PDS component
+ * that accepts an `iconName` prop.
+ *
+ * The icon registry is shared across all components, so any component using
+ * a renamed icon name (e.g. Button, ButtonLink, IconButton, Alert, etc.)
+ * needs updating — not just the Icon component itself.
+ *
+ * Driven by props.typeChanges[prop=iconName].migration in mappings.json.
+ *
+ * Usage (all components):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/icon-name-updates.js \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Usage (single component — recommended for by-component migrations):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/icon-name-updates.js \
+ *     --only=Button \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Limitations:
+ *   - Only static string literals and JSX expression containers are
+ *     transformed. Dynamic values (variables, expressions) are left as-is
+ *     and need manual review.
+ */
+
+const path = require('path');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Build a flat map of oldIconName → newIconName from all iconName typeChanges
+function buildIconNameMap() {
+	const map = {};
+	for (const entry of mappings.props.typeChanges) {
+		if (entry.prop !== 'iconName' || !entry.migration) continue;
+		for (const [from, to] of Object.entries(entry.migration)) {
+			if (from === 'note') continue;
+			const cleanTo = to.split(' ')[0];
+			if (cleanTo !== from) map[from] = cleanTo;
+		}
+	}
+	return map;
+}
+
+const ICON_NAME_MAP = buildIconNameMap();
+
+module.exports = function transform(file, api, options) {
+	const j = api.jscodeshift;
+	const root = j(file.source);
+
+	if (Object.keys(ICON_NAME_MAP).length === 0) return;
+
+	// Parse --only flag: comma-separated component names
+	const onlyComponents =
+		options && options.only
+			? new Set(
+					options.only
+						.split(',')
+						.map((s) => s.trim())
+						.filter(Boolean),
+				)
+			: null;
+
+	// Map local import name → exported component name
+	const localToExported = new Map();
+
+	root.find(j.ImportDeclaration).forEach((nodePath) => {
+		if (nodePath.node.source.value !== '@pantheon-systems/pds-toolkit-react')
+			return;
+		nodePath.node.specifiers.forEach((spec) => {
+			if (spec.type === 'ImportSpecifier') {
+				localToExported.set(spec.local.name, spec.imported.name);
+			}
+		});
+	});
+
+	if (localToExported.size === 0) return;
+
+	let changed = false;
+
+	root.find(j.JSXOpeningElement).forEach((nodePath) => {
+		const nameNode = nodePath.node.name;
+		if (nameNode.type !== 'JSXIdentifier') return;
+
+		const exportedName = localToExported.get(nameNode.name);
+		if (!exportedName) return;
+
+		if (onlyComponents && !onlyComponents.has(exportedName)) return;
+
+		nodePath.node.attributes.forEach((attr) => {
+			if (attr.type !== 'JSXAttribute') return;
+			if (attr.name.name !== 'iconName') return;
+			if (!attr.value) return;
+
+			// iconName="circlePlusOutline"
+			if (attr.value.type === 'StringLiteral') {
+				const newName = ICON_NAME_MAP[attr.value.value];
+				if (newName) {
+					attr.value = j.stringLiteral(newName);
+					changed = true;
+				}
+				return;
+			}
+
+			// iconName={"circlePlusOutline"}
+			if (
+				attr.value.type === 'JSXExpressionContainer' &&
+				attr.value.expression.type === 'StringLiteral'
+			) {
+				const newName = ICON_NAME_MAP[attr.value.expression.value];
+				if (newName) {
+					attr.value.expression = j.stringLiteral(newName);
+					changed = true;
+				}
+			}
+		});
+	});
+
+	return changed ? root.toSource() : undefined;
+};
+
+module.exports.parser = 'tsx';

package/codemods/v1-to-v2/transforms/prop-renames.js

@@ -0,0 +1,109 @@
+/**
+ * Codemod: prop-renames
+ *
+ * Renames PDS v1 prop names to their v2 names on JSX elements.
+ * Driven entirely by props.renames in mappings.json.
+ *
+ * Usage (all renames):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-renames.js \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Usage (single component — recommended for by-component migrations):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-renames.js \
+ *     --only=Button \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Usage (multiple components):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-renames.js \
+ *     --only=Button,Icon \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * --only accepts a comma-separated list of component names.
+ *
+ * Limitations:
+ *   - Renames where `from` is a nested path (e.g. `options[].description`)
+ *     cannot be transformed at the JSX attribute level and are skipped.
+ *     These require manual review.
+ */
+
+const path = require('path');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Build lookup: { 'ComponentName.oldPropName': 'newPropName' }
+// Skips entries where `from` is a nested path (contains '.' or '[]').
+function buildRenamesLookup() {
+	const lookup = {};
+	for (const entry of mappings.props.renames) {
+		const { component, from, to } = entry;
+		if (!component || !from || !to) continue;
+		// Skip nested paths — these can't be transformed at the attribute level
+		if (from.includes('.') || from.includes('[')) continue;
+		lookup[`${component}.${from}`] = to;
+	}
+	return lookup;
+}
+
+const ALL_RENAMES = buildRenamesLookup();
+
+module.exports = function transform(file, api, options) {
+	const j = api.jscodeshift;
+	const root = j(file.source);
+
+	// Parse --only flag: comma-separated component names
+	const onlyComponents =
+		options && options.only
+			? new Set(
+					options.only
+						.split(',')
+						.map((s) => s.trim())
+						.filter(Boolean),
+				)
+			: null;
+
+	// Map local import name → exported component name
+	const localToExported = new Map();
+
+	root.find(j.ImportDeclaration).forEach((nodePath) => {
+		if (nodePath.node.source.value !== '@pantheon-systems/pds-toolkit-react')
+			return;
+		nodePath.node.specifiers.forEach((spec) => {
+			if (spec.type === 'ImportSpecifier') {
+				localToExported.set(spec.local.name, spec.imported.name);
+			}
+		});
+	});
+
+	if (localToExported.size === 0) return;
+
+	let changed = false;
+
+	root.find(j.JSXOpeningElement).forEach((nodePath) => {
+		const nameNode = nodePath.node.name;
+		if (nameNode.type !== 'JSXIdentifier') return;
+
+		const exportedName = localToExported.get(nameNode.name);
+		if (!exportedName) return;
+
+		if (onlyComponents && !onlyComponents.has(exportedName)) return;
+
+		nodePath.node.attributes.forEach((attr) => {
+			if (attr.type !== 'JSXAttribute') return;
+
+			const propName = attr.name.name;
+			if (typeof propName !== 'string') return;
+
+			const newPropName = ALL_RENAMES[`${exportedName}.${propName}`];
+			if (!newPropName) return;
+
+			attr.name = j.jsxIdentifier(newPropName);
+			changed = true;
+		});
+	});
+
+	return changed ? root.toSource() : undefined;
+};
+
+module.exports.parser = 'tsx';

package/codemods/v1-to-v2/transforms/prop-value-standardization.js

@@ -4,10 +4,26 @@
  * Standardizes size-related prop values across PDS v1→v2.
  * Driven entirely by props.typeChanges[].migration in mappings.json.
  *
- * Usage:
+ * Usage (all components):
  *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-value-standardization.js \
  *     --extensions=tsx,ts,jsx,js \
  *     src/
+ *
+ * Usage (single component — recommended for by-component migrations):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-value-standardization.js \
+ *     --only=Spinner \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Usage (multiple components):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/prop-value-standardization.js \
+ *     --only=Spinner,Avatar \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * --only accepts a comma-separated list of exported component names. When
+ * provided, only rules for those components are applied. This prevents the
+ * transform from rewriting size values on components that are still on V1.
  */
 
 const path = require('path');
@@ -43,10 +59,22 @@ function buildMigrationLookup() {
 
 const MIGRATION_LOOKUP = buildMigrationLookup();
 
-module.exports = function transform(file, api) {
+module.exports = function transform(file, api, options) {
 	const j = api.jscodeshift;
 	const root = j(file.source);
 
+	// Parse --only flag into a Set of component names for O(1) lookup.
+	// Accepts comma-separated values: --only=Spinner,Avatar
+	const onlyComponents =
+		options && options.only
+			? new Set(
+					options.only
+						.split(',')
+						.map((s) => s.trim())
+						.filter(Boolean),
+				)
+			: null;
+
 	// Map local import name → exported component name
 	// Handles aliased imports: import { Spinner as MySpinner } → { MySpinner: 'Spinner' }
 	const localToExported = new Map();
@@ -73,6 +101,9 @@ module.exports = function transform(file, api) {
 		const exportedName = localToExported.get(nameNode.name);
 		if (!exportedName) return;
 
+		// Skip this component if --only is set and it isn't in the list
+		if (onlyComponents && !onlyComponents.has(exportedName)) return;
+
 		nodePath.node.attributes.forEach((attr) => {
 			if (attr.type !== 'JSXAttribute' || !attr.value) return;