@teacss/postcss 0.1.0-alpha.1 → 0.3.0

package/LICENSE

@@ -1,7 +1,7 @@
-MIT License
+# MIT License
 
-Copyright (c) 2022 WorkOS
-Copyright (c) 2024 BillGO
+Copyright (c) 2021-PRESENT Anthony Fu <https://github.com/antfu>
+Copyright (c) 2026-PRESENT Billgo <hi@billgo.me>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1 +1,57 @@
-# @teacss/postcss-breakpoints
+# @teacss/postcss
+
+**PostCSS integration for TeaCSS.**
+
+## Purpose
+
+The plugin runs TeaCSS during the PostCSS pipeline, transforms TeaCSS CSS
+directives, and injects generated utilities into the current stylesheet.
+
+Use this package when PostCSS is the application's CSS build boundary. It owns
+TeaCSS's PostCSS plugin behavior and reports file and directory dependencies to
+the surrounding runner; the runner remains responsible for file watching and
+rebuilds. Projects whose Vite, Astro, Rsbuild, or Bun integration already owns
+TeaCSS generation do not need to add this plugin as a second pipeline.
+
+PostCSS is a host peer rather than a bundled runtime. Install one compatible
+PostCSS 8 copy in the application:
+
+```sh
+bun add teacss
+bun add -d @teacss/postcss postcss
+```
+
+## Usage
+
+```js
+import { pluginTeacss } from "teacss/postcss";
+
+export default {
+  plugins: [pluginTeacss()],
+};
+```
+
+```css
+@preset "standard";
+@source "./src/**/*.{ts,tsx,html}";
+@custom { --color-brand-500: #0f766e; }
+@teacss;
+```
+
+Use `@teacss;` to choose where generated utilities are injected.
+When a stylesheet has multiple `@teacss` insertion points, each generated layer
+is emitted at most once across bare, `all`, explicit, and negated layer forms.
+Use `@custom {}` to define theme values in the CSS entry; PostCSS resolves
+`theme("...")` in declaration values but does not provide an `@theme` at-rule.
+The plugin reports both file dependencies and stable directory dependencies for
+positive `@source` globs, so PostCSS runners can rebuild when a new matching file
+is created. If a glob's static root does not exist yet, the directory dependency
+falls back to its nearest existing parent. Relative `@source` globs resolve from
+the CSS entry directory, including when the discovered entry is nested at
+`src/index.css`.
+
+## Status
+
+Pre-1.0. Install `@teacss/postcss` beside `teacss`, then use the stable
+`teacss/postcss` facade subpath in applications. Integration authors may import
+`@teacss/postcss` directly when they intentionally do not use the facade.

package/dist/esm.d.mts

@@ -0,0 +1,21 @@
+import { UserConfig } from "@teacss/core";
+import { Result, Root } from "postcss";
+//#region src/types.d.ts
+interface TeacssPostcssPluginOptions {
+  content?: (string | {
+    raw: string;
+    extension: string;
+  })[];
+  directiveMap?: {
+    apply?: string;
+    screen?: string;
+    teacss?: string;
+  };
+  cwd?: string;
+  configOrPath?: string | UserConfig;
+}
+//#endregion
+//#region src/esm.d.ts
+declare function createPlugin(options: TeacssPostcssPluginOptions): (root: Root, result: Result) => Promise<void>;
+//#endregion
+export { createPlugin };

package/dist/esm.mjs

