@pantheon-systems/pds-toolkit-react 2.0.0-alpha.7 → 2.0.0-alpha.71

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

@@ -0,0 +1,178 @@
+/**
+ * Codemod: css-class-renames
+ *
+ * Renames PDS CSS utility classes in JSX className attributes — and any
+ * other prop ending in "ClassName" (e.g. iconClassName, labelClassName),
+ * a common pattern for components with multiple styleable slots.
+ * 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}`}
+ *   - Ternaries / logical expressions, as a bare className expression or
+ *     nested inside a template literal's ${...} slot, as long as every
+ *     branch reached is itself a plain string literal:
+ *       className={isActive ? 'pds-overline-text' : 'other-class'}
+ *       className={`base ${isEmployee ? 'pds-color-bg-info' : 'pds-color-bg-default'}`}
+ *       className={isOpen && 'pds-overline-text'}
+ *   - Any other *ClassName prop, matched the same way as className:
+ *       iconClassName={isActive ? 'pds-overline-text' : 'other-class'}
+ *
+ * Does not handle:
+ *   - CSS/SCSS files — run a find-and-replace over those separately.
+ *   - Truly dynamic class names (a variable, function call, or any branch
+ *     of a ternary/logical expression that isn't itself a string literal).
+ *
+ * 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 };
+}
+
+// Recursively rename any string-literal branch reachable from `node` without
+// crossing into a non-literal value — i.e. it descends into ternaries
+// (ConditionalExpression) and logical expressions (&&/||), renaming each
+// branch that is itself a string literal, but leaves anything else (a
+// variable, a function call, a member expression, ...) untouched since its
+// value isn't knowable statically. Returns the (possibly replaced) node and
+// whether anything changed; does not mutate in place, so callers must
+// reassign the returned node back onto its parent.
+function renameStringLiteralBranches(node, j) {
+	if (!node) return { node, changed: false };
+
+	if (node.type === 'StringLiteral' || node.type === 'Literal') {
+		const { changed, result } = renameClasses(node.value);
+		return changed
+			? { node: j.stringLiteral(result), changed: true }
+			: { node, changed: false };
+	}
+
+	if (node.type === 'ConditionalExpression') {
+		const consequent = renameStringLiteralBranches(node.consequent, j);
+		const alternate = renameStringLiteralBranches(node.alternate, j);
+		if (consequent.changed) node.consequent = consequent.node;
+		if (alternate.changed) node.alternate = alternate.node;
+		return { node, changed: consequent.changed || alternate.changed };
+	}
+
+	if (node.type === 'LogicalExpression') {
+		const left = renameStringLiteralBranches(node.left, j);
+		const right = renameStringLiteralBranches(node.right, j);
+		if (left.changed) node.left = left.node;
+		if (right.changed) node.right = right.node;
+		return { node, changed: left.changed || right.changed };
+	}
+
+	return { node, changed: false };
+}
+
+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)
+		.filter((nodePath) => /className$/i.test(nodePath.node.name.name))
+		.forEach((nodePath) => {
+			const { value } = nodePath.node;
+			if (!value) return;
+
+			// className="pds-overline-text foo"
+			if (value.type === 'StringLiteral') {
+				const { changed: c, result } = 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 ${isActive ? 'a' : 'b'}`}
+			if (expression.type === 'TemplateLiteral') {
+				expression.quasis.forEach((quasi) => {
+					const { changed: c, result } = renameClasses(quasi.value.raw);
+					if (c) {
+						quasi.value.raw = result;
+						quasi.value.cooked = result;
+						changed = true;
+					}
+				});
+
+				expression.expressions.forEach((expr, index) => {
+					const { changed: c, node: renamed } = renameStringLiteralBranches(
+						expr,
+						j,
+					);
+					if (c) {
+						expression.expressions[index] = renamed;
+						changed = true;
+					}
+				});
+				return;
+			}
+
+			// className={'pds-overline-text'}
+			// className={isActive ? 'pds-overline-text' : 'other-class'}
+			// className={isOpen && 'pds-overline-text'}
+			const { changed: c, node: renamed } = renameStringLiteralBranches(
+				expression,
+				j,
+			);
+			if (c) {
+				value.expression = renamed;
+				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

@@ -0,0 +1,143 @@
+/**
+ * Codemod: prop-value-standardization
+ *
+ * Standardizes size-related prop values across PDS v1→v2.
+ * Driven entirely by props.typeChanges[].migration in mappings.json.
+ *
+ * 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');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Build lookup: { 'ComponentName.propName': { oldValue: newValue } }
+// Skips entries that are notes or no-ops.
+function buildMigrationLookup() {
+	const lookup = {};
+
+	for (const entry of mappings.props.typeChanges) {
+		const { component, prop, migration } = entry;
+		if (!migration || typeof migration !== 'object' || Array.isArray(migration))
+			continue;
+
+		const map = {};
+		for (const [from, to] of Object.entries(migration)) {
+			if (from === 'note') continue;
+			// Strip parenthetical notes e.g. "s (removed, use 's' instead)" → "s"
+			const cleanTo = to.split(' ')[0];
+			// Skip no-op entries where value is unchanged
+			if (cleanTo === from) continue;
+			map[from] = cleanTo;
+		}
+
+		if (Object.keys(map).length > 0) {
+			lookup[`${component}.${prop}`] = map;
+		}
+	}
+
+	return lookup;
+}
+
+const MIGRATION_LOOKUP = buildMigrationLookup();
+
+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();
+
+	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;
+		// Skip member expressions like <Foo.Bar />
+		if (nameNode.type !== 'JSXIdentifier') return;
+
+		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;
+
+			const propName = attr.name.name;
+			if (typeof propName !== 'string') return;
+
+			const map = MIGRATION_LOOKUP[`${exportedName}.${propName}`];
+			if (!map) return;
+
+			// size="sm"
+			if (attr.value.type === 'StringLiteral') {
+				const newValue = map[attr.value.value];
+				if (newValue) {
+					attr.value = j.stringLiteral(newValue);
+					changed = true;
+				}
+				return;
+			}
+
+			// size={"sm"}
+			if (
+				attr.value.type === 'JSXExpressionContainer' &&
+				attr.value.expression.type === 'StringLiteral'
+			) {
+				const newValue = map[attr.value.expression.value];
+				if (newValue) {
+					attr.value.expression = j.stringLiteral(newValue);
+					changed = true;
+				}
+			}
+		});
+	});
+
+	return changed ? root.toSource() : undefined;
+};
+
+module.exports.parser = 'tsx';