@ethlete/core 5.0.0-next.60 → 5.0.0-next.62

package/generators/tailwind-4-color-theme/generator.js

@@ -1,15 +1,12 @@
 import { formatFiles, logger, visitNotIgnoredFiles } from '@nx/devkit';
+import { posix } from 'path';
 import { Project, SyntaxKind } from 'ts-morph';
 export default async function generate(tree, schema) {
     logger.log('\n🔄 Starting Tailwind 4 theme generator...\n');
     const themesPath = schema.themesPath || 'src/themes.ts';
     const outputPath = schema.outputPath || 'src/styles/generated-tailwind-themes.css';
     const prefix = schema.prefix || 'et';
-    // The runtime prefix drives the theme-swap CSS variables (--<runtimePrefix>-color-primary)
-    // and selectors (.<runtimePrefix>-color--<name>). It defaults to `prefix` so existing
-    // consumers who only ever passed one prefix see no change in output.
     const runtimePrefix = schema.runtimePrefix || prefix;
-    // Step 1: Check if themes file exists
     if (!tree.exists(themesPath)) {
         logger.error(`❌ Themes file not found at: ${themesPath}`);
         logger.log(`\nPlease specify the correct path using --themesPath option.`);
@@ -17,16 +14,14 @@ export default async function generate(tree, schema) {
         return;
     }
     logger.log(`📁 Reading themes from: ${themesPath}`);
-    // Step 2: Read and parse themes file
     const themesContent = tree.read(themesPath, 'utf-8');
     if (!themesContent) {
         logger.error('❌ Failed to read themes file');
         return;
     }
-    // Step 3: Try to extract themes using TypeScript
     let themes;
     try {
-        themes = extractThemesFromContent(themesContent, themesPath);
+        themes = extractThemesFromContent(tree, themesContent, themesPath);
         logger.log(`✅ Found ${themes.length} theme(s)`);
     }
     catch (error) {
@@ -36,7 +31,7 @@ export default async function generate(tree, schema) {
         logger.log('  export const THEMES = [...] satisfies Theme[];\n');
         return;
     }
-    // Step 4: Apply the generation-time default override, if any. The shared theme
+    // Apply the generation-time default override, if any. The shared theme
     // definitions may mark a default via isDefault, but in a monorepo each app picks its
     // own default at its generation invocation - the option wins over the definitions.
     if (schema.defaultTheme) {
@@ -50,7 +45,6 @@ export default async function generate(tree, schema) {
             return;
         }
     }
-    // Step 5: Validate theme configuration
     try {
         validateThemeConfiguration(themes);
     }
@@ -59,27 +53,24 @@ export default async function generate(tree, schema) {
         logger.error(`   ${error instanceof Error ? error.message : String(error)}`);
         return;
     }
-    // Step 6: Generate Tailwind CSS
     logger.log('\n🎨 Generating Tailwind theme CSS...');
     const css = generateTailwindThemeCss(themes, prefix, runtimePrefix, schema);
     const typesOutputPath = schema.typesOutputPath ?? outputPath.replace(/\.css$/, '.d.ts');
     if (typesOutputPath === outputPath) {
         throw new Error('A custom outputPath must end in .css or be paired with a distinct typesOutputPath.');
     }
-    // Step 7: Write the generated CSS file
     const outputDir = outputPath.substring(0, outputPath.lastIndexOf('/'));
     if (outputDir && !tree.exists(outputDir)) {
         logger.log(`📁 Creating directory: ${outputDir}`);
     }
     tree.write(outputPath, css);
     logger.log(`✅ Generated Tailwind themes at: ${outputPath}`);
-    // Step 8: Generate the `EthleteColorThemeNameRegistry` augmentation, so `etProvideColor`
+    // Generate the `EthleteColorThemeNameRegistry` augmentation, so `etProvideColor`
     // (and anything else that accepts a `RegisteredColorThemeName`) is checked/autocompleted
     // against this app's actual theme names, instead of a plain `string`.
     const typesDts = generateColorThemeNameTypes(themes, schema);
     tree.write(typesOutputPath, typesDts);
     logger.log(`✅ Generated color theme name types at: ${typesOutputPath}`);
-    // Step 9: Try to find and update main styles file
     const mainStylesFiles = findMainStylesFile(tree);
     if (mainStylesFiles.length > 0) {
         logger.log('\n📝 Found potential main styles files:');
@@ -92,26 +83,21 @@ export default async function generate(tree, schema) {
     }
     logger.log('\n✅ Generation completed successfully!\n');
 }
-//#endregion
-//#region Helper Functions
-function extractThemesFromContent(content, filePath) {
-    // Create an in-memory TypeScript project
+function extractThemesFromContent(tree, content, filePath) {
     const project = new Project({
         useInMemoryFileSystem: true,
         compilerOptions: {
-            target: 99, // ESNext
-            module: 99, // ESNext
+            target: 99,
+            module: 99,
         },
     });
-    // Add the source file
     const sourceFile = project.createSourceFile(filePath, content);
+    const context = { tree, project };
     const themes = [];
-    // Find all exported const declarations
     const exportedDeclarations = sourceFile.getVariableDeclarations().filter((decl) => {
         const statement = decl.getVariableStatement();
         return statement?.isExported();
     });
-    // Look for the THEMES or themes array
     const themesArray = exportedDeclarations.find((decl) => {
         const name = decl.getName();
         return name === 'THEMES' || name === 'themes';
@@ -131,7 +117,6 @@ function extractThemesFromContent(content, filePath) {
     if (!initializer.isKind(SyntaxKind.ArrayLiteralExpression)) {
         throw new Error('THEMES export must be an array literal');
     }
-    // Get the array elements (these are references to the theme const declarations)
     const elements = initializer.getElements();
     for (const element of elements) {
         let themeObj;
@@ -160,7 +145,7 @@ function extractThemesFromContent(content, filePath) {
             continue;
         }
         try {
-            const theme = parseThemeObject(themeObj, sourceFile);
+            const theme = parseThemeObject(themeObj, sourceFile, context);
             themes.push(theme);
         }
         catch (error) {
@@ -172,7 +157,7 @@ function extractThemesFromContent(content, filePath) {
     }
     return themes;
 }
-function parseThemeObject(obj, sourceFile) {
+function parseThemeObject(obj, sourceFile, context) {
     const properties = obj.getProperties();
     const theme = {};
     for (const prop of properties) {
@@ -204,7 +189,7 @@ function parseThemeObject(obj, sourceFile) {
             case 'secondary':
             case 'tertiary':
                 if (initializer.isKind(SyntaxKind.ObjectLiteralExpression)) {
-                    theme[propName] = parseThemeSwatch(initializer, sourceFile);
+                    theme[propName] = parseThemeSwatch(initializer, sourceFile, context);
                 }
                 break;
         }
@@ -214,8 +199,6 @@ function parseThemeObject(obj, sourceFile) {
     }
     return theme;
 }
-// Makes the named theme the sole default, overriding any isDefault flags in the theme
-// definitions. Matches the theme's name or its CSS-safe form. Returns the resolved name.
 function applyDefaultThemeOverride(themes, defaultTheme) {
     const wanted = createCssThemeName(defaultTheme);
     const target = themes.find((t) => t.name === defaultTheme || createCssThemeName(t.name) === wanted);
@@ -229,15 +212,12 @@ function applyDefaultThemeOverride(themes, defaultTheme) {
 }
 function validateThemeConfiguration(themes) {
     const defaultThemes = themes.filter((t) => t.isDefault);
-    // Error: No default theme
     if (defaultThemes.length === 0) {
         throw new Error('No default theme found. At least one theme must have isDefault: true');
     }
-    // Error: Multiple default themes
     if (defaultThemes.length > 1) {
         throw new Error(`Multiple default themes found: ${defaultThemes.map((t) => t.name).join(', ')}. Only one theme can have isDefault: true`);
     }
-    // Error: Duplicate theme types
     const typeMap = new Map();
     for (const theme of themes) {
         if (!theme.type) {
@@ -253,7 +233,7 @@ function validateThemeConfiguration(themes) {
         }
     }
 }
-function parseThemeSwatch(obj, sourceFile) {
+function parseThemeSwatch(obj, sourceFile, context) {
     const properties = obj.getProperties();
     const swatch = {};
     for (const prop of properties) {
@@ -265,7 +245,7 @@ function parseThemeSwatch(obj, sourceFile) {
         if (!initializer) {
             continue;
         }
-        const colorMap = parseColorMap(initializer, sourceFile);
+        const colorMap = parseColorMap(initializer, sourceFile, context);
         if (!colorMap) {
             continue;
         }
@@ -286,13 +266,58 @@ function parseThemeSwatch(obj, sourceFile) {
 }
 const COLOR_MAP_KEYS = ['default', 'hover', 'focus', 'active', 'disabled'];
 const isColorMapKey = (name) => COLOR_MAP_KEYS.some((key) => key === name);
-function parseColorMap(initializer, sourceFile) {
+function unwrapTypeExpressions(expression) {
+    let current = expression;
+    while (current?.isKind(SyntaxKind.AsExpression) || current?.isKind(SyntaxKind.SatisfiesExpression)) {
+        current = current.getExpression();
+    }
+    return current;
+}
+function resolveConstInitializer(name, sourceFile, context) {
+    const local = sourceFile.getVariableDeclarations().find((decl) => decl.getName() === name);
+    if (local) {
+        const initializer = unwrapTypeExpressions(local.getInitializer());
+        return initializer ? { initializer, sourceFile } : null;
+    }
+    const importDecl = sourceFile
+        .getImportDeclarations()
+        .find((decl) => decl.getNamedImports().some((named) => (named.getAliasNode()?.getText() ?? named.getName()) === name));
+    if (!importDecl) {
+        return null;
+    }
+    const specifier = importDecl.getModuleSpecifierValue();
+    const filePath = sourceFile.getFilePath();
+    const importedName = importDecl
+        .getNamedImports()
+        .find((named) => (named.getAliasNode()?.getText() ?? named.getName()) === name)
+        ?.getName() ?? name;
+    const warnUnresolved = (reason) => logger.warn(`⚠️  Could not resolve "${name}" imported from "${specifier}" in ${filePath} (${reason}); it is ignored.`);
+    if (!specifier.startsWith('.')) {
+        warnUnresolved('package imports are not followed');
+        return null;
+    }
+    const base = posix.join(posix.dirname(filePath), specifier).replace(/^\//, '');
+    const candidates = [`${base}.ts`, posix.join(base, 'index.ts'), base];
+    const resolvedPath = candidates.find((candidate) => context.tree.isFile(candidate));
+    if (!resolvedPath) {
+        warnUnresolved('file not found in the workspace');
+        return null;
+    }
+    const importedFile = context.project.getSourceFile(resolvedPath) ??
+        context.project.createSourceFile(resolvedPath, context.tree.read(resolvedPath, 'utf-8') ?? '');
+    const declaration = importedFile.getVariableDeclarations().find((decl) => decl.getName() === importedName);
+    const initializer = unwrapTypeExpressions(declaration?.getInitializer());
+    if (!initializer?.isKind(SyntaxKind.ObjectLiteralExpression)) {
+        warnUnresolved(`not an object literal in ${resolvedPath}`);
+        return null;
+    }
+    return { initializer, sourceFile: importedFile };
+}
+function parseColorMap(initializer, sourceFile, context) {
     if (initializer.isKind(SyntaxKind.Identifier)) {
-        const declaration = sourceFile.getVariableDeclarations().find((decl) => decl.getName() === initializer.getText());
-        const referencedInitializer = declaration?.getInitializer();
-        return referencedInitializer ? parseColorMap(referencedInitializer, sourceFile) : null;
+        const resolved = resolveConstInitializer(initializer.getText(), sourceFile, context);
+        return resolved ? parseColorMap(resolved.initializer, resolved.sourceFile, context) : null;
     }
-    // Handle spread expressions by resolving references
     if (initializer.isKind(SyntaxKind.ObjectLiteralExpression)) {
         const colorMap = {};
         const properties = initializer.getProperties();
@@ -305,30 +330,22 @@ function parseColorMap(initializer, sourceFile) {
                 }
             }
             else if (prop.isKind(SyntaxKind.SpreadAssignment)) {
-                // Handle spread: { ...onColorDark, disabled: '...' }
                 const spreadExpr = prop.getExpression();
                 if (spreadExpr.isKind(SyntaxKind.Identifier)) {
-                    const referencedName = spreadExpr.getText();
-                    const referencedDecl = sourceFile.getVariableDeclarations().find((decl) => decl.getName() === referencedName);
-                    if (referencedDecl) {
-                        const referencedObj = referencedDecl.getInitializer();
-                        if (referencedObj?.isKind(SyntaxKind.ObjectLiteralExpression)) {
-                            const spreadColors = parseColorMap(referencedObj, sourceFile);
-                            if (spreadColors) {
-                                Object.assign(colorMap, spreadColors);
-                            }
-                        }
+                    const resolved = resolveConstInitializer(spreadExpr.getText(), sourceFile, context);
+                    if (resolved) {
+                        Object.assign(colorMap, parseColorMap(resolved.initializer, resolved.sourceFile, context));
                     }
                 }
+                else {
+                    logger.warn(`⚠️  Unsupported spread "...${spreadExpr.getText()}" in ${sourceFile.getFilePath()}; it is ignored.`);
+                }
             }
         }
-        // Apply fallbacks for required fields
         const defaultColor = colorMap.default;
         if (defaultColor) {
-            // Check if this is a ThemeColorMap (has hover, active, or disabled explicitly set)
             const isThemeColorMap = colorMap.hover !== undefined || colorMap.active !== undefined || colorMap.disabled !== undefined;
             if (isThemeColorMap) {
-                // For ThemeColorMap - apply fallbacks for all required fields
                 const hoverColor = colorMap.hover || defaultColor;
                 const result = {
                     default: defaultColor,
@@ -339,7 +356,6 @@ function parseColorMap(initializer, sourceFile) {
                 };
                 return result;
             }
-            // For OnThemeColorMap - no fallbacks needed, all fields are optional except default
             return colorMap;
         }
         return null;
@@ -347,7 +363,6 @@ function parseColorMap(initializer, sourceFile) {
     return null;
 }
 function createCssThemeName(name) {
-    // Convert theme name to CSS-safe format (e.g., "Primary Blue" -> "primary-blue")
     return name
         .toLowerCase()
         .replace(/\s+/g, '-')
@@ -390,31 +405,21 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
  */
 
 `;
-    // Validation is now done separately before this function is called
-    const defaultThemes = themes.filter((t) => t.isDefault);
-    const regularThemes = themes.filter((t) => !t.isDefault);
-    // Generate static Tailwind @theme block for each theme
     for (const theme of themes) {
         const name = createCssThemeName(theme.name);
-        // Add comment for theme section
         tailwindVars.push(`  /* ${theme.name} theme */`);
-        // Primary colors for Tailwind utilities
         addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}`, theme.primary.color);
         tailwindVars.push('');
-        // On colors for Tailwind utilities
         addTailwindColorVariants(tailwindVars, `${utilityPrefix}-on-${name}`, theme.primary.onColor);
         tailwindVars.push('');
-        // Ink colors for standalone foreground usage
         addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-ink`, theme.primary.inkColor || theme.primary.color);
         tailwindVars.push('');
-        // Secondary colors if present
         if (theme.secondary) {
             addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-secondary`, theme.secondary.color);
             tailwindVars.push('');
             addTailwindColorVariants(tailwindVars, `${utilityPrefix}-on-${name}-secondary`, theme.secondary.onColor);
             tailwindVars.push('');
         }
-        // Tertiary colors if present
         if (theme.tertiary) {
             addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-tertiary`, theme.tertiary.color);
             tailwindVars.push('');
@@ -423,10 +428,8 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
         }
     }
     tailwindVars.push('');
-    // Main theme dynamic colors
-    const mainThemes = [...defaultThemes, ...regularThemes];
-    const hasSecondary = mainThemes.some((t) => t.secondary);
-    const hasTertiary = mainThemes.some((t) => t.tertiary);
+    const hasSecondary = themes.some((t) => t.secondary);
+    const hasTertiary = themes.some((t) => t.tertiary);
     // Collect the dynamic theme colors once. They are emitted in `@theme` (so Tailwind generates
     // the utilities) and ALSO re-declared on every color selector in the alias block below. A
     // Tailwind `@theme` variable only lands on `:root`, so `rgb(var(--<runtime>-color-*))` resolves
@@ -444,19 +447,14 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
     }
     tailwindVars.push('  /* Dynamic theme colors (references runtime CSS variables) */');
     tailwindVars.push(...dynamicColorVars);
-    // Generate runtime CSS for all themes
     themes.forEach((theme) => {
         const name = createCssThemeName(theme.name);
-        // Determine if this is the default theme
         const isDefault = theme.isDefault;
-        // Generate color variant (.<runtimePrefix>-color--{name})
         if (isDefault) {
-            // Default color gets :root and .<runtimePrefix>-color--default selectors
             const selectors = [':root', `.${runtimePrefix}-color--default`, `.${runtimePrefix}-color--${name}`];
             themeVars.push(`${selectors.join(', ')} {`);
         }
         else {
-            // Regular colors just get their own class
             themeVars.push(`.${runtimePrefix}-color--${name} {`);
         }
         addThemeColorVariants(themeVars, runtimePrefix, '', theme);
@@ -468,7 +466,6 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
     while (dynamicColorAliasLines.length && dynamicColorAliasLines[dynamicColorAliasLines.length - 1] === '') {
         dynamicColorAliasLines.pop();
     }
-    // Convenience var aliases - available on any element with a color class (or root for default)
     const aliasBlock = `/* Convenience aliases (rgb + solid + opacity variants) */
 @layer base {
   :root, :where([class*="${runtimePrefix}-color--"]) {
@@ -508,14 +505,12 @@ function addDynamicThemeColors(vars, utilityPrefix, runtimePrefix, tailwindName,
     if (addSpacingBefore && vars.length > 0 && vars[vars.length - 1] !== '') {
         vars.push('');
     }
-    // Color variants
     vars.push(`  --color-${utilityPrefix}-${tailwindName}: rgb(var(--${runtimePrefix}-color-${cssVarName}));`);
     vars.push(`  --color-${utilityPrefix}-${tailwindName}-hover: rgb(var(--${runtimePrefix}-color-${cssVarName}-hover));`);
     vars.push(`  --color-${utilityPrefix}-${tailwindName}-focus: rgb(var(--${runtimePrefix}-color-${cssVarName}-focus));`);
     vars.push(`  --color-${utilityPrefix}-${tailwindName}-active: rgb(var(--${runtimePrefix}-color-${cssVarName}-active));`);
     vars.push(`  --color-${utilityPrefix}-${tailwindName}-disabled: rgb(var(--${runtimePrefix}-color-${cssVarName}-disabled));`);
     vars.push('');
-    // On-color variants
     vars.push(`  --color-${utilityPrefix}-on-${tailwindName}: rgb(var(--${runtimePrefix}-color-on-${cssVarName}));`);
     vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-hover: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-hover));`);
     vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-focus: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-focus));`);
@@ -532,25 +527,18 @@ function addDynamicInkColors(vars, utilityPrefix, runtimePrefix, tailwindName, c
     vars.push('');
 }
 function addTailwindColorVariants(vars, colorName, colorSet) {
-    // Tailwind 4 requires --color-* prefix and rgb() wrapper
-    // Always generate all variants with fallbacks
     vars.push(`  --color-${colorName}: rgb(${colorSet.default});`);
-    // For hover: use hover if exists, otherwise default
     const hoverValue = 'hover' in colorSet && colorSet.hover ? colorSet.hover : colorSet.default;
     vars.push(`  --color-${colorName}-hover: rgb(${hoverValue});`);
-    // For focus: use focus if exists, otherwise hover, otherwise default
     const focusValue = 'focus' in colorSet && colorSet.focus ? colorSet.focus : hoverValue;
     vars.push(`  --color-${colorName}-focus: rgb(${focusValue});`);
-    // For active: use active if exists, otherwise hover, otherwise default
     const activeValue = 'active' in colorSet && colorSet.active ? colorSet.active : hoverValue;
     vars.push(`  --color-${colorName}-active: rgb(${activeValue});`);
-    // For disabled: use disabled if exists, otherwise default
     const disabledValue = 'disabled' in colorSet && colorSet.disabled ? colorSet.disabled : colorSet.default;
     vars.push(`  --color-${colorName}-disabled: rgb(${disabledValue});`);
 }
 function addThemeColorVariants(vars, prefix, altPrefix, theme) {
     const addSwatch = (level, swatch) => {
-        // Color variants with fallbacks
         const defaultColor = swatch.color.default;
         const hoverColor = swatch.color.hover || defaultColor;
         const focusColor = swatch.color.focus || hoverColor;
@@ -562,7 +550,6 @@ function addThemeColorVariants(vars, prefix, altPrefix, theme) {
         vars.push(`  --${prefix}-color-${altPrefix}${level}-active: ${activeColor};`);
         vars.push(`  --${prefix}-color-${altPrefix}${level}-disabled: ${disabledColor};`);
         vars.push('');
-        // On color variants with fallbacks
         const onDefaultColor = swatch.onColor.default;
         const onHoverColor = swatch.onColor.hover || onDefaultColor;
         const onFocusColor = swatch.onColor.focus || onHoverColor;
@@ -605,4 +592,3 @@ function findMainStylesFile(tree) {
     });
     return potentialFiles;
 }
-//#endregion

package/migrations/legacy-color-themes.md

@@ -0,0 +1,38 @@
+# Move the runtime color theming to Tailwind 4
+
+`provideColorThemes()` injects the color theme CSS at runtime and pairs with a Tailwind 3 config built from
+`createTailwindColorThemes()`. It is deprecated: `@ethlete/components` expects
+`provideColorThemesWithTailwind4()`, the CSS the Tailwind 4 generators emit, and a set of surface themes.
+
+The theme data carries over unchanged. A codemod does the mechanical part; the rest is setup that depends
+on the app.
+
+## What to change
+
+1. Run the codemod:
+
+   ```bash
+   nx g @ethlete/core:migrate-legacy-color-themes
+   ```
+
+   It rewrites every `provideColorThemes(X)` imported from `@ethlete/core` into
+   `provideColorThemesWithTailwind4(X)`, fixes the import, and writes
+   `legacy-color-themes-migration-tasks.md` at the workspace root. Pass `--projects` or `--include` to
+   migrate one app at a time.
+
+2. Work through `legacy-color-themes-migration-tasks.md`. It lists, per call site, the
+   `tailwind-4-color-theme` generator run that replaces the runtime styles, every Tailwind 3 helper left
+   in a config, and - when no app provides any yet - the surface themes to build.
+
+3. Move the Tailwind 3 config to Tailwind 4, run both generators, and import the generated `.css` in each
+   app's global stylesheet. Keep the prefix the Tailwind 3 config used, so the utility names stay.
+
+4. Derive the first surface themes from the app's existing page background, text, muted text and border
+   colors. Ask the user before inventing colors the app does not have.
+
+5. Search the app's own CSS for `--et-color-alt-`. Those variables are not emitted any more; move the
+   region into its own `etProvideColor` scope and read `--et-color-primary` there.
+
+6. Build the app and compare a page against the old one: the colors must match.
+
+The guide is at <https://ethlete-sdk-docs.web.app/core/theming#migrating-from-runtime-theming>.

package/migrations/seo-directive-removed.md

@@ -9,7 +9,8 @@ function call. Both are decisions about the call site.
 
 ## What to change
 
-1. Find every component that injects `SeoDirective` or lists it in `hostDirectives` or `imports`.
+1. Find every component that injects `SeoDirective` or `SEO_DIRECTIVE_TOKEN`, or lists the directive in
+   `hostDirectives` or `imports`.
 2. Remove the directive from the component.
 3. Replace the `updateConfig({ … })` call with one `apply*Binding` call per key it set.
 4. Turn an Observable value into a signal: `toSignal()` at the edge of the component, or a

package/migrations.json

@@ -4,6 +4,7 @@
       "name": "to-v5",
       "version": "5.0.0-beta.11",
       "kind": "auto",
+      "level": "required",
       "description": "Rewrite the v4 core API into its v5 shape.",
       "generator": "@ethlete/core:migrate-to-v5"
     },
@@ -11,6 +12,7 @@
       "name": "provider-shape",
       "version": "5.0.0-next.37",
       "kind": "auto",
+      "level": "required",
       "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape.",
       "generator": "@ethlete/core:migrate-provider-shape",
       "docs": "/core/providers"
@@ -19,6 +21,7 @@
       "name": "seo-directive-removed",
       "version": "5.0.0-next.41",
       "kind": "assisted",
+      "level": "required",
       "description": "SeoDirective and SeoConfig are gone. Every call site moves to the apply*Binding function for its key.",
       "instructions": "./migrations/seo-directive-removed.md",
       "docs": "/core/seo"
@@ -27,6 +30,7 @@
       "name": "surface-interaction-swatch",
       "version": "5.0.0-next.46",
       "kind": "auto",
+      "level": "required",
       "description": "Rewrite surface theme interactionColor maps into the { color, onColor, inkColor } swatch shape.",
       "generator": "@ethlete/core:migrate-surface-interaction-swatch",
       "docs": "/core/theming"
@@ -35,9 +39,20 @@
       "name": "surface-theme-regenerate",
       "version": "5.0.0-next.46",
       "kind": "manual",
+      "level": "required",
       "description": "Regenerate the surface theme stylesheet, so the new swatch reaches the CSS variables.",
       "instructions": "./migrations/surface-theme-regenerate.md",
       "docs": "/core/theming"
+    },
+    {
+      "name": "legacy-color-themes",
+      "version": "5.0.0-next.62",
+      "kind": "assisted",
+      "level": "recommended",
+      "description": "Move the runtime color theming to Tailwind 4: provideColorThemes becomes provideColorThemesWithTailwind4, and the generated CSS and surface themes replace the runtime styles.",
+      "scan": "@ethlete/core:migrate-legacy-color-themes",
+      "instructions": "./migrations/legacy-color-themes.md",
+      "docs": "/core/theming#migrating-from-runtime-theming"
     }
   ]
 }

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@ethlete/core",
-  "version": "5.0.0-next.60",
+  "version": "5.0.0-next.62",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
-    "@angular/common": "22.1.6",
-    "@angular/core": "22.1.6",
-    "@angular/forms": "22.1.6",
-    "@angular/platform-browser": "22.1.6",
-    "@angular/router": "22.1.6",
+    "@angular/common": "^22.1.0",
+    "@angular/core": "^22.1.0",
+    "@angular/forms": "^22.1.0",
+    "@angular/platform-browser": "^22.1.0",
+    "@angular/router": "^22.1.0",
     "@ethlete/types": "^2.0.0-beta.4",
-    "@floating-ui/dom": "1.8.0",
-    "@nx/devkit": "23.1.0",
-    "rxjs": "7.8.2",
-    "ts-morph": "21.0.1",
-    "typescript": "6.0.3"
+    "@floating-ui/dom": "^1.6.0",
+    "@nx/devkit": "^23.0.0",
+    "rxjs": "^7.8.0",
+    "ts-morph": "^21.0.0",
+    "typescript": "^6.0.0"
   },
   "peerDependenciesMeta": {
     "@nx/devkit": {