Definition Context for Hover Info (#197)

* return definition context for hover info

* update E2E test

* return definition context of value declaration

* update E2E test

* add definition preview description in README

* add changelog

Author: mizdra

.changeset/big-badgers-roll.md

@@ -0,0 +1,6 @@
+---
+'@css-modules-kit/ts-plugin': minor
+'@css-modules-kit/core': minor
+---
+
+feat: support "Definition Preview for Hover"

README.md

@@ -39,6 +39,15 @@ https://github.com/user-attachments/assets/df1e2feb-2a1a-4bf5-ae70-1cac36d90409
 
 </details>
 
+<details>
+<summary>Definition Preview by Hover</summary>
+
+You can preview the definition with <kbd>Command</kbd> + <kbd>Hover</kbd> on macOS and VS Code (key bindings may vary depending on your OS and editor).
+
+https://github.com/user-attachments/assets/8d42acb8-2822-4fe6-89ce-8472c7065b8b
+
+</details>
+
 <details>
 <summary>Automatically update import statements when moving `*.module.css`</summary>
 

packages/core/src/parser/at-value-parser.test.ts

@@ -24,6 +24,18 @@ describe('parseAtValue', () => {
       [
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 19,
+                "line": 1,
+                "offset": 18,
+              },
+              "start": {
+                "column": 1,
+                "line": 1,
+                "offset": 0,
+              },
+            },
             "loc": {
               "end": {
                 "column": 13,
@@ -43,6 +55,18 @@ describe('parseAtValue', () => {
         },
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 25,
+                "line": 2,
+                "offset": 44,
+              },
+              "start": {
+                "column": 1,
+                "line": 2,
+                "offset": 20,
+              },
+            },
             "loc": {
               "end": {
                 "column": 20,
@@ -62,6 +86,18 @@ describe('parseAtValue', () => {
         },
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 14,
+                "line": 3,
+                "offset": 59,
+              },
+              "start": {
+                "column": 1,
+                "line": 3,
+                "offset": 46,
+              },
+            },
             "loc": {
               "end": {
                 "column": 13,
@@ -81,6 +117,18 @@ describe('parseAtValue', () => {
         },
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 29,
+                "line": 4,
+                "offset": 89,
+              },
+              "start": {
+                "column": 1,
+                "line": 4,
+                "offset": 61,
+              },
+            },
             "loc": {
               "end": {
                 "column": 15,
@@ -100,6 +148,18 @@ describe('parseAtValue', () => {
         },
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 35,
+                "line": 5,
+                "offset": 125,
+              },
+              "start": {
+                "column": 1,
+                "line": 5,
+                "offset": 91,
+              },
+            },
             "loc": {
               "end": {
                 "column": 15,
@@ -255,6 +315,18 @@ describe('parseAtValue', () => {
         },
         {
           "atValue": {
+            "declarationLoc": {
+              "end": {
+                "column": 28,
+                "line": 9,
+                "offset": 268,
+              },
+              "start": {
+                "column": 2,
+                "line": 9,
+                "offset": 242,
+              },
+            },
             "loc": {
               "end": {
                 "column": 20,

packages/core/src/parser/at-value-parser.ts

@@ -6,6 +6,11 @@ interface ValueDeclaration {
   name: string;
   // value: string; // unused
   loc: Location;
+  /**
+   * NOTE: The `declarationLoc` for value declaration does not include the trailing semicolon.
+   * @example `@value white: #fff` has `declarationLoc` as `{ start: { line: 1, column: 1, offset: 0 }, end: { line: 1, column: 19, offset: 18 } }`.
+   */
+  declarationLoc: Location;
 }
 
 interface ValueImportDeclaration {
@@ -149,7 +154,15 @@ export function parseAtValue(atValue: AtRule): ParseAtValueResult {
       column: start.column + name.length,
       offset: start.offset + name.length,
     };
-    const parsedAtValue = { type: 'valueDeclaration', name, loc: { start, end } } as const;
+    const parsedAtValue: ValueDeclaration = {
+      type: 'valueDeclaration',
+      name,
+      loc: { start, end },
+      declarationLoc: {
+        start: atValue.source!.start!,
+        end: atValue.positionBy({ index: atValue.toString().length }),
+      },
+    } as const;
     return { atValue: parsedAtValue, diagnostics };
   }
   diagnostics.push({