Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require blast-project/ui-bundle
   

   Publish the bundle’s assets and configuration:

   php artisan vendor:publish --provider="Blast\UIBundle\BlastUIBundle" --tag="public"
   php artisan vendor:publish --provider="Blast\UIBundle\BlastUIBundle" --tag="config"
   

2. First Use Case: Basic UI Integration

   • Include the bundle’s CSS/JS in your resources/views/layouts/app.blade.php:

     @vite(['resources/css/app.css', 'node_modules/blast-ui-bundle/dist/css/blast.css'])
     @vite(['resources/js/app.js', 'node_modules/blast-ui-bundle/dist/js/blast.js'])
     

   • Use the provided Blade directives for common UI components (e.g., {{ blast_alert('Success!') }}).

3. Key Files to Review

   • config/blast-ui.php: Core settings (theming, component defaults).
   • resources/views/vendor/blast-ui/: Pre-built components (alerts, modals, etc.).
   • node_modules/blast-ui-bundle/src/: Core JavaScript/TypeScript logic.

Implementation Patterns

1. Component Integration

• Blade Directives: Use built-in directives for rapid UI assembly:

  {{ blast_modal('Edit User', 'user-edit-form') }}
  {{ blast_button('Save', 'primary', 'submit-form') }}
  

• Dynamic Data Binding: Pass Laravel variables directly:

  {{ blast_alert($message, 'info') }}
  

2. Theming & Customization

• Override Defaults: Extend the blast-ui config in config/blast-ui.php:

  'theme' => [
      'primary' => '#3498db',
      'danger' => '#e74c3c',
  ],
  

• Sass Variables: Override SCSS variables in resources/scss/blast/_variables.scss:

  $blast-primary: #2ecc71;
  

3. JavaScript Integration

• Event Listeners: Attach to blast UI elements via data attributes:

  document.querySelector('[data-blast-modal]').addEventListener('blast:open', (e) => {
      console.log('Modal opened:', e.detail.id);
  });
  

• Custom Components: Extend the bundle’s JS API:

  BlastUI.registerComponent('blast-tooltip', {
      template: '<div class="tooltip">{{ text }}</div>',
      props: ['text']
  });
  

4. Form Handling

• Validation Integration: Use the bundle’s validation helpers:

  {{ blast_form('user', [
      'name' => 'text|required',
      'email' => 'email|required'
  ]) }}
  

• CSRF Protection: Automatically included via Blade directives (no manual tokens needed).

5. Asset Optimization

• Vite/Laravel Mix: Bundle JS/CSS via Vite for production builds:

  // vite.config.js
  export default {
      build: {
          rollupOptions: {
              input: {
                  blast: './node_modules/blast-ui-bundle/dist/js/blast.js'
              }
          }
      }
  };
  

Gotchas and Tips

Pitfalls

1. Asset Paths: Ensure node_modules/blast-ui-bundle/dist/ is included in your Vite/Laravel Mix config. Missing assets will break UI rendering.
2. Blade Cache: Clear Blade cache after publishing config:

   php artisan view:clear
   

3. JavaScript Conflicts: Avoid naming collisions with BlastUI global. Use TypeScript for large projects:

   import { BlastUI } from 'blast-ui-bundle';
   

4. Deprecated Methods: Check CHANGELOG.md for breaking changes in minor updates.

Debugging

• Console Logs: Enable debug mode in config/blast-ui.php:

  'debug' => env('APP_DEBUG', false),
  

• Network Tab: Verify JS/CSS files load (404s indicate misconfigured paths).
• Blade Errors: Wrap directives in @error blocks:

  @error
      {{ blast_alert('Failed to render component.', 'danger') }}
  @enderror
  

Extension Points

1. Custom Components: Create new components by extending BlastUI.Component:

   class CustomComponent extends BlastUI.Component {
       static template = `<button @click="handleClick">{{ label }}</button>`;
   }
   BlastUI.register('custom-button', CustomComponent);
   

2. Server-Side Logic: Hook into Laravel events (e.g., BlastUI\Events\ComponentRendered).
3. Testing: Use Pest/Laravel’s HTTP tests to verify Blade directives:

   $response = $this->view('dashboard', ['message' => 'Test']);
   $response->assertSee('blast_alert("Test")');
   

Pro Tips

• Dark Mode: Use CSS variables for dynamic theming:

  @media (prefers-color-scheme: dark) {
      :root {
          --blast-primary: #9b59b6;
      }
  }
  

• Lazy Loading: Load JS components on demand:

  <blast-modal data-src="/modal-content"></blast-modal>
  

• Accessibility: Validate components with axe or Lighthouse—the bundle includes ARIA attributes by default.