Ti Theme Toolkit Laravel Package

## Getting Started

### Minimal Setup for Daily Use
1. **Extend `AbstractThemeServiceProvider`** (5 lines):
   ```php
   use TiPowerUp\ThemeToolkit\AbstractThemeServiceProvider;

   class MyThemeServiceProvider extends AbstractThemeServiceProvider {
       protected function themeCode(): string { return 'my-theme'; }
       // Other overrides as needed
   }

Key: Register this in config/app.php under providers.

2. Configure fields.php (3 lines):

   use TiPowerUp\ThemeToolkit\Fields\BaseSchema;
   return BaseSchema::merge(['tabs' => BaseSchema::tabs()]);
   

   Daily use: This auto-generates the theme customizer UI in TastyIgniter admin.

3. Add Tailwind/Vite presets (1 line each):

   // tailwind.config.js
   import toolkit from '@tipowerup/ti-theme-toolkit/tailwind-preset';
   export default { presets: [toolkit] };
   
   // vite.config.js
   import { toolkitPreset } from '@tipowerup/ti-theme-toolkit/vite-preset';
   export default toolkitPreset({ input: ['resources/src/js/app.js'] });
   

   Daily use: Handles dark mode, color tokens, and build optimizations.

4. Import CSS/JS (2 lines):

   /* resources/src/css/app.css */
   @import '@tipowerup/ti-theme-toolkit/css/theme.css';
   @tailwind base;
   

   // resources/src/js/app.js
   import '@tipowerup/ti-theme-toolkit/js/dark-mode';
   

   Daily use: Activates dark mode toggle and CSS variables.

First Use Case: Customizing Colors

1. Edit fields.php to override defaults:

   return BaseSchema::merge([
       'tabs' => [
           'colors' => [
               'fields' => [
                   'color[primary]' => ['default' => '#3b82f6'], // Tailwind blue-500
               ],
           ],
       ],
   ]);
   

2. Run npm run build and php artisan igniter:theme-vendor-publish.
3. Verify in admin panel: Colors update automatically, and Tailwind utilities like bg-primary work.

Implementation Patterns

Core Workflow: Theme Development Loop

1. Design Phase:

   • Extend BaseSchema in fields.php to define customizer options.
   • Override themeCode(), viewsPath(), etc., in ServiceProvider.
   • Tip: Use BaseSchema::merge() to inherit defaults while customizing.

2. Frontend Integration:

   • Dark Mode: Use Alpine’s darkmode store:

     const darkMode = DarkModeStore();
     darkMode.toggle(); // Toggles html.dark class
     

   • Color Tokens: Reference CSS variables:

     .header { background: rgb(var(--color-primary)); }
     

   • Pattern: Tailwind classes (text-primary-500) map to these vars via the preset.

3. Livewire Components:

   • Use shared components (e.g., Login, Contact) by dropping blade views in resources/views/livewire/.
   • Override toolkit components by adding classes to Livewire/ with the same relative path.
   • Example: To customize the newsletter form:

     // MyTheme/Livewire/NewsletterSubscribeForm.php
     class NewsletterSubscribeForm extends \TiPowerUp\ThemeToolkit\Livewire\NewsletterSubscribeForm {
         public function render() {
             return view('my-theme.livewire.newsletter-subscribe-form');
         }
     }
     

4. Error Handling:

   • Place custom error views in resources/views/errors/404.blade.php.
   • The toolkit auto-wires these for storefront (admin errors use TastyIgniter’s defaults).

5. Asset Management:

   • Use igniter:theme-vendor-publish to sync assets to public/vendor/my-theme.
   • Automation: The registerAutoVendorPublish() listener runs this on theme activation.

Integration Tips

• TastyIgniter Admin:

  • Theme settings appear under Appearance > Themes > [Your Theme].
  • Use ThemePayloadResolver::resolve() in custom admin controllers to access theme data.

• Blade Components:

  • Publish shared components via BladeComponentServiceProvider:

    $this->loadBladeComponentsFrom(__DIR__.'/View/Components');
    

• Dark Mode Persistence:

  • The Alpine store syncs with localStorage. Extend with:

    darkMode.on('changed', (isDark) => {
        // Custom logic (e.g., analytics)
    });
    

• TypeScript:

  • Enable strict typing in tsconfig.json:

    {
      "compilerOptions": {
        "strict": true
      }
    }
    

  • Use toolkit’s .d.ts files for full IntelliSense (e.g., DarkModeStore).

Gotchas and Tips

Pitfalls

1. CSS Variable Conflicts:

   • Issue: Custom CSS may override toolkit’s --color-* vars.
   • Fix: Use !important sparingly; prefer Tailwind classes (bg-[var(--color-primary)]).

2. Livewire Component Overrides:

   • Issue: Overriding NewsletterSubscribeForm may break if the toolkit’s class isn’t properly namespaced.
   • Fix: Ensure your class extends the toolkit’s version:

     use TiPowerUp\ThemeToolkit\Livewire\NewsletterSubscribeForm;
     

3. Dark Mode Class Strategy:

   • Issue: Some libraries (e.g., Font Awesome) may not respect html.dark.
   • Fix: Use the toolkit’s dark-mode.js as a base and extend:

     document.documentElement.classList.add('dark');
     

4. Tailwind Safelist:

   • Issue: Dynamic classes (e.g., bg-[var(--color-primary)]) may be purged.
   • Fix: Configure safelist in tailwind.config.js:

     safelist: [
       'bg-[var(--color-primary)]',
       'text-[var(--color-primary)]',
     ],
     

5. Theme Activation:

   • Issue: Assets may not publish if the theme is activated post-install.
   • Fix: Use the registerAutoVendorPublish() listener (enabled by default).

6. PHP Namespace Reflection:

   • Gotcha: phpNamespace() defaults to the class’s namespace, but may fail for anonymous classes or complex inheritance.
   • Fix: Explicitly override if needed:

     protected function phpNamespace(): string { return 'MyVendor\\MyTheme'; }
     

Debugging Tips

1. Theme Data:

   • Dump resolved theme data in a blade view:

     {{ dd(\TiPowerUp\ThemeToolkit\Support\ThemePayloadResolver::resolve()) }}
     

2. Livewire Registration:

   • Check registered components:

     \Livewire::getComponentClasses(); // Debug in Tinker
     

3. Dark Mode:

   • Inspect the Alpine store:

     console.log(DarkModeStore().data);
     

4. CSS Variables:

   • Override in browser dev tools to test:

     :root { --color-primary: #ff0000; }
     

Extension Points

1. Custom Form Widgets:

   • Extend BannerManager or create new widgets by implementing FormWidgetInterface.

2. Color Palette Logic:

   • Override ColorHelper::derivePrimaryPalette() to customize shade generation.

3. Tailwind Preset:

   • Extend the preset in tailwind.config.js:

     export default {
       presets: [toolkit],
       theme: {
         extend: {
           colors: {
             'custom': 'rgb(var(--color-custom))',
           },
         },
       },
     };
     

4. Dark Mode Events:

   • Listen for darkmode:changed in your JS:

     window.addEventListener('darkmode:changed', (e) => {
         console.log('Dark mode is now:', e.detail);
     });
     

5. View Composer:

   • Access theme data in all views via $themeBrandStyle and $themeNeutralStyle:

     <html style="{{ $themeBrandStyle }}">
     

Configuration Quirks

• Vite Auto-Detection:

  • The preset auto-detects app.ts over app.js. To force JS, rename your entry file.

• Tailwind Content Paths:

  • Ensure content in tailwind.config.js includes:

    content: [
      './resources/**/*.blade.php',
      './resources/src/**/*.{js,ts}',
    ],
    

• Livewire Namespace:

  • The auto