@analogjs/vite-plugin-angular 3.0.0-alpha.2 → 3.0.0-alpha.20

package/src/lib/angular-vite-plugin.d.ts

@@ -1,53 +1,153 @@
-import { NgtscProgram } from '@angular/compiler-cli';
-import * as ts from 'typescript';
-import { Plugin } from 'vite';
-import { FileReplacement } from './plugins/file-replacements.plugin.js';
+import { NgtscProgram } from "@angular/compiler-cli";
+import * as ts from "typescript";
+import { Plugin } from "vite";
+import type { StylePreprocessor } from "./style-preprocessor.js";
+import { FileReplacement } from "./plugins/file-replacements.plugin.js";
 export declare enum DiagnosticModes {
-    None = 0,
-    Option = 1,
-    Syntactic = 2,
-    Semantic = 4,
-    All = 7
+	None = 0,
+	Option = 1,
+	Syntactic = 2,
+	Semantic = 4,
+	All = 7
 }
 export interface PluginOptions {
-    tsconfig?: string | (() => string);
-    workspaceRoot?: string;
-    inlineStylesExtension?: string;
-    jit?: boolean;
-    advanced?: {
-        /**
-         * Custom TypeScript transformers that are run before Angular compilation
-         */
-        tsTransformers?: ts.CustomTransformers;
-    };
-    supportedBrowsers?: string[];
-    transformFilter?: (code: string, id: string) => boolean;
-    /**
-     * Additional files to include in compilation
-     */
-    include?: string[];
-    additionalContentDirs?: string[];
-    liveReload?: boolean;
-    disableTypeChecking?: boolean;
-    fileReplacements?: FileReplacement[];
-    experimental?: {
-        useAngularCompilationAPI?: boolean;
-    };
+	tsconfig?: string | (() => string);
+	workspaceRoot?: string;
+	inlineStylesExtension?: string;
+	jit?: boolean;
+	advanced?: {
+		/**
+		* Custom TypeScript transformers that are run before Angular compilation
+		*/
+		tsTransformers?: ts.CustomTransformers;
+	};
+	supportedBrowsers?: string[];
+	transformFilter?: (code: string, id: string) => boolean;
+	/**
+	* Additional files to include in compilation
+	*/
+	include?: string[];
+	additionalContentDirs?: string[];
+	liveReload?: boolean;
+	disableTypeChecking?: boolean;
+	fileReplacements?: FileReplacement[];
+	experimental?: {
+		useAngularCompilationAPI?: boolean;
+	};
+	/**
+	* Optional preprocessor that transforms component CSS before it enters Vite's
+	* preprocessCSS pipeline. Runs on every component stylesheet (both external
+	* `.component.css` files and inline `styles: [...]` blocks).
+	*
+	* @param code - Raw CSS content of the component stylesheet
+	* @param filename - Resolved file path of the stylesheet (or containing .ts file for inline styles)
+	* @returns Transformed CSS string, or the original code if no transformation is needed
+	*/
+	stylePreprocessor?: StylePreprocessor;
+	/**
+	* First-class Tailwind CSS v4 integration for Angular component styles.
+	*
+	* Angular's compiler processes component CSS through Vite's `preprocessCSS()`,
+	* which runs `@tailwindcss/vite` — but each component stylesheet is processed
+	* in isolation without access to the root Tailwind configuration (prefix, @theme,
+	* @custom-variant, @plugin definitions). This causes errors like:
+	*
+	*   "Cannot apply utility class `sa:grid` because the `sa` variant does not exist"
+	*
+	* The `tailwindCss` option solves this by auto-injecting a `@reference` directive
+	* into every component CSS file that uses Tailwind utilities, pointing it to the
+	* root Tailwind stylesheet so `@tailwindcss/vite` can resolve the full configuration.
+	*
+	* @example Basic usage — reference a root Tailwind CSS file:
+	* ```ts
+	* import { resolve } from 'node:path';
+	*
+	* angular({
+	*   tailwindCss: {
+	*     rootStylesheet: resolve(__dirname, 'src/styles/tailwind.css'),
+	*   },
+	* })
+	* ```
+	*
+	* @example With prefix detection — only inject for files using specific prefixes:
+	* ```ts
+	* angular({
+	*   tailwindCss: {
+	*     rootStylesheet: resolve(__dirname, 'src/styles/tailwind.css'),
+	*     // Only inject @reference into files that use these prefixed classes
+	*     prefixes: ['sa:', 'tw:'],
+	*   },
+	* })
+	* ```
+	*
+	* @example AnalogJS platform — passed through the `vite` option:
+	* ```ts
+	* analog({
+	*   vite: {
+	*     tailwindCss: {
+	*       rootStylesheet: resolve(__dirname, '../../../libs/meritos/tailwind.config.css'),
+	*     },
+	*   },
+	* })
+	* ```
+	*/
+	tailwindCss?: {
+		/**
+		* Absolute path to the root Tailwind CSS file that contains `@import "tailwindcss"`,
+		* `@theme`, `@custom-variant`, and `@plugin` definitions.
+		*
+		* A `@reference` directive pointing to this file will be auto-injected into
+		* component CSS files that use Tailwind utilities.
+		*/
+		rootStylesheet: string;
+		/**
+		* Optional list of class prefixes to detect (e.g. `['sa:', 'tw:']`).
+		* When provided, `@reference` is only injected into component CSS files that
+		* contain at least one of these prefixes. When omitted, `@reference` is injected
+		* into all component CSS files that contain `@apply` or `@` directives.
+		*
+		* @default undefined — inject into all component CSS files with `@apply`
+		*/
+		prefixes?: string[];
+	};
 }
 export declare function angular(options?: PluginOptions): Plugin[];
