Fusion Ui Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dahromy/fusion-ui
   

   Publish assets (if using Blade):

   php artisan vendor:publish --provider="Dahromy\FusionUI\FusionUIServiceProvider" --tag=fusion-ui-assets
   

2. First Use Case Include the CSS/JS in your layout:

   @vite(['resources/css/fusion-ui.css', 'resources/js/fusion-ui.js'])
   

   Or use the Blade directive (if published):

   @fusionUi
   

3. Basic Component Usage Copy-paste a component from the docs into your Blade view:

   <fusion-button type="primary">Click Me</fusion-button>
   

   Or use the JS API for dynamic rendering:

   import { FusionButton } from 'fusion-ui';
   new FusionButton({ text: 'Click Me', type: 'primary' }).mount('#app');
   

Implementation Patterns

Workflow Integration

1. Component Library Approach

   • Modular Design: Treat fusion-ui as a "copy-paste" library. Store components in a components/ directory (e.g., resources/views/components/fusion/).
   • Example Structure:

     resources/
     ├── views/
     │   ├── components/
     │   │   ├── fusion/
     │   │   │   ├── button.blade.php
     │   │   │   ├── modal.blade.php
     │   │   │   └── ...
     │   └── layouts/
     │       └── app.blade.php (include @fusionUi)
     

2. Dynamic Rendering with JS

   • Use the JS API for SPAs or dynamic content:

     // Initialize components on DOM ready
     document.addEventListener('DOMContentLoaded', () => {
       new FusionModal({ title: 'Confirm', content: 'Are you sure?' }).mount('#modal-target');
     });
     

   • Laravel Mix/Vite: Import components directly in your JS entry file:

     import { FusionDropdown } from 'fusion-ui';
     

3. Theming and Customization

   • Override default styles via CSS variables (documented in the docs):

     :root {
       --fusion-primary: #3b82f6; /* Tailwind blue-500 */
     }
     

   • Extend components by copying their templates and modifying them in your project.

4. Form Integration

   • Use components with Laravel Collective or Livewire:

     <fusion-form>
       <fusion-input name="email" label="Email"></fusion-input>
       <fusion-button type="submit">Save</fusion-button>
     </fusion-form>
     

   • For Livewire, bind events to Livewire methods:

     new FusionButton({
       text: 'Update',
       onClick: () => @this.updateData()
     });
     

5. Accessibility (a11y) Patterns

   • Leverage built-in a11y features (e.g., aria-* attributes, keyboard navigation).
   • Extend components for custom a11y needs:

     <fusion-tooltip content="Help text" aria-label="Additional details">
       Hover me
     </fusion-tooltip>
     

Gotchas and Tips

Pitfalls

1. Asset Conflicts

   • Issue: CSS/JS conflicts if multiple UI libraries are loaded.
   • Fix: Use unique class prefixes or scope styles:

     .fusion-ui { /* Scope all Fusion UI styles */
       --fusion-primary: #your-color;
     }
     

2. Dynamic Component Initialization

   • Issue: Components may not initialize if DOM elements are added after page load (e.g., AJAX).
   • Fix: Re-initialize components after dynamic content loads:

     document.body.addEventListener('ajaxComplete', () => {
       document.querySelectorAll('[data-fusion-component]').forEach(el => {
         const component = FusionUI.getComponent(el.dataset.fusionComponent);
         new component(el).init();
       });
     });
     

3. Blade vs. JS API

   • Gotcha: Blade components are static; JS API is dynamic. Mixing them may require manual syncing.
   • Tip: Use Blade for static layouts and JS API for interactive elements.

4. Missing Documentation

   • Issue: Some edge cases (e.g., nested components, custom events) lack examples.
   • Tip: Inspect the source code for undocumented features. Example:

     // Undocumented: Disable a button programmatically
     const button = new FusionButton({ text: 'Submit' });
     button.disable(); // Not in docs, but works
     

5. Livewire/Alpine Integration

   • Gotcha: Event binding may clash with Livewire/Alpine.
   • Fix: Use wire:ignore or custom event names:

     <div wire:ignore>
       <fusion-dropdown @fusion:open="handleOpen"></fusion-dropdown>
     </div>
     

Debugging Tips

1. Console Logging Enable debug logs for Fusion UI:

   FusionUI.debug = true; // Logs component lifecycle
   

2. Inspecting Components Use browser dev tools to inspect rendered components. Look for:

   • Missing classes (e.g., fusion-button--primary).
   • Unclosed tags or malformed HTML.

3. Common Errors

   • Error: FusionUI is not defined. Fix: Ensure JS is loaded after the DOM is ready or use defer:

     <script src="fusion-ui.js" defer></script>
     

   • Error: Styles not applying. Fix: Check CSS specificity or variable overrides.

Extension Points

1. Custom Components Extend the base FusionComponent class to create reusable variants:

   class CustomButton extends FusionButton {
     constructor(options) {
       super({ ...options, type: 'custom' });
     }
     mounted() {
       this.el.classList.add('custom-button');
     }
   }
   

2. Event System Listen to custom events (e.g., @fusion:click in Blade or addEventListener in JS):

   document.addEventListener('fusion:modal:open', (e) => {
     console.log('Modal opened:', e.detail);
   });
   

3. Configuration Override defaults globally via FusionUI.config:

   FusionUI.config = {
     transitionDuration: '0.3s',
     defaultTheme: 'dark'
   };
   

4. Server-Side Rendering (SSR) For Inertia.js or SSR frameworks, pre-render components in Blade and hydrate with JS:

   <!-- Blade -->
   <fusion-modal id="my-modal" data-content="{{ $content }}"></fusion-modal>
   
   <!-- JS -->
   const modal = new FusionModal({
     content: document.getElementById('my-modal').dataset.content
   });