@@ -0,0 +1,440 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, extname, join, normalize, relative, resolve } from "node:path";
+import process from "node:process";
+import { createRecoveryConfigLoader, entryDiscoveryFiles, getConfigSourcesFromError } from "@teacss/config";
+import { createGenerator, expandVariantGroup, splitClassTokens } from "@teacss/core";
+import { hasIconFn, hasThemeFn } from "@teacss/rule-helpers";
+import { defaultFilesystemGlobs } from "@teacss/runtime";
+import postcss from "postcss";
+import { glob, isDynamicPattern } from "tinyglobby";
+import { formatMissingApplyTokens, missingApplyTokens, prepareApplyUtilities, renderStandaloneApplyUtility, resolveApplyTokens, resolveCssFunction, resolveScreenQuery } from "@teacss/directives/core";
+import { generate, parse, walk } from "css-tree";
+//#region src/apply.ts
+async function parseApply(root, generator, directiveName) {
+	const rules = [];
+	const lastParentAfterNode = /* @__PURE__ */ new Map();
+	const applyHosts = /* @__PURE__ */ new Map();
+	root.walkAtRules(directiveName, (rule) => {
+		rules.push(rule);
+	});
+	const resolvedRules = await Promise.all(rules.map(async (rule) => {
+		const parsed = await resolveApplyTokens(splitClassTokens(expandVariantGroup(rule.params)), generator);
+		const missing = missingApplyTokens(parsed);
+		if (missing.length) throw rule.error(formatMissingApplyTokens(missing));
+		return {
+			parsed,
+			rule
+		};
+	}));
+	for (const { parsed, rule } of resolvedRules) {
+		const hostRule = rule.parent;
+		if (!hostRule) continue;
+		const source = rule.source;
+		const utils = prepareApplyUtilities(parsed, generator.parentOrders);
+		if (!utils.length) {
+			rule.remove();
+			continue;
+		}
+		const parentAfterNodes = [];
+		let applyHost;
+		for (const utility of utils) if (utility.kind === "standalone") {
+			if (!applyHost) {
+				applyHost = applyHosts.get(hostRule);
+				if (!applyHost) {
+					let prelude;
+					if (hostRule.type === "rule") prelude = parse(hostRule.selector, { context: "selectorList" });
+					else prelude = parse(hostRule.toString(), { context: "rule" }).prelude;
+					const selector = generate(prelude);
+					applyHost = {
+						prelude,
+						selector,
+						replacementSelector: selector
+					};
+					applyHosts.set(hostRule, applyHost);
+				}
+			}
+			const css = renderStandaloneApplyUtility(applyHost, utility);
+			const parsedCss = postcss.parse(css);
+			parsedCss.walkDecls((declaration) => {
+				declaration.source = source;
+			});
+			parentAfterNodes.push(...parsedCss.nodes);
+		} else {
+			const css = postcss.parse(utility.body);
+			css.walkDecls((declaration) => {
+				declaration.source = source;
+			});
+			hostRule.insertAfter(rule, css);
+		}
+		if (parentAfterNodes.length) {
+			const anchor = lastParentAfterNode.get(hostRule);
+			if (anchor) anchor.after(parentAfterNodes);
+			else hostRule.after(parentAfterNodes);
+			lastParentAfterNode.set(hostRule, parentAfterNodes.at(-1));
+		}
+		rule.remove();
+		if (hostRule.type === "rule" && !hostRule.nodes?.length) hostRule.remove();
+	}
+}
+//#endregion
+//#region src/screen.ts
+async function parseScreen(root, generator, directiveName) {
+	root.walkAtRules(directiveName, (rule) => {
+		const query = resolveScreenQuery(rule.params, generator.config.theme);
+		if (!query) return;
+		rule.name = "media";
+		rule.params = query;
+	});
+}
+//#endregion
+//#region src/theme.ts
+async function parseTheme(root, generator) {
+	const tasks = [];
+	root.walkDecls((decl) => {
+		if (!hasThemeFn(decl.value) && !hasIconFn(decl.value)) return;
+		tasks.push(transformDeclarationValue(decl.value, generator).then((value) => {
+			decl.value = value;
+		}));
+	});
+	await Promise.all(tasks);
+}
+async function transformDeclarationValue(value, generator) {
+	const replacements = [];
+	const tasks = [];
+	walk(parse(value, {
+		context: "value",
+		parseCustomProperty: true,
+		positions: true
+	}), function(node) {
+		if (node.type !== "Function" || node.name !== "theme" && node.name !== "icon" || !node.loc) return;
+		tasks.push(resolveCssFunction(generator, node, (start, end) => value.slice(start, end)).then((replacement) => {
+			if (replacement === void 0) return;
+			replacements.push({
+				start: node.loc.start.offset,
+				end: node.loc.end.offset,
+				value: replacement
+			});
+		}));
+		return this.skip;
+	});
+	await Promise.all(tasks);
+	return applyReplacements(value, replacements);
+}
+function applyReplacements(value, replacements) {
+	let output = value;
+	for (const replacement of replacements.sort((a, b) => b.start - a.start)) output = `${output.slice(0, replacement.start)}${replacement.value}${output.slice(replacement.end)}`;
+	return output;
+}
+//#endregion
+//#region src/esm.ts
+const DEFAULT_GENERATED_IGNORE = [
+	"**/dist/**",
+	"**/build/**",
+	"**/storybook-static/**"
+];
+const MAX_CONFIG_STABILITY_ATTEMPTS = 5;
+function stripQueryAndHash(id) {
+	return id.replace(/[?#].*$/, "");
+}
+async function existingDirectory(target) {
+	let current = target;
+	while (true) {
+		try {
+			if ((await stat(current)).isDirectory()) return current;
+		} catch (error) {
+			const code = error.code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+		}
+		const parent = dirname(current);
+		if (parent === current) return current;
+		current = parent;
+	}
+}
+async function resolveDirectoryDependency(cwd, pattern, literal = false) {
+	if (pattern.startsWith("!")) return;
+	const absolute = resolve(cwd, pattern);
+	let staticPattern = pattern;
+	if (!literal) while (isDynamicPattern(staticPattern)) staticPattern = dirname(staticPattern);
+	let dir = resolve(cwd, staticPattern);
+	if (literal || staticPattern === pattern) dir = dirname(dir);
+	dir = await existingDirectory(dir);
+	return {
+		dir,
+		glob: relative(dir, absolute).replaceAll("\\", "/")
+	};
+}
+function fileSignature({ mtimeMs, ctimeMs, size, ino }) {
+	return `${mtimeMs}:${ctimeMs}:${size}:${ino}`;
+}
+async function readChangedFile(file, previousSignature) {
+	try {
+		const signature = fileSignature(await stat(file));
+		if (signature === previousSignature) return null;
+		return {
+			content: await readFile(file, "utf8"),
+			signature
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+function replaceRuleWithCss(rule, generatedCss) {
+	const css = postcss.parse(generatedCss);
+	css.walkDecls((declaration) => {
+		declaration.source = rule.source;
+	});
+	rule.replaceWith(css);
+}
+function replaceTeacssAtRules(root, generation, directiveName) {
+	const emittedLayers = /* @__PURE__ */ new Set();
+	root.walkAtRules(directiveName, (rule) => {
+		if (!rule.params) {
+			const layers = generation.layers.filter((layer) => !emittedLayers.has(layer));
+			replaceRuleWithCss(rule, generation.getLayers(layers) || "");
+			for (const layer of layers) emittedLayers.add(layer);
+			return;
+		}
+		const excludeLayers = [];
+		const includeLayers = [];
+		for (const layer of rule.params.split(",")) {
+			const name = layer.trim();
+			if (!name) continue;
+			if (name.startsWith("!")) {
+				if (name.slice(1)) excludeLayers.push(name.slice(1));
+			} else includeLayers.push(name);
+		}
+		if (excludeLayers.length > 0 && includeLayers.length > 0) console.warn(`Warning: Mixing normal and negated layer names in "@${directiveName} ${rule.params}" is not recommended.`);
+		let layers = [];
+		if (includeLayers.length > 0) {
+			const included = includeLayers.includes("all") ? generation.layers : includeLayers;
+			layers = included.filter((layer, index) => generation.layers.includes(layer) && included.indexOf(layer) === index && !emittedLayers.has(layer));
+		} else if (excludeLayers.length > 0) layers = generation.layers.filter((layer) => !excludeLayers.includes(layer) && !emittedLayers.has(layer));
+		replaceRuleWithCss(rule, generation.getLayers(layers) || "");
+		for (const layer of layers) emittedLayers.add(layer);
+	});
+}
+function createPlugin(options) {
+	const { cwd = process.cwd(), configOrPath } = options;
+	const configTarget = typeof configOrPath === "string" ? resolve(cwd, configOrPath) : cwd;
+	const hasInlineConfig = Boolean(configOrPath && typeof configOrPath === "object");
+	const hasExplicitEntry = typeof configOrPath === "string" && extname(configTarget).toLowerCase() === ".css";
+	const inlineOptionContent = (options.content ?? []).map((content, idx) => {
+		if (typeof content === "string") return content;
+		const extension = content.extension.replace(/^\./, "") || "html";
+		return {
+			code: content.raw,
+			id: `__postcss_content_${idx}.${extension}`
+		};
+	});
+	const directiveMap = {
+		apply: "apply",
+		screen: "screen",
+		teacss: "teacss",
+		...options.directiveMap
+	};
+	const loadConfig = createRecoveryConfigLoader();
+	let config;
+	const getConfig = () => {
+		config ??= loadConfig(cwd, configOrPath).catch((error) => {
+			config = void 0;
+			throw error;
+		});
+		return config;
+	};
+	const getConfigSourceFiles = (activeSources) => {
+		const files = new Set(activeSources);
+		if (hasInlineConfig) return files;
+		if (hasExplicitEntry) files.add(configTarget);
+		else for (const file of entryDiscoveryFiles) files.add(join(configTarget, file));
+		return files;
+	};
+	const getConfigSignature = async (activeSources) => {
+		if (hasInlineConfig) return "";
+		return (await Promise.all(Array.from(getConfigSourceFiles(activeSources)).sort().map(async (file) => {
+			try {
+				return `${file}:${fileSignature(await stat(file))}`;
+			} catch (error) {
+				if (error.code === "ENOENT") return `${file}:missing`;
+				throw error;
+			}
+		}))).join("|");
+	};
+	let generatorState;
+	let configRequestVersion = 0;
+	let pendingConfig;
+	async function getGeneratorState() {
+		const signature = await getConfigSignature(generatorState?.sources ?? []);
+		if (generatorState?.signature === signature) return generatorState;
+		if (pendingConfig?.signature === signature) return pendingConfig.promise;
+		const version = ++configRequestVersion;
+		const forceReload = Boolean(generatorState || pendingConfig || config);
+		let task;
+		task = (async () => {
+			let expectedSignature = signature;
+			let mustReload = forceReload;
+			let stableResolved;
+			let next;
+			for (let attempt = 0; attempt < MAX_CONFIG_STABILITY_ATTEMPTS; attempt++) {
+				const resolved = mustReload ? await loadConfig(cwd, configOrPath) : await getConfig();
+				const resolvedSignature = await getConfigSignature(resolved.sources);
+				if (resolvedSignature === expectedSignature) {
+					stableResolved = resolved;
+					next = {
+						generator: await createGenerator(resolved.config),
+						signature: resolvedSignature,
+						sources: resolved.sources,
+						entryDir: resolved.sources[0] ? dirname(resolved.sources[0]) : cwd,
+						fileMap: /* @__PURE__ */ new Map(),
+						fileClassMap: /* @__PURE__ */ new Map(),
+						scanRequestVersion: 0
+					};
+					break;
+				}
+				expectedSignature = resolvedSignature;
+				mustReload = true;
+			}
+			if (!stableResolved || !next) throw new Error(`TeaCSS config did not stabilize after ${MAX_CONFIG_STABILITY_ATTEMPTS} load attempts`);
+			if (configRequestVersion === version) {
+				config = Promise.resolve(stableResolved);
+				generatorState = next;
+				return next;
+			}
+			const latest = pendingConfig?.promise;
+			if (latest && latest !== task) return await latest;
+			return generatorState ?? next;
+		})();
+		pendingConfig = {
+			signature,
+			promise: task
+		};
+		try {
+			return await task;
+		} finally {
+			if (pendingConfig?.promise === task) pendingConfig = void 0;
+		}
+	}
+	const directiveNames = new Set(Object.values(directiveMap));
+	return async function plugin(root, result) {
+		const from = stripQueryAndHash(result.opts.from ?? "") || join(cwd, "__teacss_postcss_input.css");
+		let isTarget = false;
+		let isScanTarget = false;
+		root.walk((node) => {
+			if (node.type === "atrule") {
+				if (node.name === directiveMap.teacss) {
+					isTarget = true;
+					isScanTarget = true;
+					return false;
+				}
+				if (directiveNames.has(node.name)) isTarget = true;
+			} else if (!isTarget && node.type === "decl" && (hasThemeFn(node.value) || hasIconFn(node.value))) isTarget = true;
+		});
+		if (!isTarget) return;
+		const dependencyFiles = /* @__PURE__ */ new Set();
+		const dependencyDirectories = /* @__PURE__ */ new Set();
+		const addDependency = (file) => {
+			const normalized = normalize(file);
+			if (dependencyFiles.has(normalized)) return;
+			dependencyFiles.add(normalized);
+			result.messages.push({
+				type: "dependency",
+				plugin: directiveMap.teacss,
+				file: normalized,
+				parent: from
+			});
+		};
+		const addDirectoryDependency = async (base, pattern, literal = false) => {
+			const dependency = await resolveDirectoryDependency(base, pattern, literal);
+			if (!dependency) return;
+			const key = `${dependency.dir}\0${dependency.glob}`;
+			if (dependencyDirectories.has(key)) return;
+			dependencyDirectories.add(key);
+			result.messages.push({
+				type: "dir-dependency",
+				plugin: directiveMap.teacss,
+				...dependency,
+				parent: from
+			});
+		};
+		let state;
+		try {
+			state = await getGeneratorState();
+		} catch (error) {
+			for (const file of getConfigSourcesFromError(error)) {
+				addDependency(file);
+				await addDirectoryDependency(cwd, file, true);
+			}
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`TeaCSS config not found: ${message}`);
+		}
+		const { generator } = state;
+		for (const file of getConfigSourceFiles(state.sources)) addDependency(file);
+		await parseApply(root, generator, directiveMap.apply);
+		await parseTheme(root, generator);
+		await parseScreen(root, generator, directiveMap.screen);
+		if (!isScanTarget) {
+			if (result.opts.from) addDependency(from);
+			return;
+		}
+		const scanRequestVersion = ++state.scanRequestVersion;
+		const fileMap = new Map(state.fileMap);
+		const fileClassMap = new Map(state.fileClassMap);
+		const configuredGlobs = generator.config.content?.filesystem;
+		const globs = configuredGlobs ?? defaultFilesystemGlobs;
+		const scanCwd = configuredGlobs === void 0 ? cwd : state.entryDir;
+		for (const pattern of globs) await addDirectoryDependency(scanCwd, pattern);
+		const ignore = [...globs.some((i) => i.includes("node_modules")) ? [] : ["**/node_modules/**"], ...configuredGlobs === void 0 ? DEFAULT_GENERATED_IGNORE : []];
+		const plainContent = [...inlineOptionContent, ...generator.config.content?.inline ?? []];
+		const entries = await glob(globs, {
+			cwd: scanCwd,
+			absolute: true,
+			ignore,
+			expandDirectories: false
+		});
+		const activeFiles = new Set(entries);
+		for (const file of fileMap.keys()) if (!activeFiles.has(file)) fileMap.delete(file);
+		for (const file of fileClassMap.keys()) if (!activeFiles.has(file)) fileClassMap.delete(file);
+		const classes = /* @__PURE__ */ new Set();
+		const inlineMatches = await Promise.all(plainContent.map(async (c, idx) => {
+			if (typeof c === "function") c = await c();
+			if (typeof c === "string") c = { code: c };
+			return (await generator.generate(c.code, {
+				id: c.id ?? `__plain_content_${idx}__`,
+				preflights: false,
+				safelist: false
+			})).matched;
+		}));
+		for (const matched of inlineMatches) for (const candidate of matched) classes.add(candidate);
+		const BATCH_SIZE = 500;
+		const scanFile = async (file) => {
+			addDependency(file);
+			const source = await readChangedFile(file, fileMap.get(file));
+			if (source === void 0) {
+				fileMap.delete(file);
+				fileClassMap.delete(file);
+				return;
+			}
+			if (source === null) return;
+			const { matched } = await generator.generate(source.content, {
+				id: file,
+				preflights: false,
+				safelist: false
+			});
+			fileClassMap.set(file, matched);
+			fileMap.set(file, source.signature);
+		};
+		for (let i = 0; i < entries.length; i += BATCH_SIZE) await Promise.all(entries.slice(i, i + BATCH_SIZE).map(scanFile));
+		for (const file of [...fileClassMap.keys()].sort()) {
+			const set = fileClassMap.get(file);
+			for (const candidate of set) classes.add(candidate);
+		}
+		const generation = await generator.generate(classes);
+		if (state.scanRequestVersion === scanRequestVersion) {
+			state.fileMap = fileMap;
+			state.fileClassMap = fileClassMap;
+		}
+		replaceTeacssAtRules(root, generation, directiveMap.teacss);
+	};
+}
+//#endregion
+export { createPlugin };

package/dist/index.d.ts

@@ -1,11 +1,27 @@
-export { default as postcssBreakpoints } from '@teacss/postcss-breakpoints';
-export { default as postcssWhitespace } from '@teacss/postcss-whitespace';
-export { default as postcssAutoprefixer } from 'autoprefixer';
-export { default as postcssCombineDuplicatedSelectors } from 'postcss-combine-duplicated-selectors';
-export { default as postcssCustomMedia } from 'postcss-custom-media';
-export { default as postcssDiscardComments } from 'postcss-discard-comments';
-export { default as postcssDiscardDuplicates } from 'postcss-discard-duplicates';
-export { default as postcssDiscardEmpty } from 'postcss-discard-empty';
-export { default as postcssDiscardUnused } from 'postcss-discard-unused';
-export { default as postcssImport } from 'postcss-import';
-export { default as postcssNesting } from 'postcss-nesting';
+import { Result, Root } from "postcss";
+import { UserConfig } from "@teacss/core";
+//#region src/types.d.ts
+interface TeacssPostcssPluginOptions {
+  content?: (string | {
+    raw: string;
+    extension: string;
+  })[];
+  directiveMap?: {
+    apply?: string;
+    screen?: string;
+    teacss?: string;
+  };
+  cwd?: string;
+  configOrPath?: string | UserConfig;
+}
+//#endregion
+//#region src/index.d.ts
+declare function pluginTeacss(options?: TeacssPostcssPluginOptions): {
+  postcssPlugin: string;
+  plugins: ((root: Root, result: Result) => Promise<void>)[];
+};
+declare namespace pluginTeacss {
+  var postcss: boolean;
+}
+//#endregion
+export { TeacssPostcssPluginOptions, pluginTeacss };