support prioritizeNamedImports option

Author: mizdra

README.md

@@ -165,6 +165,26 @@ Determines whether to generate named exports in the d.ts file instead of a defau
 }
 ```
 
+### `cmkOptions.prioritizeNamedImports`
+
+Type: `boolean`, Default: `false`
+
+Whether to prioritize named imports over namespace imports when adding import statements. This option only takes effect when `cmkOptions.namedExports` is `true`.
+
+When this option is `true`, `import { button } from '...'` will be added. When this option is `false`, `import button from '...'` will be added.
+
+```jsonc
+{
+  "compilerOptions": {
+    // ...
+  },
+  "cmkOptions": {
+    "namedExports": true,
+    "prioritizeNamedImports": true,
+  },
+}
+```
+
 ## Limitations
 
 - Sass/Less are not supported to simplify the implementation

packages/core/src/config.test.ts

@@ -29,7 +29,8 @@ describe('readTsConfigFile', () => {
           "cmkOptions": {
             "dtsOutDir": "generated/cmk",
             "arbitraryExtensions": false,
-            "namedExports": true
+            "namedExports": true,
+            "prioritizeNamedImports": true
           }
         }
       `,
@@ -42,6 +43,7 @@ describe('readTsConfigFile', () => {
         dtsOutDir: 'generated/cmk',
         arbitraryExtensions: false,
         namedExports: true,
+        prioritizeNamedImports: true,
       },
       compilerOptions: expect.objectContaining({
         module: ts.ModuleKind.ESNext,

packages/core/src/config.ts

@@ -15,8 +15,8 @@ export interface CMKConfig {
   excludes: string[];
   dtsOutDir: string;
   arbitraryExtensions: boolean;
-  /** Whether to generate named exports in the d.ts file instead of a default export. */
   namedExports: boolean;
+  prioritizeNamedImports: boolean;
   /**
    * A root directory to resolve relative path entries in the config file to.
    * This is an absolute path.
@@ -71,6 +71,7 @@ interface UnnormalizedRawConfig {
   dtsOutDir?: string;
   arbitraryExtensions?: boolean;
   namedExports?: boolean;
+  prioritizeNamedImports?: boolean;
 }
 
 /**
@@ -148,6 +149,17 @@ function parseRawData(raw: unknown, tsConfigSourceFile: ts.TsConfigSourceFile):
         });
       }
     }
+    if ('prioritizeNamedImports' in raw.cmkOptions) {
+      if (typeof raw.cmkOptions.prioritizeNamedImports === 'boolean') {
+        result.config.prioritizeNamedImports = raw.cmkOptions.prioritizeNamedImports;
+      } else {
+        result.diagnostics.push({
+          category: 'error',
+          text: `\`prioritizeNamedImports\` in ${tsConfigSourceFile.fileName} must be a boolean.`,
+          // MEMO: Location information can be obtained from `tsConfigSourceFile.statements`, but this is complicated and will be omitted.
+        });
+      }
+    }
   }
   return result;
 }
@@ -242,6 +254,7 @@ export function readConfigFile(project: string): CMKConfig {
     dtsOutDir: join(basePath, config.dtsOutDir ?? 'generated'),
     arbitraryExtensions: config.arbitraryExtensions ?? false,
     namedExports: config.namedExports ?? false,
+    prioritizeNamedImports: config.prioritizeNamedImports ?? false,
     basePath,
     configFileName,
     compilerOptions,

packages/ts-plugin/src/language-plugin.ts

@@ -53,11 +53,16 @@ export function createCSSLanguagePlugin(
         // So, ts-plugin uses a fault-tolerant Parser to parse CSS.
         safe: true,
       });
-      const { text, mapping, linkedCodeMapping } = createDts(cssModule, {
+      // eslint-disable-next-line prefer-const
+      let { text, mapping, linkedCodeMapping } = createDts(cssModule, {
         resolver,
         matchesPattern,
         namedExports: config.namedExports,
       });
+      if (config.namedExports && !config.prioritizeNamedImports) {
+        // Export `styles` to appear in code completion suggestions
+        text += 'declare const styles: {};\nexport default styles;\n';
+      }
       return {
         id: 'main',
         languageId: LANGUAGE_ID,

packages/ts-plugin/src/language-service/feature/code-fix.ts

@@ -1,9 +1,9 @@
-import type { CMKConfig } from '@css-modules-kit/core';
-import { isComponentFileName } from '@css-modules-kit/core';
+import type { CMKConfig, Resolver } from '@css-modules-kit/core';
+import { isComponentFileName, isCSSModuleFile } from '@css-modules-kit/core';
 import type { Language } from '@volar/language-core';
 import ts from 'typescript';
 import { isCSSModuleScript } from '../../language-plugin.js';
-import { createPreferencesForCompletion } from '../../util.js';
+import { convertDefaultImportsToNamespaceImports, createPreferencesForCompletion } from '../../util.js';
 
 // ref: https://github.com/microsoft/TypeScript/blob/220706eb0320ff46fad8bf80a5e99db624ee7dfb/src/compiler/diagnosticMessages.json
 export const CANNOT_FIND_NAME_ERROR_CODE = 2304;
@@ -13,6 +13,7 @@ export function getCodeFixesAtPosition(
   language: Language<string>,
   languageService: ts.LanguageService,
   project: ts.server.Project,
+  resolver: Resolver,
   config: CMKConfig,
 ): ts.LanguageService['getCodeFixesAtPosition'] {
   // eslint-disable-next-line max-params
@@ -28,6 +29,11 @@ export function getCodeFixesAtPosition(
       ),
     );
 
+    if (config.namedExports && !config.prioritizeNamedImports) {
+      convertDefaultImportsToNamespaceImports(prior, fileName, resolver);
+      excludeNamedImports(prior, fileName, resolver);
+    }
+
     if (isComponentFileName(fileName)) {
       // If a user is trying to use a non-existent token (e.g. `styles.nonExistToken`), provide a code fix to add the token.
       if (errorCodes.includes(PROPERTY_DOES_NOT_EXIST_ERROR_CODE)) {
@@ -42,10 +48,29 @@ export function getCodeFixesAtPosition(
       }
     }
 
-    return prior;
+    return prior.filter((codeFix) => codeFix.changes.length > 0);
   };
 }
 
+/**
+ * Exclude code fixes that add named imports (e.g. `import { foo } from './a.module.css'`)
+ */
+function excludeNamedImports(codeFixes: ts.CodeFixAction[], fileName: string, resolver: Resolver): void {
+  for (const codeFix of codeFixes) {
+    if (codeFix.fixName !== 'import') continue;
+    const match = codeFix.description.match(/^Add import from "(.*)"$/u);
+    if (!match) continue;
+    const specifier = match[1]!;
+    const resolved = resolver(specifier, { request: fileName });
+    if (!resolved || !isCSSModuleFile(resolved)) continue;
+
+    for (const change of codeFix.changes) {
+      change.textChanges = change.textChanges.filter((textChange) => !textChange.newText.startsWith(`import {`));
+    }
+    codeFix.changes = codeFix.changes.filter((change) => change.textChanges.length > 0);
+  }
+}
+
 interface TokenConsumer {
   /** The token name (e.g. `foo` in `styles.foo`) */
   tokenName: string;

packages/ts-plugin/src/language-service/feature/completion.ts

@@ -1,7 +1,7 @@
-import type { CMKConfig } from '@css-modules-kit/core';
-import { getCssModuleFileName, isComponentFileName, STYLES_EXPORT_NAME } from '@css-modules-kit/core';
+import type { CMKConfig, Resolver } from '@css-modules-kit/core';
+import { getCssModuleFileName, isComponentFileName, isCSSModuleFile, STYLES_EXPORT_NAME } from '@css-modules-kit/core';
 import ts from 'typescript';
-import { createPreferencesForCompletion } from '../../util.js';
+import { convertDefaultImportsToNamespaceImports, createPreferencesForCompletion } from '../../util.js';
 
 export function getCompletionsAtPosition(
   languageService: ts.LanguageService,
@@ -20,7 +20,7 @@ export function getCompletionsAtPosition(
     if (isComponentFileName(fileName)) {
       const cssModuleFileName = getCssModuleFileName(fileName);
       for (const entry of prior.entries) {
-        if (isStylesEntryForCSSModuleFile(entry, cssModuleFileName)) {
+        if (isDefaultExportedStylesEntry(entry) && entry.data.fileName === cssModuleFileName) {
           // Prioritize the completion of the `styles' import for the current .ts file for usability.
           // NOTE: This is a hack to make the completion item appear at the top
           entry.sortText = '0';
@@ -30,21 +30,52 @@ export function getCompletionsAtPosition(
         }
       }
     }
+    if (config.namedExports && !config.prioritizeNamedImports) {
+      // When `namedExports` is enabled, you can write code as follows:
+      // ```tsx
+      // import { button } from './a.module.css';
+      // const Button = () => <button className={button}>Click me!</button>;
+      // ```
+      // However, it is more common to use namespace imports for styles.
+      // ```tsx
+      // import * as styles from './a.module.css';
+      // const Button = () => <button className={styles.button}>Click me!</button>;
+      // ```
+      // Therefore, completion for tokens like `button` is disabled.
+      prior.entries = prior.entries.filter((entry) => !isNamedExportedTokenEntry(entry));
+    }
     return prior;
   };
 }
 
+type DefaultExportedStylesEntry = ts.CompletionEntry & {
+  data: ts.CompletionEntryData;
+};
+
 /**
- * Check if the completion entry is the `styles` entry for the CSS module file.
+ * Check if the completion entry is the default exported `styles` entry.
  */
-function isStylesEntryForCSSModuleFile(entry: ts.CompletionEntry, cssModuleFileName: string) {
+function isDefaultExportedStylesEntry(entry: ts.CompletionEntry): entry is DefaultExportedStylesEntry {
   return (
     entry.name === STYLES_EXPORT_NAME &&
-    entry.data &&
+    entry.data !== undefined &&
     // eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison
     entry.data.exportName === ts.InternalSymbolName.Default &&
-    entry.data.fileName &&
-    entry.data.fileName === cssModuleFileName
+    entry.data.fileName !== undefined &&
+    isCSSModuleFile(entry.data.fileName)
+  );
+}
+
+/**
+ * Check if the completion entry is a named exported token entry.
+ */
+function isNamedExportedTokenEntry(entry: ts.CompletionEntry): boolean {
+  return (
+    entry.data !== undefined &&
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison
+    entry.data.exportName !== ts.InternalSymbolName.Default &&
+    entry.data.fileName !== undefined &&
+    isCSSModuleFile(entry.data.fileName)
   );
 }
 
@@ -56,3 +87,28 @@ function isClassNamePropEntry(entry: ts.CompletionEntry) {
     entry.isSnippet
   );
 }
+
+export function getCompletionEntryDetails(
+  languageService: ts.LanguageService,
+  resolver: Resolver,
+  config: CMKConfig,
+): ts.LanguageService['getCompletionEntryDetails'] {
+  // eslint-disable-next-line max-params
+  return (fileName, position, entryName, formatOptions, source, preferences, data) => {
+    const details = languageService.getCompletionEntryDetails(
+      fileName,
+      position,
+      entryName,
+      formatOptions,
+      source,
+      preferences,
+      data,
+    );
+    if (!details) return undefined;
+
+    if (config.namedExports && !config.prioritizeNamedImports && details.codeActions) {
+      convertDefaultImportsToNamespaceImports(details.codeActions, fileName, resolver);
+    }
+    return details;
+  };
+}

packages/ts-plugin/src/language-service/proxy.ts

@@ -4,7 +4,7 @@ import type { Language } from '@volar/language-core';
 import type ts from 'typescript';
 import { CMK_DATA_KEY, isCSSModuleScript } from '../language-plugin.js';
 import { getCodeFixesAtPosition } from './feature/code-fix.js';
-import { getCompletionsAtPosition } from './feature/completion.js';
+import { getCompletionEntryDetails, getCompletionsAtPosition } from './feature/completion.js';
 import { getApplicableRefactors, getEditsForRefactor } from './feature/refactor.js';
 import { getSemanticDiagnostics } from './feature/semantic-diagnostic.js';
 import { getSyntacticDiagnostics } from './feature/syntactic-diagnostic.js';
@@ -48,7 +48,8 @@ export function proxyLanguageService(
   proxy.getApplicableRefactors = getApplicableRefactors(languageService, project);
   proxy.getEditsForRefactor = getEditsForRefactor(languageService);
   proxy.getCompletionsAtPosition = getCompletionsAtPosition(languageService, config);
-  proxy.getCodeFixesAtPosition = getCodeFixesAtPosition(language, languageService, project, config);
+  proxy.getCompletionEntryDetails = getCompletionEntryDetails(languageService, resolver, config);
+  proxy.getCodeFixesAtPosition = getCodeFixesAtPosition(language, languageService, project, resolver, config);
 
   return proxy;
 }

packages/ts-plugin/src/util.ts

@@ -1,4 +1,4 @@
-import type { CMKConfig } from '@css-modules-kit/core';
+import { type CMKConfig, isCSSModuleFile, type Resolver, STYLES_EXPORT_NAME } from '@css-modules-kit/core';
 import ts from 'typescript';
 
 /** The error code used by tsserver to display the css-modules-kit error in the editor. */
@@ -27,3 +27,32 @@ export function createPreferencesForCompletion<T extends ts.UserPreferences>(pre
     autoImportFileExcludePatterns: [...(preferences.autoImportFileExcludePatterns ?? []), config.dtsOutDir],
   };
 }
+/**
+ * Convert default imports to namespace imports for CSS modules.
+ * For example, convert `import styles from './styles.module.css'` to `import * as styles from './styles.module.css'`.
+ */
+export function convertDefaultImportsToNamespaceImports(
+  codeFixes: ts.CodeFixAction[] | ts.CodeAction[],
+  fileName: string,
+  resolver: Resolver,
+): void {
+  for (const codeFix of codeFixes) {
+    if ('fixName' in codeFix && codeFix.fixName !== 'import') continue;
+    // Check if the code fix is to add an import for a CSS module.
+    const match = codeFix.description.match(/^Add import from "(.*)"$/u);
+    if (!match) continue;
+    const specifier = match[1]!;
+    const resolved = resolver(specifier, { request: fileName });
+    if (!resolved || !isCSSModuleFile(resolved)) continue;
+
+    // If the specifier is a CSS module, convert the import to a namespace import.
+    for (const change of codeFix.changes) {
+      for (const textChange of change.textChanges) {
+        textChange.newText = textChange.newText.replace(
+          `import ${STYLES_EXPORT_NAME} from`,
+          `import * as ${STYLES_EXPORT_NAME} from`,
+        );
+      }
+    }
+  }
+}