weapp-tailwindcss 5.2.14 → 5.3.0

package/README.md

@@ -1,17 +1,64 @@
 # weapp-tailwindcss
 
-> 简体中文 | [English](./README.en.md)
+> English | [简体中文](./README.zh-CN.md)
 
-这个包是把 Tailwind CSS 带到小程序生态的核心入口，负责类名转译、CSS 兼容、框架构建适配和 Tailwind v4 支持。
+Bring Tailwind CSS to every platform. `weapp-tailwindcss` is the core compiler and build integration layer for delivering utility-first styles to Web, mini programs, and native cross-platform runtimes.
 
-## 官网
+## What it provides
 
-更多接入方式、配置说明和框架示例见 [weapp-tailwindcss 官方文档](https://tw.icebreaker.top)。
+- Tailwind CSS v4 generation through a shared compiler boundary.
+- Vite, Webpack, Rspack, Gulp, PostCSS, and Node.js integration points.
+- Precise class transformation based on the generated Tailwind candidate set.
+- CSS compatibility transforms for WeChat, Alipay, ByteDance, QQ, and other mini-program style environments.
+- Shared generation foundations for React Native, Expo, ReactLynx, and Rspeedy integrations.
 
-Tailwind CSS 4 项目中，入口 CSS 需要同时满足两点：在项目里被实际引入，并通过 `cssEntries` 显式传给插件用于稳定识别。`cssEntries` 应使用项目根目录解析出的绝对路径；它不是替代 import 的开关。
+## Choose an integration
 
-## 运行环境
+| Target | Recommended entry |
+| --- | --- |
+| Web / H5 | `weapp-tailwindcss/vite`, Webpack/Rspack integration, or `@weapp-tailwindcss/cli` |
+| uni-app / uni-app x | Vite or Webpack integration selected by the framework build chain |
+| Taro / Mpx / native mini programs | Vite, Webpack, Rspack, or Gulp integration |
+| React Native / Expo | `@weapp-tailwindcss/react-native` |
+| ReactLynx / Rspeedy | `@weapp-tailwindcss/lynx` |
 
-从 `weapp-tailwindcss@5.2.0` 开始，需要 Node.js `>=22.12.0`。该版本默认支持从 CommonJS 加载 ESM。
+Start with the [installation guide](https://tw.icebreaker.top/docs/quick-start/install) or select a framework from the [documentation website](https://tw.icebreaker.top/).
 
-通过 HBuilderX 使用 `uni-app` 或 `uni-app x` 时，还需要 HBuilderX `>=5.11`。旧版 HBuilderX 的内置 Node 可能无法加载当前依赖中的 ESM 模块。
+## Tailwind CSS 4 entry
+
+Your CSS entry must be imported by the application build graph. Configure `cssEntries` with absolute paths resolved from the project root when stable entry discovery is required, but do not treat it as a replacement for importing the CSS file.
+
+```css
+@import "tailwindcss";
+@source "./src";
+```
+
+Tailwind generation remains owned by `weapp-tailwindcss`. Do not add `@tailwindcss/vite` or `@tailwindcss/postcss` as a second generator in the same build.
+
+## CLI
+
+Install the independently published CLI together with this package and Tailwind CSS:
+
+```bash
+pnpm add -D @weapp-tailwindcss/cli weapp-tailwindcss tailwindcss
+pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch
+```
+
+The CLI generates Web CSS by default. `--target weapp` performs CSS-only mini-program compatibility conversion; complete WXML, JavaScript, and WXSS projects still require a bundler integration. Watch mode uses `@parcel/watcher` native events by default and supports explicit polling with `--poll`.
+
+See the [CLI guide](https://tw.icebreaker.top/docs/tools/weapp-tw-cli) for source maps, stdin/stdout, watch mode, and `canonicalize`.
+
+## Runtime requirements
+
+- Node.js `^22.18.0 || >=24.11.0` for the current release line.
+- HBuilderX `>=5.11` when using uni-app or uni-app x through HBuilderX.
+
+## Community and support
+
+- [Documentation](https://tw.icebreaker.top/)
+- [GitHub Issues](https://github.com/sonofmagic/weapp-tailwindcss/issues)
+- [GitHub Discussions](https://github.com/sonofmagic/weapp-tailwindcss/discussions)
+
+## License
+
+[MIT](../../LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,64 @@
+# weapp-tailwindcss
+
+> [English](./README.md) | 简体中文
+
+把 Tailwind CSS 的原子化开发体验带到全端。`weapp-tailwindcss` 是面向 Web、小程序与原生跨端运行时的核心编译器和构建集成层。
+
+## 核心能力
+
+- 通过统一编译边界生成 Tailwind CSS v4 样式。
+- 提供 Vite、Webpack、Rspack、Gulp、PostCSS 与 Node.js 接入入口。
+- 基于 Tailwind 已生成候选集合精确转换 class，避免误伤业务字符串。
+- 处理微信、支付宝、抖音、QQ 等小程序样式环境的 CSS 兼容差异。
+- 为 React Native、Expo、ReactLynx 与 Rspeedy 集成提供共享生成基础。
+
+## 选择接入方式
+
+| 目标 | 推荐入口 |
+| --- | --- |
+| Web / H5 | `weapp-tailwindcss/vite`、Webpack/Rspack 集成或 `@weapp-tailwindcss/cli` |
+| uni-app / uni-app x | 按框架构建链选择 Vite 或 Webpack 集成 |
+| Taro / Mpx / 原生小程序 | Vite、Webpack、Rspack 或 Gulp 集成 |
+| React Native / Expo | `@weapp-tailwindcss/react-native` |
+| ReactLynx / Rspeedy | `@weapp-tailwindcss/lynx` |
+
+从[安装指南](https://tw.icebreaker.top/zh-cn/docs/quick-start/install)开始，或在[中文官网](https://tw.icebreaker.top/zh-cn/)按框架选择接入方式。
+
+## Tailwind CSS 4 入口
+
+CSS 入口必须被应用构建图实际引入。需要稳定识别入口时，通过 `cssEntries` 配置从项目根目录解析出的绝对路径，但不要把它当成 CSS import 的替代品。
+
+```css
+@import "tailwindcss";
+@source "./src";
+```
+
+Tailwind 样式生成统一由 `weapp-tailwindcss` 接管，同一构建中不要再叠加 `@tailwindcss/vite` 或 `@tailwindcss/postcss` 作为第二套生成器。
+
+## CLI
+
+独立 CLI 需要与本包和 Tailwind CSS 一起安装：
+
+```bash
+pnpm add -D @weapp-tailwindcss/cli weapp-tailwindcss tailwindcss
+pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch
+```
+
+CLI 默认生成 Web CSS。`--target weapp` 只进行小程序 CSS 兼容转换；完整 WXML、JavaScript 与 WXSS 项目仍需使用构建器集成。watch 默认使用 `@parcel/watcher` 原生事件，也可以通过 `--poll` 显式切换轮询。
+
+source map、stdin/stdout、watch 与 `canonicalize` 的完整用法见 [CLI 指南](https://tw.icebreaker.top/zh-cn/docs/tools/weapp-tw-cli)。
+
+## 运行环境
+
+- 当前版本需要 Node.js `^22.18.0 || >=24.11.0`。
+- 通过 HBuilderX 使用 uni-app 或 uni-app x 时需要 HBuilderX `>=5.11`。
+
+## 社区与支持
+
+- [官方文档](https://tw.icebreaker.top)
+- [GitHub Issues](https://github.com/sonofmagic/weapp-tailwindcss/issues)
+- [技术交流群](https://tw.icebreaker.top/zh-cn/docs/community/group)
+
+## License
+
+[MIT](../../LICENSE)

package/dist/bundlers/rspack/rule-match.d.ts

@@ -0,0 +1,13 @@
+export interface RspackRuleLike {
+    exclude?: unknown;
+    include?: unknown;
+    oneOf?: unknown[];
+    resource?: unknown;
+    resourceQuery?: unknown;
+    rules?: unknown[];
+    test?: unknown;
+    type?: unknown;
+    use?: unknown;
+    [key: string]: unknown;
+}
+export declare function resolveRuleCssMatch(rule: RspackRuleLike): boolean | undefined;

package/dist/bundlers/vite/generate-bundle/root-style-output.d.ts

@@ -41,4 +41,11 @@ export declare function restoreFrameworkRootMiniProgramImportShellAssets(bundle:
     shouldKeep: (file: string, css: string) => boolean | undefined;
     targetByFile: ReadonlyMap<string, string>;
 }): number;
+export declare function linkFrameworkRootStyleToRuntimeEntry(bundle: OutputBundle, options: {
+    debug?: ((format: string, ...args: unknown[]) => void) | undefined;
+    matchesCss: (file: string) => boolean;
+    onUpdate?: ((file: string, oldVal: string, newVal: string) => void) | undefined;
+    recordCssAssetResult?: ((file: string, css: string) => void) | undefined;
+    targetByFile: ReadonlyMap<string, string>;
+}): 1 | 0;
 export declare function shouldMoveRootMiniProgramStyleToImportShellOrigin(enabled: boolean | undefined): enabled is true;

package/dist/bundlers/vite/shared/create-framework-plugins.d.ts

@@ -18,6 +18,7 @@ export interface ViteFrameworkBranchContext {
     getExtraPluginPlatform?: () => ViteFrameworkExtraPluginPlatform;
     styleInjectorDelegate: ViteStyleInjectorDelegateFactory;
     isRuntimeClassSetFeatureEnabled?: (context: ViteFrameworkRuntimeFeatureContext) => boolean;
+    sourceCandidatesBeforeExtraPlugin?: (plugin: Plugin) => boolean;
 }
 export interface ViteFrameworkExtraPluginContext {
     customAttributesEntities: ReturnType<typeof toCustomAttributesEntities>;

package/dist/bundlers/vite/shared/framework-plugin-order.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function orderFrameworkSourceCandidatePlugins(extraPlugins: Plugin[], rewritePlugins: Plugin[], sourceCandidatesPlugin: Plugin, beforeExtraPlugin?: (plugin: Plugin) => boolean): Plugin<any>[];

package/dist/{transform-BiHG42Rp.cjs → component-local-style-BirkN5f8.cjs}

@@ -1,7 +1,6 @@
 const require_object = require("./object-DbHtAXRk.cjs");
 const require_wxml = require("./wxml-CQmBCjOR.cjs");
 let _tailwindcss_mangle_engine = require("@tailwindcss-mangle/engine");
-let _vue_compiler_dom = require("@vue/compiler-dom");
 //#region src/uni-app-x/component-local-style-binding.ts
 const OPTIONS_CLASS_SECTIONS = /* @__PURE__ */ new Set(["computed", "methods"]);
 function readStaticName(path) {
@@ -120,6 +119,10 @@ function extractLiteralValue(path) {
 function createAlias(fileId, utility, index) {
 	return `wtu-${createStableHash(`${fileId}:${utility}`)}-${index.toString(36)}`;
 }
+function serializeApplyUtility(utility) {
+	if (!utility.endsWith("!") || utility.endsWith("\\!")) return utility;
+	return `${utility.slice(0, -1)}#{'!'}`;
+}
 function isRuntimeCandidate(candidate, runtimeSet) {
 	if (!runtimeSet || runtimeSet.size === 0) return false;
 	return runtimeSet.has(candidate) || runtimeSet.has(require_wxml.replaceWxml(candidate));
@@ -179,6 +182,7 @@ var UniAppXComponentLocalStyleCollector = class {
 		require_object._defineProperty(this, "aliasByUtility", /* @__PURE__ */ new Map());
 		require_object._defineProperty(this, "aliasByLookup", /* @__PURE__ */ new Map());
 		require_object._defineProperty(this, "classBindingNames", /* @__PURE__ */ new Set());
+		require_object._defineProperty(this, "deepUtilities", /* @__PURE__ */ new Set());
 	}
 	ensureAlias(utility) {
 		const cached = this.aliasByUtility.get(utility);
@@ -199,8 +203,12 @@ var UniAppXComponentLocalStyleCollector = class {
 		}
 		return rewritten;
 	}
-	collectAndRewriteStaticClass(literal) {
-		return this.rewriteLiteral(literal);
+	collectAndRewriteStaticClass(literal, options = {}) {
+		const rewritten = this.rewriteLiteral(literal);
+		if (options.deep) {
+			for (const candidate of (0, _tailwindcss_mangle_engine.splitCandidateTokens)(literal)) if (this.aliasByUtility.has(candidate)) this.deepUtilities.add(candidate);
+		}
+		return rewritten;
 	}
 	collectRuntimeClasses(rawSource, options = {}) {
 		const wrapped = options.wrapExpression ? `${EXPRESSION_WRAPPER_PREFIX}${rawSource}${EXPRESSION_WRAPPER_SUFFIX}` : rawSource;
@@ -218,7 +226,10 @@ var UniAppXComponentLocalStyleCollector = class {
 				const classContext = options.wrapExpression || require_wxml.isClassContextLiteralPath(path) || isClassBindingLiteralPath(path, classBindingRoots);
 				for (const candidate of candidates) {
 					if (!candidate || !classContext || !isRuntimeCandidate(candidate, this.runtimeSet)) continue;
-					if (!hasTopLevelVariant(candidate)) this.ensureAlias(candidate);
+					if (!hasTopLevelVariant(candidate)) {
+						this.ensureAlias(candidate);
+						if (options.deep) this.deepUtilities.add(candidate);
+					}
 				}
 			}
 		} catch {}
@@ -282,176 +293,30 @@ var UniAppXComponentLocalStyleCollector = class {
 		if (!this.hasStyles()) return "";
 		const lines = [];
 		for (const [utility, alias] of this.aliasByUtility) {
-			lines.push(`.${alias} {`);
-			lines.push(`  @apply ${utility};`);
+			const selector = this.deepUtilities.has(utility) ? `.${alias}, :deep(.${alias})` : `.${alias}`;
+			lines.push(`${selector} {`);
+			lines.push(`  @apply ${serializeApplyUtility(utility)};`);
 			lines.push("}");
 		}
 		return `${lines.join("\n")}\n`;
 	}
 };
 //#endregion
-//#region src/uni-app-x/transform.ts
-function traverse(node, visitor) {
-	visitor(node);
-	if (Array.isArray(node.children)) {
-		for (const child of node.children) if (child && typeof child === "object" && "type" in child) traverse(child, visitor);
+Object.defineProperty(exports, "UniAppXComponentLocalStyleCollector", {
+	enumerable: true,
+	get: function() {
+		return UniAppXComponentLocalStyleCollector;
 	}
-}
-function updateStaticAttribute(ms, prop, offset, content = prop.value?.content) {
-	if (!prop.value) return;
-	const start = offset + prop.value.loc.start.offset + 1;
-	const end = offset + prop.value.loc.end.offset - 1;
-	if (start < end) ms.update(start, end, require_wxml.replaceWxml(content ?? ""));
-}
-function updateStaticAttributeWithLocalStyle(ms, prop, offset, collector, content = prop.value?.content) {
-	if (!prop.value) return;
-	const start = offset + prop.value.loc.start.offset + 1;
-	const end = offset + prop.value.loc.end.offset - 1;
-	if (start < end) ms.update(start, end, collector.collectAndRewriteStaticClass(content ?? ""));
-}
-function updateDirectiveExpression(ms, prop, offset, jsHandler, runtimeSet) {
-	if (prop.exp?.type !== _vue_compiler_dom.NodeTypes.SIMPLE_EXPRESSION) return;
-	const expression = prop.exp.content;
-	const start = offset + prop.exp.loc.start.offset;
-	const end = offset + prop.exp.loc.end.offset;
-	if (start >= end) return;
-	const generated = require_wxml.generateCode(expression, {
-		jsHandler,
-		runtimeSet,
-		wrapExpression: true
-	});
-	ms.update(start, end, generated);
-}
-function updateDirectiveExpressionWithLocalStyle(ms, prop, offset, jsHandler, collector, runtimeSet) {
-	if (prop.exp?.type !== _vue_compiler_dom.NodeTypes.SIMPLE_EXPRESSION) return;
-	const expression = prop.exp.content;
-	const start = offset + prop.exp.loc.start.offset;
-	const end = offset + prop.exp.loc.end.offset;
-	if (start >= end) return;
-	collector.collectRuntimeClasses(expression, { wrapExpression: true });
-	const generated = require_wxml.generateCode(expression, {
-		jsHandler,
-		runtimeSet,
-		wrapExpression: true
-	});
-	ms.update(start, end, collector.rewriteTransformedCode(generated, { wrapExpression: true }));
-}
-function shouldEnableLocalStyle(id, options) {
-	if (options.enableComponentLocalStyle && shouldEnableComponentLocalStyle(id)) return true;
-	if (options.enablePageLocalStyle && shouldEnablePageLocalStyle(id)) return true;
-	return false;
-}
-function shouldHandleAttribute(tag, attrName, disabledDefaultTemplateHandler, matchCustomAttribute) {
-	const lowerName = attrName.toLowerCase();
-	const shouldHandleDefault = !disabledDefaultTemplateHandler && lowerName === "class";
-	const shouldHandleCustom = matchCustomAttribute?.(tag, attrName) ?? false;
-	return {
-		shouldHandleDefault,
-		shouldHandleCustom,
-		shouldHandle: shouldHandleDefault || shouldHandleCustom
-	};
-}
-const defaultCreateJsHandlerOptions = { babelParserOptions: { plugins: ["typescript"] } };
-const UVUE_NVUE_RE = /\.(?:uvue|nvue)(?:\?.*)?$/;
-const SFC_BLOCK_RE = /<(template|script|style)\b([^>]*)>([\s\S]*?)<\/\1>/gi;
-const SCRIPT_SETUP_RE = /(?:^|\s)setup(?:\s|=|$)/;
-const STYLE_SCOPED_RE = /(?:^|\s)scoped(?:\s|=|$)/i;
-function parseSfc(code) {
-	const descriptor = {
-		errors: [],
-		styles: []
-	};
-	for (const match of code.matchAll(SFC_BLOCK_RE)) {
-		const type = match[1];
-		const attrs = match[2] ?? "";
-		const content = match[3] ?? "";
-		const full = match[0];
-		const contentStart = (match.index ?? 0) + full.indexOf(">") + 1;
-		const block = {
-			content,
-			start: contentStart,
-			end: contentStart + content.length,
-			attrs
-		};
-		if (type === "template" && !descriptor.template) {
-			try {
-				descriptor.template = {
-					...block,
-					ast: (0, _vue_compiler_dom.parse)(content)
-				};
-			} catch (error) {
-				descriptor.errors.push(error);
-				descriptor.template = block;
-			}
-			continue;
-		}
-		if (type === "script") {
-			if (SCRIPT_SETUP_RE.test(attrs)) descriptor.scriptSetup ?? (descriptor.scriptSetup = block);
-			else descriptor.script ?? (descriptor.script = block);
-			continue;
-		}
-		if (type === "style") descriptor.styles.push(block);
+});
+Object.defineProperty(exports, "shouldEnableComponentLocalStyle", {
+	enumerable: true,
+	get: function() {
+		return shouldEnableComponentLocalStyle;
 	}
-	return descriptor;
-}
-function transformUVue(code, id, jsHandler, runtimeSet, options = {}) {
-	if (!UVUE_NVUE_RE.test(id)) return;
-	const { customAttributesEntities, disabledDefaultTemplateHandler = false } = options;
-	const matchCustomAttribute = require_wxml.createAttributeMatcher(customAttributesEntities);
-	const ms = new require_wxml.MagicString(code);
-	const descriptor = parseSfc(code);
-	const localStyleCollector = shouldEnableLocalStyle(id, options) ? new UniAppXComponentLocalStyleCollector(id, runtimeSet) : void 0;
-	if (descriptor.errors.length === 0) {
-		if (descriptor.template?.ast) {
-			const templateOffset = descriptor.template.start;
-			traverse(descriptor.template.ast, (node) => {
-				if (node.type !== _vue_compiler_dom.NodeTypes.ELEMENT) return;
-				const tag = node.tag;
-				for (const prop of node.props) if (prop.type === _vue_compiler_dom.NodeTypes.ATTRIBUTE) {
-					const { shouldHandle, shouldHandleDefault } = shouldHandleAttribute(tag, prop.name, disabledDefaultTemplateHandler, matchCustomAttribute);
-					if (!shouldHandle) continue;
-					if (shouldHandleDefault && localStyleCollector) updateStaticAttributeWithLocalStyle(ms, prop, templateOffset, localStyleCollector);
-					else updateStaticAttribute(ms, prop, templateOffset);
-					if (shouldHandleDefault) continue;
-				} else if (prop.type === _vue_compiler_dom.NodeTypes.DIRECTIVE && prop.name === "bind" && prop.arg?.type === _vue_compiler_dom.NodeTypes.SIMPLE_EXPRESSION && prop.arg.isStatic) {
-					const attrName = prop.arg.content;
-					const { shouldHandle } = shouldHandleAttribute(tag, attrName, disabledDefaultTemplateHandler, matchCustomAttribute);
-					if (!shouldHandle) continue;
-					if (attrName.toLowerCase() === "class" && localStyleCollector) updateDirectiveExpressionWithLocalStyle(ms, prop, templateOffset, jsHandler, localStyleCollector, runtimeSet);
-					else updateDirectiveExpression(ms, prop, templateOffset, jsHandler, runtimeSet);
-				}
-			});
-		}
-		if (descriptor.script) {
-			localStyleCollector?.collectRuntimeClasses(descriptor.script.content);
-			const { code } = jsHandler(descriptor.script.content, runtimeSet ?? /* @__PURE__ */ new Set(), defaultCreateJsHandlerOptions);
-			ms.update(descriptor.script.start, descriptor.script.end, localStyleCollector ? localStyleCollector.rewriteTransformedCode(code) : code);
-		}
-		if (descriptor.scriptSetup) {
-			localStyleCollector?.collectRuntimeClasses(descriptor.scriptSetup.content);
-			const { code } = jsHandler(descriptor.scriptSetup.content, runtimeSet ?? /* @__PURE__ */ new Set(), defaultCreateJsHandlerOptions);
-			ms.update(descriptor.scriptSetup.start, descriptor.scriptSetup.end, localStyleCollector ? localStyleCollector.rewriteTransformedCode(code) : code);
-		}
-		if (localStyleCollector?.hasStyles()) {
-			const scopedStyle = descriptor.styles.findLast((style) => STYLE_SCOPED_RE.test(style.attrs));
-			if (scopedStyle) {
-				const separator = scopedStyle.content.endsWith("\n") ? "" : "\n";
-				ms.appendLeft(scopedStyle.end, `${separator}${localStyleCollector.toStyleRules()}`);
-			} else ms.append(`\n${localStyleCollector.toStyleBlock()}`);
-		}
+});
+Object.defineProperty(exports, "shouldEnablePageLocalStyle", {
+	enumerable: true,
+	get: function() {
+		return shouldEnablePageLocalStyle;
 	}
-	const result = {
-		code: ms.toString(),
-		map: null
-	};
-	Object.defineProperty(result, "map", {
-		configurable: true,
-		enumerable: true,
-		get() {
-			return ms.generateMap();
-		}
-	});
-	return result;
-}
-//#endregion
-exports.transformUVue = transformUVue;
+});