@aihu/css-engine 0.2.5 → 0.3.0

package/README.md

@@ -51,7 +51,7 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [
     viteAihuPlugin({
-      css: { shadowMode: 'none' },   // ← REQUIRED for utility classes
+      css: { shadowMode: 'none' },   // ← styles this component + external light-DOM children
     }),
   ],
 })
@@ -70,17 +70,22 @@ bun add @aihu/css-engine
 }
 ```
 
-That's it. After `bun run build`, `dist/assets/index-*.css` contains the
-emitted rules (`.flex{display:flex}`, `.gap-6{gap:1.5rem}`, etc.).
+That's it. With the default `shadowMode: 'open'`, the scoped rules
+(`.flex{display:flex}`, `.gap-6{gap:1.5rem}`, etc.) fold into each component's
+shadow `<style>`. With `shadowMode: 'none'` (the example above) they instead
+land in `dist/assets/index-*.css` after `bun run build`.
 
-#### Why `shadowMode: 'none'`?
+#### When do you need `shadowMode: 'none'`?
 
-Utility classes rely on the global cascade. With the default `shadowMode: 'open'`
-each component lives behind its own shadow root, so global rules can't reach
-template elements. Switching to `'none'` mounts components without a shadow
-root and lets the bundled CSS reach them. Pick `'open'` or `'closed'` only if
-you're authoring components with hand-written `@style { ... }` blocks instead
-of utility classes.
+Scoped utility classes work fine behind a shadow root (the default `'open'`):
+`@aihu/css-engine` compiles each SFC's classes to a per-component stylesheet and
+folds it into that component's shadow `<style>`. It is scoped by design and does
+**not** rely on the global cascade.
+
+Use `'none'` only when you want the utility CSS in the light DOM — for example to
+style external / slotted child elements that live outside your component's shadow
+root, or to emit a single global sheet. (Truly global frameworks like Tailwind,
+UnoCSS, or Pico do require `'none'`, but `@aihu/css-engine` does not.)
 
 #### Style packs vs the utility scanner — they are separate
 
@@ -88,7 +93,7 @@ Two distinct things ship in `@aihu/css-engine`:
 
 | Concern | What you do | Output |
 |---|---|---|
-| **Utility scanner** (this section) | Install package + set `css.shadowMode: 'none'` | Per-class rules folded into the Vite CSS bundle |
+| **Utility scanner** (this section) | Install the package (works in any shadow mode; default `'open'` folds into the shadow style) | Per-component scoped rules (or the Vite CSS bundle under `'none'`) |
 | **Theme packs** (color tokens, fonts) | `import "@aihu/css-engine/styles/aihu-graphite.css"` in your entry | `--color-*` / `--font-*` CSS custom properties at `:root` |
 
 Theme packs are plain CSS imports — they emit token variables, not utility
@@ -193,7 +198,7 @@ npm install @aihu/css-engine
 bun add @aihu/css-engine
 ```
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: install -->
 
@@ -204,12 +209,12 @@ bun add @aihu/css-engine
 
 | | |
 |---|---|
-| **Version** | `0.2.5` |
+| **Version** | `0.3.0` |
 | **Tier** | D — Compiler — CSS engine (Tailwind v4 hard fork, WC-native scoped output) |
 | **Published files** | 5 entries |
 | **License** | MIT |
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: stats -->
 
@@ -228,7 +233,7 @@ bun add @aihu/css-engine
 | `./runtime/cn` | `./dist/runtime/cn.js` | `—` |
 | `./runtime/progressive` | `./dist/runtime/progressive.js` | `—` |
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: exports -->
 
@@ -248,7 +253,7 @@ bun add @aihu/css-engine
 - `@aihu/css-engine-linux-x64-gnu` — `0.1.2`
 - `@aihu/css-engine-win32-x64-msvc` — `0.1.2`
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: deps -->
 
@@ -261,7 +266,7 @@ bun add @aihu/css-engine
 - [@aihu/compiler](../compiler)
 - [Aihu framework root](../../README.md)
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: see-also -->
 
