Merge pull request #749 from dev-five-git/feat/tailwind-v4-complete

feat(extractor): compile containers, masks, 3D transforms, functional @Utility and class helpers

Author: owjs3901

.changepacks/changepack_log_tailwind_v4_complete.json

@@ -0,0 +1,9 @@
+{
+  "changes": {
+    "bindings/devup-ui-wasm/package.json": "Patch",
+    "packages/rsbuild-plugin/package.json": "Patch",
+    "packages/bun-plugin/package.json": "Patch"
+  },
+  "note": "More of Tailwind CSS v4 compiles: container queries (@sm:, @max-md:, @min-[400px]:, @sm/main:) and @container utilities, mask-* (all but the gradient masks), text-shadow-*, inset-shadow-*, font-variant-numeric utilities (tabular-nums and the like), 3D transforms (rotate-x/y/z, translate-z, scale-z, translate-3d, scale-3d, transform-3d, backface-*, perspective-*, perspective-origin-*), contain-* and outline-hidden (with its forced-colors fallback). The project's Tailwind CSS is read further: functional @utility with --value() and --modifier(), @apply in @utility, and theme(--name) in arbitrary values; classes of @plugin entries stay as written. A className now compiles the classes of cn()/twMerge() calls whose arguments are all static (merged as tailwind-merge does, the later class wins), of consts bound to class strings, and of cva() calls (base, variants, compound variants). The Rsbuild plugin reads the Tailwind CSS again and compiles every module again when it changes, and the Bun plugin reads it again. No new build errors",
+  "date": "2026-10-01T00:00:00.000Z"
+}

apps/landing/src/app/(detail)/docs/migration/tailwind/page.mdx

@@ -31,9 +31,12 @@ A class is never rewritten into something different from what Tailwind CSS would
 Classes compile in the `className` of Devup UI components, and the build only reads what it can know:
 
 - string literals, template literals, `cond ? 'a' : 'b'`, `a && 'b'`, `a || 'b'` and parentheses,
-- the arguments of `clsx(...)`, `classnames(...)` and `classNames(...)` (strings, arrays, and the keys of objects), and `['a', cond && 'b'].join(' ')`.
+- a `const` of the same file bound to a string (`const base = 'p-4 card'`, read as the classes it holds wherever the `className` reads it; a `let`, a parameter or a template with `${}` is not),
+- the arguments of `clsx(...)`, `classnames(...)` and `classNames(...)` (strings, arrays, and the keys of objects), and `['a', cond && 'b'].join(' ')`, each class compiled where it is written,
+- `cn(...)` and `twMerge(...)` when **every** argument is a string, a template without `${}`, or an array of them: the build merges them as tailwind-merge does, so a Tailwind class that a later one sets again is dropped (`cn('p-4 m-2', 'p-2')` keeps `m-2` and `p-2`; a variant (`hover:p-2`), a breakpoint and `!` each count apart, and `px-4` and `p-2` both stay) and compiles what is left. `cn` is read as `twMerge(clsx(...))`: if your `cn` does something else, give it another name. A `cn()` with a condition or any other argument is left alone, since its result is only known at runtime and the strings in it must reach `twMerge` as written,
+- the strings of `cva(base, { variants, compoundVariants })` in a file that imports Devup UI: the base, every variant option and every compound variant `class`/`className` compile where they are written (`cva` only joins them, so each class stays a class). A file without a Devup UI import is not compiled at all, so put `cva` calls in a file that has one.
 
-Other helpers (`cn`, `twMerge`, `cva`) may merge or drop classes by rules the build does not run, so their strings are not compiled. A class that is only known at runtime (a variable, a prop, a computed string) cannot be compiled either. In every case the `className` keeps working as before, as plain text.
+A class that is only known at runtime (a prop, a computed string, an imported constant, a `cn()` with a condition) cannot be compiled. In every case the `className` keeps working as before, as plain text.
 
 A plain DOM element (`<div className="p-4" />`) or a component that is not a Devup UI component is **not** touched: its `className` is passed through as written, so Tailwind (its own build) can style it. Use `<Box as="div" className="p-4" />` when you want the class compiled.
 
