chaincss 1.13.2 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to ChainCSS will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-04-10
+
+### 🎉 Major Release: Zero-Runtime Architecture
+
+ChainCSS 2.0 is a complete rewrite focused on **zero-runtime CSS-in-JS** with optional runtime for development.
+
+### ✨ Added
+
+- **Zero-runtime mode**: Styles compile to static CSS at build time (0KB in production)
+- **Shorthand properties**: `$.bg()`, `$.c()`, `$.p()`, `$.m()`, `$.rounded()`, etc. (write less, do more)
+- **Responsive breakpoint methods**: `.mobile()`, `.tablet()`, `.desktop()`, `.sm()`, `.md()`, `.lg()`, `.xl()`
+- **Animation presets**: `.fadeIn()`, `.slideInUp()`, `.pulse()`, `.spin()`, `.bounce()`, `.shake()`, etc.
+- **Math/Calc helpers**: `$.calc()`, `$.add()`, `$.subtract()`, `$.multiply()`, `$.divide()`
+- **Debug mode**: `.debug()` with console output showing source file and line number
+- **Style versioning**: Source comments in CSS (`/* Generated from: nav.chain.js:15 */`)
+- **Timeline/Diff viewer**: Track style changes with `chaincss build --timeline` and `chaincss timeline diff`
+- **Configurable breakpoints**: Custom breakpoints in `chaincss.config.js`
+- **Environment-aware defaults**: `readable` class names in development, `hash` in production
+- **Atomic CSS optimization**: Automatic detection and reuse of common styles (opt-in)
+- **CLI tool**: `chaincss init`, `chaincss build`, `chaincss watch`, `chaincss clean`
+- **Vite plugin**: Seamless integration with Vite
+- **Webpack plugin**: Webpack loader for .chain.js files
+- **TypeScript support**: Full type definitions with generated types
+- **Recipe system**: Variant-based component styling
+- **Design tokens**: Built-in token system with theme contracts
+- **Optional runtime**: 3.2KB runtime for development and dynamic theming
+- **React hooks**: `useChainStyles`, `useDynamicChainStyles`, `useThemeChainStyles`, `createStyledComponent`
+- **Vue composables**: `useAtomicClasses`, `createStyledComponent`
+- **Improved file structure**: Each component has its own `styles/` folder with `.chain.js`, `.class.js`, and `.css` files
+- **Global styles separation**: `global-style/` folder for global CSS
+- **Better minification**: `global.css` minified for production, component CSS unminified for debugging
+
+### 🔧 Changed
+
+- Complete rewrite from runtime-only to hybrid architecture
+- New package structure with ESM support
+- Better tree-shaking for smaller bundles
+- Improved CSS property validation
+- Class name generation now uses `readable` format by default in development
+
+### 🗑️ Removed
+
+- `@melcanz85/chaincss` legacy package reference (now unified under `chaincss`)
+
+### 📚 Documentation
+
+- New documentation site with interactive playground
+- Migration guide from v1.x
+- API reference with examples
+- CLI reference with all commands
+- Configuration guide with all options
+
+---
+
+## [1.13.3] - 2026-03-30
+
+### Fixed
+- Bug fixes and performance improvements
+
+### Changed
+- Updated dependencies
+
+---
+
+## [1.0.0] - 2023-01-01
+
+### 🎉 Initial Release
+
+- Chainable CSS API
+- Runtime style injection
+- React hooks
+- Vue composables
+- Token system
+- Recipe variants

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Rommel Caneos
+Copyright (c) 2006 Rommel Caneos
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,5 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-EOF
+SOFTWARE.

package/README.md

@@ -4,146 +4,271 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Live Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://chaincss.dev)
 
-> Chainable CSS-in-JS with build-time compilation, atomic CSS, and zero-runtime options
+> **ChainCSS** The JavaScript-native styling engine for the modern web.
 
 > **Note:** The previous package `@melcanz85/chaincss` is no longer supported.  
-> **Please install `chaincss` instead:** `npm install chaincss`
+> **Please install this updated `chaincss` instead:** `npm install chaincss`
 
-##  Features
+## ✨ Features
 
-### Core Styling Features
+### Core Styling
 
