Getting Started

Minimal Setup

Installation
```
composer require datalogix/tallkit
```
Pin to ^0.1.1 or later — this release fixes component retrieval inside the modal and toast helpers, so earlier patch versions can silently render the wrong component (or nothing) when using those methods.
```
composer require datalogix/tallkit:^0.1.1
```

Publish the package assets (if needed)

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

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>

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>.
- CHANGELOG: Read it before bumping — v0.1.1 is a patch, but the modal/toast retrieval path is worth verifying in your own app after upgrading.

Implementation Patterns

Core Workflows

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>
```

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" />

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]" />
```
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" />
```
Programmatic Modal and Toast
- modal and toast are the two helpers that resolve a component at call time. This is exactly the code path fixed in v0.1.1, so treat them as the first thing to smoke-test after upgrading.
- Toast from a Livewire/controller action (typical after a form save):
```
use function Datalogix\Tallkit\toast;

public function save()
{
    $this->post->save();

    toast()
        ->success('Post saved.')
        ->duration(4000);
}
```
- Modal opened from a server action, passing the component to render inside:
```
use function Datalogix\Tallkit\modal;

modal()
    ->component('post-edit', ['post' => $post])
    ->open();
```
- Pattern: keep the component name as a string prop bound at call time rather than instantiating the component class yourself — the helper owns retrieval, and that's the layer v0.1.1 corrected.
- Test them explicitly: a modal or toast that renders the wrong component (or a blank body) is the symptom this release addresses.

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

Stale Modal/Toast Rendering (pre-0.1.1)
- If you are on 0.1.0 or below and see modals or toasts displaying the wrong content — or an empty body — the cause is component retrieval inside modal() / toast(), not your component markup. Upgrade to ^0.1.1 before debugging your own views.
- After upgrading, clear compiled views so stale Blade output doesn't mask the fix:
```
php artisan view:clear
```

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>

Styling Conflicts
- Tailwind Overrides: Customize styles via tailwind.config.js or scoped classes:
```
/* Example: Override button padding */
.tallkit-button {
    @apply py-3 px-4;
}
```
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'])
```
- Modal and toast interactivity is Alpine-driven too — a broken x-data boot looks identical to a component retrieval failure. Rule out Alpine first.
Component Registration
- Manual Registration: If components don't render, ensure they're registered in AppServiceProvider:
```
Tallkit::registerComponents();
```
- Components referenced by string name from modal()->component('...') must be registered through the same channel, or retrieval returns nothing.

Debugging Tips

Inspect Blade Output
- Use @dd() to debug component props:
```
@dd(\Datalogix\Tallkit\Components\Button::class)
```
Check for Errors
- Enable Laravel debug mode (APP_DEBUG=true) and check logs for missing views or props.
Isolate Modal/Toast Failures
- Reproduce with a bare helper call outside your layout. If the component resolves there but not in-app, the problem is rendering context; if it fails in both, it's retrieval — the v0.1.1 fix territory.
- Confirm the installed version before filing a bug:
```
composer show datalogix/tallkit
```
Component Isolation
- Test components in isolation (e.g., a dedicated Blade file) to rule out layout conflicts.

Extension Points

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);
```
- Custom components registered this way are resolvable from modal() and toast() — verify after upgrading, since retrieval semantics changed.

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>

JavaScript Enhancements
- Extend component behavior via Alpine.js or custom JS:
```
<x-upload @uploaded="console.log('Uploaded!')" />
```
Configuration
- Publish config for global settings:
```
php artisan vendor:publish --tag="tallkit-config"
```
- Customize defaults (e.g., button sizes, colors) in config/tallkit.php.

Tallkit Laravel Package