tcss-core 1.0.0

# TCSS - Thematic CSS

A powerful CSS preprocessor that adds functions, variables, and expressions to CSS with Python-style indentation.

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()
[![License](https://img.shields.io/badge/license-MIT-blue)]()
[![Rust](https://img.shields.io/badge/rust-1.70+-orange)]()

## 🎯 Project Status

**Version 1.0.0 - Production Ready! 🎉**

**All 12 Phases: COMPLETE ✅**

### Completed Features ✅

- ✅ **Lexer & Parser** - Full TCSS syntax support
- ✅ **Executor** - Function execution and variable resolution
- ✅ **CSS Generator** - Optimized CSS output with minification
- ✅ **CLI Tool** - Command-line interface with watch mode
- ✅ **WASM Bindings** - Browser support via WebAssembly
- ✅ **JavaScript Integration** - npm package and browser loader
- ✅ **24 Built-in Functions** - Colors, math, and string utilities
- ✅ **Import System** - File imports with circular detection and caching
- ✅ **Comprehensive Tests** - 150+ tests with 80%+ code coverage
- ✅ **Complete Documentation** - 2,000+ lines of documentation
- ✅ **Performance Optimization** - Benchmarks and optimized builds
- ✅ **Publishing Ready** - Prepared for crates.io and npm

## ✨ Features

- ✅ **Variables** - Define reusable values
- ✅ **Functions** - Create custom functions with parameters
- ✅ **Expressions** - Perform calculations in CSS
- ✅ **24 Built-in Functions** - Colors, math, and string utilities
- ✅ **Import System** - Split code across multiple files
- ✅ **Python-style Indentation** - Clean, readable syntax
- ✅ **Type Safety** - Compile-time type checking
- ✅ **Zero Runtime** - Compiles to pure CSS
- ✅ **WASM Support** - Run in the browser
- ✅ **Fast** - Written in Rust for maximum performance

## 📦 Project Structure

```
TCSS/
├── tcss-core/           # Core compiler library ✅
│   ├── src/
│   │   ├── lexer.rs     # Tokenizer ✅
│   │   ├── parser.rs    # AST parser ✅
│   │   ├── executor.rs  # Function executor ✅
│   │   ├── generator.rs # CSS generator ✅
│   │   ├── import.rs    # Import processor ✅
│   │   ├── resolver.rs  # Path resolver ✅
│   │   └── builtins/    # Built-in functions ✅
│   └── tests/           # Comprehensive test suite ✅
├── tcss-cli/            # Command-line interface ✅
├── tcss-wasm/           # WebAssembly bindings ✅
├── tcss-js/             # JavaScript wrapper ✅
├── docs/                # Complete documentation ✅
└── examples/            # Example projects ✅
```

## 🚀 Quick Start

### Installation

```bash
# Using Cargo
cargo install tcss-cli

# Using npm
npm install tcss-js
```

### Your First TCSS File

**styles.tcss:**
```tcss
@var primary: #3498db
@var spacing: 16px

@fn button-padding(size):
    return size * spacing

.button:
    background: primary
    padding: button-padding(1)
    border-radius: 4px
    color: white

.button:hover:
    background: lighten(primary, 10)
```

### Compile

```bash
tcss compile styles.tcss -o styles.css
```

### Output

```css
.button {
    background: #3498db;
    padding: 16px;
    border-radius: 4px;
    color: white;
}

.button:hover {
    background: #5dade2;
}
```

## 📚 Documentation

### Getting Started
- [Quick Reference](docs/QUICK_REFERENCE.md) - Quick syntax reference
- [User Guide](docs/USER_GUIDE.md) - Complete user documentation
- [Examples](examples/) - Example TCSS files

### API & Reference
- [API Documentation](docs/API.md) - Rust and JavaScript API
- [Built-in Functions](docs/BUILTIN_FUNCTIONS.md) - Function reference
- [Import System](docs/IMPORT_SYSTEM.md) - Import documentation

### Development
- [Testing Guide](docs/TESTING.md) - How to run and write tests
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Optimization Guide](docs/OPTIMIZATION.md) - Performance optimization

### Publishing
- [Publishing Guide](docs/PUBLISHING.md) - How to publish releases
- [Changelog](CHANGELOG.md) - Version history
- [Project Summary](docs/PROJECT_SUMMARY.md) - Complete project overview

## 💡 Examples

### Variables & Functions

```tcss
@var primary-color: #3498db
@var base-spacing: 16px

@fn spacing(multiplier):
    return multiplier * base-spacing

.card:
    padding: spacing(2)
    background: primary-color
```

### Built-in Functions

```tcss
// Color manipulation
.button:
    background: darken(#3498db, 10)
    border-color: lighten(#3498db, 10)
    color: rgba(255, 255, 255, 0.9)

// Math operations
.box:
    width: max(100px, 50%)
    padding: clamp(16px, 2vw, 32px)

// String utilities
.text:
    font-family: uppercase("arial")
```

### Imports

```tcss
@import './colors.tcss'
@import './theme/base.tcss'
@import '@tcss/core'

.button:
    background: primary
```

## 🧪 Testing

Run the comprehensive test suite:

```bash
# Run all tests
cargo test

# Run specific test suite
cargo test --test integration_tests
cargo test --test e2e_tests

# Run with coverage
cargo tarpaulin --out Html
```

**Test Coverage: 80%+**

- ✅ **Unit Tests** - All core modules (lexer, parser, executor, generator, etc.)
- ✅ **Integration Tests** - End-to-end compilation workflows
- ✅ **E2E Tests** - File I/O, imports, and complete workflows
- ✅ **Built-in Function Tests** - All 24 built-in functions
- ✅ **Import System Tests** - Circular detection, caching, resolution

## 🛠️ Usage

### CLI

```bash
# Compile a file
tcss compile input.tcss -o output.css

# Compile with minification
tcss compile input.tcss -o output.css --minify

# Watch for changes
tcss watch input.tcss -o output.css
```

### Rust API

```rust
use tcss_core::{Lexer, Parser, Executor, Generator};

let source = r#"
    @var primary: #3498db
    .button:
        background: primary
"#;

let mut lexer = Lexer::new(source);
let tokens = lexer.tokenize()?;
let mut parser = Parser::new(tokens);
let program = parser.parse()?;
let mut executor = Executor::new();
let executed = executor.execute(&program)?;
let mut generator = Generator::new();
let css = generator.generate(&executed)?;
```

### JavaScript API

```javascript
import { compile } from 'tcss-js';

const tcss = `
@var primary: #3498db

.button:
    background: primary
`;

const css = compile(tcss);
```

### Browser

```html
<link rel="tcss" href="styles.tcss">
<script type="module">
    import { init } from './tcss-js/index.js';
    await init();
</script>
```

## 📋 Development Roadmap

- [x] **Phase 1: Core Lexer/Tokenizer** ✅
- [x] **Phase 2: AST Parser** ✅
- [x] **Phase 3: Expression Evaluator** ✅
- [x] **Phase 4: CSS Generator** ✅
- [x] **Phase 5: Error Handling** ✅
- [x] **Phase 6: CLI Tool** ✅
- [x] **Phase 7: WebAssembly Bindings** ✅
- [x] **Phase 8: JavaScript Integration** ✅
- [x] **Phase 9: Built-in Functions Library** ✅
- [x] **Phase 10: Import System** ✅
- [x] **Phase 11: Testing & Documentation** ✅
- [x] **Phase 12: Optimization & Publishing** ✅

## 🛠️ Technology Stack

- **Rust** - Core implementation language
- **wasm-bindgen** - WebAssembly bindings
- **serde** - Serialization framework
- **clap** - CLI argument parsing
- **tempfile** - Testing utilities

## 🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- Inspired by Sass, Less, and Stylus
- Built with Rust for performance and safety
- Uses wasm-bindgen for WebAssembly support

## 💬 Support

- GitHub Issues: [Report bugs or request features](https://github.com/tosiiko/TCSS/issues)
- Documentation: [Read the docs](https://github.com/tosiiko/TCSS/tree/main/docs)
- Examples: [See examples](https://github.com/tosiiko/TCSS/tree/main/examples)

---

Made with ❤️ by TCSS Contributors

**Current Version:** 1.0.0 - Production Ready! 🎉