Promo Bar Statamic Laravel Package

Getting Started

This is a small patch release (v1.1.1) with three bug fixes: no-JS phone rendering, stacked-bar view counting, and keyboard-focus retention across responsive resizes. There are no breaking changes, no new config keys, and no migrations implied. Upgrading is a composer update away, but the fixes change observable behavior on phones, so re-check your mobile rendering and analytics after upgrading.

Minimal steps:

1. composer update vendor/package — Laravel auto-discovery handles the service provider.
2. Publish what you need: php artisan vendor:publish --tag=package-config (and --tag=package-views / --tag=package-migrations if you have not already). Run php artisan migrate if the views table is new to your app.
3. Render the bars once in your layout — typically a Blade component (<x-bars />) or an include placed just before </body>.
4. Render one bar first: a top announcement with a CTA, an activation window, and a device scope. Load the page, then narrow the window below the phone breakpoint with JavaScript disabled to confirm the v1.1.1 fix — you should now see the first eligible bar instead of nothing.

Where to look first:

• The published config — bar definitions, ordering, rotation interval, and the phone breakpoint. Ordering is now behaviorally significant (see Gotchas).
• The Blade view — the markup that gets rendered, including the wrapper classes the resize/focus logic keys off.
• The views migration/table — how an impression is recorded, and whether it is server-side or a JS beacon.
• The JS entry point — rotation, stacking, view reporting, and the new focus-restoration handler.

Implementation Patterns

Single render point. Render the bars component exactly once, in your base layout. Duplicating it across layouts (e.g. a separate auth layout and app layout) double-counts views and can stack the same bar twice.

Ordering is the no-JS contract. With JavaScript off on a phone, only the first eligible bar is shown. Treat config order as the fallback priority: the bar you most want phone users to see goes first. If you use rotation, remember there is no rotation without JS, so a rotating set must still make sense when only its first member is visible.

Stacked vs. rotating. Stacked bars now count a view only for the bar actually shown, not the ones collapsed below it. That means your impressions report is finally comparable between mobile and desktop. If you were compensating for the old over-counting in dashboards or exports, remove that fudge factor.

Targeting and segments. Scope bars by device, audience, route, or date window. Because the phone fallback picks the first eligible bar, an expired or out-of-scope first bar correctly yields to the next one — worth a test if your bars are heavily scheduled.

Layout integration. Place the component outside any v-if/@auth block that would re-mount it on navigation; in Inertia or Livewire apps the component can re-render on every visit, inflating counts. Mount it on a persistent layout element, or gate the view beacon to full page loads.

Testing. A feature test asserting the rendered markup and the resulting row in the views table covers the counting regression. For the focus fix, a browser test (Dusk/Pest browser) that focuses a control inside a bar, resizes past the phone breakpoint, and asserts document.activeElement moves to the still-visible bar — or to the first focusable element after the bars — is the direct check for v1.1.1.

Gotchas and Tips

• No-JS is now "first bar only," not "nothing." Audit any CSS or layout that assumed the bar container would be empty without JS; the container now has content and height on phones.
• View counts are per shown bar. Don't compute impressions by counting rendered bar nodes in the DOM — hidden stacked bars are in the markup but are not counted. Use the recorded rows.
• Rotation is a JS feature. Critical messaging (downtime, legal notices) should not live only in a rotating slot; on a no-JS phone, only the first bar exists.
• Focus moves on resize. v1.1.1 relocates focus when the bar containing it is hidden, or sends it to the first thing after the bars. If you have custom focus management (modals, skip links) near the top of the page, verify it still behaves when a tablet is rotated mid-interaction while a bar link is focused.
• Breakpoint mismatch. The phone breakpoint in config and the breakpoint in your CSS must agree. If CSS hides a bar at a width the package still considers visible, you can record a view for something the user never saw.
• Full-page caching suppresses counts. If the bars are rendered from cache, the server-side counter never fires. Either exclude pages from the cache or ensure the beacon path is used; verify after upgrading that your counts did not silently drop.
• Debugging checklist for the three fixes: disable JS and load on a narrow viewport (fix 1); inspect the views rows for stacked bars rather than the DOM (fix 2); focus a link inside a bar, rotate/resize with the keyboard, and watch document.activeElement (fix 3).
• Extension points. Custom bar views, the view-recording listener/event, and the config scopes are the natural seams — prefer overriding the published view or listening to the recorded event over forking the resize/focus script, which is the part most likely to churn in future patches.