@aihu/css-engine 0.2.4 → 0.3.0

package/README.md

@@ -34,38 +34,143 @@ as a per-platform `optionalDependencies` package
 resolved automatically at build time — no Rust toolchain required. In a monorepo
 dev clone the engine falls back to the workspace `target/release` binary.
 
-### Usage with `viteAihuPlugin`
+### Enabling utility-class CSS in a user project
 
-When `@aihu/css-engine` is installed alongside `@aihu/app`, the compiler hook
-inside `viteAihuPlugin` automatically scans every `.aihu` SFC and folds the
-generated utility CSS into the build. **No additional plugin wiring is needed.**
-
-There is one configuration knob you almost certainly want: **`shadowMode: 'none'`**.
-Utility classes rely on the global cascade, so they must escape the per-component
-shadow root. Forward this through `viteAihuPlugin`'s `css` option:
+Utility-class CSS is **auto-wired by presence** — install `@aihu/css-engine`
+alongside `@aihu/app`, set one config knob, and every `.aihu` file in your
+project is scanned and the matched rules land in your bundle's CSS asset.
+There is no separate `viteCssEnginePlugin`, no `aihu.config.ts` file, no
+preset selection step. The entire user surface is the `css` option on
+`viteAihuPlugin()` in `vite.config.ts`:
 
 ```ts
-// vite.config.ts
+// vite.config.ts — the entire surface
 import { viteAihuPlugin } from '@aihu/app'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [
     viteAihuPlugin({
-      css: { shadowMode: 'none' },
+      css: { shadowMode: 'none' },   // ← styles this component + external light-DOM children
     }),
   ],
 })
 ```
 
