Blatui Laravel Package

Getting Started

Minimal Setup

1. Install the CLI and dependencies:

   composer require anousss007/blatui
   composer require gehrisandro/tailwind-merge-laravel mallardduck/blade-lucide-icons
   npm install -D alpinejs @alpinejs/anchor @alpinejs/collapse @alpinejs/focus
   

2. Publish foundations (theme tokens + Alpine engine):

   php artisan vendor:publish --tag=blatui-foundations
   

   Update your Vite entrypoints:

   /* resources/css/app.css */
   @import "./blatui.css";
   

   // resources/js/app.js
   import "./blatui.js";
   

3. Verify setup:

   php artisan blatui:init
   

First Use Case: Adding a Button

php artisan blatui:add button

This copies the button component to resources/views/components/ui/button.blade.php. Use it in Blade:

<x-ui.button>Click Me</x-ui.button>

Implementation Patterns

Workflow: Component Adoption

1. List available components:

   php artisan blatui:list
   

   Example output:

   Components:
   - button
   - card
   - input
   - ...
   Blocks:
   - dashboard
   - login-page
   Charts:
   - line-chart
   - bar-chart
   

2. Add components in bulk:

   php artisan blatui:add button card input select
   

3. Theme consistency: Override tokens in resources/css/blatui.css:

   @layer theme {
     --primary: #3b82f6;
     --primary-foreground: white;
   }
   

Integration Tips

• Existing Alpine.js projects: Skip blatui.js and register BlatUI into your Alpine instance:

  import { registerBlatUI } from './blatui-core.js';
  registerBlatUI(Alpine);
  

• Dynamic imports: Lazy-load components with Blade @once or Vite dynamic imports:

  @once
  <x-ui.button>Lazy Button</x-ui.button>
  @endonce
  

• Custom props: Extend components by adding props in their Blade files:

  <!-- resources/views/components/ui/button.blade.php -->
  <button {{ $attributes->merge(['class' => 'bg-blue-500']) }}>
    {{ $slot }}
  </button>
  

• Blocks and charts: Copy-paste from the live demo into your project.

Gotchas and Tips

Pitfalls

1. Tailwind v4 requirement:

   • BlatUI uses @theme inline and OKLCH colors. If you see Invalid @theme rule, run:

     npx @tailwindcss/upgrade
     

2. Alpine.js conflicts:

   • Importing blatui.js in projects with existing Alpine instances will boot a second instance.
   • Fix: Use registerBlatUI(Alpine) before Alpine.start().

3. Missing dependencies:

   • Charts require apexcharts. Run blatui:add to see dependency warnings:

     Installing charts requires: composer require apexcharts
     

4. Theme token overrides:

   • Overriding tokens in blatui.css won’t apply to already-rendered components.
   • Fix: Clear cache (php artisan cache:clear) or restart dev server.

Debugging

• Check setup:

  php artisan blatui:init
  

  Outputs missing dependencies or misconfigurations.

• Component-specific issues:

  php artisan blatui:list <component>
  

  Shows usage examples and props.

• Alpine debugging: Add x-data to components to inspect state:

  <x-ui.button x-data="{ open: false }">Debug</x-ui.button>
  

Extension Points

1. Customize components: Edit files in resources/views/components/ui/ directly. Changes persist across updates.

2. Add new variants: Clone an existing component (e.g., button.blade.php) and modify its props/Blade logic.

3. Extend the engine: Modify resources/js/blatui-core.js to add custom Alpine directives or chart types.

4. Dark mode: Use Tailwind’s dark: variants or override tokens in blatui.css:

   @layer theme dark {
     --background: #1f2937;
   }
   

Pro Tips

• Component organization: Group components by feature in subdirectories (e.g., resources/views/components/ui/forms/).

• Partial updates: Use blatui:add --all sparingly. Prefer adding only needed components to avoid bloat.

• Accessibility: Leverage BlatUI’s built-in WCAG AA compliance. Audit with:

  npm install -g axe-core
  axe "http://your-app.test"
  

• Performance: Lazy-load heavy components (e.g., charts) with Alpine:

  <div x-data="{ loadChart: false }" @click="loadChart = true">
    <template x-if="loadChart">
      <x-ui.line-chart :data="chartData" />
    </template>
  </div>
  

```markdown
### Additional Notes for Daily Use
- **Version pinning**:
  Pin `anousss007/blatui` in `composer.json` to avoid unexpected updates:
  ```json
  "anousss007/blatui": "^1.13"

• CI/CD: Add to your pipeline:

  composer require anousss007/blatui --dev
  php artisan blatui:init --verify
  

• Collaboration: Document component usage in a README.md at resources/views/components/.

• Tailwind JIT: Ensure tailwind.config.js has:

  module.exports = {
    content: [
      './resources/views/**/*.blade.php',
      './resources/js/**/*.js',
    ],
  }
  

• Lucide Icons: Use icons via Blade components:

  <x-ui.icon name="check" class="h-4 w-4" />
  

  (Requires mallardduck/blade-lucide-icons.)