feat(content-mapper): add an experimental content mapper for TypeScript 7

.changeset/add-content-mapper.md

@@ -0,0 +1,5 @@
+---
+'@css-modules-kit/content-mapper': minor
+---
+
+feat: add `@css-modules-kit/content-mapper`, an experimental content mapper for TypeScript 7

.vscode/launch.json

@@ -190,6 +190,34 @@
         "TSS_DEBUG": "5859"
       }
     },
+    {
+      "name": "content-mapper: tsc (7-content-mapper)",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}/examples/7-content-mapper",
+      "program": "${workspaceFolder}/packages/content-mapper/node_modules/typescript/bin/tsc",
+      "args": ["--noEmit", "--runExternalCode"],
+      "console": "integratedTerminal",
+      "preLaunchTask": "vp: build",
+      "presentation": {
+        "group": "content-mapper"
+      }
+    },
+    {
+      // Uses the default profile instead of `--profile-temp`, because the language server is provided by the TypeScript 7 extension installed there.
+      "name": "content-mapper: vscode (7-content-mapper)",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/vscode",
+        "--skip-welcome",
+        "--folder-uri=${workspaceFolder}/examples/7-content-mapper"
+      ],
+      "preLaunchTask": "vp: build",
+      "presentation": {
+        "group": "content-mapper"
+      }
+    },
     {
       "name": "vscode-test",
       "type": "extensionHost",

.vscode/tasks.json

@@ -36,6 +36,12 @@
         "cwd": "${workspaceFolder}/packages/vscode"
       },
       "group": "build"
+    },
+    {
+      "label": "vp: build",
+      "type": "shell",
+      "command": "vp run build",
+      "group": "build"
     }
   ]
 }

AGENTS.md

@@ -19,6 +19,7 @@ This project is a monorepo and consists of the following packages:
   - Wrapper to run ts-plugin in VS Code
 - **packages/stylelint-plugin**: Stylelint plugin
 - **packages/eslint-plugin**: ESLint plugin
+- **packages/content-mapper**: TypeScript content mapper that provides language features on TypeScript 7
 - **crates/zed**: Zed editor extension (Rust implementation)
   - Wrapper to run ts-plugin in Zed
 