-| Feature | Description |
-|---------|-------------|
-| **Chainable API** | `$().color('red').padding('10px').block()` |
-| **CSS Properties** | All standard CSS properties (camelCase) |
-| **Multiple Selectors** | `.block('.btn', '.button', '[type="button"]')` |
-| **Hover States** | `.hover().backgroundColor('blue').end()` |
-| **Hover Exit** | `.end()` method to exit hover mode |
-| **Nested Selectors** | `.select('.parent .child')` |
-| **Token Resolution** | `$colors.primary` → actual color value |
-| **CSS Property Validation** | Warns on invalid CSS properties |
-
-### At-Rules (CSS Rules)
-
-| At-Rule | Method | Example |
-|---------|--------|---------|
-| **Media Queries** | `.media()` | `.media('(max-width: 768px)', (css) => {...})` |
-| **Keyframes** | `.keyframes()` | `.keyframes('slide', (kf) => {...})` |
-| **Font Face** | `.fontFace()` | `.fontFace((css) => {...})` |
-| **Supports** | `.supports()` | `.supports('display: grid', (css) => {...})` |
-| **Container Queries** | `.container()` | `.container('(min-width: 400px)', (css) => {...})` |
-| **CSS Layers** | `.layer()` | `.layer('components', (css) => {...})` |
-| **Counter Styles** | `.counterStyle()` | `.counterStyle('circled', (css) => {...})` |
-| **Custom Properties** | `.property()` | `.property('--my-color', (css) => {...})` |
-
-### Design System
-
-| Feature | Description |
-|---------|-------------|
-| **Design Tokens** | `createTokens()` with colors, spacing, typography |
-| **Token Getter** | `tokens.get('colors.primary')` |
-| **Token Resolution in Styles** | `$colors.primary` syntax |
-| **Responsive Values** | `responsive({ base: '16px', sm: '14px', lg: '18px' })` |
-| **Theme Switching** | Dynamic token updates at runtime |
-| **CSS Variables Output** | `tokens.toCSSVariables()` |
+| Feature | Description | Example |
+|---------|-------------|---------|
+| **Chainable API** | Intuitive method chaining | `$.color('red').padding('10px')` |
+| **Shorthand Properties** | Write less, do more | `$.bg('blue').c('white').p('20px')` |
+| **CSS Properties** | All standard CSS properties | `$.display('flex').gap('1rem')` |
+| **Multiple Selectors** | Style multiple elements | `.$el('.btn', '.button')` |
+| **Hover States** | Interactive styles | `.hover().bg('darkblue').end()` |
+| **Responsive Breakpoints** | Built-in breakpoint methods | `.mobile(css => css.p('1rem'))` |
+| **Media Queries** | Custom media queries | `.media('(max-width: 768px)', ...)` |
 
-### Component System
+### 🚀 Advanced Features
 
-| Feature | Description |
-|---------|-------------|
-| **Framework Agnostic** | React, Next.js, Vite, Webpack |
-| **Recipe System** | `recipe()` for variant-based components |
-| **Base Styles** | `recipe({ base: $().padding('8px').block() })` |
-| **Variants** | `variants: { color: { primary: $().bg('blue').block() } }` |
-| **Default Variants** | `defaultVariants: { color: 'primary' }` |
-| **Compound Variants** | `compoundVariants: [{ variants: { color: 'primary', size: 'lg' }, style: ... }]` |
-| **Variant Combination** | `button({ color: 'primary', size: 'lg' })` |
-| **Compile All Variants** | `button.compileAll()` |
+| Feature | Description | Example |
+|---------|-------------|---------|
+| **Animation Presets** | Pre-built animations | `.fadeIn().duration('0.3s')` |
+| **Math Helpers** | CSS calc() helpers | `$.width($.calc('100% - 20px'))` |
+| **Design Tokens** | Centralized design values | `tokens.get('colors.primary')` |
+| **Debug Mode** | Console debugging for styles | `$.debug().bg('red')` |
+| **Source Comments** | Track style origins | `/* Generated from: nav.chain.js:15 */` |
+| **Style Timeline** | Track style changes | `chaincss build --timeline` |
 
-### Build-Time Features (CLI)
+### 🏗️ Build System
 
 | Feature | Command/Flag |
 |---------|--------------|
-| **CSS Compilation** | `chaincss input.jcss output/dir` |
-| **Watch Mode** | `--watch` flag |
-| **Atomic CSS Optimization** | `--atomic` flag |
-| **Source Maps** | `--source-map` flag |
-| **Minification** | Via CleanCSS (built-in) |
-| **Autoprefixer** | `--prefixer-mode auto` |
-| **Class Map Generation** | `.map.json` output |
-| **JS Module Export** | `.classes.js` output |
-| **TypeScript Definitions** | `.classes.d.ts` output |
-| **Build Manifest** | `chaincss-manifest.json` |
-| **CSS Property Cache** | Local cache for faster builds |
-
-### React Runtime Features
-
-| Feature | Description |
-|---------|-------------|
-| **useChainStyles** | Main React hook for styles |
-| **useDynamicChainStyles** | For dynamic styles with dependencies |
-| **useThemeChainStyles** | For theme-aware styles |
-| **ChainCSSGlobal** | Global style injection component |
-| **withChainStyles** | HOC for class components |
-| **cx** | Class name utility (like clsx) |
+| **CSS Compilation** | `chaincss build` |
+| **Watch Mode** | `chaincss watch` |
+| **Config File** | `chaincss.config.js` |
+| **Auto-prefixer** | Built-in via `--prefixer` |
+| **Minification** | Global.css minified, components unminified |
+| **TypeScript Support** | Full type definitions |
+| **Source Maps** | For debugging |
+
+### ⚛️ Framework Support
+
+| Framework | Support |
+|-----------|---------|
+| **React** | ✅ `useChainStyles` hook, `createStyledComponent` |
+| **Vue** | ✅ `useAtomicClasses` composable |
+| **Solid** | ✅ Coming soon |
+| **Svelte** | ✅ Coming soon |
+| **Vanilla** | ✅ Runtime mode |
 
