# Theme Logo Files

This directory contains SVG logo files for each theme. These logos are used throughout the application in navigation, authentication pages, and other UI components.

## Files

- `timebank_cc.blade.php` - Default Timebank.cc theme logo
- `uuro.blade.php` - Uuro theme logo
- `vegetable.blade.php` - Vegetable theme logo
- `yellow.blade.php` - Yellow theme logo

## Customization

The files in this directory belong to every installation: a change here is a code change, committed to git.

### A platform's own logo (one installation)

Put it in the installation's platform folder instead (outside git; see `references/MULTI_PLATFORM_INSTANCES.md`,
section 3). The platform's copy wins over the file here:

```bash
php artisan platform:override logos.uuro     # copies this file to platform/views/logos/uuro.blade.php
```

Then replace the SVG in the copy, and run `php artisan view:clear`. A theme of the platform's own (in
`platform/theme.php`) can have its logo view only there, e.g. `platform/views/logos/mybrand.blade.php` for
`'svg_inline' => 'logos.mybrand'`.

### Requirements for every logo file

Whether here or in a platform folder, **ensure the SVG includes:**
   - `class="fill-theme-logo w-full h-full"` for theme-aware coloring and responsive sizing
   - Dynamic title tag: `<title>{{ $logoTitle ?? config('app.name') . ' ' . __('logo') }}</title>`
   - The `viewBox` attribute for aspect ratio (no fixed width/height)

### A new theme for every installation

1. **Copy an existing logo file:**
   ```bash
   cp timebank_cc.blade.php my_new_theme.blade.php
   ```

2. **Edit the SVG content** in `my_new_theme.blade.php`

3. **Update theme configuration** in `config/themes.php`:
   ```php
   'my_new_theme' => [
       'name' => 'My New Theme',
       'logos' => [
           'svg_inline' => 'logos.my_new_theme',
           'email_logo' => 'app-images/my_new_theme_mail_logo.png',
       ],
       // ... other theme settings
   ],
   ```

4. **Add the theme to `config/themes.php.example`** too, so every installation gets it through `config:merge`.

## Important Notes

- **SVG logos** in this directory are tracked in git; a `git pull` replaces them. A platform's own logo therefore
  belongs in its platform folder (above), which git never touches.
- **Email/PDF logos** (PNG): `platform/public/mail-logo.png` and `mail-logo-inverted.png` in the platform folder, or the
  older way, the file named in the theme's `logos.email_logo` in `storage/app/public/app-images/` (gitignored).
- Use the `theme_logo()` helper function to access logo paths in code; for the email logo
  `theme_email_logo_url()` (emails) and `theme_email_logo_file()` (PDFs).

## Usage in Code

```php
// Get SVG inline view name
$svgView = theme_logo('svg_inline'); // Returns: 'logos.timebank_cc'

// Include in Blade template (uses default tooltip)
@include(theme_logo('svg_inline'))

// Include with custom tooltip text
@include(theme_logo('svg_inline'), ['logoTitle' => __('Go to homepage')])

// Include with context-specific tooltip
@include(theme_logo('svg_inline'), ['logoTitle' => __('Search') . ' - ' . config('app.name')])

// Email logo, platform folder first
$url = theme_email_logo_url();   // for <img src> in emails
$file = theme_email_logo_file(); // a file path, for PDFs and inline images
```

## Dynamic Tooltip Text

All logo files support dynamic tooltip text via the `$logoTitle` variable:

- **Default behavior:** If no `$logoTitle` is provided, the tooltip defaults to `config('app.name') . ' ' . __('logo')`
- **Custom tooltips:** Pass `['logoTitle' => 'Your custom text']` when including the logo
- **Context-aware:** Different components can use different tooltips (e.g., "Go to homepage" on login, "Search" on dashboard)

## White-Label Deployment

The logo system is designed to support white-label deployments:

- Each installation sets `TIMEBANK_THEME=your_theme` in `.env`, or has its own theme in `platform/theme.php`
- Theme-specific logos are automatically loaded; a logo in the platform folder wins over the one here
- The platform folder and email logos in `storage/` persist through git updates
- No conflicts when pulling latest code from repository

For more information, see `references/THEME_IMPLEMENTATION.md`.