@@ -72,7 +75,7 @@ The CSS file of your project that imports `tailwindcss` can define more, as it d
 @custom-variant theme-midnight (&:where([data-theme='midnight'] *));
 ```
 
-Every plugin reads the file when the build starts. The Vite, webpack and Next.js plugins also read it again when it, or a CSS file it imports with a relative path, changes (the Rsbuild and Bun plugins do not watch it, so restart them after a change). So `bg-brand`, `p-gutter`, `3xl:flex`, `animate-wiggle`, `content-auto` and `theme-midnight:bg-black` compile.
+Every plugin reads the file when the build starts, and again when it, or a CSS file it imports with a relative path, changes: Vite, webpack, Next.js and Rsbuild compile every module again, and the Bun plugin (a runtime plugin, with no rebuild of its own) reads the definitions again, so a module compiles with them the next time Bun loads it. So `bg-brand`, `p-gutter`, `3xl:flex`, `animate-wiggle`, `content-auto` and `theme-midnight:bg-black` compile.
 
 The file is found, in this order: the `tailwind.css` option of `devup.json`, else the first of `src/app/globals.css`, `app/globals.css`, `src/globals.css`, `src/index.css`, `src/styles/globals.css`, `src/styles.css`, `src/style.css`, `src/app.css`, `styles/globals.css`, `app/app.css` that imports `tailwindcss`.
 
@@ -84,9 +87,15 @@ The file is found, in this order: the `tailwind.css` option of `devup.json`, els
 
 Use `"css": false` to read none.
 
-What is read: `@theme` variables of the color, spacing (`--spacing`, `--spacing-*`), shadow, blur, radius, ease, animate, `default-transition-*` and breakpoint namespaces (and `@keyframes` inside `@theme`), resets such as `--color-*: initial` and `--*: initial`, `@utility` with plain declarations, and `@custom-variant` as a selector list, or a block holding `@slot;` in a selector, `@media` or `@supports`. A `@custom-variant` with the name of a built-in variant (`dark`) replaces it.
+What is read:
 
-What is not read keeps its classes as written: functional `@utility` (`tab-*` with `--value()`), nested rules and `@apply` in `@utility`, `@plugin`, `@config`, values using `theme()`, and a file whose braces do not balance. If the project changes the values of a namespace the build does not read (`--text-*`, `--font-*`, `--leading-*`, `--tracking-*`, `--container-*`, `--perspective-*`, `--aspect-*`), the classes that read it (`text-lg`, `font-bold`, `max-w-sm` ...) also stay as written, instead of compiling to a default the project replaced.
+- `@theme` variables of the color, spacing (`--spacing`, `--spacing-*`), shadow, inset-shadow, text-shadow, drop-shadow, blur, radius, ease, animate, perspective, container (`@sm:`), `default-transition-*` and breakpoint namespaces (and `@keyframes` inside `@theme`), and resets such as `--color-*: initial` and `--*: initial`.
+- `@utility name { ... }` with declarations and `@apply` lines. `@apply` writes out the utilities it names (`@apply px-4 py-2!`), also through other `@utility` that apply utilities; a utility with a variant (`hover:p-4`), one that styles children (`space-x-4`), an unknown one, or a loop leaves the whole `@utility` as written.
+- Functional `@utility name-* { ... }` whose declarations read `--value(...)` and `--modifier(...)`. An argument is `integer`, `number`, `percentage`, a literal (`'inherit'`), a theme namespace (`--tab-size-*`, `--color-*`, `--spacing-*`) or an arbitrary type (`[length]`, `[color]`, `[number]`, `[url]`); the first argument the value fits is used. A declaration that reads a `--modifier()` that is not given is dropped; a `--value()` no argument fits makes the class stay as written; `--spacing()`, `--alpha()` and the other functions of a utility are not run, so a utility using them stays as written.
+- `@custom-variant` as a selector list, or a block holding `@slot;` in a selector, `@media` or `@supports`. A `@custom-variant` with the name of a built-in variant (`dark`) replaces it.
+- `theme(--name)` in arbitrary values (`p-[theme(--spacing-gutter)]`, `bg-[theme(--color-brand)]`, `w-[calc(theme(--spacing)*2)]`): a theme variable of the project, a color, or a spacing step. A call for a variable the build cannot read (including the v3 form `theme(colors.red.500)`) makes the class stay as written.
+
+What is not read keeps its classes as written: `@plugin` and `@config` (they run JavaScript, whose output the build does not know: the classes a plugin such as `@tailwindcss/typography` makes, like `prose`, stay in the `className` for Tailwind's own build), nested rules in `@utility`, `theme()` in CSS (outside arbitrary values), `--theme()`, and a file whose braces do not balance. If the project changes the values of a namespace the build does not read (`--text-*`, `--font-*`, `--leading-*`, `--tracking-*`, `--container-*`, `--perspective-*`, `--aspect-*`), the classes that read it (`text-lg`, `font-bold`, `max-w-sm` ...) also stay as written, instead of compiling to a default the project replaced.
 
 ## Classes and style props on one element
 
@@ -98,4 +107,4 @@ Tailwind classes and Devup UI props both become one atomic class per property in
 
 ## What stays as written
 
-Utilities this build does not compile stay in the `className`: container (`container`, `@container` queries), the masks (`mask-*`), `text-shadow-*`, `inset-shadow-*`, composed font-variant-numeric (`tabular-nums`), 3D transform steps (`rotate-x-*`, `translate-z-*`, `scale-z-*`), `contain-*`, `outline-hidden`, and the variants and values that are not listed in Tailwind CSS v4.
+Utilities this build does not compile stay in the `className`: `container` (it sets a width per breakpoint, which one class cannot hold), the gradient masks (`mask-linear-*`, `mask-radial-*`, `mask-conic-*`, `mask-t|r|b|l|x|y-from|to-*`), and the variants and values that are not listed in Tailwind CSS v4. Container queries (`@sm:`, `@max-md:`, `@min-[400px]:`, `@sm/main:`) and the `@container` utilities, the other masks (`mask-none`, `mask-[...]`, sizes, positions, repeats, clips, origins, composites, modes), `text-shadow-*`, `inset-shadow-*`, `font-variant-numeric` (`tabular-nums` and the like, composing), 3D transforms (`rotate-x|y|z-*`, `translate-z-*`, `scale-z-*`, `translate-3d`, `scale-3d`, `transform-3d`, `backface-*`, `perspective-*`), `contain-*` and `outline-hidden` compile as Tailwind CSS v4 writes them.

libs/css/src/tailwind_definitions.rs

@@ -17,14 +17,26 @@ pub struct CustomVariant {
     pub at_rule: Option<(AtRuleKind, String)>,
 }
 
+/// One line of the body of an `@utility`
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum UtilityItem {
+    /// `property: value`
+    Declaration(String, String),
+    /// `@apply a b c`: the utilities that are applied
+    Apply(Vec<String>),
+}
+
 #[derive(Debug, Default)]
 struct Definitions {
     theme: BTreeMap<String, String>,
     /// Namespaces `--ns-*: initial` empties, such as `--color-`
     resets: BTreeSet<String>,
     /// `--*: initial` empties every namespace
     reset_all: bool,
-    utilities: BTreeMap<String, Vec<(String, String)>>,
+    utilities: BTreeMap<String, Vec<UtilityItem>>,
+    /// `@utility name-*`, by `name`: declarations that read `--value()` and
+    /// `--modifier()`
+    functional: BTreeMap<String, Vec<(String, String)>>,
     variants: BTreeMap<String, CustomVariant>,
     keyframes: BTreeMap<String, String>,
 }
@@ -137,6 +149,25 @@ fn compact(value: &str) -> String {
     out
 }
 
+/// The declarations and `@apply` lines of `body`, `None` when it holds anything
+/// else
+fn utility_items(body: &str) -> Option<Vec<UtilityItem>> {
+    parse_items(body)?
+        .into_iter()
+        .map(|item| match item {
+            Item::Statement(statement) => match statement.strip_prefix("@apply") {
+                Some(tokens) if tokens.starts_with(char::is_whitespace) => Some(
+                    UtilityItem::Apply(tokens.split_whitespace().map(str::to_string).collect()),
+                ),
+                Some(_) => None,
+                None => declaration(&statement)
+                    .map(|(property, value)| UtilityItem::Declaration(property, value)),
+            },
+            Item::Block(..) => None,
+        })
+        .collect()
+}
+
 /// `name: value` as the pair it declares
 fn declaration(statement: &str) -> Option<(String, String)> {
     let (name, value) = statement.split_once(':')?;
@@ -201,14 +232,24 @@ impl Definitions {
     }
 
     fn read_utility(&mut self, name: &str, body: &str) {
-        if name.is_empty() || name.contains('*') || name.contains(char::is_whitespace) {
+        if name.is_empty() || name.contains(char::is_whitespace) {
             return;
         }
-        if let Some(declarations) = declarations(body) {
-            self.utilities.insert(name.to_string(), declarations);
+        if let Some(root) = name.strip_suffix("-*") {
+            if let Some(declarations) =
+                declarations(body).filter(|_| !root.is_empty() && !root.contains('*'))
+            {
+                self.functional.insert(root.to_string(), declarations);
+            }
+            return;
+        }
+        if name.contains('*') {
+            return;
+        }
+        if let Some(items) = utility_items(body) {
+            self.utilities.insert(name.to_string(), items);
         }
     }
-
     fn read_custom_variant(&mut self, rest: &str, body: Option<&str>) {
         let rest = rest.trim();
         let (name, definition) = rest.split_once(char::is_whitespace).unwrap_or((rest, ""));
@@ -388,12 +429,18 @@ pub fn theme_keys(namespace: &str) -> Vec<String> {
     .unwrap_or_default()
 }
 
-/// The declarations of the `@utility` named `name`
+/// The body of the `@utility` named `name`
 #[must_use]
-pub fn custom_utility(name: &str) -> Option<Vec<(String, String)>> {
+pub fn custom_utility(name: &str) -> Option<Vec<UtilityItem>> {
     with(|definitions| definitions.utilities.get(name).cloned())
 }
 
+/// The declarations of the functional `@utility` named `<root>-*`
+#[must_use]
+pub fn functional_utility(root: &str) -> Option<Vec<(String, String)>> {
+    with(|definitions| definitions.functional.get(root).cloned())
+}
+
 /// The `@custom-variant` named `name`
 #[must_use]
 pub fn custom_variant(name: &str) -> Option<CustomVariant> {
@@ -475,19 +522,41 @@ mod tests {
     #[serial]
     fn utilities_are_static_declarations() {
         set_tailwind_css(
-            "@layer base { a { color: red } } @utility content-auto { content-visibility: auto; contain-intrinsic-size: 0 500px } @utility tab-* { tab-size: --value(integer); } @utility nested { &:hover { color: red } } @utility empty { } @utility two words { a: b }",
+            "@layer base { a { color: red } } @utility content-auto { content-visibility: auto; contain-intrinsic-size: 0 500px } @utility tab-* { tab-size: --value(integer); } @utility nested { &:hover { color: red } } @utility empty { } @utility two words { a: b } @utility btn { @apply px-4 py-2; color: red; } @utility bad-apply { @applyx a; } @utility any-* x { a: b } @utility -* { a: b } @utility a*b { a: b } @utility fn-* { a: b; &:hover { c: d } }",
         );
         assert_eq!(
             custom_utility("content-auto"),
             Some(vec![
-                ("content-visibility".to_string(), "auto".to_string()),
-                ("contain-intrinsic-size".to_string(), "0 500px".to_string()),
+                UtilityItem::Declaration("content-visibility".to_string(), "auto".to_string()),
+                UtilityItem::Declaration(
+                    "contain-intrinsic-size".to_string(),
+                    "0 500px".to_string()
+                ),
             ])
         );
         assert_eq!(custom_utility("tab-*"), None);
+        assert_eq!(
+            functional_utility("tab"),
+            Some(vec![(
+                "tab-size".to_string(),
+                "--value(integer)".to_string()
+            )])
+        );
         assert_eq!(custom_utility("nested"), None);
         assert_eq!(custom_utility("empty"), Some(vec![]));
         assert_eq!(custom_utility("two"), None);
+        assert_eq!(
+            custom_utility("btn"),
+            Some(vec![
+                UtilityItem::Apply(vec!["px-4".to_string(), "py-2".to_string()]),
+                UtilityItem::Declaration("color".to_string(), "red".to_string()),
+            ])
+        );
+        assert_eq!(custom_utility("bad-apply"), None);
+        assert_eq!(functional_utility("any"), None);
+        assert_eq!(functional_utility("fn"), None);
+        assert_eq!(functional_utility(""), None);
+        assert_eq!(custom_utility("a*b"), None);
         set_tailwind_css("");
     }