-### Plugin Ecosystem
+### 🔌 Plugins
 
 | Plugin | Description |
 |--------|-------------|
-| **Vite Plugin** | `.jcss` support with HMR |
-| **Webpack Plugin** | Build-time compilation |
-| **Next.js Plugin** | SSR support |
-| **Webpack Loader** | ChainCSS loader for webpack |
+| **Vite** | Automatic `.chain.js` compilation |
+| **Webpack** | Build-time integration |
+| **Next.js** | SSR support |
 
-### Development Tools
+### 📁 File Structure
 
-| Feature | Description |
-|---------|-------------|
-| **TypeScript Support** | Full type definitions (`types.d.ts`) |
-| **Configuration File** | `chaincss.config.cjs` for customization |
-| **Cache Management** | Atomic optimizer cache |
-| **Cache Cleanup** | Auto cleanup of old cache files |
-| **Atomic Optimizer Stats** | `atomicOptimizer.getStats()` |
-| **configureAtomic** | Programmatic atomic config |
+```
+src/
+├── components/
+│   └── Button/
+│       ├── Button.tsx
+│       └── styles/
+│           ├── button.chain.js    # Source styles
+│           ├── button.class.js    # Generated class names
+│           └── button.css         # Generated CSS
+├── global-style/
+│   ├── global.chain.js             # Global styles
+│   └── global.css                  # Combined CSS
+└── chaincss.config.js              # Configuration
+```
 
-### CSS Output Features
+## 📦 Installation
 
-| Feature | Description |
-|---------|-------------|
-| **Pure CSS Output** | `global.css` generation |
-| **Atomic CSS Output** | Reusable atomic classes |
-| **Source Maps** | `.map` files for debugging |
-| **Class Mapping** | Selector → atomic class map |
-| **Minified Output** | Via CleanCSS |
-| **Vendor Prefixing** | Via Autoprefixer |
+```bash
+npm install chaincss
+```
 
-### Performance Features
+## 🚀 Quick Start
 
-| Feature | Description |
-|---------|-------------|
-| **Zero Runtime Option** | Build mode = 0KB runtime |
-| **Small Runtime** | Runtime mode = ~3.2KB |
-| **Tree Shaking** | `sideEffects: false` |
-| **Atomic CSS Optimization** | Eliminates duplicate styles |
-| **Cache Strategy** | File + compiled function cache |
+### 1. Initialize configuration
+
+```bash
+npx chaincss init
+# or for full configuration
+npx chaincss init --full
+```
+
+### 2. Create your first style
+
+```javascript
+// src/components/Button/styles/button.chain.js
+import { $ } from 'chaincss';
+
+export const button = $
+  .bg('#667eea')
+  .c('white')
+  .p('12px 24px')
+  .rounded('8px')
+  .cursor('pointer')
+  .hover()
+    .bg('#5a67d8')
+  .end()
+  .$el('.btn');
+```
+
+### 3. Build styles
+
+```bash
+npx chaincss build
+```
+
+### 4. Use in React
+
+```jsx
+import { button } from './styles/button.class.js';
+import './styles/button.css';
+
+function Button() {
+  return <button className={button}>Click me</button>;
+}
+```
+
+## 📝 Examples
+
+### Responsive Design
+
+```javascript
+export const title = $
+  .fontSize('3rem')
+  .mobile(css => css.fontSize('1.5rem'))
+  .tablet(css => css.fontSize('2rem'))
+  .desktop(css => css.fontSize('2.5rem'))
+  .$el('.title');
+```
 
-### Security & Compatibility
+### Animations
 
