@aurora-ds/theme 1.0.3

package/README.dev.md

@@ -0,0 +1,342 @@
+# Aurora Theme - Developer Guide
+
+This document is intended for developers who want to contribute to the Aurora Theme library.
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** >= 10.9.0
+- **React** >= 18.0.0 (peer dependency)
+
+## Project Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/LilianMrzt/Aurora.git
+cd Aurora
+
+# Install dependencies
+npm install
+```
+
+---
+
+## Available Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev` | `npm run dev` | Build in watch mode (development) |
+| `build` | `npm run build` | Production build |
+| `test` | `npm test` | Run tests in watch mode |
+| `test:run` | `npm run test:run` | Run tests once |
+| `test:coverage` | `npm run test:coverage` | Tests with coverage report |
+| `lint` | `npm run lint` | ESLint check |
+| `lint:fix` | `npm run lint:fix` | Auto-fix ESLint issues |
+| `typecheck` | `npm run typecheck` | TypeScript check |
+| `size` | `npm run size` | Bundle size check |
+| `audit` | `npm run audit` | Dependency security audit |
+| `audit:fix` | `npm run audit:fix` | Auto-fix vulnerabilities |
+| `validate` | `npm run validate` | Lint + TypeCheck + Tests |
+| `ci` | `npm run ci` | Full CI pipeline |
+
+---
+
+## Project Structure
+
+```
+aurora/
+├── src/                       # Source code
+│   ├── index.ts              # Main entry point (exports)
+│   ├── providers/            # React Context providers
+│   │   ├── ThemeProvider.tsx
+│   │   └── index.ts
+│   ├── types/                # TypeScript types
+│   │   ├── colors/           # Color types
+│   │   ├── palettes/         # Palette types
+│   │   └── theme/            # Theme types
+│   └── utils/                # Utilities
+│       ├── styles/           # CSS-in-JS style utilities
+│       └── theme/            # Theme creation utilities
+├── tests/                    # Unit tests
+│   ├── setup.ts              # Vitest configuration
+│   ├── providers/            # Provider tests
+│   └── utils/                # Utility tests
+├── dist/                     # Production build (generated)
+├── coverage/                 # Coverage report (generated)
+├── tsconfig.json             # Main TS config
+├── tsconfig.build.json       # Build TS config
+├── tsconfig.test.json        # Test TS config
+├── tsup.config.ts            # Bundler config
+├── vitest.config.ts          # Test config
+└── package.json
+```
+
+---
+
+## Development
+
+### Start Development Mode
+
+```bash
+npm run dev
+```
+
+This launches `tsup` in watch mode which automatically recompiles on every change.
+
+### Run Tests
+
+```bash
+# Watch mode (development)
+npm test
+
+# Single run
+npm run test:run
+
+# With coverage
+npm run test:coverage
+```
+
+### Code Verification
+
+```bash
+# Check everything at once
+npm run validate
+
+# Or separately
+npm run lint        # ESLint
+npm run typecheck   # TypeScript
+npm run test:run    # Tests
+```
+
+---
+
+## Build & Publishing
+
+### Production Build
+
+```bash
+npm run build
+```
+
+The build generates in `dist/`:
+- `index.js` - ESM module
+- `index.cjs` - CommonJS module
+- `index.d.ts` - TypeScript types
+- `index.d.cts` - CommonJS types
+
+### Pre-publish Verification
+
+```bash
+# Full CI pipeline
+npm run ci
+```
+
+This command runs:
+1. `lint` - Code verification
+2. `typecheck` - Type checking
+3. `test:run` - Test execution
+4. `build` - Production build
+5. `size` - Size check (< 10 KB gzipped)
+6. `audit` - Security audit
+
+### Publishing to npm
+
+```bash
+# 1. Update version in package.json
+# 2. Update CHANGELOG.md
+# 3. Commit and tag
+
+npm version patch  # or minor, major
+git push --follow-tags
+
+# 4. Publish
+npm publish --access public
+```
+
+> Note: `prepublishOnly` automatically runs `npm run ci` before publishing.
+
+---
+
+## Updating the Library
+
+### Updating Dependencies
+
+```bash
+# View available updates
+npm outdated
+
+# Update dependencies
+npm update
+
+# Or to update to latest major versions
+npx npm-check-updates -u
+npm install
+```
+
+### After an Update
+
+1. **Run full validation:**
+   ```bash
+   npm run validate
+   ```
+
+2. **Check bundle size:**
+   ```bash
+   npm run size
+   ```
+
+3. **Check for vulnerabilities:**
+   ```bash
+   npm run audit
+   ```
+
+---
+
+## Adding a New Feature
+
+### 1. Create Types (if needed)
+
+Add in `src/types/`:
+
+```typescript
+// src/types/theme/NewFeature.ts
+export interface NewFeature {
+    // ...
+}
+```
+
+Export in `src/types/index.ts`.
+
+### 2. Create the Utility
+
+Add in `src/utils/`:
+
+```typescript
+// src/utils/newFeature.ts
+export const newFeature = () => {
+    // ...
+}
+```
+
+Export in `src/utils/index.ts` and `src/index.ts`.
+
+### 3. Write Tests
+
+```typescript
+// tests/utils/newFeature.test.ts
+import { describe, it, expect } from 'vitest'
+import { newFeature } from '@/utils/newFeature'
+
+describe('newFeature', () => {
+    it('should ...', () => {
+        expect(newFeature()).toBe(...)
+    })
+})
+```
+
+### 4. Update Documentation
+
+- Update `README.md` with the public API
+- Update `CHANGELOG.md` in the `[Unreleased]` section
+
+---
+
+## Code Conventions
+
+### Commits
+
+Use the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+feat: add new color palette
+fix: resolve caching issue
+docs: update README
+test: add unit tests for createTheme
+refactor: improve style engine performance
+chore: update dependencies
+```
+
+### Code Style
+
+- **Indentation**: 4 spaces
+- **Quotes**: Single `'`
+- **Semicolons**: No
+- **Trailing comma**: Yes
+
+ESLint and TypeScript are configured to validate these rules.
+
+### Exports
+
+All public exports must be in `src/index.ts`:
+
+```typescript
+// Types
+export type { Theme, BaseColors, ... } from './types'
+
+// Providers
+export { ThemeProvider, useTheme } from './providers'
+
+// Utils
+export { createStyles, createTheme, ... } from './utils'
+```
+
+---
+
+## Size Limits
+
+The bundle must stay under **10 KB gzipped** for each format:
+
+```json
+"size-limit": [
+    { "path": "dist/index.js", "limit": "10 KB", "gzip": true },
+    { "path": "dist/index.cjs", "limit": "10 KB", "gzip": true }
+]
+```
+
+If the limit is exceeded:
+- Optimize the code
+- Use tree-shaking
+- Avoid unnecessary dependencies
+
+---
+
+## Test Coverage
+
+Target: **> 80%** coverage.
+
+Reports are generated in `coverage/`:
+- `coverage/index.html` - Interactive HTML report
+- `coverage/coverage-final.json` - Raw data
+
+---
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for:
+- Supported versions
+- How to report a vulnerability
+- Project security practices
+
+### Key Points
+
+- **No `eval()`** or `Function()` constructor
+- **CSS sanitization** to prevent injections
+- **Regular auditing** of dependencies
+
+---
+
+## Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [Vitest Documentation](https://vitest.dev/)
+- [tsup Documentation](https://tsup.egoist.dev/)
+- [ESLint Rules](https://eslint.org/docs/rules/)
+
+---
+
+## Contact
+
+For any development questions:
+- Email: lilian.marzet@gmail.com
+- Issues: [GitHub Issues](https://github.com/LilianMrzt/Aurora/issues)
+

package/README.md

@@ -0,0 +1,390 @@
+# Aurora Theme
+
+A performant, type-safe, and **fully customizable** CSS-in-JS theme management library for React applications.
+
+## Features
+
+- 🎨 **Modular Theming** - Customize colors, spacing, or any token independently
+- 🎯 **Color Scales** - 20 color palettes with 12 shades each (25-950)
+- ⚡ **Optimized Performance** - LRU caching, static style deduplication
+- 🖥️ **SSR Support** - Server-side rendering compatible
+- 📦 **Lightweight** - No runtime dependencies besides React
+- 🔒 **Type-safe** - Full TypeScript support with generics
+- 🌗 **Dark Mode Ready** - Light and dark variants for all palettes
+
+## Installation
+
+```bash
+npm install @aurora-dev-ui/theme
+```
+
+## Quick Start
+
+```tsx
+import { defaultTheme, ThemeProvider, createStyles } from '@aurora-dev-ui/theme'
+
+// 1. Wrap your app
+<ThemeProvider theme={defaultTheme}>
+    <App />
+</ThemeProvider>
+
+// 2. Create styles
+const STYLES = createStyles((theme) => ({
+    container: {
+        padding: theme.spacing.md,
+        backgroundColor: theme.colors.surface,
+        borderRadius: theme.radius.lg,
+    },
+}))
+
+// 3. Use in components
+function MyComponent() {
+    return <div className={STYLES.container}>Hello!</div>
+}
+```
+
+---
+
+## Color Scales
+
+Aurora provides **20 color scales** with **12 shades each** (25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950).
+
+### Available Scales
+
+**Neutrals**
+- `gray` - Pure neutral, universal default
+- `slate` - Cool/blue undertone, tech & corporate
+- `stone` - Warm undertone, lifestyle & natural
+
+**Colors**
+- `red` `orange` `amber` `yellow` `lime` `green`
+- `emerald` `teal` `cyan` `sky` `blue` `indigo`
+- `violet` `purple` `fuchsia` `pink` `rose`
+
+### Usage
+
+```tsx
+import { colors, indigo, emerald } from '@aurora-ui/theme'
+
+// Via the colors object
+colors.indigo[500]  // '#6366f1'
+colors.emerald[400] // '#34d399'
+colors.gray[900]    // '#18181b'
+
+// Or import individual scales
+indigo[600]         // '#4f46e5'
+emerald[50]         // '#ecfdf5'
+
+// Special values
+colors.white        // '#ffffff'
+colors.black        // '#000000'
+colors.transparent  // 'transparent'
+```
+
+### Build Custom Theme Colors
+
+```tsx
+import { colors, defaultTheme, createTheme } from '@aurora-ui/theme'
+
+const myTheme = createTheme(defaultTheme, {
+    colors: {
+        primary: colors.purple[500],
+        primaryHover: colors.purple[600],
+        primaryActive: colors.purple[700],
+        primarySubtle: colors.purple[50],
+        // ... other colors
+    }
+})
+```
+
+---
+
+## Theme Palettes (Presets)
+
+Aurora includes **8 ready-to-use color palettes**, each with light and dark variants.
+
+### Available Palettes
+
+| Palette | Style | Best For |
+|---------|-------|----------|
+| `indigo` | Modern, professional | SaaS, business apps |
+| `rose` | Warm, friendly | Social, lifestyle |
+| `emerald` | Fresh, natural | Health, fintech |
+| `violet` | Creative, bold | Creative, gaming |
+| `amber` | Energetic, warm | Food, education |
+| `cyan` | Tech, modern | Tech, startups |
+| `slate` | Minimal, corporate | Enterprise, B2B |
+| `gray` | Ultra minimal | Portfolios, luxury |
+
+### Usage
+
+```tsx
+import { 
+    palettes, 
+    roseLight, 
+    roseDark,
+    createTheme, 
+    defaultTheme 
+} from '@aurora-ui/theme'
+
+// Option 1: Import directly
+const roseTheme = createTheme(defaultTheme, { colors: roseLight })
+const roseDarkTheme = createTheme(defaultTheme, { colors: roseDark })
+
+// Option 2: Via palettes object
+const theme = createTheme(defaultTheme, { 
+    colors: palettes.emerald.light 
+})
+
+// Option 3: Dynamic switching
+const [isDark, setIsDark] = useState(false)
+const theme = createTheme(defaultTheme, {
+    colors: palettes.violet[isDark ? 'dark' : 'light']
+})
+```
+
+---
+
+## Modular Customization
+
+Customize only what you need - colors, spacing, or any individual token.
+
+### Available Presets
+
+```tsx
+import {
+    // Complete themes
+    defaultTheme,
+    defaultDarkTheme,
+    
+    // Individual presets
+    defaultColors,
+    defaultDarkColors,
+    defaultSpacing,
+    defaultRadius,
+    defaultShadows,
+    defaultFontSize,
+    defaultFontWeight,
+    defaultLineHeight,
+    defaultZIndex,
+    defaultTransition,
+} from '@aurora-ui/theme'
+```
+
+### Customize Only Colors
+
+```tsx
+import { defaultTheme, defaultColors, createTheme } from '@aurora-ui/theme'
+
+const myTheme = createTheme(defaultTheme, {
+    colors: {
+        ...defaultColors,
+        primary: '#your-brand-color',
+        primaryHover: '#your-brand-hover',
+    },
+})
+```
+
+### Customize Only Spacing
+
+```tsx
+import { defaultTheme, defaultSpacing, createTheme } from '@aurora-ui/theme'
+
+const myTheme = createTheme(defaultTheme, {
+    spacing: {
+        ...defaultSpacing,
+        md: '1.25rem',  // Override medium
+        lg: '2rem',     // Override large
+    },
+})
+```
+
+### Mix and Match
+
+```tsx
+import { 
+    defaultSpacing, 
+    defaultRadius,
+    defaultShadows,
+    emeraldLight,
+    createTheme,
+    defaultTheme,
+} from '@aurora-ui/theme'
+
+const myTheme = createTheme(defaultTheme, {
+    colors: emeraldLight,           // Use emerald palette
+    spacing: defaultSpacing,         // Keep default spacing
+    radius: {
+        ...defaultRadius,
+        md: '8px',                   // More rounded
+    },
+})
+```
+
+---
+
+## Theme Structure
+
+### Colors
+
+| Token | Description |
+|-------|-------------|
+| `primary`, `onPrimary`, `primaryHover`, `primaryActive`, `primarySubtle` | Primary brand color |
+| `secondary`, `onSecondary`, `secondaryHover`, `secondaryActive`, `secondarySubtle` | Secondary actions |
+| `accent`, `onAccent`, `accentHover`, `accentSubtle` | Accent/highlight |
+| `background`, `surface`, `surfaceHover`, `surfaceActive`, `elevated`, `overlay` | Surfaces |
+| `text`, `textSecondary`, `textTertiary`, `textInverse` | Text hierarchy |
+| `border`, `borderHover`, `borderFocus`, `borderSubtle` | Borders |
+| `success`, `warning`, `error`, `info` + variants | Semantic colors |
+| `link`, `linkHover`, `linkVisited`, `focus` | Interactive |
+| `disabled`, `disabledText` | Disabled states |
+
+### Spacing
+
+```tsx
+spacing: {
+    none: '0',
+    xs: '0.25rem',   // 4px
+    sm: '0.5rem',    // 8px
+    md: '1rem',      // 16px
+    lg: '1.5rem',    // 24px
+    xl: '2rem',      // 32px
+}
+```
+
+### Other Tokens
+
+| Token | Values |
+|-------|--------|
+| `radius` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `full` |
+| `shadows` | `none`, `xs`, `sm`, `md`, `lg`, `xl` |
+| `fontSize` | `xs`, `sm`, `md`, `lg`, `xl` |
+| `fontWeight` | `light`, `regular`, `medium`, `semibold`, `bold` |
+| `lineHeight` | `none`, `tight`, `normal`, `relaxed` |
+| `zIndex` | `behind`, `base`, `dropdown`, `sticky`, `fixed`, `overlay`, `modal`, `popover`, `tooltip`, `toast` |
+| `transition` | `fast`, `normal`, `slow` |
+
+---
+
+## Extending Types
+
+Add custom tokens with full TypeScript support:
+
+```tsx
+import type { BaseColors, ExtendTheme } from '@aurora-ui/theme'
+
+// Extend colors
+type MyColors = BaseColors & {
+    brand: string
+    brandHover: string
+}
+
+// Create extended theme type
+type MyTheme = ExtendTheme<{
+    colors: MyColors
+}>
+
+// Use with type safety
+const STYLES = createStyles<MyTheme>((theme) => ({
+    button: {
+        backgroundColor: theme.colors.brand, // ✅ TypeScript knows this!
+    },
+}))
+
+// Access in components
+const theme = useTheme<MyTheme>()
+```
+
+---
+
+## Dynamic Styles
+
+```tsx
+const STYLES = createStyles((theme) => ({
+    button: (variant: 'primary' | 'secondary', size: 'sm' | 'md' | 'lg') => ({
+        backgroundColor: theme.colors[variant],
+        padding: theme.spacing[size],
+        borderRadius: theme.radius.md,
+        transition: theme.transition.fast,
+    }),
+}))
+
+// Usage
+<button className={STYLES.button('primary', 'md')}>Click me</button>
+```
+
+---
+
+## SSR Support
+
+```tsx
+import { getSSRStyles, clearSSRRules } from '@aurora-ui/theme'
+
+// Server-side
+const html = renderToString(<App />)
+const styles = getSSRStyles()
+
+const fullHtml = `
+<!DOCTYPE html>
+<html>
+<head>
+    <style id="aurora-styles">${styles}</style>
+</head>
+<body>${html}</body>
+</html>
+`
+
+clearSSRRules() // Reset for next request
+```
+
+---
+
+## API Reference
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `Theme` | Complete theme structure |
+| `BaseColors` | Color token type |
+| `BaseSpacing` | Spacing token type |
+| `ColorScale` | Color scale type (25-950) |
+| `ColorName` | Union of color scale names |
+| `PaletteName` | Union of palette names |
+| `ExtendTheme<T>` | Helper to extend theme |
+| `DeepPartial<T>` | For partial overrides |
+
+### Components & Hooks
+
+| Export | Description |
+|--------|-------------|
+| `ThemeProvider` | Theme context provider |
+| `useTheme<T>()` | Access current theme |
+
+### Styling
+
+| Export | Description |
+|--------|-------------|
+| `createStyles<T>()` | Create themed styles |
+| `keyframes()` | CSS keyframe animations |
+| `fontFace()` | @font-face rules |
+| `cssVariables()` | CSS custom properties |
+
+---
+
+## Contributing
+
+Interested in contributing? Check out the [Developer Guide](./README.dev.md) for:
+
+- Development setup
+- Available scripts
+- Project structure
+- Coding conventions
+- Publishing process
+
+---
+
+## License
+
+MIT
+