feat(useSortedClasses): sort @container and other bare utilities with modifiers (#11356)

Author: johncarmack1984

.changeset/tailwind-bare-utility-modifiers.md

@@ -0,0 +1,5 @@
+---
+"@biomejs/biome": patch
+---
+
+The Tailwind parser now understands modifiers on bare utilities (`@container/sidebar`, `shadow/50`).

crates/biome_js_analyze/Cargo.toml

@@ -20,6 +20,10 @@ name    = "js_analyzer"
 harness = false
 name    = "use_sorted_classes_parser"
 
+[[bench]]
+harness = false
+name    = "use_sorted_classes_v4"
+
 [dependencies]
 biome_analyze             = { workspace = true }
 biome_analyze_macros      = { workspace = true }

crates/biome_js_analyze/benches/fixtures/modifier_classes.txt

@@ -0,0 +1 @@
+group/menu peer/toggle group-hover/menu:flex group-hover/menu:opacity-100 group-focus/menu:visible peer-checked/toggle:bg-blue-500 peer-checked/toggle:text-white peer-hover/tab:underline peer-focus/tab:ring-2 group-has-[:checked]/row:bg-slate-50 group-data-[state=open]/item:rotate-180 dark:group-hover/menu:bg-slate-800 sm:peer-checked/toggle:ring-4 md:group-hover/menu:flex @container @container/sidebar @sm:grid @sm:grid-cols-2 @md:grid-cols-3 @lg/sidebar:flex @sm/main:text-sm @max-md:hidden @max-lg/main:flex-col @min-[400px]:p-4 @[400px]:gap-2 @[24rem]/card:rounded-lg @7xl:max-w-none min-[600px]:columns-2 max-[900px]:hidden min-sm:text-xs [&_p]:text-slate-600 [&_svg]:size-4 [&\_literal]:underline [&>li]:mt-2 [&.active]:font-bold hover/broken:flex w-1/2 bg-red-500/50 bg-red-500/[.35] group-hover/[.5]:opacity-75

crates/biome_js_analyze/benches/use_sorted_classes_v4.rs

@@ -0,0 +1,65 @@
+use biome_js_analyze::lint::nursery::use_sorted_classes::sort_v4::sort_class_list;
+use biome_tailwind_parser::parse_tailwind;
+use criterion::{BenchmarkId, Criterion, Throughput, black_box, criterion_group, criterion_main};
+
+#[cfg(target_os = "windows")]
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
+#[cfg(all(
+    any(target_os = "macos", target_os = "linux"),
+    not(target_env = "musl")
+))]
+#[global_allocator]
+static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+
+#[cfg(all(target_env = "musl", target_os = "linux", target_arch = "aarch64"))]
+#[global_allocator]
+static GLOBAL: std::alloc::System = std::alloc::System;
+
+// The full work a wired rule does per class string: parse the Tailwind
+// candidate list and sort it with the v4 engine.
+const CLASS_STRING_FIXTURES: &[(&str, &str)] = &[
+    (
+        "simple_classes",
+        include_str!("fixtures/simple_classes.txt"),
+    ),
+    (
+        "variant_classes",
+        include_str!("fixtures/variant_classes.txt"),
+    ),
+    (
+        "arbitrary_classes",
+        include_str!("fixtures/arbitrary_classes.txt"),
+    ),
+    (
+        "modifier_classes",
+        include_str!("fixtures/modifier_classes.txt"),
+    ),
+    ("stress", include_str!("fixtures/stress.txt")),
+    (
+        "extreme_stress",
+        include_str!("fixtures/extreme_stress.txt"),
+    ),
+];
+
+fn bench_use_sorted_classes_v4(c: &mut Criterion) {
+    let mut group = c.benchmark_group("use_sorted_classes_v4");
+
+    for (name, content) in CLASS_STRING_FIXTURES {
+        let content = content.trim();
+        group.throughput(Throughput::Bytes(content.len() as u64));
+        group.bench_with_input(
+            BenchmarkId::new("parse_and_sort", name),
+            content,
+            |b, input| {
+                b.iter(|| black_box(sort_class_list(&parse_tailwind(black_box(input)).tree())));
+            },
+        );
+    }
+
+    group.finish();
+}
+
+criterion_group!(use_sorted_classes_v4, bench_use_sorted_classes_v4);
+criterion_main!(use_sorted_classes_v4);

crates/biome_js_analyze/src/lint/nursery/use_sorted_classes/sort_v4.rs

