@analogjs/vite-plugin-angular 3.0.0-alpha.3 → 3.0.0-alpha.30

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

@@ -1,48 +1,232 @@
-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 { ModuleNode, Plugin, ViteDevServer } from "vite";
+import type { StylePreprocessor } from "./style-preprocessor.js";
+import { type DebugOption } from "./utils/debug.js";
+import { FileReplacement } from "./plugins/file-replacements.plugin.js";
+import { AnalogStylesheetRegistry } from "./stylesheet-registry.js";
+import { type AngularStylePipelineOptions } from "./style-pipeline.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[];
+	/**
+	* Enables Angular's HMR during development/watch mode.
+	*
+	* Defaults to `true` for watch mode. Set to `false` to disable HMR while
+	* keeping other stylesheet externalization behavior available when needed.
+	*/
+	hmr?: boolean;
+	/**
+	* @deprecated Use `hmr` instead. Kept as a compatibility alias.
+	*/
+	liveReload?: boolean;
+	disableTypeChecking?: boolean;
+	fileReplacements?: FileReplacement[];
+	experimental?: {
+		useAngularCompilationAPI?: boolean;
+	};
+	/**
+	* Enable debug logging for specific scopes.
+	*
+	* - `true` → enables all `analog:angular:*` scopes
+	* - `string[]` → enables listed namespaces (e.g. `['analog:angular:tailwind']`)
+	* - `{ scopes?, mode? }` → object form with optional `mode: 'build' | 'dev'`
+	*   to restrict output to a specific Vite command (omit for both)
+	*
+	* Also responds to the `DEBUG` env var (Node.js) or `localStorage.debug`
+	* (browser), using the `obug` convention.
+	*/
+	debug?: DebugOption;
+	/**
+	* 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;
+	/**
+	* Experimental Angular stylesheet-resource hooks for community-maintained
+	* style-pipeline plugins.
+	*
+	* These hooks run inside the Angular resource pipeline, which is the seam a
+	* standalone Vite plugin cannot own on its own.
+	*/
+	stylePipeline?: AngularStylePipelineOptions;
+	/**
+	* 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 normalizeIncludeGlob(workspaceRoot: string, glob: string): string;
+export declare function evictDeletedFileMetadata(file: string, { removeActiveGraphMetadata, removeStyleOwnerMetadata, classNamesMap, fileTransformMap }: {
+	removeActiveGraphMetadata: (file: string) => void;
+	removeStyleOwnerMetadata: (file: string) => void;
+	classNamesMap: Map<string, string>;
+	fileTransformMap: Map<string, string>;
+}): void;
+export declare function injectViteIgnoreForHmrMetadata(code: string): string;
+export declare function isIgnoredHmrFile(file: string): boolean;
 export declare function angular(options?: PluginOptions): Plugin[];
-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;
+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;
+}>;
+/**
+* Returns every live Vite module that can legitimately represent a changed
+* Angular resource file.
+*
+* For normal files, `getModulesByFile()` is enough. For Angular component
+* stylesheets, it is not: the browser often holds virtual hashed requests
+* (`/abc123.css?direct&ngcomp=...` and `/abc123.css?ngcomp=...`) that are no
+* longer discoverable from the original source path alone. We therefore merge:
+* - watcher event modules
+* - module-graph modules by source file
+* - registry-tracked live request ids resolved back through the module graph
+*/
+export declare function getModulesForChangedFile(server: ViteDevServer, file: string, eventModules?: readonly ModuleNode[], stylesheetRegistry?: AnalogStylesheetRegistry): Promise<ModuleNode[]>;
+export declare function isModuleForChangedResource(mod: ModuleNode, changedFile: string, stylesheetRegistry?: AnalogStylesheetRegistry): boolean;
+/**
+* Refreshes any already-served stylesheet records that map back to a changed
+* source file.
+*
+* This is the critical bridge for externalized Angular component styles during
+* HMR. Angular's resource watcher can notice that `/src/...component.css`
+* changed before Angular recompilation has had a chance to repopulate the
+* stylesheet registry. If we emit a CSS update against the existing virtual
+* stylesheet id without first refreshing the registry content, the browser gets
+* a hot update containing stale CSS. By rewriting the existing served records
+* from disk up front, HMR always pushes the latest source content.
+*/
+export declare function refreshStylesheetRegistryForFile(file: string, stylesheetRegistry?: AnalogStylesheetRegistry, stylePreprocessor?: StylePreprocessor): void;
+export declare function findComponentStylesheetWrapperModules(server: ViteDevServer, changedFile: string, directModule: ModuleNode, fileModules: ModuleNode[], stylesheetRegistry?: AnalogStylesheetRegistry): Promise<ModuleNode[]>;
+interface TemplateClassBindingIssue {
+	line: number;
+	column: number;
+	snippet: string;
+}
+export declare function findStaticClassAndBoundClassConflicts(template: string): TemplateClassBindingIssue[];
+export declare function findBoundClassAndNgClassConflicts(template: string): TemplateClassBindingIssue[];
+export declare function findTemplateOwnerModules(server: ViteDevServer, resourceFile: string): ModuleNode[];
+export declare function getFileMetadata(program: ts.BuilderProgram, angularCompiler?: NgtscProgram["compiler"], hmrEnabled?: 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;
+export {};