Spire Ui Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require stratos/spire-ui
   

   Add the required Blade directives to your main layout (resources/views/layouts/app.blade.php):

   @spireStyles
   @livewireStyles
   <!-- ... -->
   @spireScripts
   @livewireScripts
   

2. First Component: Use a pre-built component directly in a Blade view:

   <x-spire::button type="primary">Save Changes</x-spire::button>
   

   Verify the button renders with Tailwind styling and Alpine/Livewire interactivity.

3. Explore Core Components: Check the documentation (if available) for:

   • <x-spire::card> for content containers
   • <x-spire::modal> for dialogs
   • <x-spire::dropdown> for interactive menus

Implementation Patterns

Workflows

1. Component Composition: Use Blade slots for flexible content:

   <x-spire::card>
       <x-slot name="header">
           <h3>User Profile</h3>
       </x-slot>
       <p>Content here...</p>
   </x-spire::card>
   

2. Livewire Integration: Pair Spire components with Livewire for dynamic behavior:

   <x-spire::button wire:click="save" type="primary">
       Save
   </x-spire::button>
   

3. Dark Mode: Toggle via Alpine.js:

   <button x-on:click="darkMode = !darkMode" class="dark:hidden">
       Toggle Dark Mode
   </button>
   

4. Localization: Use Laravel’s trans() helper with Spire’s i18n support:

   <x-spire::button>{{ trans('spire.ui.save') }}</x-spire::button>
   

Integration Tips

• Admin Layout: Publish the pre-built layout for rapid development:

  php artisan vendor:publish --tag=spire-ui-layouts
  

  Customize resources/views/components/layouts/admin.blade.php for your app’s branding.

• Custom Theming: Override Tailwind colors in tailwind.config.js:

  module.exports = {
      theme: {
          extend: {
              colors: {
                  primary: '#3b82f6', // Override Spire’s default
              },
          },
      },
  }
  

• Alpine.js Extensions: Extend Spire’s Alpine components in resources/js/app.js:

  document.addEventListener('alpine:init', () => {
      Alpine.data('spire', () => ({
          init() {
              console.log('Custom Spire logic');
          },
      }));
  });
  

Gotchas and Tips

Pitfalls

1. Missing Directives: Forgetting @spireStyles/@spireScripts will break component assets. Verify the directives are in every layout where Spire components are used.

2. Livewire Conflicts: Spire’s Livewire scripts may conflict with custom Livewire components. Ensure @livewireScripts is placed after @spireScripts in the layout.

3. Dark Mode Quirks: Alpine’s dark mode toggle (x-data="darkMode = false") requires Tailwind’s dark: variants. Test in both light/dark modes early:

   <div x-data="{ darkMode: false }" :class="{ 'dark': darkMode }">
       <!-- Content -->
   </div>
   

4. Component Isolation: Spire components assume Tailwind’s base styles. Avoid overriding core classes (e.g., .btn, .card) unless necessary.

Debugging

• Asset Loading: Check the browser’s Network tab for spire.css/spire.js 404 errors. Ensure the package is installed and directives are correct.

• Alpine Errors: Use x-init for debugging:

  <div x-init="console.log('Alpine initialized')"></div>
  

• Livewire Sync: If Livewire updates don’t trigger, verify:

  • @this is used in Livewire components.
  • No JavaScript errors block Livewire’s event listeners.

Extension Points

1. Custom Components: Extend Spire’s components by copying from vendor/stratos/spire-ui/resources/views to resources/views/vendor/spire-ui and modifying.

2. Slot Overrides: Use x-slot to replace default content:

   <x-spire::modal>
       <x-slot name="footer">
           <x-spire::button type="danger">Delete</x-spire::button>
       </x-slot>
   </x-spire::modal>
   

3. Tailwind Config: Extend Spire’s theme in tailwind.config.js:

   module.exports = {
       presets: [require('spire-ui/tailwind')],
       theme: {
           extend: {
               fontFamily: {
                   sans: ['Inter', 'sans-serif'], // Override Spire’s default
               },
           },
       },
   };
   

4. Localization: Add translations to resources/lang/{locale}/spire.php:

   return [
       'ui' => [
           'save' => 'Enregistrer', // French
       ],
   ];