npm package: @ruhff/theme-editor
Description: Interactive theme editor for Ruhff design system
Latest version: 0.0.3

# @ruhff/theme-editor

Interactive theme editor for the Ruhff design system. Provides a comprehensive interface for creating, editing, and managing themes with real-time preview capabilities.

## Features

- **Interactive Theme Editing**: Visual interface for modifying component themes
- **Design Token Management**: Edit and organize design tokens (colors, typography, etc.)
- **Real-time Preview**: See changes instantly in the preview panel
- **Import/Export**: Support for importing and exporting themes as JSON or ZIP files
- **Floating Interface**: Non-intrusive floating editor that can be positioned anywhere
- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- **Framework Integration**: Built for Vue 3 with seamless integration into existing projects

## Installation

```bash
npm install @ruhff/theme-editor
```

## Basic Usage

### Using the Theme Editor Component

```vue
<template>
  <ThemeEditor
    :components="componentsMeta"
    :config="{ enableFloating: true }"
    @theme-changed="handleThemeChange"
    @tokens-changed="handleTokensChange"
  />
</template>

<script setup>
import { ThemeEditor } from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'

const componentsMeta = [
  {
    name: 'Button',
    variants: ['primary', 'secondary', 'danger'],
    styleCssVars: ['--button-bg', '--button-color', '--button-border']
  }
]

function handleThemeChange(themes) {
  console.log('Themes updated:', themes)
}

function handleTokensChange(tokens) {
  console.log('Tokens updated:', tokens)
}
</script>
```

### Using the Floating Theme Editor

```vue
<template>
  <FloatingThemeEditor
    :components="componentsMeta"
    :config="{ keyboardShortcuts: true }"
  />
</template>

<script setup>
import { FloatingThemeEditor } from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'
</script>
```

### Vue Plugin Installation

```javascript
import { createApp } from 'vue'
import ThemeEditorPlugin from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'

const app = createApp()
app.use(ThemeEditorPlugin)
```

## Advanced Usage

### Custom Configuration

```typescript
import type { ThemeEditorConfig } from '@ruhff/theme-editor'

const config: ThemeEditorConfig = {
  enableFloating: true,
  enableInlineEditing: true,
  keyboardShortcuts: true,
  defaultThemeSet: 'dark',
  autoSave: false
}
```

### Import/Export Functionality

```typescript
import { useThemeImportExport } from '@ruhff/theme-editor'

const { exportAsZip, exportAsJson, importFromFile } = useThemeImportExport()

// Export themes as ZIP
await exportAsZip(tokens, themes, {
  format: 'zip',
  includeTokens: true,
  includeThemes: true,
  separateFiles: true
})

// Import from file
const fileInput = document.querySelector('input[type="file"]')
const file = fileInput.files[0]
const { tokens, themes } = await importFromFile(file)
```

### Theme Validation

```typescript
import { useThemeValidation } from '@ruhff/theme-editor'

const { validateTokens, validateThemes } = useThemeValidation(componentsMeta)

const tokenValidation = validateTokens(tokens)
const themeValidation = validateThemes(themes)

if (!tokenValidation.isValid) {
  console.error('Token errors:', tokenValidation.errors)
}
```

## Component Props

### ThemeEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `components` | `ComponentMeta[]` | `[]` | Array of component metadata |
| `initialTokens` | `ThemeTokens` | `undefined` | Initial design tokens |
| `initialThemes` | `AllThemes` | `undefined` | Initial theme configurations |
| `config` | `ThemeEditorConfig` | `{}` | Editor configuration options |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `theme-changed` | `ThemeSet` | Emitted when themes are modified |
| `tokens-changed` | `ThemeTokens` | Emitted when tokens are modified |
| `export-requested` | `{ tokens, themes }` | Emitted when export is triggered |

## Types

```typescript
interface ComponentMeta {
  name: string
  styleCssVars: string[]
  variants: string[]
}

interface ThemeEditorConfig {
  enableFloating?: boolean
  enableInlineEditing?: boolean
  keyboardShortcuts?: boolean
  defaultThemeSet?: string
  autoSave?: boolean
}
```

## Styling

The theme editor uses CSS custom properties for styling. You can customize the appearance by overriding these variables:

```css
:root {
  --te-color-primary: #3b82f6;
  --te-color-bg: #ffffff;
  --te-color-text: #1e293b;
  --te-border-radius: 6px;
}
```

## useComponentEditor

The `useComponentEditor` composable provides visual component editing that automatically opens the theme editor with the selected component.

### Basic Usage

```vue
<script setup>
import { useComponentEditor } from '@ruhff/theme-editor'
import { FloatingThemeEditor } from '@ruhff/theme-editor'
import componentsMeta from '@ruhff/blocks/components-meta.json'

// Set up component editor - integrates automatically with FloatingThemeEditor
const { isEditMode, enableEditMode, disableEditMode } = useComponentEditor(componentsMeta)
</script>

<template>
  <!-- Your components in .example containers -->
  <div class="example">
    <button data-component="Button" class="primary">Click me</button>
    <div data-component="Card">Card content</div>
  </div>

  <!-- FloatingThemeEditor handles the integration automatically -->
  <FloatingThemeEditor :components="componentsMeta" />
</template>
```

### Features

- **Visual Component Editing**: Press `Cmd/Ctrl + Shift + E` to enable edit mode
- **Click to Edit**: Click any component in edit mode to open the theme editor
- **Automatic Detection**: Detects components via `data-component` attributes or CSS selectors
- **Variant Detection**: Automatically detects component variants from CSS classes
- **Real-time Integration**: Uses the new theme engine for instant theme updates

### How it Works

1. **Enable Edit Mode**: Use `Cmd/Ctrl + Shift + E` or call `enableEditMode()`
2. **Click Component**: Click any component in an `.example` container
3. **Auto-Open Editor**: Theme editor opens with component and variant pre-selected
4. **Edit Theme**: Changes apply in real-time through the theme engine

### Component Detection Priority

1. **data-component attribute**: `data-component="Button"` (most reliable)
2. **CSS selectors**: `.button`, `.btn`, `.card`, `.badge`, etc.
3. **Class names**: Capitalized classes like `Button`, `Card`

### Variant Detection

Variants are detected from CSS classes matching component metadata:
- `class="button primary"` → variant `&.primary`
- `class="button"` → variant `&` (base)

## Integration with @ruhff/theme-engine

This package works seamlessly with `@ruhff/theme-engine` for runtime theming:

```typescript
import { useDesignTokens, useMultiTheme } from '@ruhff/theme-engine'

// The theme editor automatically integrates with theme-engine
// when both packages are installed
```

## Contributing

See the main repository for contribution guidelines.

## License

MIT