@knighted/css 1.1.0-rc.7 → 1.1.0

package/README.md

@@ -121,6 +121,22 @@ When the `.knighted-css` import targets a JavaScript/TypeScript module, the gene
 import Button, { knightedCss, stableSelectors } from './button.knighted-css.js'
 ```
 
+Need hashed class names instead of stable selectors? Run the CLI with `--hashed` to emit proxy modules that export `selectors` backed by `knightedCssModules` from the loader-bridge:
+
+```sh
+knighted-css-generate-types --root . --include src --hashed
+```
+
+```ts
+import Button, { knightedCss, selectors } from './button.knighted-css.js'
+
+selectors.card // hashed CSS Modules class name
+```
+
+> [!IMPORTANT]
+> `--hashed` requires wiring `@knighted/css/loader-bridge` to handle `?knighted-css` queries so
+> the generated proxies can read `knightedCss` and `knightedCssModules` at build time.
+
 Refer to [docs/type-generation.md](../../docs/type-generation.md) for CLI options and workflow tips.
 
 ### Combined + runtime selectors

package/dist/cjs/generateTypes.cjs

@@ -87,6 +87,7 @@ async function generateTypes(options = {}) {
         cacheDir,
         stableNamespace: options.stableNamespace,
         autoStable: options.autoStable,
+        hashed: options.hashed,
         tsconfig,
         resolver: options.resolver,
     };
@@ -142,12 +143,14 @@ async function generateDeclarations(options) {
                             : undefined,
                         resolver: options.resolver,
                     });
-                    selectorMap = (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
-                        css,
-                        namespace: resolvedNamespace,
-                        resourcePath: resolvedPath,
-                        emitWarning: message => warnings.push(message),
-                    }).selectorMap;
+                    selectorMap = options.hashed
+                        ? collectSelectorTokensFromCss(css)
+                        : (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
+                            css,
+                            namespace: resolvedNamespace,
+                            resourcePath: resolvedPath,
+                            emitWarning: message => warnings.push(message),
+                        }).selectorMap;
                 }
                 catch (error) {
                     warnings.push(`Failed to extract CSS for ${relativeToRoot(resolvedPath, options.rootDir)}: ${formatErrorMessage(error)}`);
@@ -164,7 +167,7 @@ async function generateDeclarations(options) {
                 continue;
             }
             const proxyInfo = await resolveProxyInfo(manifestKey, selectorSource, resolvedPath, proxyInfoCache);
-            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest, proxyInfo ?? undefined);
+            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest, selectorSource, proxyInfo ?? undefined, options.hashed ?? false);
             if (moduleWrite) {
                 selectorModuleWrites += 1;
             }
@@ -356,29 +359,65 @@ function buildSelectorModulePath(resolvedPath) {
     const base = ext ? resolvedPath.slice(0, -ext.length) : resolvedPath;
     return `${base}${SELECTOR_MODULE_SUFFIX}`;
 }
-function formatSelectorModuleSource(selectors, proxyInfo) {
+function formatSelectorModuleSource(selectors, proxyInfo, options = {}) {
     const header = '// Generated by @knighted/css/generate-types\n// Do not edit.';
     const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
+    const isHashed = options.hashed === true;
     const lines = entries.map(([token, selector]) => `  ${JSON.stringify(token)}: ${JSON.stringify(selector)},`);
     const literal = lines.length > 0
         ? `{
 ${lines.join('\n')}
 } as const`
         : '{} as const';
+    const typeLines = entries.map(([token]) => `  readonly ${JSON.stringify(token)}: string`);
+    const typeLiteral = typeLines.length > 0
+        ? `{
+${typeLines.join('\n')}
+}`
+        : 'Record<string, string>';
     const proxyLines = [];
+    const reexportLines = [];
+    const hashedSpecifier = options.selectorSource && options.resolvedPath
+        ? buildProxyModuleSpecifier(options.resolvedPath, options.selectorSource)
+        : undefined;
     if (proxyInfo) {
-        proxyLines.push(`export * from '${proxyInfo.moduleSpecifier}'`);
+        reexportLines.push(`export * from '${proxyInfo.moduleSpecifier}'`);
         if (proxyInfo.includeDefault) {
-            proxyLines.push(`export { default } from '${proxyInfo.moduleSpecifier}'`);
+            reexportLines.push(`export { default } from '${proxyInfo.moduleSpecifier}'`);
+        }
+    }
+    if (isHashed) {
+        const sourceSpecifier = proxyInfo?.moduleSpecifier ?? hashedSpecifier;
+        if (sourceSpecifier) {
+            proxyLines.push(`import { knightedCss as __knightedCss, knightedCssModules as __knightedCssModules } from '${sourceSpecifier}?knighted-css'`);
+            proxyLines.push('export const knightedCss = __knightedCss');
+            proxyLines.push('export const knightedCssModules = __knightedCssModules');
         }
+    }
+    else if (proxyInfo) {
         proxyLines.push(`export { knightedCss } from '${proxyInfo.moduleSpecifier}?knighted-css'`);
     }
-    const defaultExport = proxyInfo ? '' : '\nexport default stableSelectors';
-    const stableBlock = `export const stableSelectors = ${literal}
+    const exportName = isHashed ? 'selectors' : 'stableSelectors';
+    const typeName = isHashed ? 'KnightedCssSelectors' : 'KnightedCssStableSelectors';
+    const tokenTypeName = isHashed
+        ? 'KnightedCssSelectorToken'
+        : 'KnightedCssStableSelectorToken';
+    const defaultExport = proxyInfo ? '' : `\nexport default ${exportName}`;
+    const selectorBlock = isHashed
+        ? `export const ${exportName} = __knightedCssModules as ${typeLiteral}
+
+export type ${typeName} = typeof ${exportName}
+export type ${tokenTypeName} = keyof typeof ${exportName}${defaultExport}`
+        : `export const ${exportName} = ${literal}
 
-export type KnightedCssStableSelectors = typeof stableSelectors
-export type KnightedCssStableSelectorToken = keyof typeof stableSelectors${defaultExport}`;
-    const sections = [header, proxyLines.join('\n'), stableBlock].filter(Boolean);
+export type ${typeName} = typeof ${exportName}
+export type ${tokenTypeName} = keyof typeof ${exportName}${defaultExport}`;
+    const sections = [
+        header,
+        proxyLines.join('\n'),
+        reexportLines.join('\n'),
+        selectorBlock,
+    ].filter(Boolean);
     return `${sections.join('\n\n')}
 `;
 }
@@ -424,10 +463,14 @@ function isWithinRoot(filePath, rootDir) {
     const relative = node_path_1.default.relative(rootDir, filePath);
     return relative === '' || (!relative.startsWith('..') && !node_path_1.default.isAbsolute(relative));
 }
-async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest, proxyInfo) {
+async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest, selectorSource, proxyInfo, hashed) {
     const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
     const targetPath = buildSelectorModulePath(resolvedPath);
-    const source = formatSelectorModuleSource(selectors, proxyInfo);
+    const source = formatSelectorModuleSource(selectors, proxyInfo, {
+        hashed,
+        selectorSource,
+        resolvedPath,
+    });
     const hash = hashContent(source);
     const previousEntry = previousManifest[manifestKey];
     const needsWrite = previousEntry?.hash !== hash || !(await fileExists(targetPath));
@@ -578,6 +621,22 @@ function isStyleResource(filePath) {
     const normalized = filePath.toLowerCase();
     return STYLE_EXTENSIONS.some(ext => normalized.endsWith(ext));
 }
+function collectSelectorTokensFromCss(css) {
+    const tokens = new Set();
+    const pattern = /\.([A-Za-z_-][A-Za-z0-9_-]*)\b/g;
+    let match;
+    while ((match = pattern.exec(css)) !== null) {
+        const token = match[1];
+        if (token) {
+            tokens.add(token);
+        }
+    }
+    const map = new Map();
+    for (const token of tokens) {
+        map.set(token, token);
+    }
+    return map;
+}
 async function resolveProxyInfo(manifestKey, selectorSource, resolvedPath, cache) {
     if (isStyleResource(resolvedPath)) {
         return null;
@@ -681,6 +740,7 @@ async function runGenerateTypesCli(argv = process.argv.slice(2)) {
             outDir: parsed.outDir,
             stableNamespace: parsed.stableNamespace,
             autoStable: parsed.autoStable,
+            hashed: parsed.hashed,
             resolver,
         });
         reportCliResult(result);
@@ -697,6 +757,7 @@ function parseCliArgs(argv) {
     let outDir;
     let stableNamespace;
     let autoStable = false;
+    let hashed = false;
     let resolver;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -707,6 +768,10 @@ function parseCliArgs(argv) {
             autoStable = true;
             continue;
         }
+        if (arg === '--hashed') {
+            hashed = true;
+            continue;
+        }
         if (arg === '--root' || arg === '-r') {
             const value = argv[++i];
             if (!value) {
@@ -752,7 +817,10 @@ function parseCliArgs(argv) {
         }
         include.push(arg);
     }
-    return { rootDir, include, outDir, stableNamespace, autoStable, resolver };
+    if (autoStable && hashed) {
+        throw new Error('Cannot combine --auto-stable with --hashed');
+    }
+    return { rootDir, include, outDir, stableNamespace, autoStable, hashed, resolver };
 }
 function printHelp() {
     console.log(`Usage: knighted-css-generate-types [options]
@@ -763,6 +831,7 @@ Options:
       --out-dir <path>           Directory to store selector module manifest cache
       --stable-namespace <name>  Stable namespace prefix for generated selector maps
       --auto-stable              Enable autoStable when extracting CSS for selectors
+      --hashed                   Emit selectors backed by loader-bridge hashed modules
       --resolver <path>          Path or package name exporting a CssResolver
   -h, --help                     Show this help message
 `);