Laravel Headless Ui Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require schaefersoft/laravel-headless-ui
   

   No manual registration needed—auto-discovery handles it.

2. Import Assets: Add to your CSS:

   @import '../../vendor/schaefersoft/laravel-headless-ui/resources/css/hui.css';
   

   Add to your JS (pre-built):

   import '../../vendor/schaefersoft/laravel-headless-ui/dist/js/hui.js';
   

3. First Use Case: Use the x-hui::tabs component in a Blade view:

   <x-hui::tabs>
       <x-hui::tabs.tablist>
           <x-hui::tabs.tab>Tab 1</x-hui::tabs.tab>
           <x-hui::tabs.tab>Tab 2</x-hui::tabs.tab>
       </x-hui::tabs.tablist>
       <x-hui::tabs.panel>Content 1</x-hui::tabs.panel>
       <x-hui::tabs.panel>Content 2</x-hui::tabs.panel>
   </x-hui::tabs>
   

Where to Look First

• Documentation: Check the GitHub repo for component-specific docs (e.g., tabs.md, range-slider.md).
• Blade Prefix: All components use x-hui:: prefix (e.g., x-hui::dropdown, x-hui::dialog).
• Styling: Components are unstyled—use your own CSS or Tailwind classes.

Implementation Patterns

Usage Patterns

1. Component Composition:

   • Tabs: Nest tablist and tab inside tabs, followed by panel in order.

     <x-hui::tabs :initial-index="1">
         <x-hui::tabs.tablist class="flex gap-4">
             <x-hui::tabs.tab>Settings</x-hui::tabs.tab>
             <x-hui::tabs.tab>Profile</x-hui::tabs.tab>
         </x-hui::tabs.tablist>
         <x-hui::tabs.panel>Settings content</x-hui::tabs.panel>
         <x-hui::tabs.panel>Profile content</x-hui::tabs.panel>
     </x-hui::tabs>
     

   • Range Slider: Combine track, thumb, and track.value for dual-thumb sliders.

     <x-hui::range-slider>
         <x-hui::range-slider.track>
             <x-hui::range-slider.track.value/>
             <x-hui::range-slider.thumb role="min" min="0" max="100" value="20"/>
             <x-hui::range-slider.thumb role="max" min="0" max="100" value="80"/>
         </x-hui::range-slider.track>
     </x-hui::range-slider>
     

2. Dynamic Initialization:

   • Use :initial-index for tabs or data-active for one-off active states.
   • For sliders, set value directly on thumb components.

3. Syncing Inputs:

   • Use x-hui::range-slider.input to sync thumb values with native inputs:

     <x-hui::range-slider.input role="min" class="w-16"/>
     <span data-hui-range-slider-value="min"></span>
     

Workflows

1. Form Integration:

   • Bind slider thumbs to form fields via name attribute:

     <x-hui::range-slider.thumb role="min" name="price_min" value="{{ old('price_min', 20) }}"/>
     

   • Validate using Laravel’s validation rules (e.g., min, max).

2. Conditional Rendering:

   • Use Blade @if to toggle components dynamically:

     @if(auth()->user()->can('edit_profile'))
         <x-hui::tabs.tab>Edit Profile</x-hui::tabs.tab>
     @endif
     

3. Accessibility:

   • Leverage ARIA attributes (e.g., aria-disabled="true" for disabled tabs).
   • Ensure keyboard navigation works by testing ArrowLeft/ArrowRight for tabs.

Integration Tips

• Tailwind CSS: Use layer(base) for HUI CSS to avoid specificity conflicts:

  @import '../../vendor/schaefersoft/laravel-headless-ui/resources/css/hui.css' layer(base);
  

• Vite/Laravel Mix: Import the pre-built JS for zero-config usage:

  import '../../vendor/schaefersoft/laravel-headless-ui/dist/js/hui.js';
  

• TypeScript: Import the source for custom builds:

  import '../../vendor/schaefersoft/laravel-headless-ui/resources/js/hui.ts';
  

Gotchas and Tips

Pitfalls

1. Thumb Role Requirement:

   • Error: role is required for x-hui::range-slider.thumb (must be "min" or "max").
   • Fix: Use the ThumbRole enum or strings:

     <x-hui::range-slider.thumb role="min" .../>
     

2. Panel Order Mismatch:

   • Error: Tabs and panels must align in order. Mismatches cause silent failures.
   • Fix: Ensure tabs.tab and tabs.panel are in the same sequence.

3. CSS Specificity:

   • Error: Custom styles may not override HUI defaults due to specificity.
   • Fix: Use !important sparingly or increase specificity:

     .my-tabs .hui-tabs-tab[data-active] { ... }
     

4. Disabled State:

   • Error: Disabled tabs/panels may not visually indicate their state.
   • Fix: Use data-disabled or aria-disabled in CSS:

     <x-hui::tabs.tab data-disabled>...</x-hui::tabs.tab>
     

     [data-disabled] { opacity: 0.5; }
     

Debugging

1. Console Errors:

   • Check browser console for missing role attributes or invalid props.
   • Example error: Invalid role "foo" for thumb. Must be "min" or "max".

2. Initial Index Fallback:

   • If :initial-index is invalid, the first enabled tab activates.
   • Debug: Add {{ dd($tabs->initialIndex) }} to verify the value.

3. Slider Value Sync:

   • If data-hui-range-slider-value elements don’t update, ensure:
     • The role matches the thumb (e.g., data-hui-range-slider-value="min").
     • The JS bundle is loaded.

Config Quirks

1. No Global Config:

   • The package has no config file—all settings are passed via Blade props.

2. Vertical Tabs:

   • Set :vertical="true" and update keyboard navigation expectations (use ArrowUp/ArrowDown).

3. Thumb Styling:

   • Native <input type="range"> thumbs require CSS pseudo-elements:

     .hui-range-slider-thumb::-webkit-slider-thumb {
         appearance: none;
         width: 20px;
         height: 20px;
         background: #4f46e5;
     }
     

Extension Points

1. Custom Components:

   • Extend the package by creating new Blade components in resources/views/vendor/schaefersoft/headless-ui.
   • Example: Copy resources/views/components/range-slider.blade.php and modify.

2. JavaScript Hooks:

   • Listen for HUI events via custom JS:

     document.addEventListener('hui:tab:change', (e) => {
         console.log('Active tab changed:', e.detail.index);
     });
     

3. Tailwind Variants:

   • Use Tailwind’s data-* variants for dynamic styling:

     <x-hui::tabs.tab class="data-[active]:bg-blue-500">...</x-hui::tabs.tab>