Pinex Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require ujnana/pinex in your Laravel project. Ensure your project meets the requirements (PHP 8.1+, Laravel 11+, Livewire 3+, Tailwind CSS 4+).

2. Tailwind Integration Update your resources/css/app.css with:

   @import "tailwindcss";
   @source "../../vendor/ujnana/pinex/src/Views";
   

   Rebuild Tailwind assets (npx tailwindcss -i ./resources/css/app.css -o ./resources/css/dist.css --watch).

3. First Use Case Use the Button component in a Livewire view:

   <x-pinex.button type="primary" wire:click="submitForm">
       Save Changes
   </x-pinex.button>
   

   Register the component in your Livewire class:

   use Ujnana\Pinex\Components\Button;
   

Implementation Patterns

Component Usage Workflows

1. Livewire Integration All Pinex components are designed for Livewire 3. Use them directly in Blade templates:

   <x-pinex.input
       wire:model="name"
       label="Full Name"
       placeholder="Enter your name"
       :error="$errors->first('name')"
   />
   

2. Dynamic Props Leverage Tailwind variants via props (e.g., variant="outline", size="lg"):

   <x-pinex.button variant="outline" size="lg" wire:click="reset">
       Reset
   </x-pinex.button>
   

3. Nested Components Combine components for complex UIs (e.g., Card + Table):

   <x-pinex.card>
       <x-slot name="header">
           <h3 class="text-lg font-medium">User List</h3>
       </x-slot>
       <x-pinex.table :data="$users" />
   </x-pinex.card>
   

4. Slot-Based Layouts Use named slots for custom content:

   <x-pinex.modal>
       <x-slot name="title">Confirm Action</x-slot>
       <x-slot name="content">Are you sure?</x-slot>
       <x-slot name="footer">
           <x-pinex.button type="primary" wire:click="confirm">Yes</x-pinex.button>
       </x-slot>
   </x-pinex.modal>
   

Common Patterns

• Form Handling: Pair <x-pinex.input> with Livewire model binding (wire:model) and validation.
• State Management: Use wire:click, wire:model.defer, and wire:ignore for reactive UIs.
• Accessibility: Ensure components include ARIA attributes (e.g., aria-modal, aria-label).

Gotchas and Tips

Pitfalls

1. Tailwind v4 Configuration

   • Issue: Missing @source directive may break component styles.
   • Fix: Verify app.css includes @source pointing to Pinex views.
   • Debug: Check browser dev tools for unresolved Tailwind classes.

2. Livewire 3 Compatibility

   • Issue: Older Livewire 2 syntax (e.g., wire:model.lazy) may fail.
   • Fix: Use Livewire 3’s wire:model without .lazy (or update to Livewire 3).

3. Component Overrides

   • Issue: Customizing components requires publishing assets.
   • Fix: Publish Pinex views:

     php artisan vendor:publish --tag=pinex-views
     

     Then modify resources/views/vendor/pinex/.

4. Modal Z-Index Conflicts

   • Issue: Modals may appear behind other elements.
   • Fix: Override Tailwind’s z-index in your CSS:

     .pinex-modal-overlay { z-index: 50; }
     

Debugging Tips

• Inspect Props: Use {{ dd($this->props) }} in Livewire components to debug passed props.
• Tailwind Conflicts: Disable Pinex’s Tailwind imports temporarily to isolate issues.
• Livewire Events: Log events in handleClick() or similar methods to trace interactions.

Extension Points

1. Custom Variants Extend components by adding new variants (e.g., variant="danger"):

   <x-pinex.button variant="danger" wire:click="delete">
       Delete
   </x-pinex.button>
   

   Update the component’s Tailwind classes in the source or published views.

2. New Components Fork the package or create a wrapper component:

   // app/View/Components/PinexExtendedButton.php
   class PinexExtendedButton extends Button {
       public function render() {
           $this->class += ' custom-class';
           return parent::render();
       }
   }
   

3. Dark Mode Ensure Pinex components support Tailwind’s dark: variants by adding:

   @layer components {
       .dark .pinex-button {
           @apply bg-gray-800 text-white;
       }
   }
   

4. Localization Override labels/placeholders via Blade slots or Livewire props:

   <x-pinex.input label="{{ __('Custom Label') }}" />