Ux Haptics Laravel Package

Getting Started

zairigimad/ux-haptics is a fresh (v1.0.0) Laravel package for firing device haptic feedback (vibration patterns) from your Blade/Livewire UI. Treat it as a thin, opinionated wrapper over the Web Vibration API plus Laravel-side ergonomics (config, Blade helpers, asset registration).

Minimal steps:

1. Install and publish:

   composer require zairigimad/ux-haptics
   php artisan vendor:publish --tag="ux-haptics-config"
   

   If the package ships JS, also run the publish tag for assets and make sure the script is included in your layout (or via @hapticsScripts / the documented directive — confirm the exact tag in the README before wiring it in).

2. Where to look first:

   • config/haptics.php — the pattern presets (tap, success, warning, error, etc.) and any enable/disable switch.
   • src/ — the service provider (what gets registered, whether a Facade is aliased) and the Blade component/directive classes.
   • resources/js/ — the client driver. This is where the real behaviour lives; read it before assuming a pattern duration.

3. First use case — the highest-value one: tap confirmation on a mobile-first action button.

   <x-haptics.button pattern="tap">Save</x-haptics.button>
   

   Or, if the package exposes a helper/directive:

   <button type="submit" @haptics('tap')>Save</button>
   

4. Verify on a real device. Desktop Chrome DevTools will not vibrate; the best you get is a console call. Test on Android Chrome at minimum, and confirm the silent no-op on iOS Safari (see Gotchas).

Implementation Patterns

Centralize patterns in config, not in markup. Define your semantic vocabulary once (tap, success, error, destructive) in config/haptics.php with durations/intensity, then reference the names in Blade. When design wants "softer" feedback you change one array instead of grepping 200 views.

Server-driven feedback for Livewire/AJAX. Haptics are a response signal, so the natural place to dispatch them is after a round trip. Two viable shapes:

• Optimistic: fire tap on the click, fire success/error when the Livewire response lands (via Livewire.hook('morph.updated') or a $this->dispatch('haptics', pattern: 'success') from the component).
• Authoritative: only fire on the server-confirmed event. Slightly laggier but never lies to the user.

Pick one and be consistent; mixing them produces double-buzzes.

Destructive-action confirmation. The single best UX use: a distinct warning pattern on the "Delete" confirm button. It's a genuinely useful affordance because it's felt before the dialog is read.

Progressive enhancement layer. Keep haptics out of your core interaction flow. The pattern should always be optional sugar — wrap triggers so that a missing/unsupported API (or a user opt-out) degrades to nothing, never to a JS error that blocks the submit.

Accessibility opt-out. Store a user preference (localStorage or a user column) and check it in the JS driver before vibrating. Offer it in settings next to reduced-motion. Users with sensory sensitivities and users in meetings will thank you.

Testing. Haptics are untestable in PHPUnit in any meaningful sense. What you can assert is that your components render the expected pattern name/attribute. If the package offers a fake/spy, use it in Dusk/Playwright-adjacent tests; otherwise assert on rendered HTML.

Gotchas and Tips

• iOS Safari does not implement navigator.vibrate. It silently does nothing — no error, no warning. This is not a bug in the package. Plan for iOS to be a no-op and never make a haptic the only confirmation signal.
• User-gesture requirement. Vibration must be triggered from a real user interaction on most mobile browsers. A haptic fired from a timer, a setTimeout, or a websocket push callback will be dropped. Fire synchronously in the click/submit handler, or accept that server-driven patterns may be ignored.
• Double-fire. If you wire a Blade directive and a Livewire $dispatch, you'll feel two buzzes. Audit your triggers; a quick console.count() in the driver reveals it fast.
• Vite/asset pipeline. If the package publishes JS, it won't be in your bundle by default. Either import it in resources/js/app.js or include the published file — check whether the service provider auto-registers it. After publishing, php artisan config:cache / view:cache in production or your edits won't appear.
• Debugging is device-only. Build a hidden debug route or a ?haptics=debug flag that logs the pattern name and duration to console so you can confirm dispatch without buzzing your hand fifty times.
• Don't vibrate on scroll, hover, or per-keystroke typing. Battery, annoyance, and on some Android builds it interferes with the keyboard. Reserve haptics for commit-level events.
• Extension point worth using: most wrappers like this let you register custom patterns or override the driver. If you need a bespoke pulse train, publish the config/JS and extend rather than forking — v1.0.0 is young, so keep your diff against the package small.
• Pin the version. At 1.0.0 with only an "Initial Release" changelog, the API surface is still settling. Use "zairigimad/ux-haptics": "^1.0" and read the changelog before minor bumps; treat 1.x as potentially unstable in spirit.