@ethlete/core 5.0.0-next.44 → 5.0.0-next.46

package/generators/devtools-about/generator.js

@@ -0,0 +1,113 @@
+import { formatFiles, joinPathFragments, logger, readProjectConfiguration, updateProjectConfiguration, visitNotIgnoredFiles, } from '@nx/devkit';
+const SCRIPT_PATH = 'tools/generate-build-info.js';
+const SCRIPT = `const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const [, , outputPath, packageJsonPath] = process.argv;
+
+const read = (command) => {
+  try {
+    return execSync(command, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+};
+
+const version = fs.existsSync(packageJsonPath)
+  ? JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8')).version
+  : null;
+
+const info = {
+  version: version ?? 'unknown',
+  sha: read('git rev-parse --short HEAD') ?? 'unknown',
+  branch: read('git rev-parse --abbrev-ref HEAD') ?? 'unknown',
+  builtAt: new Date().toISOString(),
+};
+
+const contents =
+  '// Generated by ' +
+  ${JSON.stringify(SCRIPT_PATH)} +
+  ' - do not edit.\\n\\nexport const APP_BUILD_INFO = ' +
+  JSON.stringify(info, null, 2) +
+  ' as const;\\n';
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, contents);
+`;
+const PLACEHOLDER = `// Generated by ${SCRIPT_PATH} - do not edit.
+
+export const APP_BUILD_INFO = {
+  version: 'unknown',
+  sha: 'unknown',
+  branch: 'unknown',
+  builtAt: '1970-01-01T00:00:00.000Z',
+} as const;
+`;
+const relativeImport = (from, to) => {
+    const fromParts = from.split('/').slice(0, -1);
+    const toParts = to.replace(/\.ts$/, '').split('/');
+    while (fromParts.length && toParts.length && fromParts[0] === toParts[0]) {
+        fromParts.shift();
+        toParts.shift();
+    }
+    const up = fromParts.length ? fromParts.map(() => '..') : ['.'];
+    return [...up, ...toParts].join('/');
+};
+/** Wires the `provideQueryDevtools({ about })` call up to the generated constant, if it can be found. */
+const wireProvider = (tree, projectRoot, outputPath) => {
+    let wired = false;
+    visitNotIgnoredFiles(tree, projectRoot, (file) => {
+        if (wired || !file.endsWith('.ts'))
+            return;
+        const contents = tree.read(file, 'utf-8');
+        if (!contents?.includes('provideQueryDevtools('))
+            return;
+        if (!contents.includes('provideQueryDevtools()')) {
+            logger.warn(`${file} already passes options to provideQueryDevtools() - add \`about: APP_BUILD_INFO\` to them yourself.`);
+            wired = true;
+            return;
+        }
+        const importPath = relativeImport(file, outputPath);
+        tree.write(file, `import { APP_BUILD_INFO } from '${importPath}';\n` +
+            contents.replace('provideQueryDevtools()', 'provideQueryDevtools({ about: APP_BUILD_INFO })'));
+        wired = true;
+    });
+    return wired;
+};
+export const devtoolsAboutGenerator = async (tree, options) => {
+    const project = readProjectConfiguration(tree, options.project);
+    const outputPath = options.outputPath ?? joinPathFragments(project.sourceRoot ?? project.root, 'build-info.ts');
+    if (!tree.exists(SCRIPT_PATH))
+        tree.write(SCRIPT_PATH, SCRIPT);
+    if (!tree.exists(outputPath))
+        tree.write(outputPath, PLACEHOLDER);
+    const gitignore = tree.read('.gitignore', 'utf-8') ?? '';
+    // Regenerated on every build, and its SHA changes with every commit - committing it would put a
+    // one-line diff in every commit that says nothing about the change.
+    if (!gitignore.includes(outputPath))
+        tree.write('.gitignore', `${gitignore.trimEnd()}\n${outputPath}\n`);
+    project.targets ??= {};
+    project.targets['build-info'] = {
+        executor: 'nx:run-commands',
+        options: {
+            commands: [`node ${SCRIPT_PATH} ${outputPath} ${joinPathFragments(project.root, 'package.json')}`],
+        },
+    };
+    for (const target of ['build', 'serve']) {
+        const config = project.targets[target];
+        if (!config)
+            continue;
+        config.dependsOn ??= [];
+        if (!config.dependsOn.includes('build-info'))
+            config.dependsOn.push('build-info');
+    }
+    updateProjectConfiguration(tree, options.project, project);
+    if (!wireProvider(tree, project.root, outputPath)) {
+        logger.warn(`No provideQueryDevtools() call found in ${project.root} - pass \`about: APP_BUILD_INFO\` to it yourself.`);
+    }
+    if (!options.skipFormat)
+        await formatFiles(tree);
+};
+export default devtoolsAboutGenerator;
+//# sourceMappingURL=generator.js.map

