Hwkui Laravel Package

Getting Started

• Install via Composer: composer require hawkiq/livewire-hwkui.
• Publish assets/config: php artisan vendor:publish --tag=hwkui-assets and php artisan vendor:publish --tag=hwkui-config (check the package’s README for exact tags; some releases combine them).
• Include the package’s CSS/JS in your layout (usually via @hwkuiStyles / @hwkuiScripts or a published asset link).
• First use case: drop a component into a Blade view, e.g. a button or modal (<x-hwkui::button>), or set up the Tour widget for onboarding. The Tour widget is the most feature-rich entry point—define steps in a Livewire component or config and render <x-hwkui::tour :steps="$steps" />.
• Look first at the package’s config/hwkui.php (or similarly named config) to see available components and global options, and at the published views to understand the markup contract.

Implementation Patterns

• Blade component composition: Use the package’s Blade components as building blocks. Most UI elements (buttons, modals, alerts, etc.) are used directly in Blade, so you can nest them inside Livewire components without extra wiring.
• Tour widget setup: Define tour steps as an array of selectors/texts, then pass to the Tour component. Since 1.1.3, the Tour survives wire:navigate navigation—so you can use it in SPA-style Livewire apps without re-initializing on every page change.
• Customizing the Tour: Use the new options prop/array to override texts and the next button color. Example: <x-hwkui::tour :steps="$steps" :options="['nextButtonColor' => '#0ea5e9', 'nextText' => 'Continue']" />. Keep option keys in sync with the package’s documented API.
• Livewire integration: Trigger tours from Livewire actions (e.g., after onboarding completes) by dispatching a browser event or using $this->dispatch('hwkui-tour-start') if the package exposes such hooks. Check the package source for event names.
• Theming: Prefer CSS variables or the config file over hard-coded overrides. The new color option is a convenience, but global theming via CSS custom properties will keep upgrades painless.
• Testing: In feature tests, assert that the Tour component renders with expected step data. For browser tests (Dusk/Pest browser), verify that wire:navigate links don’t break the tour—this was the 1.1.3 fix.

Gotchas and Tips

• Asset cache: After updating to 1.1.3, re-publish assets and clear caches (php artisan vendor:publish --tag=hwkui-assets --force, php artisan view:clear, php artisan cache:clear). Stale JS is the most common reason the wire:navigate fix appears not to work.
• wire:navigate compatibility: The Tour widget fix is specific to Livewire’s SPA navigation. If you use Turbo, Inertia, or custom history APIs, test carefully—the fix may only cover wire:navigate.
• Options API stability: The new options array is convenient but may not be fully documented yet. Read the component’s source to confirm exact keys (e.g., nextButtonColor vs next_button_color) and whether colors accept CSS values or only hex.
• Config publishing: If you published config/views before 1.1.3, your local copies won’t include new option defaults. Diff the package’s original files or re-publish with --force and merge changes.
• Debugging the Tour: If steps don’t highlight, verify that target selectors exist at the time the tour starts (especially inside Livewire-rendered content). Use browser dev tools to confirm the tour’s JS is loaded and no console errors occur.
• Extension points: The package likely exposes Blade slots and class overrides. Prefer slots for content and CSS classes for styling; avoid editing vendor files. For deeper customisation, extend the published view or wrap the component in your own Blade component.