@@ -149,7 +150,7 @@ function myFunction() {
 - Write PR descriptions and commit messages in English
 - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
   - `<type>` is one of: feat, fix, docs, refactor, test, chore, deps
-  - `[optional scope]`: choose one of core, ts-plugin, codegen, vscode, stylelint-plugin, eslint-plugin, zed
+  - `[optional scope]`: choose one of core, ts-plugin, codegen, vscode, stylelint-plugin, eslint-plugin, content-mapper, zed
     - For changes spanning multiple packages, use comma-separated scopes like `feat(core, ts-plugin): ...`
 - If you make changes that affect users, add a changeset file under `.changeset`
   - The changeset body must be a single summary line only.

CONTRIBUTING.md

@@ -30,6 +30,7 @@ You can run code in debug mode from the "Run and Debug" panel in VS Code. To sta
 - `eslint-plugin (...)`: Debug for `eslint-plugin` package
 - `stylelint (...)`: Debug for `stylelint` package
 - `vscode (...)`: Debug for `vscode` and `ts-plugin` package
+- `content-mapper: ...`: Run the `content-mapper` package on `examples/7-content-mapper`
 - `vscode-test`: Debug for `vp run vscode-test`
 
 Good to know:
@@ -40,6 +41,16 @@ Good to know:
 - In VS Code, you can view the Extension Host log with `F1 > Output: Show Output Channels... > Extension Host`.
   - If the extension fails to load, the log will be output there.
 
+### Content Mapper
+
+1. Install the [TypeScript 7](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) extension in VS Code
+1. Start `content-mapper: vscode (7-content-mapper)` from the "Run and Debug" panel
+1. Trust the workspace, and select "Allow" when asked whether to use the TypeScript 7 tsdk configured in the workspace
+
+Good to know:
+
+- In VS Code, you can view the language server log with `F1 > Output: Show Output Channels... > TypeScript 7`.
+
 ### Zed Extension
 
 Debugging Zed Extension is a bit tricky.

README.md

@@ -22,7 +22,7 @@ In addition, CSS Modules Kit provides various tools for CSS Modules (e.g., codeg
 
 ## Get Started
 
-See [docs/get-started.md](./docs/get-started.md).
+See [docs/get-started.md](./docs/get-started.md). If you use TypeScript 7, see [docs/get-started-ts7.md](./docs/get-started-ts7.md) (experimental).
 
 ## Playground
 
@@ -36,6 +36,7 @@ See [docs/get-started.md](./docs/get-started.md).
 - [`@css-modules-kit/codegen`](./packages/codegen/README.md)
 - [`@css-modules-kit/stylelint-plugin`](./packages/stylelint-plugin/README.md)
 - [`@css-modules-kit/eslint-plugin`](./packages/eslint-plugin/README.md)
+- [`@css-modules-kit/content-mapper`](./packages/content-mapper/README.md) (experimental)
 
 ## Supported Language Features
 

docs/get-started-ts7.md

@@ -0,0 +1,72 @@
+# Get Started (TypeScript 7)
+
+> [!WARNING]
+> TypeScript 7 support is experimental. Breaking changes may be introduced in any release.
+
+This guide is for projects that use TypeScript 7.1 or later. If you use TypeScript 6 or earlier, see [Get Started](./get-started.md).
+
+On TypeScript 7, CSS Modules Kit consists of the following two tools:
+
+- content-mapper ([`@css-modules-kit/content-mapper`](../packages/content-mapper/README.md))
+- linter-plugin ([`@css-modules-kit/stylelint-plugin`](../packages/stylelint-plugin/README.md) or [`@css-modules-kit/eslint-plugin`](../packages/eslint-plugin/README.md))
+
+ts-plugin and codegen do not work on TypeScript 7. content-mapper replaces both of them.
+
+This guide explains each tool and how to set it up.
+
+## Install content-mapper
+
+content-mapper is a TypeScript [content mapper](../packages/content-mapper/README.md#what-is-a-content-mapper) for CSS Modules. It makes TypeScript load `*.module.css` files directly, both in the editor and in `tsc`. Therefore, `.module.css.d.ts` files are not needed. Only a part of the features of ts-plugin is available. For details, see [Support Status](../packages/content-mapper/README.md#support-status).
+
+To install content-mapper, run the following command:
+
+```bash
+npm i -D @css-modules-kit/content-mapper
+```
+
+Register content-mapper in `tsconfig.json`.
+
+```json
+{
+  "contentMappers": [
+    {
+      "package": "@css-modules-kit/content-mapper",
+      "extensions": [".css"]
+    }
+  ]
+}
+```
+
+Make sure the [`include`](https://www.typescriptlang.org/tsconfig/#include) option includes `*.module.css` files. Otherwise, TypeScript does not load `*.module.css` files that are not imported from anywhere yet, so they get no diagnostics, and auto-import does not suggest them.
+
+- ✅ Good cases:
+  - Omit `include` (equivalent to `["**/*"]`)
+  - `["src"]` (equivalent to `["src/**/*"]`)
+  - `["src/**/*"]`
+- ❌ Bad cases:
+  - `["src/**/*.ts"]`
+  - `["src/index.ts"]`
+
+To type-check from the command line, pass `--runExternalCode` to `tsc`.
+
+```bash
+npx tsc --noEmit --runExternalCode
+```
+
+To use the language features in VS Code, install the [TypeScript 7](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) extension, and add the following to `.vscode/settings.json`. Then trust the workspace, and select "Allow" when asked whether to use the TypeScript 7 tsdk configured in the workspace.
+
+```json
+{
+  "js/ts.experimental.useTsgo": true,
+  "js/ts.tsdk.path": "node_modules/typescript"
+}
+```
+
+## Install linter-plugin
+
+The linter-plugin is a linter plugin for `*.module.css` files. Currently, we support the following linters:
+
+- [stylelint-plugin](../packages/stylelint-plugin/README.md)
+- [eslint-plugin](../packages/eslint-plugin/README.md)
+
+All linter plugins provide the same set of rules—choose and install whichever you prefer. For installation instructions, refer to their README files.

docs/get-started.md

@@ -1,5 +1,8 @@
 # Get Started
 
+> [!NOTE]
+> ts-plugin and codegen do not work on TypeScript 7. If you use TypeScript 7, see [Get Started (TypeScript 7)](./get-started-ts7.md).
+
 CSS Modules Kit consists of the following three tools:
 
 - ts-plugin ([`@css-modules-kit/ts-plugin`](../packages/ts-plugin/README.md))

examples/7-content-mapper/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["TypeScriptTeam.native-preview"]
+}

examples/7-content-mapper/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "js/ts.experimental.useTsgo": true,
+  "js/ts.tsdk.path": "../../packages/content-mapper/node_modules/typescript"
+}

examples/7-content-mapper/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@css-modules-kit/example-content-mapper",
+  "private": true,
+  "devDependencies": {
+    "@css-modules-kit/content-mapper": "workspace:*"
+  }
+}

examples/7-content-mapper/src/a.module.css

@@ -0,0 +1,11 @@
+@value primary: #2864f0;
+
+.a_1 {
+  color: primary;
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+}

examples/7-content-mapper/src/global.css

@@ -0,0 +1,3 @@
+* {
+  margin: 0;
+}

examples/7-content-mapper/src/index.ts

@@ -0,0 +1,7 @@
+import './global.css';
+import styles from './a.module.css';
+
+styles.a_1;
+styles.primary;
+styles['fade-in'];
+styles.unknown; // Expected TS2339 error

examples/7-content-mapper/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["ES2015"],
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+
+    "noEmit": true,
+    "incremental": false,
+    "types": [] // Simplify tsserver.log
+  },
+  "contentMappers": [
+    {
+      "package": "@css-modules-kit/content-mapper",
+      "extensions": [".css"]
+    }
+  ]
+}

packages/content-mapper/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mizdra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.