@pantheon-systems/pds-toolkit-react 2.0.0-alpha.4 → 2.0.0-alpha.40

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

@@ -0,0 +1,6 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'css-class-removals';
+
+// CSS class removals apply to any element — no --only flag
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });

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

@@ -0,0 +1,6 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'css-class-renames';
+
+// CSS class renames apply to any element — no --only flag
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });

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

@@ -0,0 +1,15 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'icon-name-updates';
+
+// Unfiltered: updates iconName on all PDS components
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });
+
+// --only=Icon: updates only Icon's iconName; Button is untouched
+defineTest(
+	__dirname,
+	transform,
+	{ only: 'Icon' },
+	`${transform}/only`,
+	{ parser: 'tsx' },
+);

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

@@ -0,0 +1,15 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'prop-renames';
+
+// Unfiltered: renames all components' props
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });
+
+// --only=Button: renames only Button's props; Icon and others are untouched
+defineTest(
+	__dirname,
+	transform,
+	{ only: 'Button' },
+	`${transform}/only`,
+	{ parser: 'tsx' },
+);

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

@@ -0,0 +1,16 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'prop-value-standardization';
+const fixtures = `${__dirname}/../__testfixtures__/${transform}`;
+
+// Unfiltered: rewrites all components with size migration rules
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });
+
+// --only=Spinner: rewrites only Spinner; all other PDS components are untouched
+defineTest(
+	__dirname,
+	transform,
+	{ only: 'Spinner' },
+	`${transform}/only`,
+	{ parser: 'tsx' },
+);

package/codemods/v1-to-v2/transforms/__tests__/removed-prop-values.test.js

@@ -0,0 +1,15 @@
+const { defineTest } = require('jscodeshift/src/testUtils');
+
+const transform = 'removed-prop-values';
+
+// Unfiltered: applies all value rewrites and prop removals
+defineTest(__dirname, transform, null, `${transform}/basic`, { parser: 'tsx' });
+
+// --only=Button: transforms Button props only; Spinner is untouched
+defineTest(
+	__dirname,
+	transform,
+	{ only: 'Button' },
+	`${transform}/only`,
+	{ parser: 'tsx' },
+);

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