package/generators/devtools-about/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "devtools-about",
+  "title": "Query devtools About generator",
+  "description": "Generates the application's build info (version, commit SHA, branch, build time) and wires it into provideQueryDevtools({ about })",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The application to wire up",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which application should report its build info?"
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Where to write the generated build-info file. Defaults to `<sourceRoot>/build-info.ts`."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after generation",
+      "default": false
+    }
+  },
+  "required": ["project"]
+}

package/generators/generators.json

@@ -10,6 +10,11 @@
       "schema": "./migrate-provider-shape/schema.json",
       "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape"
     },
+    "migrate-surface-interaction-swatch": {
+      "factory": "./migrate-surface-interaction-swatch/migration",
+      "schema": "./migrate-surface-interaction-swatch/schema.json",
+      "description": "Rewrite surface theme interactionColor maps into the { color, onColor, inkColor } swatch shape"
+    },
     "tailwind-4-color-theme": {
       "factory": "./tailwind-4-color-theme/generator",
       "schema": "./tailwind-4-color-theme/schema.json",
@@ -19,6 +24,11 @@
       "factory": "./tailwind-4-surface-theme/generator",
       "schema": "./tailwind-4-surface-theme/schema.json",
       "description": "Generate surface theming for Tailwind CSS v4"
+    },
+    "devtools-about": {
+      "factory": "./devtools-about/generator",
+      "schema": "./devtools-about/schema.json",
+      "description": "Generate the app's build info and wire it into provideQueryDevtools({ about })"
     }
   }
 }

package/generators/migrate-surface-interaction-swatch/interaction-swatch.js

@@ -0,0 +1,43 @@
+import { Project, SyntaxKind } from 'ts-morph';
+const INTERACTION_KEYS = ['default', 'hover', 'focus', 'active', 'disabled'];
+const createProject = () => new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+        target: 99,
+        module: 99,
+    },
+});
+const isFlatInteractionColor = (initializer) => initializer
+    .getProperties()
+    .some((property) => property.isKind(SyntaxKind.PropertyAssignment) && INTERACTION_KEYS.includes(property.getName()));
+const findFlatInteractionColor = (sourceFile) => {
+    for (const property of sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+        if (property.getName() !== 'interactionColor')
+            continue;
+        const initializer = property.getInitializer();
+        if (initializer?.isKind(SyntaxKind.ObjectLiteralExpression) && isFlatInteractionColor(initializer)) {
+            return initializer;
+        }
+    }
+    return null;
+};
+/**
+ * Rewrites `interactionColor: { default, hover, … }` into `interactionColor: { color: { default, … } }`,
+ * the swatch shape that also carries the optional `onColor` and `inkColor` maps.
+ */
+export const migrateInteractionSwatchInFile = (filePath, content) => {
+    if (!content.includes('interactionColor')) {
+        return { changed: false, content };
+    }
+    const sourceFile = createProject().createSourceFile(filePath, content);
+    let changed = false;
+    // Re-queried after every rewrite: manipulating the AST forgets the nodes a single up-front
+    // collection would have handed us.
+    for (let initializer = findFlatInteractionColor(sourceFile); initializer;) {
+        initializer.replaceWithText(`{ color: ${initializer.getText()} }`);
+        changed = true;
+        initializer = findFlatInteractionColor(sourceFile);
+    }
+    return { changed, content: changed ? sourceFile.getFullText() : content };
+};
+//# sourceMappingURL=interaction-swatch.js.map

package/generators/migrate-surface-interaction-swatch/migration.js

