@mochi-css/vanilla 2.1.0 → 3.0.1

package/README.md

@@ -1,7 +1,8 @@
 # 🧁 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.
+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
 
@@ -45,7 +46,8 @@ 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.
+`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"
@@ -59,10 +61,11 @@ globalCss({
 
 ### `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.
+`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.
 
 ```tsx
-import {styled} from "@mochi-css/vanilla"
+import { styled } from "@mochi-css/react"
 
 const Button = styled("button", {
     borderRadius: 10,
@@ -127,7 +130,8 @@ A style definition is either a bundle of styles returned by `css`, or an object
 
 ## Nested Selectors
 
-Mochi-CSS supports nested selectors, allowing you to define styles for child elements, pseudo-classes, and pseudo-elements directly within your style definitions.
+Mochi-CSS supports nested selectors, allowing you to define styles for child elements, pseudo-classes,
+and pseudo-elements directly within your style definitions.
 
 The `&` character represents the parent selector and must be included in every nested selector:
 
@@ -400,11 +404,14 @@ const redButtonStyle = css(baseButtonStyle, {
 })
 ```
 
-This works, but requires you to either manually select which style to apply in your component logic, or create separate components for each variant.
-Mochi-CSS allows you to define variants directly in your style definition and automatically generates the corresponding props for your component.
+This works, but requires you to either manually select which style to apply in your component logic,
+or create separate components for each variant.
+Mochi-CSS allows you to define variants directly in your style definition
+and automatically generates the corresponding props for your component.
 
 ```tsx
-import {styled, css} from "@mochi-css/vanilla"
+import { css } from "@mochi-css/vanilla"
+import { styled } from "@mochi-css/react"
 
 const buttonStyle = css({
     border: "2px solid black",
@@ -433,13 +440,16 @@ const SomeComponent = () => <div>
 </div>
 ```
 
-`defaultVariants` is optional, but specifying defaults for all variants ensures predictable styling when variant props are omitted.
+`defaultVariants` is optional,
+but specifying defaults for all variants ensures predictable styling when variant props are omitted.
 
 ## Tokens
 
-Mochi-CSS provides typed wrappers around CSS variables to help with type safety. Tokens ensure that only valid values are assigned to your CSS variables.
+Mochi-CSS provides typed wrappers around CSS variables to help with type safety.
+Tokens ensure that only valid values are assigned to your CSS variables.
 
-Create tokens using the `createToken<T>(name)` function, where `T` is a CSS value type like `CssColorLike`, `CssLengthLike`, or `string`:
+Create tokens using the `createToken<T>(name)` function,
+where `T` is a CSS value type like `CssColorLike`, `CssLengthLike`, or `string`:
 
 ```ts
 import {createToken, css, CssColorLike} from "@mochi-css/vanilla"

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import { ComponentProps, ComponentType, FC, HTMLElementType } from "react";
-import { ObsoleteProperties, Properties } from "csstype";
+import { ObsoleteProperties, Properties, PropertiesHyphen } from "csstype";
 
 //#region src/values/index.d.ts
 type CssVar = `--${string}`;
@@ -275,7 +274,6 @@ declare const propertyUnits: {
   readonly interestDelay: "ms";
   readonly interestDelayEnd: "ms";
   readonly interestDelayStart: "ms";
-  readonly itemFlow: "px";
   readonly left: "px";
   readonly letterSpacing: "px";
   readonly lineHeight: "px";
@@ -415,12 +413,12 @@ declare const propertyUnits: {
   readonly textSizeAdjust: "%";
   readonly textUnderlineOffset: "px";
   readonly timelineTrigger: "px";
-  readonly timelineTriggerExitRange: "px";
-  readonly timelineTriggerExitRangeEnd: "px";
-  readonly timelineTriggerExitRangeStart: "px";
-  readonly timelineTriggerRange: "px";
-  readonly timelineTriggerRangeEnd: "px";
-  readonly timelineTriggerRangeStart: "px";
+  readonly timelineTriggerActivationRange: "px";
+  readonly timelineTriggerActivationRangeEnd: "px";
+  readonly timelineTriggerActivationRangeStart: "px";
+  readonly timelineTriggerActiveRange: "px";
+  readonly timelineTriggerActiveRangeEnd: "px";
+  readonly timelineTriggerActiveRangeStart: "px";
   readonly top: "px";
   readonly transformOrigin: "px";
   readonly transition: "ms";
@@ -450,7 +448,11 @@ type PropsWithUnit = PropertyWithUnit & keyof Props;
 /**
  * Converts a kebab-case string to camelCase.
  */
-
+declare function kebabToCamel(str: string): string;
+/**
+ * Converts a camelCase string to kebab-case.
+ */
+declare function camelToKebab(str: string): string;
 /**
  * Checks if a key represents a CSS at-rule (media, container, supports, layer).
  */
@@ -542,10 +544,11 @@ declare class CssObjectBlock {
   readonly subBlocks: CssObjectSubBlock[];
   /**
    * Creates a new CSS block from style properties.
-   * Generates a unique class name based on the content hash.
+   * Generates a unique class name based on the content hash, or uses the provided class name.
    * @param styles - The style properties to compile
+   * @param className - Optional stable class name; if omitted, a content-hash-based name is generated
    */
-  constructor(styles: StyleProps);
+  constructor(styles: StyleProps, className?: string);
   /**
    * Gets the CSS class selector for this block.
    */
@@ -632,13 +635,18 @@ declare class CSSObject<V extends AllVariants = DefaultVariants> {
   /**
    * Creates a new CSSObject from style props.
    * Compiles main styles and all variant options into CSS blocks.
+   * @param props - Base style props plus variant definitions
+   * @param props.variants - Named variant groups, each mapping variant values to style props
+   * @param props.defaultVariants - Default value for each variant when none is provided at runtime
+   * @param props.compoundVariants - Style props applied when a specific combination of variants is active
+   * @param className - Optional stable class name for the main block
    */
   constructor({
     variants,
     defaultVariants,
     compoundVariants,
     ...props
-  }: MochiCSSProps<V>);
+  }: MochiCSSProps<V>, className?: string);
   /**
    * Serializes the entire CSS object to a CSS string.
    * Outputs main block first, then all variant blocks in sorted order.
@@ -649,6 +657,20 @@ declare class CSSObject<V extends AllVariants = DefaultVariants> {
 //#endregion
 //#region src/css.d.ts
 declare function isMochiCSS(value: unknown): value is MochiCSS;
+/**
+ * Runtime representation of a CSS style definition with variant support.
+ * Holds generated class names and provides methods to compute the final
+ * className string based on selected variants.
+ *
+ * @template V - The variant definitions type mapping variant names to their options
+ *
+ * @example
+ * const styles = MochiCSS.from(new CSSObject({
+ *   color: 'blue',
+ *   variants: { size: { small: { fontSize: 12 }, large: { fontSize: 18 } } }
+ * }))
+ * styles.variant({ size: 'large' }) // Returns combined class names
+ */
 declare class MochiCSS<V extends AllVariants = DefaultVariants> {
   readonly classNames: string[];
   readonly variantClassNames: { [K in keyof V]: { [P in keyof V[K]]: string } };
@@ -669,6 +691,12 @@ declare class MochiCSS<V extends AllVariants = DefaultVariants> {
    * @returns Combined className string for use in components
    */
   variant(props: Partial<RefineVariants<V>>): string;
+  /**
+   * Returns the CSS selector for this style (e.g. `.abc123`).
+   * Useful for targeting this component from another style.
+   */
+  get selector(): string;
+  toString(): string;
   /**
    * Creates a MochiCSS instance from a CSSObject.
    * Extracts class names from the compiled CSS blocks.
@@ -685,46 +713,7 @@ declare class MochiCSS<V extends AllVariants = DefaultVariants> {
  * @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
-/** Props added by MochiCSS to styled components */
-type MochiProps<V extends AllVariants[]> = {
-  className?: string;
-} & Partial<RefineVariants<MergeCSSVariants<V>>>;
-/** Minimal interface for components that accept className */
-type Cls = {
-  className?: string;
-};
-/**
- * Creates a styled React component with CSS-in-JS support and variant props.
- * Similar to styled-components or Stitches, but with zero runtime overhead.
- *
- * @template T - The base element type or component type
- * @template V - The variant definitions tuple type
- * @param target - The HTML element tag name or React component to style
- * @param props - One or more style objects with optional variants
- * @returns A React functional component with merged props and variant support
- *
- * @example
- * const Button = styled('button', {
- *   padding: 8,
- *   borderRadius: 4,
- *   variants: {
- *     size: {
- *       small: { padding: 4 },
- *       large: { padding: 16 }
- *     },
- *     variant: {
- *       primary: { backgroundColor: 'blue' },
- *       secondary: { backgroundColor: 'gray' }
- *     }
- *   }
- * })
- *
- * // Usage: <Button size="large" variant="primary">Click me</Button>
- */
-declare function styled<T extends HTMLElementType | ComponentType<Cls>, V extends AllVariants[]>(target: T, ...props: { [K in keyof V]: MochiCSSProps<V[K]> }): FC<Omit<ComponentProps<T>, keyof MochiProps<V>> & MochiProps<V>>;
+declare function css<V extends AllVariants[]>(...props: { [K in keyof V]: MochiCSSProps<V[K]> | MochiCSS | string }): MochiCSS<MergeCSSVariants<V>>;
 //#endregion
 //#region src/keyframesObject.d.ts
 type KeyframeStops = Record<string, SimpleStyleProps>;
@@ -747,7 +736,11 @@ declare class MochiKeyframes {
 declare function keyframes(stops: KeyframeStops): MochiKeyframes;
 //#endregion
 //#region src/globalCssObject.d.ts
-type GlobalCssStyles = Record<string, StyleProps>;
+/** CSS properties accepting both camelCase and kebab-case names with permissive string values */
+type GlobalCssProperties = { [K in keyof (Properties & PropertiesHyphen)]?: string | number } & Record<string, unknown>;
+type GlobalCssStyles = {
+  [selector: string]: GlobalCssProperties | GlobalCssStyles;
+};
 /**
  * CSS object model for global (non-scoped) styles.
  * Accepts a map of CSS selectors to style objects and serializes them
@@ -821,4 +814,28 @@ interface SupportsHelper {
 /** 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, isMochiCSS, keyframes, media, mergeMochiCss, styled, supports };
+//#region src/hash.d.ts
+/**
+ * Hashing utilities for generating short, deterministic class names.
+ * Uses djb2 algorithm for fast string hashing.
+ * @module hash
+ */
+/**
+ * Converts a number to a base-62 string representation.
+ * @param num - The number to convert
+ * @param maxLength - Optional maximum length of the output string
+ * @returns Base-62 encoded string representation of the number
+ */
+declare function numberToBase62(num: number, maxLength?: number): string;
+/**
+ * Generates a short hash string from input using the djb2 algorithm.
+ * Used to create unique, deterministic CSS class names from style content.
+ * @param input - The string to hash
+ * @param length - Maximum length of the hash output (default: 8)
+ * @returns A short, css-safe hash string
+ * @example
+ * shortHash("color: red;") // Returns something like "A1b2C3d4"
+ */
+declare function shortHash(input: string, length?: number): string;
+//#endregion
+export { AllVariants, type AtRuleKey, CSSObject, CompoundVariant, CssLike, CssLikeObject, CssObjectBlock, CssObjectSubBlock, CssVar, CssVarVal, DefaultVariants, GlobalCssObject, GlobalCssProperties, type GlobalCssStyles, type KeyframeStops, KeyframesObject, MergeCSSVariants, MochiCSS, MochiCSSProps, MochiKeyframes, MochiSelector, RefineVariantType, RefineVariants, type StyleProps, Token, VariantProps, camelToKebab, container, createToken, css, cssFromProps, globalCss, isAtRuleKey, isMochiCSS, kebabToCamel, keyframes, media, mergeMochiCss, numberToBase62, shortHash, supports };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { ObsoleteProperties, Properties } from "csstype";
-import { ComponentProps, ComponentType, FC, HTMLElementType } from "react";
+import { ObsoleteProperties, Properties, PropertiesHyphen } from "csstype";
 
 //#region src/values/index.d.ts
 type CssVar = `--${string}`;
@@ -275,7 +274,6 @@ declare const propertyUnits: {
   readonly interestDelay: "ms";
   readonly interestDelayEnd: "ms";
   readonly interestDelayStart: "ms";
-  readonly itemFlow: "px";
   readonly left: "px";
   readonly letterSpacing: "px";
   readonly lineHeight: "px";
@@ -415,12 +413,12 @@ declare const propertyUnits: {
   readonly textSizeAdjust: "%";
   readonly textUnderlineOffset: "px";
   readonly timelineTrigger: "px";
-  readonly timelineTriggerExitRange: "px";
-  readonly timelineTriggerExitRangeEnd: "px";
-  readonly timelineTriggerExitRangeStart: "px";
-  readonly timelineTriggerRange: "px";
-  readonly timelineTriggerRangeEnd: "px";
-  readonly timelineTriggerRangeStart: "px";
+  readonly timelineTriggerActivationRange: "px";
+  readonly timelineTriggerActivationRangeEnd: "px";
+  readonly timelineTriggerActivationRangeStart: "px";
+  readonly timelineTriggerActiveRange: "px";
+  readonly timelineTriggerActiveRangeEnd: "px";
+  readonly timelineTriggerActiveRangeStart: "px";
   readonly top: "px";
   readonly transformOrigin: "px";
   readonly transition: "ms";
@@ -450,7 +448,11 @@ type PropsWithUnit = PropertyWithUnit & keyof Props;
 /**
  * Converts a kebab-case string to camelCase.
  */
-
+declare function kebabToCamel(str: string): string;
+/**
+ * Converts a camelCase string to kebab-case.
+ */
+declare function camelToKebab(str: string): string;
 /**
  * Checks if a key represents a CSS at-rule (media, container, supports, layer).
  */
@@ -542,10 +544,11 @@ declare class CssObjectBlock {
   readonly subBlocks: CssObjectSubBlock[];
   /**
    * Creates a new CSS block from style properties.
-   * Generates a unique class name based on the content hash.
+   * Generates a unique class name based on the content hash, or uses the provided class name.
    * @param styles - The style properties to compile
+   * @param className - Optional stable class name; if omitted, a content-hash-based name is generated
    */
-  constructor(styles: StyleProps);
+  constructor(styles: StyleProps, className?: string);
   /**
    * Gets the CSS class selector for this block.
    */
@@ -632,13 +635,18 @@ declare class CSSObject<V extends AllVariants = DefaultVariants> {
   /**
    * Creates a new CSSObject from style props.
    * Compiles main styles and all variant options into CSS blocks.
+   * @param props - Base style props plus variant definitions
+   * @param props.variants - Named variant groups, each mapping variant values to style props
+   * @param props.defaultVariants - Default value for each variant when none is provided at runtime
+   * @param props.compoundVariants - Style props applied when a specific combination of variants is active
+   * @param className - Optional stable class name for the main block
    */
   constructor({
     variants,
     defaultVariants,
     compoundVariants,
     ...props
-  }: MochiCSSProps<V>);
+  }: MochiCSSProps<V>, className?: string);
   /**
    * Serializes the entire CSS object to a CSS string.
    * Outputs main block first, then all variant blocks in sorted order.
@@ -649,6 +657,20 @@ declare class CSSObject<V extends AllVariants = DefaultVariants> {
 //#endregion
 //#region src/css.d.ts
 declare function isMochiCSS(value: unknown): value is MochiCSS;
+/**
+ * Runtime representation of a CSS style definition with variant support.
+ * Holds generated class names and provides methods to compute the final
+ * className string based on selected variants.
+ *
+ * @template V - The variant definitions type mapping variant names to their options
+ *
+ * @example
+ * const styles = MochiCSS.from(new CSSObject({
+ *   color: 'blue',
+ *   variants: { size: { small: { fontSize: 12 }, large: { fontSize: 18 } } }
+ * }))
+ * styles.variant({ size: 'large' }) // Returns combined class names
+ */
 declare class MochiCSS<V extends AllVariants = DefaultVariants> {
   readonly classNames: string[];
   readonly variantClassNames: { [K in keyof V]: { [P in keyof V[K]]: string } };
@@ -669,6 +691,12 @@ declare class MochiCSS<V extends AllVariants = DefaultVariants> {
    * @returns Combined className string for use in components
    */
   variant(props: Partial<RefineVariants<V>>): string;
+  /**
+   * Returns the CSS selector for this style (e.g. `.abc123`).
+   * Useful for targeting this component from another style.
+   */
+  get selector(): string;
+  toString(): string;
   /**
    * Creates a MochiCSS instance from a CSSObject.
    * Extracts class names from the compiled CSS blocks.
@@ -685,46 +713,7 @@ declare class MochiCSS<V extends AllVariants = DefaultVariants> {
  * @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
-/** Props added by MochiCSS to styled components */
-type MochiProps<V extends AllVariants[]> = {
-  className?: string;
-} & Partial<RefineVariants<MergeCSSVariants<V>>>;
-/** Minimal interface for components that accept className */
-type Cls = {
-  className?: string;
-};
-/**
- * Creates a styled React component with CSS-in-JS support and variant props.
- * Similar to styled-components or Stitches, but with zero runtime overhead.
- *
- * @template T - The base element type or component type
- * @template V - The variant definitions tuple type
- * @param target - The HTML element tag name or React component to style
- * @param props - One or more style objects with optional variants
- * @returns A React functional component with merged props and variant support
- *
- * @example
- * const Button = styled('button', {
- *   padding: 8,
- *   borderRadius: 4,
- *   variants: {
- *     size: {
- *       small: { padding: 4 },
- *       large: { padding: 16 }
- *     },
- *     variant: {
- *       primary: { backgroundColor: 'blue' },
- *       secondary: { backgroundColor: 'gray' }
- *     }
- *   }
- * })
- *
- * // Usage: <Button size="large" variant="primary">Click me</Button>
- */
-declare function styled<T extends HTMLElementType | ComponentType<Cls>, V extends AllVariants[]>(target: T, ...props: { [K in keyof V]: MochiCSSProps<V[K]> }): FC<Omit<ComponentProps<T>, keyof MochiProps<V>> & MochiProps<V>>;
+declare function css<V extends AllVariants[]>(...props: { [K in keyof V]: MochiCSSProps<V[K]> | MochiCSS | string }): MochiCSS<MergeCSSVariants<V>>;
 //#endregion
 //#region src/keyframesObject.d.ts
 type KeyframeStops = Record<string, SimpleStyleProps>;
@@ -747,7 +736,11 @@ declare class MochiKeyframes {
 declare function keyframes(stops: KeyframeStops): MochiKeyframes;
 //#endregion
 //#region src/globalCssObject.d.ts
-type GlobalCssStyles = Record<string, StyleProps>;
+/** CSS properties accepting both camelCase and kebab-case names with permissive string values */
+type GlobalCssProperties = { [K in keyof (Properties & PropertiesHyphen)]?: string | number } & Record<string, unknown>;
+type GlobalCssStyles = {
+  [selector: string]: GlobalCssProperties | GlobalCssStyles;
+};
 /**
  * CSS object model for global (non-scoped) styles.
  * Accepts a map of CSS selectors to style objects and serializes them
@@ -821,5 +814,29 @@ interface SupportsHelper {
 /** 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, isMochiCSS, keyframes, media, mergeMochiCss, styled, supports };
+//#region src/hash.d.ts
+/**
+ * Hashing utilities for generating short, deterministic class names.
+ * Uses djb2 algorithm for fast string hashing.
+ * @module hash
+ */
+/**
+ * Converts a number to a base-62 string representation.
+ * @param num - The number to convert
+ * @param maxLength - Optional maximum length of the output string
+ * @returns Base-62 encoded string representation of the number
+ */
+declare function numberToBase62(num: number, maxLength?: number): string;
+/**
+ * Generates a short hash string from input using the djb2 algorithm.
+ * Used to create unique, deterministic CSS class names from style content.
+ * @param input - The string to hash
+ * @param length - Maximum length of the hash output (default: 8)
+ * @returns A short, css-safe hash string
+ * @example
+ * shortHash("color: red;") // Returns something like "A1b2C3d4"
+ */
+declare function shortHash(input: string, length?: number): string;
+//#endregion
+export { AllVariants, type AtRuleKey, CSSObject, CompoundVariant, CssLike, CssLikeObject, CssObjectBlock, CssObjectSubBlock, CssVar, CssVarVal, DefaultVariants, GlobalCssObject, GlobalCssProperties, type GlobalCssStyles, type KeyframeStops, KeyframesObject, MergeCSSVariants, MochiCSS, MochiCSSProps, MochiKeyframes, MochiSelector, RefineVariantType, RefineVariants, type StyleProps, Token, VariantProps, camelToKebab, container, createToken, css, cssFromProps, globalCss, isAtRuleKey, isMochiCSS, kebabToCamel, keyframes, media, mergeMochiCss, numberToBase62, shortHash, supports };
 //# sourceMappingURL=index.d.ts.map