@css-modules-kit/core 0.8.0 → 0.9.0

package/src/dts-generator.ts

@@ -1,5 +1,6 @@
 import type { CSSModule, Token, TokenImporter } from './type.js';
-import { isURLSpecifier, isValidAsJSIdentifier } from './util.js';
+import type { ValidateTokenNameOptions } from './util.js';
+import { isURLSpecifier, validateTokenName } from './util.js';
 
 export const STYLES_EXPORT_NAME = 'styles';
 
@@ -17,6 +18,8 @@ interface CodeMapping {
   lengths: number[];
   /** The generated offsets of the tokens in the *.d.ts file. */
   generatedOffsets: number[];
+  /** The lengths of the tokens in the *.d.ts file. If not provided, it is assumed to be the same as `lengths`. */
+  generatedLengths?: number[];
 }
 
 /** The map linking the two codes in *.d.ts */
@@ -35,6 +38,7 @@ interface LinkedCodeMapping extends CodeMapping {
 interface GenerateDtsResult {
   text: string;
   mapping: CodeMapping;
+  secondaryMapping?: CodeMapping;
   linkedCodeMapping: LinkedCodeMapping;
 }
 
@@ -43,7 +47,7 @@ interface GenerateDtsResult {
  */
 export function generateDts(cssModule: CSSModule, options: GenerateDtsOptions): GenerateDtsResult {
   // Exclude invalid tokens
-  const localTokens = cssModule.localTokens.filter((token) => isValidName(token.name, options));
+  const localTokens = cssModule.localTokens.filter((token) => isValidTokenName(token.name, options));
   const tokenImporters = cssModule.tokenImporters
     // Exclude invalid imported tokens
     .map((tokenImporter) => {
@@ -52,8 +56,8 @@ export function generateDts(cssModule: CSSModule, options: GenerateDtsOptions):
           ...tokenImporter,
           values: tokenImporter.values.filter(
             (value) =>
-              isValidName(value.name, options) &&
-              (value.localName === undefined || isValidName(value.localName, options)),
+              isValidTokenName(value.name, options) &&
+              (value.localName === undefined || isValidTokenName(value.localName, options)),
           ),
         };
       } else {
@@ -106,28 +110,7 @@ export function generateDts(cssModule: CSSModule, options: GenerateDtsOptions):
   }
 }
 
-/**
- * Generate a d.ts file with named exports.
- * @example
- * If the CSS module file is:
- * ```css
- * @import './a.module.css';
- * @value local1: string;
- * @value imported1, imported2 as aliasedImported2 from './b.module.css';
- * .local2 { color: red }
- * ```
- * The d.ts file would be:
- * ```ts
- * // @ts-nocheck
- * export var local1: string;
- * export var local2: string;
- * export * from './a.module.css';
- * export {
- *   imported1,
- *   imported2 as aliasedImported2,
- * } from './b.module.css';
- * ```
- */
+/** Generate a d.ts file with named exports. */
 function generateNamedExportsDts(
   localTokens: Token[],
   tokenImporters: TokenImporter[],
@@ -149,6 +132,25 @@ function generateNamedExportsDts(
   let text = `// @ts-nocheck\n`;
 
   for (const token of localTokens) {
+    /**
+     * The mapping is created as follows:
+     * a.module.css:
+     * 1 | .a_1 { color: red; }
+     *   |  ^ mapping.sourceOffsets[0]
+     *   |
+     * 2 | .a_2 { color: blue; }
+     *   |  ^ mapping.sourceOffsets[1]
+     *   |
+     *
+     * a.module.css.d.ts:
+     * 1 | // @ts-nocheck
+     * 2 | export var a_1: string;
+     *   |            ^ mapping.generatedOffsets[0]
+     *   |
+     * 3 | export var a_2: string;
+     *   |            ^ mapping.generatedOffsets[1]
+     */
+
     text += `export var `;
     mapping.sourceOffsets.push(token.loc.start.offset);
     mapping.generatedOffsets.push(text.length);
@@ -157,12 +159,71 @@ function generateNamedExportsDts(
   }
   for (const tokenImporter of tokenImporters) {
     if (tokenImporter.type === 'import') {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @import './b.module.css';
+       *   |         ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @import './c.module.css';
+       *   |         ^ mapping.sourceOffsets[1]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | // @ts-nocheck
+       * 2 | export * from './b.module.css';
+       *   |               ^ mapping.generatedOffsets[0]
+       *   |
+       * 3 | export * from './c.module.css';
+       *   |               ^ mapping.generatedOffsets[1]
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
       text += `export * from `;
       mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
       mapping.lengths.push(tokenImporter.from.length + 2);
       mapping.generatedOffsets.push(text.length);
       text += `'${tokenImporter.from}';\n`;
     } else {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @value b_1, b_2 from './b.module.css';
+       *   |        ^    ^        ^ mapping.sourceOffsets[2]
+       *   |        ^    ^ mapping.sourceOffsets[1]
+       *   |        ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @value c_1 as aliased_c_1 from './c.module.css';
+       *   |        ^      ^                ^ mapping.sourceOffsets[5]
+       *   |        ^      ^ mapping.sourceOffsets[4]
+       *   |        ^ mapping.sourceOffsets[3]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | // @ts-nocheck
+       * 2 | export {
+       * 3 |   b_1,
+       *   |   ^ mapping.generatedOffsets[0]
+       *   |
+       * 4 |   b_2,
+       *   |   ^ mapping.generatedOffsets[1]
+       *   |
+       * 5 | } from './b.module.css';
+       *   |        ^ mapping.generatedOffsets[2]
+       *   |
+       * 6 | export {
+       * 7 |   c_1 as aliased_c_1,
+       *   |   ^      ^ mapping.generatedOffsets[4], linkedCodeMapping.sourceOffsets[0]
+       *   |   ^ mapping.generatedOffsets[3], linkedCodeMapping.generatedOffsets[0]
+       *   |
+       * 8 | } from './c.module.css';
+       *   |        ^ mapping.generatedOffsets[5]
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       * NOTE: linkedCodeMapping is only generated for tokens that have a `localName` (i.e., aliased tokens).
+       */
+
       text += `export {\n`;
       // eslint-disable-next-line no-loop-func
       tokenImporter.values.forEach((value) => {
@@ -203,34 +264,28 @@ function generateNamedExportsDts(
   return { text, mapping, linkedCodeMapping };
 }
 
-/**
- * Generate a d.ts file with a default export.
- * @example
- * If the CSS module file is:
- * ```css
- * @import './a.module.css';
- * @value local1: string;
- * @value imported1, imported2 as aliasedImported2 from './b.module.css';
- * .local2 { color: red }
- * ```
- * The d.ts file would be:
- * ```ts
- * // @ts-nocheck
- * const styles = {
- *   local1: '' as readonly string,
- *   local2: '' as readonly string,
- *   ...(await import('./a.module.css')).default,
- *   imported1: (await import('./b.module.css')).default.imported1,
- *   aliasedImported2: (await import('./b.module.css')).default.imported2,
- * };
- * export default styles;
- * ```
- */
+/** Generate a d.ts file with a default export. */
 function generateDefaultExportDts(
   localTokens: Token[],
   tokenImporters: TokenImporter[],
-): { text: string; mapping: CodeMapping; linkedCodeMapping: LinkedCodeMapping } {
+): {
+  text: string;
+  mapping: CodeMapping;
+  secondaryMapping: CodeMapping;
+  linkedCodeMapping: LinkedCodeMapping;
+} {
   const mapping: CodeMapping = { sourceOffsets: [], lengths: [], generatedOffsets: [] };
+  /**
+   * In "Go to Definition", mapping only the inner part of the quotes does not work.
+   * Therefore, we also generate a mapping that includes the quotes.
+   * For more details, see https://github.com/mizdra/volar-single-quote-span-problem.
+   */
+  const secondaryMapping: CodeMapping & { generatedLengths: number[] } = {
+    sourceOffsets: [],
+    lengths: [],
+    generatedOffsets: [],
+    generatedLengths: [],
+  };
   const linkedCodeMapping: LinkedCodeMapping = {
     sourceOffsets: [],
     lengths: [],
@@ -256,54 +311,150 @@ function generateDefaultExportDts(
 
   text += `declare const ${STYLES_EXPORT_NAME} = {\n`;
   for (const token of localTokens) {
-    text += `  `;
+    /**
+     * The mapping is created as follows:
+     * a.module.css:
+     * 1 | .a_1 { color: red; }
+     *   |  ^ mapping.sourceOffsets[0], secondaryMapping.sourceOffsets[0]
+     *   |
+     * 2 | .a_2 { color: blue; }
+     *   |  ^ mapping.sourceOffsets[1], secondaryMapping.sourceOffsets[1]
+     *   |
+     *
+     * a.module.css.d.ts:
+     * 1 | declare const styles = {
+     * 2 |   'a_1': '' as readonly string,
+     *   |   ^^ mapping.generatedOffsets[0]
+     *   |   ^ secondaryMapping.generatedOffsets[0]
+     *   |
+     * 3 |   'a_2': '' as readonly string,
+     *   |   ^^ mapping.generatedOffsets[1]
+     *   |   ^ secondaryMapping.generatedOffsets[1]
+     *   |
+     * 4 | };
+     */
+
+    text += `  '`;
     mapping.sourceOffsets.push(token.loc.start.offset);
-    mapping.generatedOffsets.push(text.length);
     mapping.lengths.push(token.name.length);
-    text += `${token.name}: '' as readonly string,\n`;
+    mapping.generatedOffsets.push(text.length);
+    secondaryMapping.sourceOffsets.push(token.loc.start.offset);
+    secondaryMapping.lengths.push(token.name.length);
+    secondaryMapping.generatedOffsets.push(text.length - 1);
+    secondaryMapping.generatedLengths.push(token.name.length + 2);
+    text += `${token.name}': '' as readonly string,\n`;
   }
   for (const tokenImporter of tokenImporters) {
     if (tokenImporter.type === 'import') {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @import './b.module.css';
+       *   |         ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @import './c.module.css';
+       *   |         ^ mapping.sourceOffsets[1]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | declare const styles = {
+       * 2 |   ...blockErrorType((await import('./b.module.css')).default),
+       *   |                                   ^ mapping.generatedOffsets[0]
+       *   |
+       * 3 |   ...blockErrorType((await import('./c.module.css')).default),
+       *   |                                   ^ mapping.generatedOffsets[1]
+       *   |
+       * 4 | };
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
       text += `  ...blockErrorType((await import(`;
       mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
       mapping.lengths.push(tokenImporter.from.length + 2);
       mapping.generatedOffsets.push(text.length);
       text += `'${tokenImporter.from}')).default),\n`;
     } else {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @value b_1, b_2 from './b.module.css';
+       *   |        ^    ^        ^ mapping.sourceOffsets[1]
+       *   |        ^    ^ mapping.sourceOffsets[2], secondaryMapping.sourceOffsets[1]
+       *   |        ^ mapping.sourceOffsets[0], secondaryMapping.sourceOffsets[0]
+       *   |
+       * 2 | @value c_1 as aliased_c_1 from './c.module.css';
+       *   |        ^      ^                ^ mapping.sourceOffsets[4]
+       *   |        ^      ^ mapping.sourceOffsets[3], secondaryMapping.sourceOffsets[2]
+       *   |        ^ mapping.sourceOffsets[5], secondaryMapping.sourceOffsets[3]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | declare const styles = {
+       * 2 |   'b_1': (await import('./b.module.css')).default['b_1'],
+       *   |   ^^                   ^                          ^ linkedCodeMapping.generatedOffsets[0]
+       *   |   ^^                   ^ mapping.generatedOffsets[1]
+       *   |   ^^ mapping.generatedOffsets[0]
+       *   |   ^ secondaryMapping.generatedOffsets[0], linkedCodeMapping.sourceOffsets[0]
+       *   |
+       * 3 |   'b_2': (await import('./b.module.css')).default['b_2'],
+       *   |   ^^                                              ^ linkedCodeMapping.generatedOffsets[1]
+       *   |   ^^ mapping.generatedOffsets[2]
+       *   |   ^ secondaryMapping.generatedOffsets[1], linkedCodeMapping.sourceOffsets[1]
+       *   |
+       * 4 |   'aliased_c_1': (await import('./c.module.css')).default['c_1'],
+       *   |   ^^                           ^                          ^^ mapping.generatedOffsets[5]
+       *   |   ^^                           ^                          ^ secondaryMapping.generatedOffsets[3], linkedCodeMapping.generatedOffsets[2]
+       *   |   ^^                           ^ mapping.generatedOffsets[4]
+       *   |   ^^ mapping.generatedOffsets[3]
+       *   |   ^ secondaryMapping.generatedOffsets[2], linkedCodeMapping.sourceOffsets[2]
+       *   |
+       * 5 | };
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
       // eslint-disable-next-line no-loop-func
       tokenImporter.values.forEach((value, i) => {
         const localName = value.localName ?? value.name;
         const localLoc = value.localLoc ?? value.loc;
 
-        text += `  `;
+        text += `  '`;
         mapping.sourceOffsets.push(localLoc.start.offset);
         mapping.lengths.push(localName.length);
         mapping.generatedOffsets.push(text.length);
-        linkedCodeMapping.sourceOffsets.push(text.length);
-        linkedCodeMapping.lengths.push(localName.length);
-        text += `${localName}: (await import(`;
+        secondaryMapping.sourceOffsets.push(localLoc.start.offset);
+        secondaryMapping.lengths.push(localName.length);
+        secondaryMapping.generatedOffsets.push(text.length - 1);
+        secondaryMapping.generatedLengths.push(localName.length + 2);
+        linkedCodeMapping.sourceOffsets.push(text.length - 1);
+        linkedCodeMapping.lengths.push(localName.length + 2);
+        text += `${localName}': (await import(`;
         if (i === 0) {
           mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
           mapping.lengths.push(tokenImporter.from.length + 2);
           mapping.generatedOffsets.push(text.length);
         }
-        text += `'${tokenImporter.from}')).default.`;
-        mapping.sourceOffsets.push(value.loc.start.offset);
-        mapping.lengths.push(value.name.length);
-        mapping.generatedOffsets.push(text.length);
-        linkedCodeMapping.generatedOffsets.push(text.length);
-        linkedCodeMapping.generatedLengths.push(value.name.length);
-        text += `${value.name},\n`;
+        text += `'${tokenImporter.from}')).default['`;
+        if ('localName' in value) {
+          mapping.sourceOffsets.push(value.loc.start.offset);
+          mapping.lengths.push(value.name.length);
+          mapping.generatedOffsets.push(text.length);
+          secondaryMapping.sourceOffsets.push(value.loc.start.offset);
+          secondaryMapping.lengths.push(value.name.length);
+          secondaryMapping.generatedOffsets.push(text.length - 1);
+          secondaryMapping.generatedLengths.push(value.name.length + 2);
+        }
+        linkedCodeMapping.generatedOffsets.push(text.length - 1);
+        linkedCodeMapping.generatedLengths.push(value.name.length + 2);
+        text += `${value.name}'],\n`;
       });
     }
   }
   text += `};\nexport default ${STYLES_EXPORT_NAME};\n`;
-  return { text, mapping, linkedCodeMapping };
+  return { text, mapping, linkedCodeMapping, secondaryMapping };
 }
 
-function isValidName(name: string, options: GenerateDtsOptions): boolean {
-  if (!isValidAsJSIdentifier(name)) return false;
-  if (name === '__proto__') return false;
-  if (options.namedExports && name === 'default') return false;
-  return true;
+function isValidTokenName(name: string, options: ValidateTokenNameOptions): boolean {
+  return validateTokenName(name, options) === undefined;
 }

package/src/parser/rule-parser.ts

@@ -119,14 +119,24 @@ export function parseRule(rule: Rule): ParseRuleResult {
       column: rule.source!.start!.column + className.source!.start!.column,
       offset: rule.source!.start!.offset + className.sourceIndex + 1,
     };
+    /**
+     * When there is a selector like `.\31 backslash`, `className.value` becomes `"1backslash"`.
+     * In other words, it is the string after escape sequences have been interpreted.
+     * However, here we need the raw string as written in the CSS source code.
+     * So we use `className.toString()`.
+     *
+     * The return value of `className.toString()` may contain leading dots and spaces like `" .1backslash"`.
+     * Therefore, we remove the leading spaces and dot with a regular expression.
+     */
+    const rawClassName = className.toString().replace(/^\s*\./u, '');
     const end = {
       // The end line is always the same as the start line, as a class selector cannot break in the middle.
       line: start.line,
-      column: start.column + className.value.length,
-      offset: start.offset + className.value.length,
+      column: start.column + rawClassName.length,
+      offset: start.offset + rawClassName.length,
     };
     return {
-      name: className.value,
+      name: rawClassName,
       loc: { start, end },
       declarationLoc: { start: rule.source!.start!, end: rule.positionBy({ index: rule.toString().length }) },
     };

package/src/resolver.ts

@@ -12,8 +12,8 @@ export function createResolver(
     const host: ts.ModuleResolutionHost = {
       ...ts.sys,
       fileExists: (fileName) => {
-        if (fileName.endsWith('.module.d.css.ts')) {
-          return ts.sys.fileExists(fileName.replace(/\.module\.d\.css\.ts$/u, '.module.css'));
+        if (fileName.endsWith('.d.css.ts')) {
+          return ts.sys.fileExists(fileName.replace(/\.d\.css\.ts$/u, '.css'));
         }
         return ts.sys.fileExists(fileName);
       },
@@ -26,8 +26,7 @@ export function createResolver(
       moduleResolutionCache,
     );
     if (resolvedModule) {
-      // TODO: Logging that the paths is used.
-      return resolvedModule.resolvedFileName.replace(/\.module\.d\.css\.ts$/u, '.module.css');
+      return resolvedModule.resolvedFileName.replace(/\.d\.css\.ts$/u, '.css');
     }
     return undefined;
   };

package/src/typing/typescript.d.ts

@@ -5,7 +5,7 @@ declare module 'typescript' {
     readonly files: readonly string[];
     readonly directories: readonly string[];
   }
-  // eslint-disable-next-line max-params
+
   export function matchFiles(
     path: string,
     extensions: readonly string[] | undefined,

package/src/util.ts

@@ -4,24 +4,48 @@ export function isPosixRelativePath(path: string): boolean {
 
 const JS_IDENTIFIER_PATTERN = /^[$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u;
 
-export function isValidAsJSIdentifier(name: string): boolean {
-  return JS_IDENTIFIER_PATTERN.test(name);
+/** The type of token name violation. */
+export type TokenNameViolation =
+  | 'invalid-js-identifier' // Invalid as a JavaScript identifier
+  | 'proto-not-allowed' // `__proto__` is not allowed
+  | 'default-not-allowed' // `default` is not allowed when namedExports is true
+  | 'backslash-not-allowed'; // Backslash (`\`) is not allowed
+
+export interface ValidateTokenNameOptions {
+  namedExports: boolean;
+}
+
+/**
+ * Validates a token name and returns the violation if any.
+ * @param name The token name to validate.
+ * @param options The validation options.
+ * @returns The violation, or `undefined` if the name is valid.
+ */
+export function validateTokenName(name: string, options: ValidateTokenNameOptions): TokenNameViolation | undefined {
+  if (name === '__proto__') return 'proto-not-allowed';
+  if (options.namedExports) {
+    if (name === 'default') return 'default-not-allowed';
+    if (!JS_IDENTIFIER_PATTERN.test(name)) return 'invalid-js-identifier';
+  } else {
+    if (name.includes('\\')) return 'backslash-not-allowed';
+  }
+  return undefined;
 }
 
 /**
  * The syntax pattern for consuming tokens imported from CSS Module.
- * @example `styles.foo`
+ * @example `styles.foo`, `styles['foo']`, `styles["foo"]`
  */
-// TODO(#125): Support `styles['foo']` and `styles["foo"]`
 // MEMO: The `xxxStyles.foo` format is not supported, because the css module file for current component file is usually imported with `styles`.
 //       It is sufficient to support only the `styles.foo` format.
-const TOKEN_CONSUMER_PATTERN = /styles\.([$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*)/gu;
+const TOKEN_CONSUMER_PATTERN =
+  /styles(?:\.([$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*)|\['([^']*?)'\]|\["([^"]*?)"\])/gu;
 
 export function findUsedTokenNames(componentText: string): Set<string> {
   const usedClassNames = new Set<string>();
-  let match;
-  while ((match = TOKEN_CONSUMER_PATTERN.exec(componentText)) !== null) {
-    usedClassNames.add(match[1]!);
+  for (const match of componentText.matchAll(TOKEN_CONSUMER_PATTERN)) {
+    const name = match[1] ?? match[2] ?? match[3];
+    if (name) usedClassNames.add(name);
   }
   return usedClassNames;
 }