@@ -0,0 +1,29 @@
+import { formatFiles } from '@nx/devkit';
+import { createMigrationScope } from '../migrate-provider-shape/migration-scope';
+import { migrateInteractionSwatchInFile } from './interaction-swatch';
+export default async function migrateSurfaceInteractionSwatch(tree, schema) {
+    console.log('\n🔄 Migrating surface interactionColor to the swatch shape...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    let filesChanged = 0;
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.d.ts'))
+            return;
+        const before = tree.read(filePath, 'utf-8');
+        if (!before)
+            return;
+        const result = migrateInteractionSwatchInFile(filePath, before);
+        if (!result.changed)
+            return;
+        tree.write(filePath, result.content);
+        filesChanged++;
+        console.log(`   ✓ ${filePath}`);
+    });
+    console.log(filesChanged === 0
+        ? '   Nothing to migrate.\n'
+        : `\n✅ Migrated ${filesChanged} file(s). Regenerate your surface CSS with \`nx g @ethlete/core:tailwind-4-surface-theme\`.\n`);
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+}
+//# sourceMappingURL=migration.js.map

package/generators/migrate-surface-interaction-swatch/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-surface-interaction-swatch",
+  "title": "Migrate surface interactionColor to the swatch shape",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace.",
+      "alias": "project"
+    },
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path prefixes to migrate, relative to the workspace root (e.g. 'apps/web'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

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

@@ -158,9 +158,52 @@ const COLOR_PROPS = ['background', 'color', 'colorMuted', 'colorSubtle', 'border
 const isColorProp = (name) => COLOR_PROPS.some((p) => p === name);
 const INTERACTION_KEYS = ['default', 'hover', 'focus', 'active', 'disabled'];
 const isInteractionKey = (name) => INTERACTION_KEYS.some((key) => key === name);
+const SWATCH_KEYS = ['color', 'onColor', 'inkColor'];
+const isSwatchKey = (name) => SWATCH_KEYS.some((key) => key === name);
+function parseInteractionColorMap(obj) {
+    const map = {};
+    for (const prop of obj.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const name = prop.getName();
+        const initializer = prop.getInitializer();
+        if (initializer?.isKind(SyntaxKind.StringLiteral) && isInteractionKey(name)) {
+            map[name] = initializer.getLiteralValue();
+        }
+    }
+    return map;
+}
+function parseInteractionColor(obj, themeName) {
+    const swatch = {};
+    for (const prop of obj.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const name = prop.getName();
+        const initializer = prop.getInitializer();
+        if (isInteractionKey(name)) {
+            throw new Error(`Surface theme "${themeName}" uses the old flat \`interactionColor\` shape. It now takes a swatch: ` +
+                `{ color: { default, hover, focus, active, disabled }, onColor?, inkColor? }. ` +
+                `Run \`nx g @ethlete/core:migrate-surface-interaction-swatch\` to convert your themes.`);
+        }
+        if (!initializer?.isKind(SyntaxKind.ObjectLiteralExpression) || !isSwatchKey(name))
+            continue;
+        const map = parseInteractionColorMap(initializer);
+        if (name === 'color') {
+            if (map.default && map.hover && map.focus && map.active && map.disabled) {
+                swatch.color = map;
+            }
+            continue;
+        }
+        if (map.default) {
+            swatch[name] = map;
+        }
+    }
+    return swatch.color ? swatch : undefined;
+}
 function parseSurfaceThemeObject(obj) {
     const properties = obj.getProperties();
     const theme = {};
+    let interactionColorObj = null;
     for (const prop of properties) {
         if (!prop.isKind(SyntaxKind.PropertyAssignment)) {
             continue;
@@ -177,24 +220,7 @@ function parseSurfaceThemeObject(obj) {
             continue;
         }
         if (propName === 'interactionColor' && initializer.isKind(SyntaxKind.ObjectLiteralExpression)) {
-            const interactionProps = initializer.getProperties();
-            const interactionColor = {};
-            for (const iProp of interactionProps) {
-                if (!iProp.isKind(SyntaxKind.PropertyAssignment))
-                    continue;
-                const iPropName = iProp.getName();
-                const iInit = iProp.getInitializer();
-                if (iInit?.isKind(SyntaxKind.StringLiteral) && isInteractionKey(iPropName)) {
-                    interactionColor[iPropName] = iInit.getLiteralValue();
-                }
-            }
-            if (interactionColor.default &&
-                interactionColor.hover &&
-                interactionColor.focus &&
-                interactionColor.active &&
-                interactionColor.disabled) {
-                theme.interactionColor = interactionColor;
-            }
+            interactionColorObj = initializer;
             continue;
         }
         if (propName === 'elevation') {
@@ -227,6 +253,9 @@ function parseSurfaceThemeObject(obj) {
         !theme.border) {
         throw new Error('SurfaceTheme must have name, type, elevation, background, color, colorMuted, colorSubtle, and border properties');
     }
+    if (interactionColorObj) {
+        theme.interactionColor = parseInteractionColor(interactionColorObj, theme.name);
+    }
     return theme;
 }
 // Makes the named theme the sole default of its surface type, overriding any isDefault
@@ -322,11 +351,14 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
         tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-subtle: rgb(${theme.colorSubtle});`);
         tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-border: rgb(${theme.border});`);
         if (theme.interactionColor) {
-            tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-interaction: rgb(${theme.interactionColor.default});`);
-            tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-interaction-hover: rgb(${theme.interactionColor.hover});`);
-            tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-interaction-focus: rgb(${theme.interactionColor.focus});`);
-            tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-interaction-active: rgb(${theme.interactionColor.active});`);
-            tailwindVars.push(`  --color-${utilityPrefix}-surface-${name}-interaction-disabled: rgb(${theme.interactionColor.disabled});`);
+            const { color, onColor, inkColor } = theme.interactionColor;
+            pushStaticInteractionColors(tailwindVars, `--color-${utilityPrefix}-surface-${name}-interaction`, color);
+            if (onColor) {
+                pushStaticInteractionColors(tailwindVars, `--color-${utilityPrefix}-surface-${name}-on-interaction`, onColor);
+            }
+            if (inkColor) {
+                pushStaticInteractionColors(tailwindVars, `--color-${utilityPrefix}-surface-${name}-interaction-ink`, inkColor);
+            }
         }
         tailwindVars.push('');
     }
@@ -420,11 +452,39 @@ ${tailwindVars.join('\n')}
 ${themeVars.join('\n')}
 }
 
