@mochi-css/vanilla 1.0.1 → 2.0.0

package/README.md

@@ -1,8 +1,16 @@
-# Mochi-CSS/vanilla
+# 🧁 Mochi-CSS/vanilla
 
 This package is part of the [Mochi-CSS project](https://github.com/Niikelion/mochi-css).
 It provides type-safe CSS-in-JS styling functions with static extraction support, allowing you to write styles in TypeScript that get extracted to plain CSS at build time.
 
+## Installation
+
+```bash
+npm i @mochi-css/vanilla
+```
+
+---
+
 ## Functions
 
 ### `css(...styles)`
@@ -35,6 +43,20 @@ const buttonStyles = css(textStyles, {
 })
 ```
 
+### `globalCss(styles)`
+
+`globalCss` injects styles into the global scope — they are not scoped to any class and apply to all matching elements. Use it for resets, base typography, or any styles that must target plain HTML elements.
+
+```ts
+import { globalCss } from "@mochi-css/vanilla"
+
+globalCss({
+    "*, *::before, *::after": { boxSizing: "border-box" },
+    body: { margin: 0, fontFamily: "sans-serif" },
+    "h1, h2, h3": { lineHeight: 1.2 },
+})
+```
+
 ### `styled(component, ...styles)`
 
 `styled` creates a styled component by combining a base element or component with style definitions. It automatically applies the generated class names and forwards variant props.
@@ -48,6 +70,52 @@ const Button = styled("button", {
 })
 ```
 
+### `keyframes(stops)`
+
+The `keyframes` function lets you define CSS animations using the same type-safe syntax as style definitions.
+
+Define animation stops using `from`/`to` or percentage keys:
+
+```ts
+import { keyframes, css } from "@mochi-css/vanilla"
+
+const fadeIn = keyframes({
+    from: { opacity: 0 },
+    to: { opacity: 1 }
+})
+
+const fadeInStyle = css({
+    animation: `${fadeIn} 0.3s ease`
+})
+```
+
+For more control over animation timing, use percentage-based stops:
+
+```ts
+const bounce = keyframes({
+    "0%": { transform: "translateY(0)" },
+    "50%": { transform: "translateY(-20px)" },
+    "100%": { transform: "translateY(0)" }
+})
+```
+
+Each stop can contain multiple CSS properties with auto-units:
+
+```ts
+const grow = keyframes({
+    from: {
+        opacity: 0,
+        transform: "scale(0.5)",
+        fontSize: 12  // becomes 12px
+    },
+    to: {
+        opacity: 1,
+        transform: "scale(1)",
+        fontSize: 24  // becomes 24px
+    }
+})
+```
+
 ## Style definitions
 
 A style definition is either a bundle of styles returned by `css`, or an object containing:
@@ -132,76 +200,119 @@ const linkStyle = css({
 
 ## Media Selectors
 
-Media selectors allow you to apply styles conditionally based on viewport size, color scheme preferences, and other media features. Media selectors start with the `@` symbol and are compiled into CSS media queries:
+Mochi-CSS supports `@media`, `@container`, `@supports`, and `@layer` at-rules as style object keys.
+You can write them as plain strings or use the typed helper functions exported from the package.
+
+### `media` helper
 
 ```ts
-import { css } from "@mochi-css/vanilla"
+import { css, media } from "@mochi-css/vanilla"
 
 const responsiveContainer = css({
     display: "flex",
     flexDirection: "row",
     padding: 32,
 
-    // Responsive breakpoints
-    "@max-width: 768px": {
+    // media(condition) — wraps condition in parens automatically
+    [media("max-width: 768px")]: {
         flexDirection: "column",
         padding: 16
     },
 
-    "@max-width: 480px": {
-        padding: 8
-    },
-
     // Modern range syntax
-    "@width <= 1024px": {
+    [media("width <= 1024px")]: {
         gap: 16
     },
 
-    // Color scheme preferences
-    "@prefers-color-scheme: dark": {
+    // Shorthand properties for common queries
+    [media.dark]: {
         backgroundColor: "#1a1a1a",
         color: "white"
     },
 
-    // Reduced motion
-    "@prefers-reduced-motion: reduce": {
+    [media.motion]: {
         transition: "none"
+    },
+
+    [media.print]: {
+        display: "block"
     }
 })
 ```
 
-### Combined Media Selectors
-
-You can combine multiple media conditions using `and` and `not` operators:
+Combine conditions with `media.and` / `media.or`:
 
 ```ts
-const responsiveLayout = css({
+const layout = css({
     display: "grid",
     gridTemplateColumns: "1fr",
 
-    // Screen media type with width condition
-    "@screen and (width > 1000px)": {
-        gridTemplateColumns: "1fr 1fr"
-    },
-
-    // Multiple conditions with 'and'
-    "@screen and (min-width: 768px) and (max-width: 1024px)": {
+    [media.and("min-width: 768px", "max-width: 1024px")]: {
         gridTemplateColumns: "1fr 1fr",
         gap: 16
     },
 
-    // Print styles
-    "@print": {
+    [media.or("max-width: 480px", "print")]: {
         display: "block"
+    }
+})
+```
+
+### `container` helper
+
+```ts
+import { css, container } from "@mochi-css/vanilla"
+
+const card = css({
+    fontSize: 16,
+
+    // Anonymous container query
+    [container("min-width: 400px")]: {
+        fontSize: 20
+    },
+
+    // Named container query
+    [container.named("sidebar", "min-width: 200px")]: {
+        display: "none"
+    }
+})
+```
+
+### `supports` helper
+
+```ts
+import { css, supports } from "@mochi-css/vanilla"
+
+const grid = css({
+    display: "flex",
+
+    [supports("display: grid")]: {
+        display: "grid"
     },
 
-    // Combining media type with preference
-    "@screen and (not (prefers-color-scheme: dark))": {
-        backgroundColor: "#121212"
+    [supports.not("display: grid")]: {
+        display: "flex"
+    },
+
+    [supports.and("display: grid", "gap: 1px")]: {
+        gap: 16
     }
 })
 ```
 
+### Raw strings
+
+You can also use raw at-rule strings directly without the helpers:
+
+```ts
+const styles = css({
+    "@media (max-width: 768px)": { padding: 8 },
+    "@container (min-width: 300px)": { fontSize: 20 },
+    "@supports (display: grid)": { display: "grid" },
+    "@layer utilities": { color: "red" }
+})
+```
+
 ### Combining Nested Selectors with Media Selectors
 
 Nested selectors and media selectors can be combined for fine-grained control:
@@ -214,14 +325,13 @@ const buttonStyle = css({
         backgroundColor: "darkblue",
 
         // Media selector inside nested selector
-        "@width <= 480px": {
-            // Disable hover effects on mobile (touch devices)
+        [media("max-width: 480px")]: {
             backgroundColor: "blue"
         }
     },
 
     // Media selector with nested selectors inside
-    "@max-width: 768px": {
+    [media("max-width: 768px")]: {
         padding: 8,
 
         "& > span": {
@@ -244,13 +354,13 @@ const cardStyle = css({
         size: {
             small: {
                 padding: 8,
-                "@max-width: 480px": {
+                [media("max-width: 480px")]: {
                     padding: 4
                 }
             },
             large: {
                 padding: 32,
-                "@max-width: 480px": {
+                [media("max-width: 480px")]: {
                     padding: 16
                 }
             }
@@ -360,57 +470,3 @@ Tokens can be used in two ways:
 - **As values**: Use the token directly (e.g., `backgroundColor: buttonColor`) to reference the CSS variable
 - **As keys**: Use `token.variable` (e.g., `[buttonColor.variable]: primaryColor`) to assign a value to the CSS variable
 
-## Keyframes
-
-The `keyframes` function lets you define CSS animations using the same type-safe syntax as style definitions.
-
-### Basic Usage
-
-Define animation stops using `from`/`to` or percentage keys:
-
-```ts
-import { keyframes, css } from "@mochi-css/vanilla"
-
-const fadeIn = keyframes({
-    from: { opacity: 0 },
-    to: { opacity: 1 }
-})
-
-const fadeInStyle = css({
-    animation: `${fadeIn} 0.3s ease`
-})
-```
-
-### Percentage Stops
-
-For more control over animation timing, use percentage-based stops:
-
-```ts
-const bounce = keyframes({
-    "0%": { transform: "translateY(0)" },
-    "50%": { transform: "translateY(-20px)" },
-    "100%": { transform: "translateY(0)" }
-})
-
-const bouncingElement = css({
-    animation: `${bounce} 1s ease-in-out infinite`
-})
-```
-
-### Multiple Properties
-
-Each stop can contain multiple CSS properties with auto-units:
-
-```ts
-const grow = keyframes({
-    from: {
-        opacity: 0,
-        transform: "scale(0.5)",
-        fontSize: 12  // becomes 12px
-    },
-    to: {
-        opacity: 1,
-        transform: "scale(1)",
-        fontSize: 24  // becomes 24px
-    }
-})

package/dist/index.d.mts

@@ -55,38 +55,33 @@ declare function createToken(name: string): Token;
 //#region src/selector.d.ts
 /**
  * CSS selector building and manipulation utilities.
- * Handles nested selectors (using `&` placeholder) and media queries.
+ * Handles nested selectors (using `&` placeholder) and CSS at-rules.
  * @module selector
  */
 /**
- * Immutable CSS selector builder that handles nested selectors and media queries.
+ * Immutable CSS selector builder that handles nested selectors and CSS at-rules.
  * Uses the `&` character as a placeholder for parent selector substitution.
  *
  * @example
  * const selector = new MochiSelector(['.button'])
  * selector.extend('&:hover').cssSelector // '.button:hover'
- * selector.wrap('@media (min-width: 768px)').mediaQuery // '@media (min-width: 768px)'
+ * selector.wrap('@media (min-width: 768px)').atRules // ['@media (min-width: 768px)']
  */
 declare class MochiSelector {
   private readonly cssSelectors;
-  private readonly mediaSelectors;
+  readonly atRules: string[];
   /**
    * Creates a new MochiSelector instance.
    * @param cssSelectors - Array of CSS selectors (may contain `&` placeholders)
-   * @param mediaSelectors - Array of media query conditions (without `@media` prefix)
+   * @param atRules - Array of full CSS at-rule strings e.g. `"@media (min-width: 768px)"`
    */
-  constructor(cssSelectors?: string[], mediaSelectors?: string[]);
+  constructor(cssSelectors?: string[], atRules?: string[]);
   /**
    * Gets the combined CSS selector string.
    * Multiple selectors are joined with commas.
    * @returns The CSS selector, or "*" if no selectors are defined
    */
   get cssSelector(): string;
-  /**
-   * Gets the combined media query string, if any.
-   * @returns The full `@media` query string, or undefined if no media conditions
-   */
-  get mediaQuery(): string | undefined;
   /**
    * Substitutes all `&` placeholders with the given root selector.
    * @param root - The selector to replace `&` with
@@ -104,13 +99,14 @@ declare class MochiSelector {
    */
   extend(child: string): MochiSelector;
   /**
-   * Wraps this selector with a media query condition.
-   * @param mediaQuery - The media query string (starting with `@`)
-   * @returns A new MochiSelector with the added media condition
+   * Wraps this selector with a CSS at-rule.
+   * @param atRule - The full at-rule string (e.g. `"@media (min-width: 768px)"`)
+   * @returns A new MochiSelector with the added at-rule, or unchanged if not a known at-rule
    * @example
-   * selector.wrap('@min-width: 768px') // Adds media query condition
+   * selector.wrap('@media (min-width: 768px)') // Adds media query
+   * selector.wrap('@container sidebar (min-width: 300px)') // Adds container query
    */
-  wrap(mediaQuery: string): MochiSelector;
+  wrap(atRule: string): MochiSelector;
   /**
    * Splits a comma-separated selector string into individual selectors.
    * @param selector - The selector string to split
@@ -455,11 +451,15 @@ type PropsWithUnit = PropertyWithUnit & keyof Props;
  * Converts a kebab-case string to camelCase.
  */
 
+/**
+ * Checks if a key represents a CSS at-rule (media, container, supports, layer).
+ */
+declare function isAtRuleKey(key: string): key is AtRuleKey;
 /** A nested CSS selector pattern containing the parent reference `&` */
 type NestedCssSelector = `${string}&${string}`;
-/** A CSS media query starting with `@` */
-type MediaSelector = `@${string}`;
-type NestedStyleKeys = MediaSelector | NestedCssSelector;
+/** A CSS at-rule key for media, container, supports, or layer queries */
+type AtRuleKey = `@media ${string}` | `@container ${string}` | `@supports ${string}` | `@layer ${string}`;
+type NestedStyleKeys = AtRuleKey | NestedCssSelector;
 /**
  * Style properties without nesting support.
  * Includes all standard CSS properties with type-safe value converters,
@@ -468,7 +468,7 @@ type NestedStyleKeys = MediaSelector | NestedCssSelector;
  * Properties with known units (e.g., width, height, padding) accept numbers
  * that are automatically converted with their default unit (e.g., px, ms).
  */
-type SimpleStyleProps = { [K in PropsWithUnit]?: CssLike<number | Props[K]> } & { [K in Exclude<keyof Props, PropsWithUnit>]?: CssLike<Props[K]> } & Partial<Record<CssVar, CssLike<string | number>>>;
+type SimpleStyleProps = { [K in PropsWithUnit]?: CssLike<number | Props[K]> } & { [K in Exclude<keyof Props, PropsWithUnit>]?: CssLike<Props[K]> };
 /**
  * Full style properties type with support for nested selectors and media queries.
  * Extends SimpleStyleProps to allow recursive style definitions.
@@ -478,10 +478,10 @@ type SimpleStyleProps = { [K in PropsWithUnit]?: CssLike<number | Props[K]> } &
  *   color: 'blue',
  *   padding: 16,
  *   '&:hover': { color: 'red' },
- *   '@min-width: 768px': { padding: 24 }
+ *   '@media (min-width: 768px)': { padding: 24 }
  * }
  */
-type StyleProps = SimpleStyleProps & { [K in NestedStyleKeys]?: StyleProps | CssLike<string | number> };
+type StyleProps = SimpleStyleProps & { [K in NestedStyleKeys]?: StyleProps | CssLike<string | number> } & Record<string, unknown>;
 /**
  * Converts a SimpleStyleProps object to a CSS properties record.
  * Transforms camelCase property names to kebab-case and applies value converters.
@@ -491,7 +491,7 @@ type StyleProps = SimpleStyleProps & { [K in NestedStyleKeys]?: StyleProps | Css
  * cssFromProps({ backgroundColor: 'blue', padding: 16 })
  * // { 'background-color': 'blue', 'padding': '16px' }
  */
-declare function cssFromProps(props: SimpleStyleProps): Record<string, string>;
+declare function cssFromProps(props: SimpleStyleProps & Partial<Record<CssVar, CssLike<number | string>>>): Record<string, string>;
 //#endregion
 //#region src/cssObject.d.ts
 /**
@@ -514,7 +514,8 @@ declare class CssObjectSubBlock {
   get hash(): string;
   /**
    * Converts this block to a CSS string.
-   * Handles media query wrapping if the selector has media conditions.
+   * Handles at-rule wrapping (media, container, supports, layer) if present.
+   * Multiple at-rules are nested in order.
    * @param root - The root selector to substitute for `&`
    * @returns Formatted CSS string
    */
@@ -589,7 +590,7 @@ type VariantProps<V extends AllVariants> = {
   compoundVariants?: CompoundVariant<V>[];
 };
 /** Combined type for style props with optional variants */
-type MochiCSSProps<V extends AllVariants> = StyleProps & VariantProps<V>;
+type MochiCSSProps<V extends AllVariants> = Omit<StyleProps, "variants" | "compoundVariants" | "defaultVariants"> & VariantProps<V>;
 /** Utility type to override properties of A with properties of B */
 type Override<A extends object, B extends object> = B & Omit<A, keyof B>;
 /** Recursively merges variant types from a tuple, with later types overriding earlier */
@@ -689,6 +690,13 @@ declare class MochiCSS<V extends AllVariants = DefaultVariants> {
    */
   static from<V extends AllVariants = DefaultVariants>(object: CSSObject<V>): MochiCSS<V>;
 }
+/**
+ * Merges multiple MochiCSS instances into a single one, combining their
+ * class names, variant class names, and default variants.
+ * @param instances - The MochiCSS instances to merge
+ * @returns A new MochiCSS instance with all styles combined
+ */
+declare function mergeMochiCss<V extends AllVariants[]>(instances: MochiCSS<AllVariants>[]): MochiCSS<MergeCSSVariants<V>>;
 declare function css<V extends AllVariants[]>(...props: { [K in keyof V]: MochiCSSProps<V[K]> | MochiCSS }): MochiCSS<MergeCSSVariants<V>>;
 //#endregion
 //#region src/styled.d.ts
@@ -750,5 +758,79 @@ declare class MochiKeyframes {
 }
 declare function keyframes(stops: KeyframeStops): MochiKeyframes;
 //#endregion
-export { AllVariants, CSSObject, CompoundVariant, CssLike, CssLikeObject, CssObjectBlock, CssObjectSubBlock, CssVar, CssVarVal, DefaultVariants, type KeyframeStops, KeyframesObject, MergeCSSVariants, MochiCSS, MochiCSSProps, MochiKeyframes, MochiSelector, RefineVariants, type StyleProps, Token, VariantProps, createToken, css, cssFromProps, keyframes, styled };
-//# sourceMappingURL=index.d.mts.map
+//#region src/globalCssObject.d.ts
+type GlobalCssStyles = Record<string, StyleProps>;
+/**
+ * CSS object model for global (non-scoped) styles.
+ * Accepts a map of CSS selectors to style objects and serializes them
+ * as plain CSS rules without class name scoping.
+ *
+ * @example
+ * const obj = new GlobalCssObject({
+ *   body: { margin: 0 },
+ *   'h1': { fontSize: 32 },
+ * })
+ * obj.asCssString() // "body {\n    margin: 0;\n}\n\nh1 {\n    font-size: 32px;\n}"
+ */
+declare class GlobalCssObject {
+  private readonly rules;
+  constructor(styles: GlobalCssStyles);
+  asCssString(): string;
+}
+//#endregion
+//#region src/globalCss.d.ts
+/**
+ * Creates a global CSS definition.
+ * Styles are not scoped to any class — they apply to all matching elements.
+ *
+ * @param styles - Map of CSS selectors to style objects
+ *
+ * @example
+ * globalCss({
+ *   'body': { margin: 0, padding: 0 },
+ *   '*, *::before, *::after': { boxSizing: 'border-box' },
+ * })
+ */
+declare function globalCss(styles: GlobalCssStyles): void;
+//#endregion
+//#region src/query.d.ts
+interface MediaHelper {
+  /** `@media (condition)` */
+  (condition: string): AtRuleKey & `@media ${string}`;
+  /** `@media (a) and (b) and …` */
+  and(...conditions: [string, string, ...string[]]): AtRuleKey & `@media ${string}`;
+  /** `@media (a), (b), …` */
+  or(...conditions: [string, string, ...string[]]): AtRuleKey & `@media ${string}`;
+  /** `@media (prefers-color-scheme: dark)` */
+  readonly dark: AtRuleKey & `@media ${string}`;
+  /** `@media (prefers-color-scheme: light)` */
+  readonly light: AtRuleKey & `@media ${string}`;
+  /** `@media (prefers-reduced-motion: no-preference)` */
+  readonly motion: AtRuleKey & `@media ${string}`;
+  /** `@media print` */
+  readonly print: AtRuleKey & `@media ${string}`;
+}
+/** Helper for constructing `@media` at-rule keys. */
+declare const media: MediaHelper;
+interface ContainerHelper {
+  /** `@container (condition)` — anonymous container */
+  (condition: string): AtRuleKey & `@container ${string}`;
+  /** `@container name (condition)` — named container */
+  named(name: string, condition: string): AtRuleKey & `@container ${string}`;
+}
+/** Helper for constructing `@container` at-rule keys. */
+declare const container: ContainerHelper;
+interface SupportsHelper {
+  /** `@supports (declaration)` */
+  (condition: string): AtRuleKey & `@supports ${string}`;
+  /** `@supports not (declaration)` */
+  not(condition: string): AtRuleKey & `@supports ${string}`;
+  /** `@supports (a) and (b) and …` */
+  and(...conditions: [string, string, ...string[]]): AtRuleKey & `@supports ${string}`;
+  /** `@supports (a) or (b) or …` */
+  or(...conditions: [string, string, ...string[]]): AtRuleKey & `@supports ${string}`;
+}
+/** Helper for constructing `@supports` at-rule keys. */
+declare const supports: SupportsHelper;
+//#endregion
+export { AllVariants, type AtRuleKey, CSSObject, CompoundVariant, CssLike, CssLikeObject, CssObjectBlock, CssObjectSubBlock, CssVar, CssVarVal, DefaultVariants, GlobalCssObject, type GlobalCssStyles, type KeyframeStops, KeyframesObject, MergeCSSVariants, MochiCSS, MochiCSSProps, MochiKeyframes, MochiSelector, RefineVariants, type StyleProps, Token, VariantProps, container, createToken, css, cssFromProps, globalCss, isAtRuleKey, keyframes, media, mergeMochiCss, styled, supports };