Mary V1 Community Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require williamalmeida/mary-v1-community
   

   Add Tailwind CSS and DaisyUI to your tailwind.config.js:

   module.exports = {
       plugins: [
           require('daisyui'),
           require('mary-v1-community'),
       ],
       daisyui: {
           themes: ["light", "dark", "cupcake"], // Include your preferred themes
       },
   }
   

2. Publish Assets

   npm run dev  // or `npm run build` for production
   

3. First Use Case Use a pre-built component in a Livewire blade:

   <x-mary-button type="primary" wire:click="submitForm">
       Submit
   </x-mary-button>
   

   Verify the component renders correctly in your Livewire component.

Implementation Patterns

Core Workflows

1. Component Integration

   • Livewire Components: Use <x-mary-{component}> tags (e.g., <x-mary-card>) in Livewire blades.
   • Dynamic Props: Pass props like type, size, or wire:model directly:

     <x-mary-input wire:model="name" placeholder="Enter name" type="text" />
     

   • Slots: Customize content via slots:

     <x-mary-modal>
         <x-slot name="title">Confirm Action</x-slot>
         <p>Are you sure?</p>
     </x-mary-modal>
     

2. Theming

   • Override DaisyUI themes in tailwind.config.js:

     daisyui: {
         themes: [
             {
                 mytheme: {
                     "primary": "#3b82f6",
                     "secondary": "#10b981",
                 },
             },
         ],
     }
     

   • Apply themes globally or per-component:

     <x-mary-button theme="mytheme">Custom Themed</x-mary-button>
     

3. Livewire + Mary Integration

   • State Management: Bind Livewire properties to Mary components:

     <x-mary-select wire:model="selectedOption">
         <option value="1">Option 1</option>
         <option value="2">Option 2</option>
     </x-mary-select>
     

   • Event Handling: Use wire:click or wire:change for interactivity:

     <x-mary-checkbox wire:click="toggleFeature({{ $feature->id }})">
         Enable Feature
     </x-mary-checkbox>
     

4. Layout Patterns

   • Responsive Grids: Use DaisyUI’s grid system:

     <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
         <x-mary-card>...</x-mary-card>
         <x-mary-card>...</x-mary-card>
     </div>
     

   • Forms: Leverage pre-built form components:

     <x-mary-form wire:submit.prevent="save">
         <x-mary-input wire:model="name" />
         <x-mary-button type="submit">Save</x-mary-button>
     </x-mary-form>
     

Gotchas and Tips

Common Pitfalls

1. Component Registration

   • Ensure components are auto-discovered. If using custom paths, add to config/view.php:

     'components' => [
         'mary' => App\View\Composers\MaryComposer::class,
     ],
     

   • Fix: Run php artisan view:clear if components fail to load.

2. Tailwind/DaisyUI Conflicts

   • Issue: DaisyUI styles override Tailwind or vice versa.
   • Fix: Order matters in tailwind.config.js:

     plugins: [
         require('tailwindcss'),
         require('daisyui'),
         require('mary-v1-community'), // Load last
     ],
     

3. Livewire + Mary Styling

   • Issue: Livewire’s default styles clash with Mary’s.
   • Fix: Override Livewire’s CSS in resources/css/app.css:

     @layer components {
         @import 'mary-v1-community/dist/mary.css';
     }
     

4. Dynamic Theming

   • Issue: Theme changes don’t apply dynamically.
   • Fix: Use JavaScript to toggle themes:

     document.querySelectorAll('[data-theme]').forEach(el => {
         el.addEventListener('click', () => {
             document.documentElement.setAttribute('data-theme', el.dataset.theme);
         });
     });
     

Debugging Tips

1. Inspect Components Use browser dev tools to verify classes are applied:

   <!-- Check for missing classes -->
   <x-mary-button class="debug">Hover</x-mary-button>
   

   Add debug class to inspect rendered HTML/CSS.

2. Livewire Debugging

   • Log props in Livewire component:

     public function mount() {
         $this->log('Component mounted', 'debug');
     }
     

   • Check Laravel logs (storage/logs/laravel.log) for errors.

3. Dependency Conflicts

   • Issue: Conflicts with other UI packages (e.g., Bootstrap).
   • Fix: Use !important sparingly or scope Mary’s CSS:

     .mary-component {
         @apply /* Tailwind classes */;
     }
     

Extension Points

1. Custom Components Extend existing components by copying from resources/views/components/mary/ and modifying:

   <!-- Example: Custom Alert -->
   <x-mary-alert type="info" :show="$showAlert">
       {{ $message }}
   </x-mary-alert>
   

2. Dark Mode Leverage DaisyUI’s dark mode:

   <x-mary-toggle wire:click="toggleDarkMode" />
   

   Toggle via Livewire:

   public $darkMode = false;
   public function toggleDarkMode() {
       $this->darkMode = !$this->darkMode;
       $this->dispatch('theme-updated', data: ['dark' => $this->darkMode]);
   }
   

3. Accessibility Add ARIA attributes to components:

   <x-mary-button aria-label="Submit form" wire:click="submit">
       Submit
   </x-mary-button>
   

4. Localization Use Blade’s @lang directive for multi-language support:

   <x-mary-button>{{ __('mary.submit') }}</x-mary-button>