Nova Range Filter Laravel Package

Getting Started

Version 0.0.2 is an early, pre-1.0 release, so treat the API as unstable and pin the exact version ("vendor/package": "0.0.2") rather than floating a caret constraint.

1. Install with Composer and confirm the service provider is auto-discovered (or register it manually if the package predates discovery conventions).
2. Read the README first — it is the only reliable source for the config key and/or Blade/Livewire prop name that controls the interval. The release note confirms the capability exists but not its exact spelling.
3. Publish any package config and views (php artisan vendor:publish --tag=...) so you can inspect the defaults and override markup later.
4. Run php artisan config:clear after publishing, then render a single slider on a scratch route to confirm assets load.

The first real use case is almost always a hero/marketing carousel that should auto-advance on a fixed cadence. A minimal integration should look like: one Blade component (or Livewire component) with a single, explicit interval value, rendering three to five slides, with navigation controls present before you worry about autoplay.

Where to look first: the README usage section, the published config file (for the global default interval), and the package's Blade views (to see how the interval is passed to the front-end). If the package ships JavaScript, check how the interval is read — data attribute, inline config object, or a JS initializer.

Implementation Patterns

Set a global default, override per instance. Put a sane default (e.g. 5000 ms) in the published config and override it only where a page needs different pacing. This keeps most call sites clean and makes the cadence auditable in one place.

Normalize units immediately. Determine whether the interval is milliseconds or seconds and document it in your own wrapper component. Ambiguity here is the most likely source of "the slider is broken" bug reports — a value of 5 intended as seconds but read as milliseconds produces a strobe effect. Wrap the package component in your own x-hero-slider so the unit contract lives in your codebase, not the caller's head.

Disable autoplay deliberately. Confirm how the package expresses "no autoplay" (likely 0, null, or omitting the prop) and use that for reduced-motion users and for sliders where motion is distracting. Don't rely on a very large interval as a substitute for disabling.

Livewire integration. If you drive the slider from a Livewire component, pass the interval as a public property and keep the slider container stable across renders. Re-renders that morph the DOM can leave the old timer running or reset the slide position. Use wire:ignore around the slider markup unless the slides themselves are server-driven, and key the component if slide sets change.

Pair autoplay with pause affordances. Autoplay without hover/focus pause and a visible control is an accessibility failure. If the package doesn't pause on hover/focus out of the box, handle it in your wrapper's JS and add a play/pause button.

Test the configuration surface, not the animation. In PHP tests, assert the rendered output carries the expected interval value (attribute, data property, or config injection). Don't try to assert visual transitions in PHPUnit/Pest; leave that to a browser test if you need it at all.

Multiple sliders per page. Give each instance a unique key/id and set intervals independently. Shared JS initializers that target a generic class selector will bind the wrong interval to the wrong slider.

Gotchas and Tips

• Pre-1.0 churn. With a 0.0.x version line, expect prop names, config keys, and view structure to change without a major bump. Pin the version, read every changelog entry, and keep your wrapper component thin so upgrades touch one file.
• Config caching. Published config is cached in production. After changing the default interval, php artisan config:clear (or redeploy with a fresh cache) — otherwise your change silently does nothing.
• Timer leakage across navigations. If the package uses setInterval without teardown, Turbo/Livewire navigation can accumulate timers. Watch for sliders that speed up after a few page transitions; the fix is usually re-initializing on livewire:navigated or scoping the slider to wire:ignore.
• Interval of zero. Verify explicitly whether 0 disables autoplay or is coerced into an immediate loop. Test it rather than assuming.
• Reduced motion. Honor prefers-reduced-motion by defaulting to autoplay-off. Retrofitting this after launch is harder than making it the default path.
• Debugging. Inspect the rendered HTML for the interval attribute/data value before touching JavaScript; if the value isn't in the DOM, the problem is server-side config resolution, not the front-end. Use the browser devtools to confirm only one timer is active per slider.
• Extension points. The published views are your escape hatch for markup and control changes the package doesn't expose. Prefer overriding views over forking, and keep a note of which views you've published so upgrades don't silently revert your customizations.
• Performance. Autoplay plus eager-loaded slide images is a common LCP regression. Lazy-load non-first slides regardless of what the package does by default.