@@ -0,0 +1,166 @@
+/**
+ * Codemod: component-renames
+ *
+ * Renames PDS v1 components to their v2 names. Handles two import styles:
+ *
+ * 1. Root package imports (most common):
+ *    import { IndicatorBadge } from '@pantheon-systems/pds-toolkit-react'
+ *    → import { Badge } from '@pantheon-systems/pds-toolkit-react'
+ *    Driven by components.renames in mappings.json.
+ *
+ * 2. Deep path imports:
+ *    import { IndicatorBadge } from '@pantheon-systems/pds-toolkit-react/components/badges/IndicatorBadge/IndicatorBadge'
+ *    → import { Badge } from '@pantheon-systems/pds-toolkit-react/components/badges/Badge/Badge'
+ *    Driven by imports.pathChanges in mappings.json.
+ *
+ * In both cases, non-aliased imports also update every JSX tag in the file.
+ * Aliased imports preserve the local alias — only the imported name changes.
+ *
+ * Usage (all renames):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/component-renames.js \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * Usage (single component — recommended for by-component migrations):
+ *   npx jscodeshift -t codemods/v1-to-v2/transforms/component-renames.js \
+ *     --only=IndicatorBadge \
+ *     --extensions=tsx,ts,jsx,js \
+ *     src/
+ *
+ * --only accepts a comma-separated list of OLD (v1) component names.
+ */
+
+const path = require('path');
+const mappings = require(path.join(__dirname, '../mappings.json'));
+
+// Build lookup for root package imports: { 'OldName': 'NewName' }
+function buildRenamesLookup() {
+	const lookup = {};
+	for (const entry of mappings.components.renames) {
+		lookup[entry.from] = entry.to;
+	}
+	return lookup;
+}
+
+// Build list for deep path imports: [{ from, to, oldName, newName }]
+function buildPathChangesLookup() {
+	return mappings.imports.pathChanges.map((entry) => ({
+		from: entry.from,
+		to: entry.to,
+		oldName: entry.from.split('/').pop(),
+		newName: entry.component || entry.to.split('/').pop(),
+	}));
+}
+
+const ALL_RENAMES = buildRenamesLookup();
+const ALL_PATH_CHANGES = buildPathChangesLookup();
+
+module.exports = function transform(file, api, options) {
+	const j = api.jscodeshift;
+	const root = j(file.source);
+
+	// Parse --only flag: comma-separated OLD (v1) component names
+	const onlyComponents =
+		options && options.only
+			? new Set(
+					options.only
+						.split(',')
+						.map((s) => s.trim())
+						.filter(Boolean),
+				)
+			: null;
+
+	// Apply --only filter to both lookups
+	const renames = onlyComponents
+		? Object.fromEntries(
+				Object.entries(ALL_RENAMES).filter(([from]) =>
+					onlyComponents.has(from),
+				),
+			)
+		: ALL_RENAMES;
+
+	const pathChanges = onlyComponents
+		? ALL_PATH_CHANGES.filter((p) => onlyComponents.has(p.oldName))
+		: ALL_PATH_CHANGES;
+
+	if (Object.keys(renames).length === 0 && pathChanges.length === 0) return;
+
+	// Track non-aliased renames so JSX tags can be updated in Step 2.
+	const localRenameMap = new Map(); // oldLocalName → newLocalName
+
+	let changed = false;
+
+	// Step 1: Update import declarations
+	root.find(j.ImportDeclaration).forEach((nodePath) => {
+		const source = nodePath.node.source.value;
+
+		// 1a. Root package imports
+		if (source === '@pantheon-systems/pds-toolkit-react') {
+			nodePath.node.specifiers.forEach((spec) => {
+				if (spec.type !== 'ImportSpecifier') return;
+
+				const importedName = spec.imported.name;
+				const newName = renames[importedName];
+				if (!newName) return;
+
+				const isAliased = spec.local.name !== spec.imported.name;
+				spec.imported = j.identifier(newName);
+				changed = true;
+
+				if (!isAliased) {
+					spec.local = j.identifier(newName);
+					localRenameMap.set(importedName, newName);
+				}
+			});
+			return;
+		}
+
+		// 1b. Deep path imports
+		for (const { from, to, oldName, newName } of pathChanges) {
+			if (!source.includes(from)) continue;
+
+			nodePath.node.source = j.stringLiteral(source.replace(from, to));
+			changed = true;
+
+			nodePath.node.specifiers.forEach((spec) => {
+				if (spec.type !== 'ImportSpecifier') return;
+				if (spec.imported.name !== oldName) return;
+
+				const isAliased = spec.local.name !== spec.imported.name;
+				spec.imported = j.identifier(newName);
+
+				if (!isAliased) {
+					spec.local = j.identifier(newName);
+					localRenameMap.set(oldName, newName);
+				}
+			});
+
+			break; // a source string can only match one path change
+		}
+	});
+
+	if (!changed) return;
+
+	// Step 2: Rewrite JSX tags for non-aliased renames
+	if (localRenameMap.size > 0) {
+		root.find(j.JSXOpeningElement).forEach((nodePath) => {
+			const nameNode = nodePath.node.name;
+			if (nameNode.type !== 'JSXIdentifier') return;
+
+			const newName = localRenameMap.get(nameNode.name);
+			if (newName) nodePath.node.name = j.jsxIdentifier(newName);
+		});
+
+		root.find(j.JSXClosingElement).forEach((nodePath) => {
+			const nameNode = nodePath.node.name;
+			if (nameNode.type !== 'JSXIdentifier') return;
+
+			const newName = localRenameMap.get(nameNode.name);
+			if (newName) nodePath.node.name = j.jsxIdentifier(newName);
+		});
+	}
+
+	return root.toSource();
+};
+
+module.exports.parser = 'tsx';

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';