Tallkit Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require datalogix/tallkit
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="Datalogix\Tallkit\TallkitServiceProvider" --tag="public"
   

2. First Use Case: Basic Button Include the package in your Blade view:

   @use('Datalogix\Tallkit\Components\Button')
   

   Render a button:

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

3. Where to Look First

   • Documentation: Check the GitHub README for component examples and core features.
   • Components Directory: Browse vendor/datalogix/tallkit/src/Components/ for available components (e.g., Button.php, Alert.php).
   • Blade Usage: All components are designed for Blade integration via @use or <x-component>.

Implementation Patterns

Core Workflows

1. Component Integration

   • Dynamic Components: Use autocomplete or command with dynamic data:

     <x-autocomplete :items="$dynamicItems" placeholder="Search..." />
     

   • Variants: Leverage core components like button with variants:

     <x-button type="danger" outline>Delete</x-button>
     

2. Form Fields

   • Reusable Fields: Use field wrapper for consistent styling:

     <x-field label="Username">
         <x-input name="username" />
     </x-field>
     

   • Specialized Inputs: For toggle, slider, or upload:

     <x-toggle name="active" label="Enable Feature" />
     

3. Layout Components

   • Headers/Navigations: Customize header or build a nav with active states:

     <x-header title="Dashboard" subtitle="Welcome back" />
     

   • Pagination: Extend paginator with per-page select:

     <x-paginator :items="$posts" per-page-options="[5, 10, 20]" />
     

4. Advanced Features

   • Editor/Kanban: Integrate rich text or drag-and-drop:

     <x-editor :content="$post->content" />
     

   • Pickers: Use date-picker or color-picker:

     <x-date-picker name="event_date" />
     

5. Event Handling

   • JavaScript Events: Components often emit events (e.g., autocomplete:selected). Listen via Alpine.js:

     <x-autocomplete @selected="handleSelection" />
     <script>
         document.addEventListener('autocomplete:selected', (e) => {
             console.log(e.detail);
         });
     </script>
     

Gotchas and Tips

Pitfalls

1. Dynamic Loading

   • Lazy-Loading Items: For autocomplete or command, ensure data is fetched via AJAX to avoid initial load delays:

     <x-autocomplete :items="[]">
         @push('scripts')
             <script>
                 document.querySelector('x-autocomplete').addEventListener('search', (e) => {
                     fetch(`/api/search?q=${e.detail.query}`)
                         .then(res => res.json())
                         .then(items => {
                             document.querySelector('x-autocomplete').items = items;
                         });
                 });
             </script>
         @endpush
     </x-autocomplete>
     

2. Styling Conflicts

   • Tailwind Overrides: Customize styles via tailwind.config.js or scoped classes:

     /* Example: Override button padding */
     .tallkit-button {
         @apply py-3 px-4;
     }
     

3. Missing Dependencies

   • Alpine.js: Some components (e.g., toggle, slider) require Alpine.js. Include it in your layout:

     @vite(['resources/js/app.js', 'resources/js/alpine.js'])
     

4. Component Registration

   • Manual Registration: If components don’t render, ensure they’re registered in AppServiceProvider:

     Tallkit::registerComponents();
     

Debugging Tips

1. Inspect Blade Output

   • Use @dd() to debug component props:

     @dd(\Datalogix\Tallkit\Components\Button::class)
     

2. Check for Errors

   • Enable Laravel debug mode (APP_DEBUG=true) and check logs for missing views or props.

3. Component Isolation

   • Test components in isolation (e.g., a dedicated Blade file) to rule out layout conflicts.

Extension Points

1. Custom Components

   • Extend existing components by creating child classes:

     namespace App\Components;
     use Datalogix\Tallkit\Components\Button;
     
     class CustomButton extends Button {
         public function customMethod() { ... }
     }
     

   • Register in AppServiceProvider:

     Tallkit::extend('custom-button', CustomButton::class);
     

2. Adding New Variants

   • Override core components in resources/views/vendor/tallkit/:

     <!-- resources/views/vendor/tallkit/button.blade.php -->
     @props(['type' => 'primary'])
     <button class="bg-{{ $type }}-500 ...">...</button>
     

3. JavaScript Enhancements

   • Extend component behavior via Alpine.js or custom JS:

     <x-upload @uploaded="console.log('Uploaded!')" />
     

4. Configuration

   • Publish config for global settings:

     php artisan vendor:publish --tag="tallkit-config"
     

   • Customize defaults (e.g., button sizes, colors) in config/tallkit.php.