@@ -272,6 +277,6 @@ bun add @aihu/css-engine
 
 MIT — see [LICENSE](../../LICENSE).
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.5`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: license -->

package/crates/aihu-css-core/src/emit.rs

@@ -20,8 +20,8 @@ use crate::ast::{SfcAst, SfcStyleScope};
 use crate::progressive::ProgressiveRegistry;
 use crate::scanner::{scan, ScanResult};
 use crate::theme::{extract_theme_blocks, ThemeRegistry};
-use crate::tokens::utility_to_css;
-use crate::variants::{split_variants, Variant};
+use crate::tokens::{animation_keyframes, utility_to_css};
+use crate::variants::{split_variants, AttrMatch, Variant};
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum OutputMode {
@@ -33,7 +33,10 @@ pub enum OutputMode {
 fn escape_class(class: &str) -> String {
     let mut out = String::with_capacity(class.len() + 4);
     for c in class.chars() {
-        if matches!(c, '[' | ']' | '#' | '(' | ')' | '.' | '%' | '/' | ':' | ',') {
+        if matches!(
+            c,
+            '[' | ']' | '#' | '(' | ')' | '.' | '%' | '/' | ':' | ',' | '@' | '=' | '"'
+        ) {
             out.push('\\');
         }
         out.push(c);
@@ -71,7 +74,11 @@ fn emit_token(token: &str, theme: &ThemeRegistry, prog: &ProgressiveRegistry) ->
 
     // The base (innermost) selector and declaration body.
     let mut selector = class_sel;
-    let mut media: Option<String> = None;
+    // Wrapping at-rule (e.g. `@media (min-width: …)` for breakpoints or
+    // `@container (min-width: …)` for container queries). Generalized from the
+    // old `media: Option<String>` slot so both `@media` and `@container` wrap
+    // the rule uniformly: `<at-rule> { <rule> }`.
+    let mut at_rule: Option<String> = None;
     let mut dark_cascade = false;
 
     for v in &variants {
@@ -85,9 +92,43 @@ fn emit_token(token: &str, theme: &ThemeRegistry, prog: &ProgressiveRegistry) ->
                 // `[&>div]:` → substitute `&` for the base selector.
                 selector = sel.replace('&', &selector);
             }
+            Variant::Group(Some(state)) => {
+                // `group-hover:bg-x` → `.group:hover .group-hover\:bg-x`.
+                // Prepend a descendant-combinator ancestor selector: the rule
+                // applies to the element bearing this class when an ancestor
+                // marked `class="group"` is in `:<state>`. Within a shadow root
+                // both the marker and the styled element live in the same tree,
+                // so the class selectors match per spec §6.3 scoping.
+                selector = format!(".group:{state} {selector}");
+            }
+            Variant::Peer(Some(state)) => {
+                // `peer-checked:bg-x` → `.peer:checked ~ .peer-checked\:bg-x`.
+                // Prepend a subsequent-sibling-combinator selector: the rule
+                // applies when a PRIOR sibling marked `class="peer"` is in
+                // `:<state>`. CSS can only look backward to earlier siblings,
+                // so `peer` must appear before the styled element in source.
+                selector = format!(".peer:{state} ~ {selector}");
+            }
+            // Bare `group`/`peer` never reach here (they are marker utilities,
+            // not variant prefixes); a `None` state is unreachable but handled
+            // defensively as a no-op so the base selector is emitted unchanged.
+            Variant::Group(None) | Variant::Peer(None) => {}
+            // aria-*/data-* attribute variants compile to an attribute selector
+            // appended to the base: `aria-checked:` → `.cls[aria-checked="true"]`,
+            // `data-[state=open]:` → `.cls[data-state="open"]`. A keyword data-*
+            // (`data-active:`) emits a presence selector `[data-active]`.
+            Variant::Aria(m) => selector = format!("{selector}{}", attr_selector("aria", m)),
+            Variant::Data(m) => selector = format!("{selector}{}", attr_selector("data", m)),
             Variant::Breakpoint(bp) => {
                 if let Some(min) = theme.breakpoint(bp) {
-                    media = Some(format!("(min-width: {min})"));
+                    at_rule = Some(format!("@media (min-width: {min})"));
+                }
+            }
+            // Container queries wrap the rule in an `@container` at-rule keyed on
+            // the container breakpoint scale (mirrors `breakpoint()`).
+            Variant::Container(bp) => {
+                if let Some(min) = theme.container_breakpoint(bp) {
+                    at_rule = Some(format!("@container (min-width: {min})"));
                 }
             }
             Variant::Dark | Variant::HostContextDark => {
@@ -112,12 +153,41 @@ fn emit_token(token: &str, theme: &ThemeRegistry, prog: &ProgressiveRegistry) ->
         format!("{selector} {{ {body} }}\n")
     };
 
-    Some(match media {
-        Some(q) => format!("@media {q} {{\n{rule}}}\n"),
+    let rule = match at_rule {
+        Some(at) => format!("{at} {{\n{rule}}}\n"),
+        None => rule,
+    };
+
+    // Hoist the @keyframes an `animate-*` utility depends on as a top-level
+    // sibling rule (it cannot live nested inside the selector body). Re-emitting
+    // an identical block is idempotent in CSS, so per-occurrence emission is
+    // safe. `base` is the variant-stripped class (e.g. `animate-spin`).
+    Some(match animation_keyframes(&base) {
+        Some(kf) => format!("{rule}{kf}\n"),
         None => rule,
     })
 }
 
+/// Build an attribute-selector fragment for an `aria-*`/`data-*` variant.
+///
+/// `attr_selector("aria", Name{checked, true})` → `[aria-checked="true"]`;
+/// `attr_selector("data", NameValue{state, open})` → `[data-state="open"]`;
+/// `attr_selector("data", Name{active, false})` → `[data-active]` (presence).
+fn attr_selector(family: &str, m: &AttrMatch) -> String {
+    match m {
+        AttrMatch::Name { name, imply_true } => {
+            if *imply_true {
+                format!("[{family}-{name}=\"true\"]")
+            } else {
+                format!("[{family}-{name}]")
+            }
+        }
+        AttrMatch::NameValue { name, value } => {
+            format!("[{family}-{name}=\"{value}\"]")
+        }
+    }
+}
+
 /// Emit CSS for a scanned utility set in the given mode.
 pub fn emit(result: &ScanResult, theme: &ThemeRegistry, mode: OutputMode) -> String {
     emit_with_progressive(result, theme, &ProgressiveRegistry::with_builtins(), mode)
@@ -138,6 +208,10 @@ pub fn emit_with_progressive(
                 // Flat back-compat: only plain utilities, no variant wrapping.
                 if let Some(body) = utility_to_css(token) {
                     out.push_str(&format!(".{token} {{ {body} }}\n"));
+                    if let Some(kf) = animation_keyframes(token) {
+                        out.push_str(kf);
+                        out.push('\n');
+                    }
                 }
             }
             OutputMode::Scoped => {
@@ -172,7 +246,12 @@ pub fn emit_sfc_scoped(ast: &SfcAst) -> String {
     out.push_str(&theme.emit_host_tokens());
 
     // 2. Scanned utility rules (scoped) — progressive prefixes routed via `prog`.
-    out.push_str(&emit_with_progressive(&result, &theme, &prog, OutputMode::Scoped));
+    out.push_str(&emit_with_progressive(
+        &result,
+        &theme,
+        &prog,
+        OutputMode::Scoped,
+    ));
 
     // 3. Fold the authored @style block (minus @theme directives).
     if let Some(style) = &ast.style {

package/crates/aihu-css-core/src/lib.rs

@@ -42,6 +42,11 @@ pub fn compile_classes(classes: &[String]) -> String {
             output.push_str(" { ");
             output.push_str(&body);
             output.push_str(" }\n");
+            // Hoist the matching @keyframes as a sibling rule (animate-* only).
+            if let Some(kf) = tokens::animation_keyframes(class) {
+                output.push_str(kf);
+                output.push('\n');
+            }
         }
     }
     output

package/crates/aihu-css-core/src/theme.rs

@@ -70,6 +70,20 @@ impl ThemeRegistry {
         }
     }
 
+    /// Resolve a container-query breakpoint (`@sm`/`@md`/…) to its min-width.
+    /// Mirrors [`breakpoint`] but uses Tailwind's container-query scale (which
+    /// differs from the viewport breakpoint scale): `@sm`=24rem … `@2xl`=42rem.
+    pub fn container_breakpoint(&self, name: &str) -> Option<&'static str> {
+        match name {
+            "sm" => Some("24rem"),
+            "md" => Some("28rem"),
+            "lg" => Some("32rem"),
+            "xl" => Some("36rem"),
+            "2xl" => Some("42rem"),
+            _ => None,
+        }
+    }
+
     /// Merge an `@theme { ... }` block's tokens over the current registry.
     /// Returns the number of tokens registered/overridden.
     pub fn apply_theme_block(&mut self, theme_body: &str) -> usize {