New Here Laravel Package

Getting Started

This is a UI-layer package: it adds guided "tours"/spotlight hints on top of your existing Blade views. The release notes for v1.1.5 describe the package's focus mode — a blurred page with one highlighted element and an anchored hint — so expect the day-to-day work to be mostly markup and step definitions, not backend plumbing.

1. Install and publish:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   php artisan vendor:publish --tag=<package>-assets
   

2. Look first at the published config (defaults for overlay blur, dismiss behaviour, storage driver for "tour completed" state) and then at the package's example tour definition — that file is the best documentation of the step schema.
3. Make the front end load the package's JS/CSS once, usually via a Blade directive in your layout or a Vite entry.
4. Define your first tour as data (PHP array or a tour class): an ordered list of steps, each with a CSS selector for the target element and the hint content.
5. Tag the DOM: give target elements stable selectors, e.g. data-tour="reports-export" rather than relying on Tailwind class chains that churn.

First real use case: a 4–5 step onboarding tour on the dashboard that highlights navigation, the primary action button, and the account menu, then persists completion against the user so it never shows twice.

Implementation Patterns

Steps as data, targets as attributes. Keep tour definitions in a dedicated class or config file so the same tour can be triggered from a controller, a Blade view, or an event listener. Prefer explicit data-tour attributes over structural selectors; they survive redesigns and make the step list greppable.

Per-user completion state. Almost every team ends up with a tour_completions table or a JSON column on users (tours_completed, onboarding_step). Pass the resolved "which tours are still pending" set into the view from a middleware or view composer, then let the front end fire only those. Do not rely on localStorage alone if you care about users switching devices.

Conditional and feature-flagged steps. Filter the step array server-side — hide the billing step from users without a subscription, hide the admin step from non-admins. Filtering server-side avoids shipping hints that point at elements that were never rendered (which is exactly the failure mode v1.1.5 fixed for off-screen elements).

Triggering. Two reliable patterns: (a) auto-start on page load when a pending tour matches the current route name; (b) programmatic start after a meaningful action ("your import finished — here's where the file lives"). For (b), dispatch a browser event from your controller's redirect flash data and let a small listener call the package's start method. This keeps step definitions out of controllers.

Livewire / Inertia / SPA stacks. The package targets DOM nodes, so any framework that swaps DOM needs the tour re-initialised after the render. In Livewire, start the tour from $this->dispatch(...) inside updated()/mounted() hooks; with Inertia, call the start method in the page component's mounted lifecycle. Avoid starting a tour mid-transition — wait for the morph to settle, otherwise the selector resolves to the old node.

Testing. Add one Pest/Dusk (or Laravel Browser) smoke test that loads the page with a pending tour and asserts the hint text is present and dismissible. That single test catches most regressions from package upgrades, which is what this release is.

Gotchas and Tips

• Pin ^1.1.5 if you have wide tables or horizontally scrollable panels. Before this release, a step targeting a column at the far right of a wide table opened its hint outside the viewport while the overlay stayed up — the page was blurred, inert, and had no visible dismiss control. That is a hard lock-up for the user, not a cosmetic bug. Upgrade and re-run your widest-table tour.
• Click-to-dismiss is now possible everywhere. The blurred overlay now closes the hint like Escape. If you had a step you treated as mandatory (e.g. forcing the user to acknowledge something), you can no longer assume the user must press your button. Either persist acknowledgement server-side on the button action only, or re-open the step on the next visit if the acknowledgement is missing. Don't infer completion from "the overlay disappeared".
• Focus mode lifts when the element scrolls away. This is intentional (it prevents the invisible-hint deadlock), but it means a step's hint can vanish while the user scrolls to read a long list. Keep step copy short, or anchor steps to elements near the top of their container.
• Scroll-into-view is not instant. If you programmatically advance steps in quick succession, the scroll animation and the focus-mode restore can overlap and land the hint on stale coordinates. Debounce step advancement or await the package's transition/after-step callback rather than chaining synchronously.
• Debugging invisible hints usually comes down to: target element inside a transform/filter ancestor (creates a containing block and breaks fixed-position hint anchoring), overflow: hidden clipping the target, or a z-index war with your modal/toast layer. Temporarily disable the overlay blur in config to see whether the highlight geometry or the hint positioning is wrong.
• Elements that don't exist yet. A selector that resolves to nothing silently produces a broken step. Validate step targets at definition time in a test, and prefer filtering out steps whose elements are conditionally rendered.
• Extension points worth knowing: the config's blur/dismiss options, the hint renderer/theme hook (use it to match your design system rather than overriding CSS by selector), and the step lifecycle callbacks (use onNext/completion to write progress to your backend instead of localStorage).
• Upgrade hygiene. Releases in the 1.1.x line are behavioural fixes in the front-end layer; they won't break your PHP tests but will change what users see. Keep one browser-level test per tour and check the changelog against the tours that target scrollable regions.