Capyui Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require themegazord/capyui
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Themegazord\CapyUI\CapyUIServiceProvider" --tag="public"
   php artisan vendor:publish --provider="Themegazord\CapyUI\CapyUIServiceProvider" --tag="config"
   

2. Basic Blade Integration Add the CapyUI CSS/JS to your resources/views/layouts/app.blade.php:

   @vite(['resources/css/app.css', 'node_modules/@themegazord/capyui/dist/capyui.css'])
   @vite(['resources/js/app.js', 'node_modules/@themegazord/capyui/dist/capyui.js'])
   

3. First Component Use a pre-built component in a Blade view:

   <x-capyui.button type="primary">Click Me</x-capyui.button>
   

First Use Case: Quick Form Styling

Replace a standard Laravel form with CapyUI components:

<form method="POST" action="/submit">
    @csrf
    <x-capyui.input type="text" name="username" label="Username" />
    <x-capyui.button type="submit">Submit</x-capyui.button>
</form>

Implementation Patterns

Modular Component Usage

1. Component Hierarchy

   • Base Components: <x-capyui.button>, <x-capyui.input>, <x-capyui.card>
   • Layout Components: <x-capyui.container>, <x-capyui.grid>
   • Utility Components: <x-capyui.spinner>, <x-capyui.tooltip>

2. Slot-Based Customization

   <x-capyui.card>
       <x-slot name="header">
           <h3>Custom Header</h3>
       </x-slot>
       <p>Default content</p>
   </x-capyui.card>
   

3. Dynamic Props Pass dynamic props via Blade:

   <x-capyui.button
       type="{{ $isPrimary ? 'primary' : 'secondary' }}"
       disabled="{{ $isLoading }}"
   >
       {{ $label }}
   </x-capyui.button>
   

Workflows

1. Theming Override default colors via config (config/capyui.php):

   'theme' => [
       'primary' => '#3b82f6',
       'secondary' => '#10b981',
   ],
   

   Or use CSS variables in your global stylesheet.

2. Form Integration Combine with Laravel Collective or Livewire:

   <x-capyui.input
       type="email"
       name="email"
       :value="old('email', $user->email ?? '')"
       error="{{ $errors->first('email') }}"
   />
   

3. Dark Mode Support Toggle via JavaScript:

   document.querySelector('[data-capyui-theme]').dataset.theme = 'dark';
   

Integration Tips

• Vite/Laravel Mix: Ensure @themegazord/capyui is included in your build.
• Livewire/Alpine: Use CapyUI components as wrappers for interactivity:

  <x-capyui.button wire:click="save">Save</x-capyui.button>
  

• Testing: Use @testingEnvy to render components in PHPUnit:

  $component = Blade::render('<x-capyui.button>Test</x-capyui.button>');
  

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Issue: Components appear broken if Vite isn’t configured correctly.
   • Fix: Verify @themegazord/capyui is in vite.config.js:

     resolve: {
         alias: {
             '@themegazord/capyui': path.resolve(__dirname, 'node_modules/@themegazord/capyui'),
         },
     },
     

2. Prop Conflicts

   • Issue: Custom props may clash with CapyUI’s internal props (e.g., type).
   • Fix: Prefix custom props with capyui- or use data-* attributes.

3. Blade Caching

   • Issue: Changes to components aren’t reflected due to Blade cache.
   • Fix: Clear cache:

     php artisan view:clear
     

Debugging

• Inspect Elements: Use browser dev tools to check if CSS/JS is loaded.
• Console Logs: Enable CapyUI debug mode in config:

  'debug' => env('CAPYUI_DEBUG', false),
  

• Component Validation: Use php artisan capyui:validate to check for misconfigurations.

Extension Points

1. Custom Components Extend the library by creating new components in resources/views/vendor/capyui:

   <!-- resources/views/vendor/capyui/custom-button.blade.php -->
   <x-capyui.button :class="{ 'custom-style': $custom }">
       {{ $slot }}
   </x-capyui.button>
   

   Register in AppServiceProvider:

   Blade::component('capyui.custom-button', \Themegazord\CapyUI\Views\CustomButton::class);
   

2. Plugin System Use the CapyUI::extend() method to add functionality:

   CapyUI::extend('button', function ($component) {
       $component->addProp('icon', 'string');
   });
   

3. Local Overrides Override default components by publishing and modifying:

   php artisan vendor:publish --tag="capyui-views"
   

Config Quirks

• Default Values: Config options in config/capyui.php can be overridden via environment variables (e.g., CAPYUI_THEME_PRIMARY).
• Lazy Loading: Enable for better performance:

  'lazy_load' => true,
  

  Then use data-capyui-lazy on components.

Performance Tips

• Critical CSS: Inline critical CapyUI styles for above-the-fold content.
• PurgeCSS: Whitelist CapyUI classes in your PurgeCSS config:

  // tailwind.config.js
  module.exports = {
      purge: {
          content: [
              './resources/views/**/*.blade.php',
              './node_modules/@themegazord/capyui/dist/**/*.js',
          ],
      },
  };