-| Feature | Description |
+```javascript
+export const card = $
+  .fadeInUp({ duration: '0.5s' })
+  .pulse({ duration: '2s', iteration: 'infinite' })
+  .bg('white')
+  .rounded('12px')
+  .$el('.card');
+```
+
+### Math Helpers
+
+```javascript
+export const container = $
+  .width($.calc('100% - 40px'))
+  .padding($.add($.rem(2), $.px(10)))
+  .margin($.subtract('100vw', '20px'))
+  .$el('.container');
+```
+
+### Shorthand Properties
+
+```javascript
+export const card = $
+  .bg('white')
+  .c('gray-800')
+  .p('20px')
+  .m('10px')
+  .rounded('8px')
+  .shadow('lg')
+  .$el('.card');
+```
+
+## ⚙️ Configuration
+
+Create `chaincss.config.js`:
+
+```javascript
+export default {
+  inputs: ['src/**/*.chain.js'],
+  output: 'dist/styles',
+  atomic: {
+    enabled: false,  // Enable atomic CSS optimization
+    naming: 'readable'  // or 'hash' for production
+  },
+  prefixer: {
+    enabled: true  // Auto-prefixer for cross-browser support
+  },
+  breakpoints: {
+    mobile: '(max-width: 768px)',
+    tablet: '(min-width: 769px) and (max-width: 1024px)',
+    desktop: '(min-width: 1025px)'
+  },
+  debug: false,
+  verbose: false
+};
+```
+
+## 🎯 Runtime Mode (Optional)
+
+For dynamic styles without build step:
+
+```jsx
+import { useChainStyles } from 'chaincss/runtime';
+
+function DynamicButton() {
+  const styles = useChainStyles({
+    button: {
+      backgroundColor: '#667eea',
+      color: 'white',
+      padding: '12px 24px'
+    }
+  });
+  
+  return <button className={styles.button}>Click me</button>;
+}
+```
+
+## 📊 CLI Commands
+
+| Command | Description |
 |---------|-------------|
-| **No eval()** | Uses `new Function()` with parameters |
-| **No vm2** | Native Node.js module system |
-| **Node.js 14+** | Minimum version requirement |
-| **ESM/CJS Support** | Dual module format |
-| **Browser Support** | Modern browsers via autoprefixer |
+| `chaincss init` | Create config file |
+| `chaincss init --full` | Create full config with all options |
+| `chaincss build` | Build all styles |
+| `chaincss build --timeline` | Build with timeline tracking |
+| `chaincss watch` | Watch for changes |
+| `chaincss clean` | Remove generated files |
+
+## 🔧 Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"npm:css:watch\" \"vite\"",
+    "build": "npm run css:build && vite build",
+    "css:build": "chaincss build",
+    "css:watch": "chaincss watch",
+    "css:clean": "chaincss clean"
+  }
+}
+```
+
+## 📚 Documentation
 
-## Documentation
+For complete guide, API reference, and examples:
 
-For complete guide, documentation, examples, and API reference, 
-just go to the docs section of [https://chaincss.dev](https://www.chaincss.dev)
+### [Documentation](https://chaincss.dev/docs)
 
-## License
+- [Getting Started](https://chaincss.dev/docs)
+- [Chainable API](https://chaincss.dev/docs/chainable-api)
+- [Responsive Design](https://chaincss.dev/docs/responsive)
+- [Animations](https://chaincss.dev/docs/animations)
+- [Configuration](https://chaincss.dev/docs/configuration)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
+
+## 📄 License
 
 MIT © [Rommel Caneos](https://github.com/melcanz08)
+
+## 🌟 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=melcanz08/chaincss&type=Date)](https://star-history.com/#melcanz08/chaincss&Date)

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,3 @@
+import type { BuildOptions } from '../types.js';
+export declare function buildCommand(options: BuildOptions): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/cli/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFvE"}

package/dist/cli/commands/compile.d.ts

@@ -0,0 +1,3 @@
+import type { CompileOptions } from '../types.js';
+export declare function compileCommand(options: CompileOptions): Promise<void>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/cli/commands/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/compile.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF3E"}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,5 @@
+export declare function initCommand(options: {
+    force?: boolean;
+    verbose?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAOA,wBAAsB,WAAW,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyGhG"}

package/dist/cli/commands/timeline.d.ts

@@ -0,0 +1,2 @@
+export declare function timelineCommand(action: string, options: any): Promise<void>;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/cli/commands/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/timeline.ts"],"names":[],"mappings":"AAIA,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,iBAkEjE"}

package/dist/cli/commands/watch.d.ts

@@ -0,0 +1,6 @@
+import type { BuildOptions } from '../types.js';
+export interface WatchOptions extends BuildOptions {
+    debounce?: number;
+}
+export declare function watchCommand(options: WatchOptions): Promise<void>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/cli/commands/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/watch.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0LvE"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}