Mary Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require robsontenorio/mary
   

   For Tailwind-only (no CSS):

   composer require robsontenorio/mary --with-all-dependencies --no-css
   

2. Publish Config (optional):

   php artisan vendor:publish --provider="RobsonTenorio\Mary\MaryServiceProvider" --tag="config"
   

   Configure in config/mary.php (e.g., default theme, locale, CDN paths).

3. Add to Livewire View:

   @livewireStyles
   @livewireScripts
   @maryStyles
   @maryScripts
   

First Use Case: Basic Form

<mary-input wire:model="name" label="Name" />

• Automatically handles validation, error display, and Livewire binding.
• Supports all standard HTML input types (text, email, password, etc.).

Implementation Patterns

1. Component Composition

• Nested Components: Combine components like mary-card with mary-input or mary-table:

  <mary-card>
      <mary-input wire:model="email" label="Email" />
      <mary-button type="submit">Save</mary-button>
  </mary-card>
  

• Slots: Use {{ $slot }} for custom content (e.g., mary-modal with custom footer).

2. Livewire Integration

• Two-Way Binding: All components support wire:model for reactive data:

  <mary-select wire:model="status" :options="$statuses" label="Status" />
  

• Event Handling: Listen to component events (e.g., @mary-open.window="handleDrawerOpen").

3. Theming & Customization

• Tailwind Classes: Extend with custom classes:

  <mary-button class="bg-blue-600 hover:bg-blue-700">Custom</mary-button>
  

• Config Overrides: Modify config/mary.php for global defaults (e.g., theme: 'dark').

4. Advanced Features

• Popovers/Tooltips: Add popover or tooltip attributes:

  <mary-input label="Password" popover="Show hint" />
  

• Conditional Rendering: Use x-if or x-show:

  <mary-toast x-show="showSuccess" type="success" />
  

5. Form Handling

• Validation: Built-in error display:

  <mary-input wire:model="phone" label="Phone" rules="required|numeric" />
  

• Multi-Step Forms: Use mary-tabs or mary-steps for progressive disclosure.

Gotchas and Tips

Pitfalls

1. CDN Dependencies:

   • Some components (e.g., mary-calendar) require external JS/CSS (check docs).
   • Fix: Ensure CDN paths in config/mary.php are correct or use local assets.

2. Livewire 4+ Compatibility:

   • Components are tested with Livewire 4, but older versions may need adjustments.
   • Tip: Use @this for component references in Livewire 4:

     <mary-modal @this="$modal" />
     

3. Tailwind Conflicts:

   • DaisyUI classes may conflict with custom Tailwind. Use !important sparingly or override in tailwind.config.js:

     safelist: ['bg-primary', 'text-secondary']
     

4. State Management:

   • Avoid overusing wire:model for complex state. Use Livewire properties for derived data:

     public $name;
     public $fullName => "{$this->name} Doe";
     

5. Component Isolation:

   • Some components (e.g., mary-drawer) require unique IDs. Use wire:key if dynamically rendered:

     <mary-drawer wire:key="'drawer-'.$id" />
     

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify classes/attributes.
• Check Console: Look for errors in the "Console" tab (e.g., missing CDN scripts).
• Component Events: Log events for debugging:

  <mary-modal @open="console.log('Opened')" />
  

Extension Points

1. Custom Components:

   • Extend existing components by copying from vendor/robsontenorio/mary/resources/views to resources/views/vendor/mary.
   • Override logic in a Livewire component:

     public function mount() {
         $this->dispatch('mary-init');
     }
     

2. Plugin System:

   • Use mary:register in AppServiceProvider to add custom components:

     Mary::register('custom-component', CustomComponent::class);
     

3. Localization:

   • Override translations in resources/lang/vendor/mary.
   • Example:

     'validation' => [
         'required' => 'Custom required message',
     ],
     

Performance Quirks

• Lazy-Loading: For heavy components (e.g., mary-table), use x-data to lazy-initialize:

  <mary-table x-data="{ loaded: false }" @loaded="loaded = true" />
  

• Memory Leaks: Clean up event listeners in Livewire hooks:

  public function hydrate() {
      $this->dispatch('mary-cleanup');
  }
  

Pro Tips

• Dark Mode: Use dark: variants for Tailwind classes:

  <mary-button dark:bg-gray-800>Dark Button</mary-button>
  

• Accessibility: Add aria-* attributes for screen readers:

  <mary-tooltip aria-label="Description">Hover me</mary-tooltip>
  

• Testing: Use livewire/test to test components:

  $this->assertSee('mary-input');