docs(useImportType): add caveat section (#2444)

crates/biome_js_analyze/src/lint/style/use_import_type.rs

@@ -34,6 +34,20 @@ declare_rule! {
     /// The rule ensures that all imports used only as a type use a type-only `import`.
     /// It also groups inline type imports into a grouped `import type`.
     ///
+    /// ## Caveat with TypeScript experimental decorators
+    ///
+    /// Some frameworks like Angular and NestJS rely on
+    /// [experimental TypeScript decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
+    /// which allow code to be generated based on type annotations.
+    /// This is mainly used for dependency injection.
+    ///
+    /// Since Biome doesn't know how a decorator is implemented,
+    /// it is unable to detect that an import used as a type is also used as a value in the code generated by a decorator.
+    /// This leads Biome to suggest importing some imports as type, which are actually used as value at runtime.
+    ///
+    /// We haven't found a way to support this pattern yet.
+    /// We recommend disabling this rule when using such decorators.
+    ///
     /// ## Options
     ///
     /// This rule respects the [`jsxRuntime`](https://biomejs.dev/reference/configuration/#javascriptjsxruntime)

website/src/content/docs/linter/rules/use-import-type.md

@@ -19,6 +19,20 @@ This also ensures that some modules are not loaded at runtime.
 The rule ensures that all imports used only as a type use a type-only `import`.
 It also groups inline type imports into a grouped `import type`.
 
+## Caveat with TypeScript experimental decorators
+
+Some frameworks like Angular and NestJS rely on
+[experimental TypeScript decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
+which allow code to be generated based on type annotations.
+This is mainly used for dependency injection.
+
+Since Biome doesn't know how a decorator is implemented,
+it is unable to detect that an import used as a type is also used as a value in the code generated by a decorator.
+This leads Biome to suggest importing some imports as type, which are actually used as value at runtime.
+
+We haven't found a way to support this pattern yet.
+We recommend disabling this rule when using such decorators.
+
 ## Options
 
 This rule respects the [`jsxRuntime`](https://biomejs.dev/reference/configuration/#javascriptjsxruntime)