Initial commit

2026-03-23 21:37:59 +01:00
commit 2547717edb
2193 changed files with 972171 additions and 0 deletions
--- a/references/THEME_IMPLEMENTATION.md
+++ b/references/THEME_IMPLEMENTATION.md
@@ -0,0 +1,304 @@
+# Theme System Implementation Summary
+
+## Overview
+Successfully implemented a configuration-based theming system for Timebank.cc that allows different installations to use different visual themes. The system uses CSS custom properties with Tailwind CSS for optimal performance and compatibility.
+
+## Implementation Details
+
+### 1. Configuration System
+**File**: `config/timebank-cc.php`
+- Added complete theme configuration with 4 themes
+- Environment-based theme selection via `TIMEBANK_THEME`
+- Comprehensive color palettes and typography settings for each theme
+
+### 2. CSS Architecture
+**File**: `resources/css/app.css`
+- CSS custom properties for all theme variables
+- Theme-specific data attribute selectors (`[data-theme="theme-name"]`)
+- Theme-aware utility classes (`.text-theme-primary`, `.bg-theme-surface`, etc.)
+- Backward compatibility with existing styles
+
+### 3. Tailwind Integration
+**File**: `tailwind.config.js`
+- Updated color definitions to use CSS custom properties
+- Theme-aware color palette using `rgb(var(--color-name) / <alpha-value>)`
+- Maintained WireUI/Mary component compatibility
+- Added theme-specific color variants
+
+### 4. Layout Integration
+**File**: `resources/views/layouts/app.blade.php`
+- Added `data-theme` attribute to HTML tag
+- Theme-aware CSS custom properties injection
+- Dynamic typography based on theme configuration
+
+### 5. Helper Functions & Blade Directives
+**Files**: 
+- `app/Helpers/ThemeHelper.php` - PHP helper functions
+- `app/Providers/ThemeServiceProvider.php` - Blade directives
+- `composer.json` - Autoload registration
+
+**Available Functions**:
+- `theme()` - Get theme configuration
+- `theme_id()` - Get active theme ID
+- `theme_name()` - Get theme display name
+- `theme_color($key)` - Get theme color
+- `theme_font($key)` - Get typography setting
+- `is_theme($id)` - Check active theme
+- `theme_css_vars()` - Generate CSS variables
+
+**Available Blade Directives**:
+- `@theme` - Access theme configuration
+- `@themeId` - Output theme ID
+- `@themeName` - Output theme name
+- `@themeColor` - Output theme color
+- `@isTheme` / `@endIsTheme` - Conditional theme blocks
+- `@themeCssVars` - Output CSS variables
+
+### 6. Environment Configuration
+**Files**:
+- `.env.example` - Added `TIMEBANK_THEME` configuration
+- `references/SETUP_GUIDE.md` - Documentation updated
+
+## Logo System
+
+The theme system now includes integrated logo support, allowing each theme to have its own branding while preventing git conflicts during deployments.
+
+### Logo Configuration
+
+Each theme in `config/themes.php` includes a `logos` array:
+
+```php
+'logos' => [
+    'svg_inline' => 'logos.theme_name',  // Blade view for inline SVG
+    'email_logo' => 'app-images/theme_name_mail_logo.png',  // PNG for emails/PDFs
+],
+```
+
+### Logo Files
+
+**SVG Logos (Inline):**
+- Location: `resources/views/logos/`
+- Files:
+  - `timebank_cc.blade.php` - Default theme SVG
+  - `uuro.blade.php` - Uuro theme SVG
+  - `vegetable.blade.php` - Vegetable theme SVG
+  - `yellow.blade.php` - Yellow theme SVG
+- These files are tracked in git as defaults
+- Customizations should be made per-theme
+
+**Email/PDF Logos (PNG):**
+- Location: `storage/app/public/app-images/`
+- Files:
+  - `timebank_cc_mail_logo.png`
+  - `uuro_mail_logo.png`
+  - `vegetable_mail_logo.png`
+  - `yellow_mail_logo.png`
+- These files are **gitignored** (safe from git pull overwrites)
+- Upload custom logos to this directory per installation
+
+### Logo Helper Function
+
+Use `theme_logo()` to retrieve logo paths:
+
+```php
+// Get SVG inline view
+theme_logo('svg_inline') // Returns: 'logos.timebank_cc'
+
+// Get email logo path
+theme_logo('email_logo') // Returns: 'app-images/timebank_cc_mail_logo.png'
+```
+
+### White-Label Logo Deployment
+
+**Problem Solved:** Before this system, running `deploy.sh` would overwrite custom logos from git.
+
+**Solution:**
+1. SVG logos are theme-specific Blade views
+2. Email logos are stored in gitignored `storage/` directory
+3. Theme config points to the correct logos
+4. No git conflicts during deployments
+
+**To Customize Logos for Your Installation:**
+
+1. **For SVG Logo (Website):**
+   - Edit `resources/views/logos/your_theme.blade.php`
+   - Or create a new theme-specific logo file
+   - Update `config/themes.php` to point to your logo
+
+2. **For Email/PDF Logo:**
+   - Upload your PNG logo to `storage/app/public/app-images/`
+   - Name it `your_theme_mail_logo.png`
+   - Ensure `config/themes.php` references this filename
+   - This file persists through `git pull` operations
+
+3. **Run deployment:**
+   ```bash
+   TIMEBANK_THEME=your_theme ./deploy.sh
+   ```
+
+Your custom logos will remain intact after deployment updates.
+
+## Available Themes
+
+### 1. Timebank_cc (Default)
+- **Colors**: Gray, black, white palette
+- **Typography**: Roboto body, Oswald headings (uppercase)
+- **Identity**: Professional, clean, corporate
+- **Logos**: Default Timebank.cc branding
+
+### 2. Uuro
+- **Colors**: Black, white, cyan bluish gray with vibrant accents
+- **Accents**: Pale pink, vivid red, green cyan, orange, blue, purple
+- **Typography**: System fonts, flexible sizing
+- **Identity**: Modern, high-contrast, creative
+
+### 3. Vegetable
+- **Colors**: Natural greens, earth tones, orange accents
+- **Backgrounds**: Light yellow, beige surfaces
+- **Typography**: System fonts, larger line-height (1.8)
+- **Identity**: Organic, sustainable, natural
+
+### 4. Yellow
+- **Colors**: High-contrast yellow and black
+- **Accents**: Blue, dark blue, gray tones
+- **Typography**: Poppins/Nunito Sans, clean aesthetic
+- **Identity**: Bold, energetic, modern
+
+## Usage Instructions
+
+### For Development
+```bash
+# Set theme in .env
+TIMEBANK_THEME=uuro
+
+# Build assets
+npm run build
+
+# Clear Laravel cache
+$debugBuddyStartTime = microtime(true); // Added by DebugBuddy
+php artisan config:clear
+```
+\Log::info("Execution time: " . round((microtime(true) - $debugBuddyStartTime) * 1000, 2) . "ms"); // Added by DebugBuddy
+
+### For Different Installations
+```bash
+# Healthcare installation
+TIMEBANK_THEME=vegetable
+
+# Corporate installation  
+TIMEBANK_THEME=timebank_cc
+
+# Creative/agency installation
+TIMEBANK_THEME=uuro
+
+# Energy/construction installation
+TIMEBANK_THEME=yellow
+```
+
+### In Blade Templates
+```php
+<!-- Check current theme -->
+@isTheme('uuro')
+    <div class="bg-uuro-success">Special Uuro styling</div>
+@endIsTheme
+
+<!-- Use theme colors -->
+<div class="bg-primary-500 text-theme-primary">
+    Theme-aware styling
+</div>
+
+<!-- Access theme configuration -->
+<h1 style="font-family: @themeFont('font_family_heading')">
+    @themeName Theme
+</h1>
+```
+
+### In PHP/Livewire
+```php
+// Check theme
+if (is_theme('vegetable')) {
+    // Vegetable theme specific logic
+}
+
+// Get theme colors
+$primaryColor = theme_color('primary.500');
+$accentColor = theme_color('accent');
+
+// Get typography
+$bodyFont = theme_font('font_family_body');
+```
+
+## Technical Benefits
+
+1. **Performance**: Build-time theme application, no runtime overhead
+2. **Compatibility**: Full WireUI/Mary component support
+3. **Flexibility**: Easy to add new themes without code changes
+4. **Maintainability**: Centralized theme configuration
+5. **Scalability**: CSS custom properties allow unlimited themes
+6. **Developer Experience**: Helper functions and Blade directives
+
+## File Changes Summary
+
+### Modified Files
+- `config/themes.php` - Added theme configuration and logo paths
+- `resources/css/app.css` - Added CSS custom properties
+- `tailwind.config.js` - Updated color definitions
+- `resources/views/layouts/app.blade.php` - Added theme integration
+- `composer.json` - Added helper autoload
+- `config/app.php` - Registered ThemeServiceProvider
+- `.env.example` - Added theme configuration
+- `references/SETUP_GUIDE.md` - Updated documentation
+- `app/Helpers/ThemeHelper.php` - Added theme_logo() helper function
+- `resources/views/components/jetstream/application-logo.blade.php` - Uses theme logo
+- `resources/views/components/jetstream/application-mark.blade.php` - Uses theme logo
+- `resources/views/components/jetstream/authentication-card-logo.blade.php` - Uses theme logo
+- `resources/views/vendor/mail/html/message.blade.php` - Uses theme email logo
+- `resources/views/reports/pdf.blade.php` - Uses theme email logo
+
+### New Files
+- `app/Helpers/ThemeHelper.php` - Theme helper functions
+- `app/Providers/ThemeServiceProvider.php` - Blade directive provider
+- `references/THEME_IMPLEMENTATION.md` - This documentation
+- `resources/views/logos/timebank_cc.blade.php` - Default theme SVG logo
+- `resources/views/logos/uuro.blade.php` - Uuro theme SVG logo
+- `resources/views/logos/vegetable.blade.php` - Vegetable theme SVG logo
+- `resources/views/logos/yellow.blade.php` - Yellow theme SVG logo
+- `storage/app/public/app-images/timebank_cc_mail_logo.png` - Default email/PDF logo (gitignored)
+
+## Testing Verification
+
+✅ Theme helper functions working correctly
+✅ All 4 themes loading proper colors and typography  
+✅ CSS compilation successful with theme system
+✅ Environment variable theme switching functional
+✅ Blade directives registered and accessible
+✅ WireUI/Mary component compatibility maintained
+
+## Configuration File Protection
+
+**Important:** Theme and platform configuration files are now protected from git overwrites.
+
+The application uses a **config template system**:
+- `.example` files are tracked in git (templates)
+- Actual config files are gitignored (your customizations)
+- `deploy.sh` creates configs from templates if missing
+- Your custom configs persist through deployments
+
+**Protected Files:**
+- `config/themes.php` - Theme configuration
+- `config/timebank-default.php` - Platform configuration
+- `config/timebank_cc.php` - Platform-specific overrides
+
+**For detailed information, see:** `references/BRANDING_CUSTOMIZATION.md`
+
+## Deployment Ready
+
+The theme system is ready for production deployment. Different Timebank installations can now:
+
+1. Set their theme via environment variable
+2. Build assets with their chosen theme
+3. Deploy with installation-specific branding
+4. Maintain the same codebase across all installations
+5. **Keep custom configs safe from git overwrites**
+
+Each theme provides a unique visual identity while maintaining full functionality and component compatibility.