-${aliasBlock}`;
+${aliasBlock}
+${buildSurfaceColorScope(runtimePrefix)}`;
+}
+// The reserved `surface` color scope. It bridges the two theming systems - color variables out of
+// surface variables - so `[etProvideColor]="'surface'"` renders a component in the neutral of
+// whatever surface it sits on. It lives here rather than in the SDK's own CSS because a stylesheet
+// shipped with `ProvideColorDirective` would land in every bundle that themes anything, and only
+// apps that use the scope should pay for it.
+function buildSurfaceColorScope(runtimePrefix) {
+    const tint = `var(--${runtimePrefix}-surface-interaction, var(--${runtimePrefix}-surface-color))`;
+    const on = `var(--${runtimePrefix}-surface-on-interaction, var(--${runtimePrefix}-surface-background))`;
+    const ink = `var(--${runtimePrefix}-surface-interaction-ink, var(--${runtimePrefix}-surface-color))`;
+    const state = (name, source, fallback) => INTERACTION_STATE_SUFFIXES.map((suffix) => `    --${runtimePrefix}-color-${name}${suffix}: ${suffix ? `var(--${runtimePrefix}-surface-${source}${suffix}, ${fallback})` : fallback};`).join('\n');
+    return `/* The reserved \`surface\` color: resolves the color tokens from the ambient surface's neutral swatch. */
+@layer base {
+  .${runtimePrefix}-color--surface {
+${state('primary', 'interaction', tint)}
+
+${state('on-primary', 'on-interaction', on)}
+
+${state('primary-ink', 'interaction-ink', ink)}
+  }
+}
+`;
 }
 // Dynamic surface color declarations (unindented). Emitted in `@theme` (so Tailwind generates
 // the utilities) and re-declared on every surface selector (so the utilities resolve per scope).
 function buildDynamicSurfaceColors(utilityPrefix, runtimePrefix) {
+    // `on-interaction` and `interaction-ink` are optional per theme, so each falls back to the
+    // surface's own background/color - the same defaults the `.<runtimePrefix>-color--surface`
+    // bridge applies.
+    const onFallback = `var(--${runtimePrefix}-surface-background)`;
+    const inkFallback = `var(--${runtimePrefix}-surface-color)`;
     return [
         `--color-${utilityPrefix}-surface-bg: rgb(var(--${runtimePrefix}-surface-background));`,
         `--color-${utilityPrefix}-surface: rgb(var(--${runtimePrefix}-surface-color));`,
@@ -436,8 +496,35 @@ function buildDynamicSurfaceColors(utilityPrefix, runtimePrefix) {
         `--color-${utilityPrefix}-surface-interaction-focus: rgb(var(--${runtimePrefix}-surface-interaction-focus));`,
         `--color-${utilityPrefix}-surface-interaction-active: rgb(var(--${runtimePrefix}-surface-interaction-active));`,
         `--color-${utilityPrefix}-surface-interaction-disabled: rgb(var(--${runtimePrefix}-surface-interaction-disabled));`,
+        ...INTERACTION_STATE_SUFFIXES.map((suffix) => `--color-${utilityPrefix}-surface-on-interaction${suffix}: rgb(var(--${runtimePrefix}-surface-on-interaction${suffix}, ${onFallback}));`),
+        ...INTERACTION_STATE_SUFFIXES.map((suffix) => `--color-${utilityPrefix}-surface-interaction-ink${suffix}: rgb(var(--${runtimePrefix}-surface-interaction-ink${suffix}, ${inkFallback}));`),
     ];
 }
+const INTERACTION_STATE_SUFFIXES = ['', '-hover', '-focus', '-active', '-disabled'];
+// Fills the optional states from the ones that are set, matching how the color theme generator
+// resolves a swatch: hover falls back to default, focus to hover, active and disabled to default.
+function resolveInteractionStates(map) {
+    const hover = map.hover || map.default;
+    return {
+        '': map.default,
+        '-hover': hover,
+        '-focus': map.focus || hover,
+        '-active': map.active || map.default,
+        '-disabled': map.disabled || map.default,
+    };
+}
+function pushStaticInteractionColors(vars, name, map) {
+    const states = resolveInteractionStates(map);
+    for (const suffix of INTERACTION_STATE_SUFFIXES) {
+        vars.push(`  ${name}${suffix}: rgb(${states[suffix]});`);
+    }
+}
+function pushRuntimeInteractionVars(vars, name, map, indent) {
+    const states = resolveInteractionStates(map);
+    for (const suffix of INTERACTION_STATE_SUFFIXES) {
+        vars.push(`${indent}${name}${suffix}: ${states[suffix]};`);
+    }
+}
 function pushSurfaceVars(vars, runtimePrefix, theme, indent) {
     vars.push(`${indent}--${runtimePrefix}-surface-background: ${theme.background};`);
     vars.push(`${indent}--${runtimePrefix}-surface-color: ${theme.color};`);
@@ -447,11 +534,14 @@ function pushSurfaceVars(vars, runtimePrefix, theme, indent) {
     vars.push(`${indent}--${runtimePrefix}-surface-type: ${theme.type};`);
     vars.push(`${indent}--${runtimePrefix}-surface-elevation: ${theme.elevation};`);
     if (theme.interactionColor) {
-        vars.push(`${indent}--${runtimePrefix}-surface-interaction: ${theme.interactionColor.default};`);
-        vars.push(`${indent}--${runtimePrefix}-surface-interaction-hover: ${theme.interactionColor.hover};`);
-        vars.push(`${indent}--${runtimePrefix}-surface-interaction-focus: ${theme.interactionColor.focus};`);
-        vars.push(`${indent}--${runtimePrefix}-surface-interaction-active: ${theme.interactionColor.active};`);
-        vars.push(`${indent}--${runtimePrefix}-surface-interaction-disabled: ${theme.interactionColor.disabled};`);
+        const { color, onColor, inkColor } = theme.interactionColor;
+        pushRuntimeInteractionVars(vars, `--${runtimePrefix}-surface-interaction`, color, indent);
+        if (onColor) {
+            pushRuntimeInteractionVars(vars, `--${runtimePrefix}-surface-on-interaction`, onColor, indent);
+        }
+        if (inkColor) {
+            pushRuntimeInteractionVars(vars, `--${runtimePrefix}-surface-interaction-ink`, inkColor, indent);
+        }
     }
 }
 function findMainStylesFile(tree) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/core",
-  "version": "5.0.0-next.44",
+  "version": "5.0.0-next.46",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {