@ecopages/postcss-processor 0.2.0-alpha.1 → 0.2.0-alpha.11

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `@ecopages/postcss-processor` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Features
+
+- Added reusable runtime CSS loading, a public `PostcssProcessor` class, and build-adapter registration for the plugin.
+
+### Bug Fixes
+
+- Fixed runtime PostCSS config loading and stylesheet rebuilds for Tailwind-driven template changes.
+- Fixed direct stylesheet processing and preset output so Tailwind v4 preserves injected references and nested BEM selectors.
+
+### Tests
+
+- Added processor and preset coverage for the runtime CSS loader and build adapter flow.

package/README.md

@@ -1,56 +1,32 @@
-# PostCSS Processor
+# @ecopages/postcss-processor
 
-This module provides a PostCSS processor plugin for Ecopages and utility functions for processing CSS files and strings using PostCSS. It includes built-in presets for Tailwind CSS (v3 and v4).
+PostCSS processing pipeline for Ecopages. It provides a processor plugin that seamlessly integrates PostCSS into the Ecopages build system, and includes built-in presets for Tailwind CSS (v3 and v4).
 
 ## Features
 
-- **Ecopages Processor Plugin**: Seamless integration with Ecopages build system.
-- **Tailwind Presets**: Ready-to-use configurations for Tailwind CSS v3 and v4.
-- **Automatic Configuration**: Detects `postcss.config.{js,ts,etc}` automatically.
-- **Standalone Usage**: Process CSS files or strings directly.
-- **Bun Loader**: Automatically registers a Bun loader for importing CSS in TS/JS files.
+- **Ecopages Processor Plugin**: Hook right into the build pipeline.
+- **Tailwind Presets**: Pre-configured pipelines for Tailwind CSS v3 and v4.
+- **Automatic Configuration**: Detects existing `postcss.config.{js,ts,etc}`.
+- **Bun Loader**: Registers a Bun loader for importing CSS in TS/JS files.
 
-## Install
+## Installation
 
 ```bash
 bunx jsr add @ecopages/postcss-processor
 ```
 
-## Usage with Ecopages
+## Usage
 
-Integrate the processor into your `eco.config.ts` using one of the available presets.
-
-### Tailwind v3 Preset
-
-Includes `tailwindcss`, `autoprefixer`, `postcss-import`, `cssnano`.
-
-```bash
-bun add -D tailwindcss@3.4.19
-```
-
-```typescript
-// eco.config.ts
-import { ConfigBuilder } from '@ecopages/core';
-import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
-
-const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
-
-export default config;
-```
+Integrate the processor into your `eco.config.ts` using a preset.
 
 ### Tailwind v4 Preset (Recommended)
 
-Includes `@tailwindcss/postcss`, `autoprefixer`, `postcss-nested`, `cssnano`, and handles `@reference` injection for `@apply`.
-
-```bash
-bun add -D @tailwindcss/postcss tailwindcss
-```
+Requires `@tailwindcss/postcss` and `tailwindcss` to be installed.
 
 ```typescript
 // eco.config.ts
 import path from 'node:path';
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
 import { tailwindV4Preset } from '@ecopages/postcss-processor/presets/tailwind-v4';
 
@@ -58,7 +34,7 @@ const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin(
 			tailwindV4Preset({
-				referencePath: path.resolve(import.meta.dir, 'src/styles/app.css'),
+				referencePath: path.resolve(import.meta.dirname, 'src/styles/app.css'),
 			}),
 		),
 	])
@@ -67,53 +43,41 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-### Browser Support
-
-By default, the presets target a broad range of modern browsers (`>0.3%, not ie 11, not dead, not op_mini all`).
-
-To override this, add a `browserslist` configuration to your `package.json` or create a `.browserslistrc` file in your project root. The processor will automatically detect and use your custom configuration.
-
-### Custom Configuration
-
-You can also use a standard `postcss.config.js` file or pass plugins manually.
-
-**Using `postcss.config.js`:**
-Create the file in your root, and simply add `postcssProcessorPlugin()` to your config without arguments.
+### Tailwind v3 Preset
 
-**Manual Configuration:**
+Requires `tailwindcss@3`, `autoprefixer`, `postcss-import`, and `cssnano` to be installed.
 
 ```typescript
+// eco.config.ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
-import myPlugin from 'postcss-my-plugin';
+import { tailwindV3Preset } from '@ecopages/postcss-processor/presets/tailwind-v3';
+
+const config = await new ConfigBuilder().setProcessors([postcssProcessorPlugin(tailwindV3Preset())]).build();
 
-postcssProcessorPlugin({
-	plugins: {
-		'my-plugin': myPlugin(),
-	},
-});
+export default config;
 ```
 
-**Advanced Configuration:**
+## Custom Configuration
 
-For advanced use cases, use transformation hooks to modify CSS before or after processing:
+To use your own `postcss.config.js`, simply call `postcssProcessorPlugin()` without arguments.
+
+You can also pass raw plugins or transformation hooks manually:
 
 ```typescript
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { postcssProcessorPlugin } from '@ecopages/postcss-processor';
+import myPlugin from 'postcss-my-plugin';
 
 const config = await new ConfigBuilder()
 	.setProcessors([
 		postcssProcessorPlugin({
-			// Define a filter for files to process (defaults to /\.css$/)
 			filter: /\.css$/,
-			// Provide a function to transform input before processing
-			transformInput: async (css) => `/* My Custom Header */\n${css}`,
-			// Provide a function to transform output after processing
-			transformOutput: async (css) => css.replace('blue', 'red'),
-			// Explicitly provide plugins (overrides defaults)
 			plugins: {
-				/* custom plugins */
+				'my-plugin': myPlugin(),
 			},
+			transformInput: async (css) => `/* Header */\n${css}`,
+			transformOutput: async (css) => css.replace('blue', 'red'),
 		}),
 	])
 	.build();
@@ -121,9 +85,9 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-## Standalone Usage
+## Standalone Processing
 
