@aitronos/freddy-plugins 0.4.2 → 0.4.3

package/README.md

@@ -4,6 +4,11 @@ A lightweight, dynamic, and feature-rich component library that provides a compr
 
 ## ✨ Features
 
+| Environment     | URL                                                                        | Branch    | Status     |
+| --------------- | -------------------------------------------------------------------------- | --------- | ---------- |
+| **Development** | [dev-components.aitronos.com](https://dev-components.aitronos.com)         | `develop` | ✅ Live    |
+| **Staging**     | [staging-components.aitronos.com](https://staging-components.aitronos.com) | `staging` | 🚧 Pending |
+| **Production**  | [components.aitronos.com](https://components.aitronos.com)                 | `main`    | 🚧 Pending |
 - **🚀 Lightweight**: Optimized bundle size with tree-shaking support
 - **🔄 Dynamic**: Auto-updating components with new features and improvements
 - **🎨 Rich**: 20+ components, 120+ icons, animations, and utilities
@@ -19,6 +24,11 @@ A lightweight, dynamic, and feature-rich component library that provides a compr
 # npm
 npm install @aitronos/freddy-plugins
 
+| Environment     | Memory | CPU | Max Instances | Estimated Cost/Month |
+| --------------- | ------ | --- | ------------- | -------------------- |
+| **Development** | 1Gi    | 1   | 10            | ~$15-25              |
+| **Staging**     | 1Gi    | 1   | 10            | ~$15-25              |
+| **Production**  | 1Gi    | 1   | 10            | ~$15-25              |
 # yarn
 yarn add @aitronos/freddy-plugins
 
@@ -26,10 +36,26 @@ yarn add @aitronos/freddy-plugins
 pnpm add @aitronos/freddy-plugins
 ```
 
+**Google Cloud Run Pricing (Switzerland - europe-west6):**
+
+- **CPU**: $0.00002400 per vCPU-second
+- **Memory**: $0.00000250 per GiB-second
+- **Requests**: $0.40 per million requests
 ## 🔄 Updating to New Version
 
+**Estimated Monthly Costs:**
+
+- **Development**: $15-25 (low traffic, testing)
+- **Staging**: $15-25 (pre-production testing)
+- **Production**: $15-25 (package visualization)
+- **Total Estimated**: $45-75/month
 To get the latest features, components, and bug fixes, simply update the package:
 
+**Additional Costs:**
+
+- **Artifact Registry**: ~$5-10/month (Docker images)
+- **Cloud Build**: ~$5-15/month (CI/CD builds)
+- **Network Egress**: ~$5-10/month (traffic)
 ```bash
 # npm - Update to latest version
 npm update @aitronos/freddy-plugins
@@ -50,12 +76,392 @@ pnpm update @aitronos/freddy-plugins
 pnpm add @aitronos/freddy-plugins@2.1.0
 ```
 
+## 🎨 **Color System**
+
+### **Multi-Brand Color Architecture**
+
+The Storybook implements a sophisticated color system that supports multiple brands (Contentplate, Flowplate, Freddy) with different color modes (light/dark).
+
+#### **Brand Color Palettes**
+
+| Brand            | Primary Color                        | Theme Focus | Style                        | Use Case                      |
+| ---------------- | ------------------------------------ | ----------- | ---------------------------- | ----------------------------- |
+| **Contentplate** | Purple (#7c3aed)                     | Light mode  | Clean, modern, professional  | Content management platforms  |
+| **Flowplate**    | Purple gradient (#6366f1 to #8b5cf6) | Dark mode   | Dynamic, flowing, elegant    | Workflow automation platforms |
+| **Freddy**       | Blue (#00aeef)                       | Dark mode   | Technical, precise, reliable | AI and automation tools       |
+
+#### **Color Categories**
+
+Each brand supports comprehensive color categories:
+
+- **Primary Colors**: Main brand colors with full scales (50-900)
+- **Secondary Colors**: Supporting colors for accents
+- **Neutral Colors**: Grays and whites for backgrounds
+- **Semantic Colors**: Success, warning, error, info states
+- **Interactive Colors**: Hover, focus, active, disabled states
+- **Background Colors**: Page and component backgrounds
+- **Text Colors**: Typography and content colors
+- **Border Colors**: Dividers and outlines
+
+#### **Color Modes**
+
+Each brand supports multiple color modes:
+
+- **Light Mode**: Traditional light theme with dark text
+- **Dark Mode**: Dark theme with light text and appropriate contrast
+  ...
+
+### **Color Configuration**
+
+The color system uses static configuration files for reliable theming:
+
+**Configuration Files:**
+
+- `src/dist/clean-configuration.json` - Main theme configuration
+- `src/dist/master-configuration.json` - Source configuration
+- `src/dist/complete-configuration.json` - Complete configuration
+
+**Features:**
+
+- **Total colors**: 50+ per brand/mode
+- **Interactive states**: Included
+- **Brands**: Freddy, Contentplate, Flowplate
+- **Modes**: Default, Light, Dark
+
+#### **Available CSS Variables**
+
+The system provides 43+ CSS variables that automatically update based on the selected brand and color mode:
+
+**Text Colors:**
+
+```css
+var(--text-primary)          /* Main text content */
+var(--text-secondary)        /* Secondary/subtle text */
+var(--text-accent)          /* Accent text */
+var(--text-error)           /* Error text */
+var(--text-success)         /* Success text */
+var(--text-warning)         /* Warning text */
+var(--text-info)            /* Info text */
+var(--text-link)            /* Link text */
+var(--text-inverse)         /* Text on colored backgrounds */
+```
+
+**Interactive States:**
+
+```css
+var(--text-primary-hover)   /* Primary text on hover */
+var(--text-primary-active)  /* Primary text when active */
+var(--text-primary-focus)   /* Primary text when focused */
+var(--text-secondary-hover) /* Secondary text on hover */
+var(--text-secondary-focus) /* Secondary text when focused */
+var(--text-link-hover)      /* Link text on hover */
+```
+
+**Background Colors:**
+
+```css
+var(--bg-primary)           /* Main background */
+var(--bg-secondary)         /* Secondary background */
+var(--bg-surface)           /* Surface/card background */
+```
+
+**Brand Colors:**
+
+```css
+var(--primary-color)        /* Primary actions */
+var(--error-color)          /* Error states */
+var(--success-color)        /* Success states */
+var(--warning-color)        /* Warning states */
+```
+
+**Usage in Components:**
+
+```vue
+<style scoped>
+.my-component {
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  border: 2px solid var(--border-color);
+}
+
+.my-button:hover {
+  color: var(--text-primary-hover);
+}
+</style>
+```
+
+#### **Development Rules**
+
+All components must follow the theme development rules:
+
+- ✅ **Use CSS variables** - Never hardcode colors
+- ✅ **Dynamic theming** - Colors change based on brand/mode
+- ✅ **Interactive states** - Use hover, active, focus variables
+- ✅ **Accessibility** - Maintain proper contrast ratios
+
+See `THEME_DEVELOPMENT_RULES.md` for complete guidelines.
+
+```bash
+# Generate static color configuration
+yarn generate:color-config
+```
+
+#### **Generated Files**
+
+- `dist/colors.json` - Static color configuration
+- `src/dist/clean-configuration.json` - Main theme configuration
+- `src/dist/master-configuration.json` - Source configuration
+
+## 🎨 **Brand Switching & Theme Management**
+
+### **Theme Management**
+
+The project uses a sophisticated theme management system providing dynamic brand switching and theme management capabilities.
+
+#### **Available Brands**
+
+| Brand            | Description             | Primary Use Case                      |
+| ---------------- | ----------------------- | ------------------------------------- |
+| **Freddy**       | AI and automation tools | Technical interfaces, AI platforms    |
+| **Flowplate**    | Workflow automation     | Process management, automation tools  |
+| **Contentplate** | Content management      | CMS platforms, content creation tools |
+
+#### **Available Modes**
+
+| Mode        | Description                | Best For                             |
+| ----------- | -------------------------- | ------------------------------------ |
+| **Light**   | Traditional light theme    | Daytime use, professional interfaces |
+| **Dark**    | Dark theme with light text | Night use, modern interfaces         |
+| **Default** | Brand-specific default     | General use, brand consistency       |
+
+### **Runtime Brand Switching**
+
+#### **Using the ThemeSwitcher Component**
+
+```vue
+<template>
+  <ThemeSwitcher
+    :initial-brand="'freddy'"
+    :initial-mode="'light'"
+    @theme-changed="handleThemeChange"
+    @theme-applied="handleThemeApplied"
+  />
+</template>
+
+<script setup>
+import { ThemeSwitcher } from "@/components";
+
+const handleThemeChange = (brand, mode) => {
+  console.log("Theme changed:", { brand, mode });
+  // Update your app's theme state
+};
+
+const handleThemeApplied = (brand, mode) => {
+  console.log("Theme applied:", { brand, mode });
+  // Apply the theme to your application
+};
+</script>
+```
+
+#### **Using the Theme Service**
+
+```typescript
+import { useTheme } from "@/composables/useTheme";
+
+// Get theme service
+const {
+  currentBrandId,
+  currentModeId,
+  availableBrands,
+  availableModes,
+  setBrand,
+  setMode,
+} = useTheme();
+
+// Get available brands and modes
+console.log("Available brands:", availableBrands.value);
+console.log("Available modes:", availableModes.value);
+
+// Switch brand and mode
+setBrand("freddy-public-id");
+setMode("light-mode-id");
+```
+
+### **CSS Custom Properties Integration**
+
+The system automatically generates CSS custom properties for each brand and mode:
+
+```css
+/* Freddy Light Mode */
+.freddy-light {
+  --color-primary-500: #00aeef;
+  --color-background-50: #ffffff;
+  --color-text-900: #111827;
+  --color-border-200: #e5e7eb;
+}
+
+/* Flowplate Dark Mode */
+.flowplate-dark {
+  --color-primary-500: #6366f1;
+  --color-background-50: #0f172a;
+  --color-text-50: #f8fafc;
+  --color-border-700: #374151;
+}
+
+/* Contentplate Default Mode */
+.contentplate-default {
+  --color-primary-500: #7c3aed;
+  --color-background-50: #ffffff;
+  --color-text-900: #111827;
+  --color-border-200: #e5e7eb;
+}
+```
+
+### **Component-Level Brand Switching**
+
+```vue
+<template>
+  <div :class="`component--${currentBrand}--${currentMode}`">
+    <Button :style="{ backgroundColor: primaryColor }" @click="switchBrand">
+      Switch to {{ nextBrand }}
+    </Button>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from "vue";
+import { useTheme } from "@/composables/useTheme";
+
+const { setBrand, setMode, availableBrands } = useTheme();
+
+const currentBrand = ref("freddy");
+const currentMode = ref("light");
+
+const brands = ["freddy", "flowplate", "contentplate"];
+const currentBrandIndex = computed(() => brands.indexOf(currentBrand.value));
+const nextBrand = computed(
+  () => brands[(currentBrandIndex.value + 1) % brands.length]
+);
+
+const switchBrand = () => {
+  currentBrand.value = nextBrand.value;
+
+  // Find the brand ID and set it
+  const targetBrand = availableBrands.value.find((b) =>
+    b.name.toLowerCase().includes(currentBrand.value)
+  );
+  if (targetBrand) {
+    setBrand(targetBrand.id);
+  }
+};
+</script>
+```
+
+### **Global Theme State Management**
+
+The theme system uses Vue's reactivity system for state management. See the `ThemeService.ts` for the complete implementation.
+
+### **Usage Examples**
+
+#### **Component Integration**
+
+```vue
+<template>
+  <div :class="`component--${brand}--${mode}`">
+    <button :style="{ backgroundColor: primaryColor }">Primary Button</button>
+  </div>
+</template>
+
+<script setup>
+import { useColorSystem } from "@/config/colors";
+
+const { getColor } = useColorSystem();
+
+const primaryColor = getColor({
+  brand: "contentplate",
+  mode: "light",
+  category: "primary",
+  scale: 500,
+});
+</script>
+```
+
+#### **CSS Custom Properties**
+
+```css
+.contentplate-light {
+  --color-primary-500: #7c3aed;
+  --color-background-50: #ffffff;
+  --color-text-900: #111827;
+}
+
+.flowplate-dark {
+  --color-primary-500: #6366f1;
+  --color-background-50: #0f172a;
+  --color-text-50: #f8fafc;
+}
+```
+
+#### **TypeScript Support**
+
+```typescript
+import { getColor, validateColorContrast } from "@/config/colors";
+
+// Get a specific color
+const primaryColor = getColor({
+  brand: "contentplate",
+  mode: "light",
+  category: "primary",
+  scale: 500,
+});
+
+// Validate contrast
+const result = validateColorContrast("#7c3aed", "#ffffff");
+if (!result.isAccessible) {
+  console.warn("Low contrast detected");
+}
+```
+
+### **Accessibility Features**
+
+- **WCAG Compliance**: AA standard (4.5:1) and AAA standard (7:1)
+- **Contrast Validation**: Automatic validation of color combinations
+- **Color Blindness Support**: High contrast ratios for all color combinations
+- **Semantic Colors**: Clear distinction between success, warning, error states
+
+### **Performance Optimizations**
+
+- **Static Configuration**: Reliable theme configuration from JSON files
+- **Fallback System**: Graceful degradation with default themes
+- **Efficient Processing**: Optimized color scale generation
+- **Minimal Network Requests**: Smart caching reduces API calls
+
+## 📦 **Components**
 **✨ No code changes needed!** New components and features are automatically available after updating.
 
+### **Core Components**
+
+- `Button` - Primary action buttons
+- `InputField` - Form input components
+- `Modal` - Dialog and modal components
+- `Dropdown` - Selection components
+- `Pagination` - Navigation components
 ## 🎨 Storybook Documentation
 
+### **Specialized Components**
+
+- `ChatInterface` - Real-time chat components
+- `ApiInteraction` - API testing interface
+- `LoginRegister` - Authentication components
+- `IconLibrary` - Complete icon set (100+ icons)
 Explore all components, icons, and utilities with interactive demos:
 
+### **Utility Components**
+
+- `Spinner` - Loading indicators
+- `ToastMessage` - Notification system
+- `Tooltip` - Information overlays
+- `CodeBlock` - Syntax highlighting
 **[📚 View Storybook →](https://aitronos-freddy-plugins.vercel.app/)**
 
 The Storybook provides:
@@ -75,6 +481,8 @@ The Storybook provides:
 npm install @aitronos/freddy-plugins
 ```
 
+# Staging (staging branch)
+git push origin staging
 ### Import Web Components
 
 **Option 1: Global Registration (Recommended)**
@@ -213,6 +621,24 @@ function App() {
 export default App;
 ```
 
+### Setup Guide
+
+For a concise setup guide and environment notes, see `docs/development/setup-guide.md`.
+
+### **Brand Switching Commands**
+
+```bash
+# Generate clean configuration
+yarn generate:color-config
+
+# Build the project
+yarn build
+
+# Run Storybook
+yarn storybook
+```
+
+## 📋 **Project Structure**
 ### Using Components
 
 ```tsx
@@ -268,14 +694,29 @@ declare namespace JSX {
 
 ## 🟢 Vue Usage
 
+### **Security Features**
+
+- ✅ **HTTPS only** - All traffic encrypted
+- ✅ **Security headers** - XSS, CSRF protection
+- ✅ **Content Security Policy** - Resource restrictions
+- ✅ **No sensitive data** - Public component library
 ### Installation
 
+### **Performance Optimizations**
+
+- ✅ **Gzip compression** - Reduced transfer size
+- ✅ **Static asset caching** - 1-year cache headers
+- ✅ **CDN distribution** - Global edge locations
+- ✅ **Auto-scaling** - Handles traffic spikes
 ```bash
 npm install @aitronos/freddy-plugins
 ```
 
 ### Using in Vue 3
 
+### **DNS Configuration**
+
+Add these CNAME records in Hostpoint.ch:
 ```vue
 <!-- App.vue -->
 <template>
@@ -313,10 +754,19 @@ import "@aitronos/freddy-plugins/dist/freddy-plugins.css";
 </script>
 ```
 
+### **SSL Certificates**
+
+- Automatically managed by Google Cloud
+- Custom domains require verification in Google Cloud Console
 ## 🎯 Available Components
 
 ### Core Components
 
+### **Health Checks**
+
+- **Endpoint**: `/health` - Returns 200 OK
+- **Auto-restart**: Failed instances restart automatically
+- **Logging**: Cloud Run logs available in Google Cloud Console
 - `freddy-button` - Interactive freddy-buttons with multiple variants
 - `freddy-input-field` - Form input fields
 - `freddy-modal-box` - Modal dialogs
@@ -328,6 +778,11 @@ import "@aitronos/freddy-plugins/dist/freddy-plugins.css";
 - `freddy-spinner` - Loading spinners
 - `freddy-skeleton-loader` - Skeleton loading states
 
+### **Performance Metrics**
+
+- **Response time**: < 200ms average
+- **Uptime**: 99.9% SLA with Cloud Run
+- **Availability**: Multi-zone deployment
 ### Icons (120+ available)
 
 - `icon-search` - Search icon
@@ -343,6 +798,11 @@ import "@aitronos/freddy-plugins/dist/freddy-plugins.css";
 
 ### Animations
 
+**Build Failures:**
+
+```bash
+# Check TypeScript errors
+yarn vue-tsc --noEmit
 - `freddy-anime-spaceman` - Spaceman animation
 
 ### Utilities
@@ -359,6 +819,12 @@ import "@aitronos/freddy-plugins/dist/freddy-plugins.css";
 import "@aitronos/freddy-plugins/dist/freddy-plugins.css";
 ```
 
+**Deployment Issues:**
+
+```bash
+# Check GitHub Actions logs
+# Verify GCP_SA_KEY secret is set
+# Ensure Docker build succeeds locally
 ### Custom Theming
 
 ```css
@@ -375,6 +841,11 @@ icon-search {
 }
 ```
 
+**Domain Issues:**
+
+- Verify DNS propagation (can take 24-48 hours)
+- Check custom domain verification in Google Cloud Console
+- Ensure CNAME records are correct
 ## 📚 Documentation
 
 - **[Storybook Demo](https://aitronos-freddy-plugins.vercel.app/)** - Interactive component documentation