@@ -53,9 +53,18 @@ pub fn sort_class_list(root: &TwRoot) -> String {
         .collect();
 
     // `Vec::sort_by` is stable, so Unknown-vs-Unknown comparisons returning
-    // `Equal` keep input order, and Known entries with identical keys
-    // also keep input order.
-    keyed.sort_by(|a, b| compare(&a.0, &b.0));
+    // `Equal` keep input order. Known entries whose keys tie — possible
+    // when variants share a rank (`@sm/main:flex` with `@sm:flex`) —
+    // break the tie on full candidate text, mirroring Tailwind's final
+    // candidate-string comparison.
+    keyed.sort_by(|a, b| {
+        compare(&a.0, &b.0).then_with(|| match (&a.0, &b.0) {
+            (SortKey::Known { .. }, SortKey::Known { .. }) => {
+                TwNameCollator.cmp(a.1.chars(), b.1.chars())
+            }
+            _ => Ordering::Equal,
+        })
+    });
 
     // Sort is in-place; total text length is unchanged. Pre-size the output
     // so chunked emission never re-allocates.
@@ -286,7 +295,26 @@ impl PendingSortKey {
                     return Self::Unknown;
                 };
                 let name = name.text_trimmed();
-                if let Some(entry) = STATIC_UTILITIES
+                if let Some(modifier) = s.modifier() {
+                    // Static registrations take no modifier; the few
+                    // valid bare-with-modifier forms (`@container/main`
+                    // names the container, `shadow/50` sets the shadow
+                    // color opacity) compile through a functional root's
+                    // bare placement, picked by modifier shape.
+                    if is_negative {
+                        None
+                    } else {
+                        FUNCTIONAL_UTILITIES.get(name).and_then(|entry| {
+                            let placement = if modifier_accepted(ModifierKind::Opacity, &modifier)
+                            {
+                                entry.bare_opacity
+                            } else {
+                                entry.bare_name
+                            };
+                            placement.map(|(sig, count)| (pool_signature(sig), count))
+                        })
+                    }
+                } else if let Some(entry) = STATIC_UTILITIES
                     .get(name)
                     // Tailwind registers negative statics individually
                     // (`-m-px` exists, `-flex` does not).
@@ -1190,6 +1218,56 @@ mod tests {
         assert_eq!(compare(&keys[0], &keys[1]), Ordering::Less);
     }
 
+    #[test]
+    fn group_and_peer_scopes_sort_bare_first_then_by_modifier_text() {
+        let keys = classify_all("group-hover:flex group-hover/a:flex group-hover/b:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Less);
+        assert_eq!(compare(&keys[1], &keys[2]), Ordering::Less);
+        // A bracketed modifier compares by its inner value (`.5` < `menu`).
+        let keys = classify_all("group-hover/[.5]:flex group-hover/menu:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Less);
+    }
+
+    #[test]
+    fn a_modifier_outside_group_peer_and_container_variants_is_unknown() {
+        assert_eq!(classify("hover/foo:flex"), SortKey::Unknown);
+        assert_eq!(classify("has-hover/5:flex"), SortKey::Unknown);
+        assert_eq!(classify("min-[600px]/5:flex"), SortKey::Unknown);
+    }
+
+    #[test]
+    fn an_unresolvable_breakpoint_or_container_size_is_unknown() {
+        assert_eq!(classify("min-abc:flex"), SortKey::Unknown);
+        assert_eq!(classify("@max-abc:flex"), SortKey::Unknown);
+        assert_eq!(classify("min-[var(--w)]:flex"), SortKey::Unknown);
+    }
+
+    #[test]
+    fn variants_resolving_equal_lengths_share_a_rank() {
+        // `min-[40rem]` and `sm` both resolve 40rem, so their keys tie;
+        // `sort_class_list` breaks the tie on candidate text.
+        let keys = classify_all("min-[40rem]:flex sm:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Equal);
+        // A container modifier does not participate in ordering.
+        let keys = classify_all("@sm/main:flex @sm:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Equal);
+    }
+
+    #[test]
+    fn container_sizes_compare_by_unit_text_before_magnitude() {
+        // 400px > 384px (= 24rem), but `px` < `rem` textually, so the
+        // arbitrary pixel size groups before every named (rem) size.
+        let keys = classify_all("@min-[400px]:flex @sm:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Less);
+    }
+
+    #[test]
+    fn arbitrary_selectors_compare_with_underscores_decoded() {
+        // `_` decodes to a space, which sorts below `>`.
+        let keys = classify_all("[&_p]:flex [&>p]:flex");
+        assert_eq!(compare(&keys[0], &keys[1]), Ordering::Less);
+    }
+
     #[test]
     fn unparseable_arbitrary_breakpoints_keep_the_comparator_total() {
         // Parseable and unparseable arbitrary breakpoint values sharing one