-You can use the underlying processor functions directly:
+You can bypass Ecopages entirely and use the processor utilities directly:
 
 ```typescript
 import { PostCssProcessor } from '@ecopages/postcss-processor';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/postcss-processor",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.11",
   "description": "Postcss processor, transform string or postcss file to css",
   "keywords": [
     "postcss",
@@ -8,24 +8,16 @@
     "css"
   ],
   "license": "MIT",
-  "main": "./src/postcss-processor.ts",
+  "main": "./src/postcss-processor.js",
   "type": "module",
-  "types": "./src/postcss-processor.ts",
-  "files": [
-    "src"
-  ],
+  "types": "./src/postcss-processor.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/ecopages/ecopages.git",
     "directory": "packages/processors/postcss-processor"
   },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "release:jsr": "bunx jsr publish"
-  },
   "dependencies": {
-    "@ecopages/core": "workspace:*",
-    "@ecopages/file-system": "workspace:*",
+    "@ecopages/file-system": "0.2.0-alpha.11",
     "@ecopages/logger": "latest",
     "autoprefixer": "^10.4.0",
     "browserslist": "^4.28.1",
@@ -35,6 +27,7 @@
     "postcss-nested": "^7.0.2"
   },
   "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.11",
     "@tailwindcss/postcss": ">=4",
     "tailwindcss": ">=3"
   },
@@ -46,37 +39,50 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/bun": "latest",
-    "@types/postcss-import": "^14",
-    "postcss-simple-vars": "^7.0.1",
-    "tailwindcss": "^3.4.19"
-  },
   "exports": {
     ".": {
-      "default": "./src/index.ts",
-      "types": "./src/index.ts"
+      "default": "./src/index.js",
+      "types": "./src/index.d.ts"
     },
     "./postcss-processor": {
-      "default": "./src/postcss-processor.ts",
-      "types": "./src/postcss-processor.ts"
+      "default": "./src/postcss-processor.js",
+      "types": "./src/postcss-processor.d.ts"
     },
     "./plugin": {
-      "default": "./src/plugin.ts",
-      "types": "./src/plugin.ts"
+      "default": "./src/plugin.js",
+      "types": "./src/plugin.d.ts"
     },
     "./presets": {
-      "default": "./src/presets/index.ts",
-      "types": "./src/presets/index.ts"
+      "default": "./src/presets/index.js",
+      "types": "./src/presets/index.d.ts"
     },
     "./presets/tailwind-v3": {
-      "default": "./src/presets/tailwind-v3.ts",
-      "types": "./src/presets/tailwind-v3.ts"
+      "default": "./src/presets/tailwind-v3.js",
+      "types": "./src/presets/tailwind-v3.d.ts"
     },
     "./presets/tailwind-v4": {
-      "default": "./src/presets/tailwind-v4.ts",
-      "types": "./src/presets/tailwind-v4.ts"
+      "default": "./src/presets/tailwind-v4.js",
+      "types": "./src/presets/tailwind-v4.d.ts"
+    },
+    "./postcss-processor.ts": {
+      "default": "./src/postcss-processor.js",
+      "types": "./src/postcss-processor.d.ts"
+    },
+    "./plugin.ts": {
+      "default": "./src/plugin.js",
+      "types": "./src/plugin.d.ts"
+    },
+    "./presets.ts": {
+      "default": "./src/presets/index.js",
+      "types": "./src/presets/index.d.ts"
+    },
+    "./presets/tailwind-v3.ts": {
+      "default": "./src/presets/tailwind-v3.js",
+      "types": "./src/presets/tailwind-v3.d.ts"
+    },
+    "./presets/tailwind-v4.ts": {
+      "default": "./src/presets/tailwind-v4.js",
+      "types": "./src/presets/tailwind-v4.d.ts"
     }
   }
-}
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './plugin.js';
+export * from './postcss-processor.js';

package/src/index.js

@@ -0,0 +1,2 @@
+export * from "./plugin.js";
+export * from "./postcss-processor.js";

package/src/plugin.d.ts

@@ -0,0 +1,154 @@
+/**
+ * PostCssProcessorPlugin
+ * @module @ecopages/postcss-processor
+ */
+import { Processor, type ProcessorConfig } from '@ecopages/core/plugins/processor';
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type postcss from 'postcss';
+/**
+ * Record of PostCSS plugins keyed by name
+ */
+export type PluginsRecord = Record<string, postcss.AcceptedPlugin>;
+/**
+ * Lazily creates PostCSS plugins.
+ *
+ * This is primarily used in development when a non-CSS file change forces the
+ * processor to rebuild tracked stylesheets. Some plugins, including Tailwind,
+ * keep internal caches in long-lived plugin instances, so recreating them is
+ * required to pick up newly discovered classes.
+ */
+export type PluginFactoryRecord = Record<string, () => postcss.AcceptedPlugin>;
+/**
+ * Configuration for the PostCSS processor
+ */
+export interface PostCssProcessorPluginConfig {
+    /**
+     * Regex filter to match files to process
+     */
+    filter?: RegExp;
+    /**
+     * Function to transform the contents of the file.
+     * It can be handy to add a custom header or footer to the file.
+     * Useful for injecting Tailwind v4 `@reference` directives.
+     * @param contents The contents of the file
+     * @param filePath The absolute path to the CSS file being processed
+     * @returns The transformed contents
+     */
+    transformInput?: (contents: string | Buffer, filePath: string) => string | Promise<string>;
+    /**
+     * Function to transform the output CSS after PostCSS processing.
+     * It can be handy to add a custom header or footer to the processed CSS.
+     * @param css The processed CSS
+     * @returns The transformed CSS
+     */
+    transformOutput?: (css: string) => Promise<string> | string;
+    /**
+     * Custom PostCSS plugins to use instead of the default ones
+     * @default undefined (uses default plugins)
+     */
+    plugins?: PluginsRecord;
+    /**
+     * Factory functions for recreating stateful PostCSS plugins.
+     *
+     * When provided, Ecopages uses these factories to build a fresh plugin list
+     * for dependency-driven stylesheet rebuilds during development.
+     */
+    pluginFactories?: PluginFactoryRecord;
+}
+/**
+ * PostCssProcessorPlugin
+ * A Processor for transforming CSS files.
+ */
+export declare class PostCssProcessorPlugin extends Processor<PostCssProcessorPluginConfig> {
+    static DEFAULT_OPTIONS: Required<Pick<PostCssProcessorPluginConfig, 'filter'>>;
+    private buildContributionsPrepared;
+    private postcssPlugins;
+    private pluginFactories?;
+    private readonly runtimeCssCache;
+    private readonly trackedCssFiles;
+    private watchQueue;
+    /**
+     * Maps an imported CSS file path → set of tracked CSS entry files that import it.
+     * Used to resolve which parent entry files need re-processing when a dependency changes.
+     */
+    private readonly cssDependencyMap;
+    private getCssFilter;
+    private resolveProcessedCssPath;
+    private readProcessedCssFromDist;
+    private persistProcessedCss;
+    private prewarmRuntimeCssCache;
+    /**
+     * Regex to match CSS @import statements and extract the path.
+     * Handles: @import './foo.css'; @import "./foo.css"; @import url('./foo.css');
+     */
+    private static readonly CSS_IMPORT_REGEX;
+    /**
+     * Builds the CSS dependency map by scanning tracked CSS files for @import directives.
+     * Maps each imported file to the set of tracked entry files that import it (directly or transitively).
+     */
+    private buildCssDependencyMap;
+    /**
+     * Extracts resolved absolute paths of CSS files imported via @import in the given CSS content.
+     * Recursively follows imports to capture transitive dependencies.
+     * It skips bare module imports like @import 'tailwindcss'.
+     * It recursively follows imports to capture transitive dependencies.
+     */
+    private extractCssImports;
+    /**
+     * Resolves a changed CSS file to its parent entry file(s) if it is an @import dependency.
+     * Returns an empty array if the file is not an import dependency (i.e., it's an entry file itself).
+     */
+    private resolveEntryFiles;
+    private transformCssSync;
+    private transformCssAsync;
+    matchesFileFilter(filepath: string): boolean;
+    private materializePluginFactories;
+    private refreshConfiguredPlugins;
+    private enqueueWatchTask;
+    private getTrackedCssFiles;
+    private handleDependencyChange;
+    constructor(config?: Omit<ProcessorConfig<PostCssProcessorPluginConfig>, 'name' | 'description'>);
+    /**
+     * Handles CSS file changes during development.
+     * If the file is an @import dependency, re-processes the parent entry file(s) instead.
+     * Broadcasts a css-update event for hot reloading.
+     */
+    private handleCssChange;
+    /**
+     * Processes a CSS file and broadcasts a css-update event.
+     * Skips broadcast if the processed output hasn't changed.
+     */
+    private processAndBroadcast;
+    get buildPlugins(): EcoBuildPlugin[];
+    get plugins(): EcoBuildPlugin[];
+    /**
+     * Resolves the configured PostCSS plugin list before config build seals the
+     * app manifest.
+     *
+     * @remarks
+     * Runtime setup reuses this prepared list and only performs cache prewarming.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Prepares build contributions if not already done and prewarms the runtime CSS cache.
+     */
+    setup(): Promise<void>;
+    /**
+     * Get the PostCSS plugins from the options or a config file.
+     * Searches for postcss.config.{js,cjs,mjs,ts} in the root directory.
+     */
+    private collectPostcssPlugins;
+    /**
+     * Process CSS content
+     * @param fileAsString CSS content as string
+     * @param filePath Optional file path for resolving relative imports
+     * @returns Processed CSS
+     */
+    process(fileAsString: string, filePath?: string): Promise<string>;
+    processSync(fileAsString: string, filePath?: string): string;
+    /**
+     * Teardown the PostCSS processor.
+     */
+    teardown(): Promise<void>;
+}
+export declare const postcssProcessorPlugin: (config?: PostCssProcessorPluginConfig) => PostCssProcessorPlugin;