-If `compileSfc()` fails at build time (e.g. the native `aihu-css-core` binary
-is unresolvable in your install), the compiler emits a one-shot warning to the
-console — utility classes will not appear in the output until the binary is
-restored. The build itself still succeeds.
+```bash
+bun add @aihu/css-engine
+```
+
+```jsx
+// any .aihu file — classes are scanned automatically
+@template {
+  <section class="flex gap-6 px-4 py-6">
+    <span class="text-lg font-semibold">hi</span>
+  </section>
+}
+```
+
+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`.
+
+#### When do you need `shadowMode: 'none'`?
+
+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
+
+Two distinct things ship in `@aihu/css-engine`:
+
+| Concern | What you do | Output |
+|---|---|---|
+| **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
+rules. Importing a pack alone does **not** enable the scanner; setting
+`css.shadowMode: 'none'` alone does **not** import a pack. Use both for a
+complete look; either independently is fine.
+
+### Utility vocabulary
+
+The engine is **inspired by Tailwind v4, not a fork** — the supported set is
+hand-curated in [`crates/aihu-css-core/src/tokens.rs`](crates/aihu-css-core/src/tokens.rs).
+
+**Fixed long-tail utilities** (literal class names):
+
+- **Display** — `block`, `inline-block`, `inline`, `flex`, `inline-flex`, `grid`, `inline-grid`, `hidden`, `contents`
+- **Flexbox** — `flex-row`, `flex-col`, `flex-wrap`, `flex-nowrap`, `flex-1`, `flex-auto`, `flex-none`
+- **Alignment** — `items-{start,center,end,stretch,baseline}`, `justify-{start,center,end,between,around,evenly}`
+- **Position** — `static`, `relative`, `absolute`, `fixed`, `sticky`
+- **Overflow** — `overflow-{hidden,auto,scroll,visible}`
+- **Typography** — `text-{left,center,right,justify}`, `italic`, `not-italic`, `underline`, `line-through`, `no-underline`, `uppercase`, `lowercase`, `capitalize`, `truncate`
+- **Font weight** — `font-{thin,normal,medium,semibold,bold,black}`
+- **Borders / radius** — `border`, `rounded`, `rounded-{none,sm,md,lg,xl,2xl,full}`
+- **Shadows** — `shadow`, `shadow-{sm,md,lg,none}`
+- **Sizing keywords** — `w-{full,screen,auto}`, `h-{full,screen,auto}`
+
+**Parameterized utilities** (`<prefix>-<value>`):
+
+| Prefix family | Examples | Notes |
+|---|---|---|
+| Spacing — `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`, `gap`, `gap-x`, `gap-y` | `p-4`, `mx-auto`, `gap-6` | value × `0.25rem` |
+| Sizing — `w`, `h`, `min-w`, `max-w`, `min-h`, `max-h` | `w-64`, `max-w-7xl` | spacing scale or fractions |
+| Font size — `text-{xs,sm,base,lg,xl,2xl,3xl,…}` | `text-lg` | includes paired line-height |
+| z-index — `z-{N}` | `z-10`, `z-50` | numeric only |
+| Opacity — `opacity-{N}` | `opacity-75` | 0–100 |
+| Palette colors — `bg`, `text`, `border`, `fill`, `stroke`, `ring`, `outline` followed by a named keyword | `bg-red-500`, `text-slate-700` | |
+
+**Arbitrary values** (`<prefix>-[<value>]` — emitted verbatim into the mapped
+property): `bg-[#1a1d24]`, `w-[34ch]`, `text-[14px]`, `px-[2rem]`, etc.
+Supported prefixes: `bg`, `text`, `w`, `h`, `min-w`, `max-w`, `min-h`, `max-h`,
+`p`, `px`, `py`, `m`, `mx`, `my`, `gap`, `rounded`, `border`, `leading`,
+`tracking`, `z`, `top`/`right`/`bottom`/`left`/`inset`, `fill`, `stroke`,
+`shadow`. Underscores in the bracket become spaces (Tailwind convention).
+
+**Brand color utilities** — `bg-primary`, `text-accent`, `border-muted`, etc.
+resolve to `var(--color-*)` registered by a `@theme` block or a theme pack.
+
+#### Not supported (common misses — call out to avoid surprises)
+
+The vocabulary is intentionally narrower than full Tailwind. The following are
+**not** in the table; use them and you'll get the class string in your HTML
+with **no matching CSS rule** (the scanner returns `None` and emits nothing):
+
+- `grid-cols-N` / `grid-rows-N` / `col-span-N` / `row-span-N` — **no grid template utilities**. Use `display: grid` via the `grid` class, then write a hand-authored `@style` block or an arbitrary `style="grid-template-columns:…"` attribute.
+- `mx-auto` / `my-auto` — the spacing scale is `value × 0.25rem` and doesn't include the `auto` keyword. Use `style="margin-inline: auto"` or an arbitrary value (`mx-[auto]`) instead.
+- `max-w-Nxl` / `max-w-screen` / etc. — `max-w` parameterized values follow the spacing/sizing scale, not Tailwind's named breakpoint scale. `max-w-[1280px]` (arbitrary value) works; `max-w-7xl` does not.
+- Tailwind v4 colors *outside* the named keyword set (e.g. `text-zinc-200` — depends on whether `zinc` is in `named_keyword_color`)
+- Responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) — **not yet handled** by the scanner
+- State variants outside the WC-native set (`host:`, `slotted:`, `part-*:` are supported per the variants section above; arbitrary `hover:`, `focus:`, `dark:` etc. depend on what the current `parse_variant` accepts)
+- Container queries, `@layer` ordering, JIT-style arbitrary properties (`[mask-image:url(...)]`)
+
+**The authoritative source is [`crates/aihu-css-core/src/tokens.rs`](crates/aihu-css-core/src/tokens.rs)** — the lists above are a summary of that file's match arms and may drift; when in doubt, grep that file or write a one-liner test against `utility_to_css(class_name)`.
+
+#### Production caveat — native binary must resolve
+
+The scanner runs through the prebuilt `aihu-css-compile` Rust binary. For npm
+consumers the binary ships as a per-platform `optionalDependencies` package
+(e.g. `@aihu/css-engine-darwin-arm64`) and is auto-resolved by your package
+manager. If resolution fails (offline install, unsupported platform), the
+compiler emits a one-shot console warning, the build succeeds, and utility
+rules are silently omitted from the bundle CSS. In monorepo dev clones the
+fallback is `target/release/aihu-css-compile` (run `cargo build --release -p
+aihu-css-core`).
 
 See [`examples/css-engine-utility/`](../../examples/css-engine-utility) for a
-minimal end-to-end demonstration, including an acceptance script that greps
-the built CSS for the expected `.flex { display: flex }` rule.
+minimal end-to-end demonstration, including `scripts/check-utility-css.ts`
+which greps the built CSS asset for the expected `.flex{display:flex}` rule —
+a useful pattern to copy into your own project's CI.
 
 ### Local development
 
@@ -93,7 +198,7 @@ npm install @aihu/css-engine
 bun add @aihu/css-engine
 ```
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.4`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: install -->
 
@@ -104,12 +209,12 @@ bun add @aihu/css-engine
 
 | | |
 |---|---|
-| **Version** | `0.2.4` |
+| **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.4`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: stats -->
 
@@ -128,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.4`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: exports -->
 
@@ -139,7 +244,7 @@ bun add @aihu/css-engine
 
 **Dependencies:**
 
-- `@aihu/compiler` — `workspace:*`
+- `@aihu/compiler` — `workspace:^`
 
 **Optional dependencies (platform-specific):**
 
@@ -148,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.4`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: deps -->
 
@@ -161,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.4`.</i></sub>
+<sub><i>Auto-generated against `@aihu/css-engine@0.3.0`.</i></sub>
 
 <!-- END_AUTOGEN: see-also -->
 
@@ -172,6 +277,6 @@ bun add @aihu/css-engine
 
 MIT — see [LICENSE](../../LICENSE).
 
-<sub><i>Auto-generated against `@aihu/css-engine@0.2.4`.</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 {