-export declare function getFileMetadata(program: ts.BuilderProgram, angularCompiler?: NgtscProgram['compiler'], liveReload?: boolean, disableTypeChecking?: boolean): (file: string) => {
-    errors?: undefined;
-    warnings?: undefined;
-    hmrUpdateCode?: undefined;
-    hmrEligible?: undefined;
-} | {
-    errors: string[];
-    warnings: (string | ts.DiagnosticMessageChain)[];
-    hmrUpdateCode: string | null | undefined;
-    hmrEligible: boolean;
+export declare function createFsWatcherCacheInvalidator(invalidateFsCaches: () => void, invalidateTsconfigCaches: () => void, performCompilation: () => Promise<void>): () => Promise<void>;
+/**
+* Convert Analog/Angular CLI-style file replacements into the flat record
+* expected by `AngularHostOptions.fileReplacements`.
+*
+* Only browser replacements (`{ replace, with }`) are converted. SSR-only
+* replacements (`{ replace, ssr }`) are left for the Vite runtime plugin to
+* handle — they should not be baked into the Angular compilation host because
+* that would apply them to both browser and server builds.
+*
+* Relative paths are resolved against `workspaceRoot` so that the host
+* receives the same absolute paths it would get from the Angular CLI.
+*/
+export declare function toAngularCompilationFileReplacements(replacements: FileReplacement[], workspaceRoot: string): Record<string, string> | undefined;
+/**
+* Map Angular's `templateUpdates` (keyed by `encodedFilePath@ClassName`)
+* back to absolute file paths with their associated HMR code and component
+* class name.
+*
+* Angular's private Compilation API emits template update keys in the form
+* `encodeURIComponent(relativePath + '@' + className)`. We decode and resolve
+* them so the caller can look up updates by the same normalized absolute path
+* used elsewhere in the plugin (`outputFiles`, `classNames`, etc.).
+*/
+export declare function mapTemplateUpdatesToFiles(templateUpdates: ReadonlyMap<string, string> | undefined): Map<string, {
+	className: string;
+	code: string;
+}>;
+export declare function getFileMetadata(program: ts.BuilderProgram, angularCompiler?: NgtscProgram["compiler"], liveReload?: boolean, disableTypeChecking?: boolean): (file: string) => {
+	errors?: string[];
+	warnings?: (string | ts.DiagnosticMessageChain)[];
+	hmrUpdateCode?: string | null;
+	hmrEligible?: boolean;
 };
 /**
- * Checks for vitest run from the command line
- * @returns boolean
- */
+* Checks for vitest run from the command line
+* @returns boolean
+*/
 export declare function isTestWatchMode(args?: string[]): boolean;