Wire Table Laravel Package

Getting Started

This package owns scroll positioning (scrollTo) behaviour and, since v2.2.0, accepts custom scroll targets rather than only a fixed default selector. v2.2.1 is a patch release that fixes missing nested configuration values not being loaded from the package defaults — no API changes, but it does change what your config file resolves to, so re-verify your config after upgrading.

Minimal steps:

1. Install (or upgrade) and publish any config/assets:

   composer require <vendor>/<package>   # or: composer update <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Check the service provider registration (Laravel auto-discovery usually handles it; verify in bootstrap/providers.php for Laravel 11+ or config/app.php for older apps).
3. Look first at the package's config file and its Blade directive/component or JS entry point — that is where scrollTo targets are resolved. On v2.2.1, diff your published config against the package's config/ original: nested keys you never declared now correctly fall back to defaults, so the effective config may differ from what you saw on v2.2.0.
4. First use case: wire up a single in-page anchor (e.g. a "Back to top" button or a table-of-contents link) using the default target, confirm the scroll fires, then swap in a custom target to exercise the v2.2.0 capability.
5. After upgrading to v2.2.1, run php artisan config:clear (and config:cache on deploy) before testing — a cached config from 2.2.0 will mask the fix entirely.

Keep the first integration to one page and one target before rolling it out globally.

Implementation Patterns

Default target (pre-2.2.0 behaviour). Existing code that relied on the implicit selector keeps working; nothing needs to change on upgrade. Treat this as your baseline smoke test after composer update.

Custom scrollTo targets (v2.2.0+). Pass an explicit target instead of relying on the default. Typical shapes you will encounter:

{{-- Blade component / directive style --}}
<x-scroll-to target="#pricing" />

// Config- or runtime-driven targets
'scroll_to' => [
    'default' => '#top',
    'targets' => [
        'pricing' => '#pricing',
        'faq'     => '#faq',
    ],
],

// Client-side usage
scrollTo({ target: document.querySelector('#pricing') });

Partial config overrides (now reliable on v2.2.1). Because nested values fall back to the package defaults, you can publish the config and declare only the branches you care about — e.g. set scroll_to.targets.pricing and leave the rest unset. On v2.2.0 an undeclared nested branch could resolve as missing rather than defaulted; if you worked around that by duplicating the whole default tree into your config, consider trimming it back to just your overrides so future package defaults still reach you.

Per-page target maps. Define named targets in config and reference them by key in views. This keeps selectors out of templates and makes it trivial to re-point a CTA without touching Blade files — the clearest day-to-day win from v2.2.0.

Dynamic targets from data. For CMS-driven pages or multi-step forms, resolve the target from a model attribute or request parameter and pass it through. Validate the value against an allow-list of known targets to avoid arbitrary selector injection.

Integration with navigation. Combine with request()->routeIs(...) checks or a @php $scrollTarget = ... @endphp block to auto-scroll to the active section on page load, and use the same target map for both server-rendered anchors and client-side handlers so there is one source of truth.

Progressive enhancement. Render real href="#section" anchors and let the package take over on click. Users without JS, and crawlers, still get working navigation.

Regression guard for config resolution. Add a small test that asserts your resolved config contains the expected nested defaults and your overrides — this is precisely the class of bug v2.2.1 fixes, and it will catch the next regression in config merging before it reaches a page.

Gotchas and Tips

• Nested config merging (the v2.2.1 fix). Laravel's mergeConfigFrom() is a shallow merge at the top level; nested arrays are replaced wholesale unless the package merges them explicitly. v2.2.1 fixes exactly this — missing nested values now load from the package defaults. If you were on v2.2.0 and saw null/missing values for keys you never declared, upgrading should resolve it; if you papered over it by hardcoding the full default tree, re-test before deleting those workarounds.
• Cached config hides the fix. php artisan config:cache bakes the merged array at deploy time. Clear and rebuild it as part of the upgrade, or you will "test" the old broken merge and conclude the patch did nothing.
• Selector vs. element. "Custom targets" may accept a CSS selector string, a DOM element, or a named key — these are not interchangeable. Read the release's signature and the package source (src/ and any published JS) before assuming. Passing an element where a string is expected (or vice versa) fails silently in most scroll implementations.
• Timing. Scroll calls fired before the target exists in the DOM (lazy-loaded sections, modals, Livewire/Alpine re-renders) will no-op. Defer with $nextTick, Livewire.hook('morph.updated', ...), or a DOMContentLoaded guard.
• Fixed headers. Custom targets scroll the element to the top of the viewport, which usually hides the first line behind a sticky navbar. Keep a scroll-margin-top (or the package's offset option, if present) on target elements.
• Stale asset caches. After upgrading, clear compiled views and asset caches — php artisan view:clear && php artisan config:clear — otherwise the old JS bundle without custom-target support keeps being served. Check public/vendor/<package>/ for a republished asset.
• Validation and escaping. Sanitise any target value that originates from user input or the database. A selector is injected into querySelector; unvalidated values can throw and break the whole scroll handler.
• Accessibility. Respect prefers-reduced-motion and move focus to the target (tabindex="-1" + .focus()) so keyboard users land where the viewport did.
• Testing. Assert on the emitted attribute/markup rather than actual scrolling (JSDOM does not scroll). A Feature test checking the rendered data-scroll-target is the cheapest regression guard when you next upgrade; a config assertion covers the merge behaviour.
• Extension points. Prefer the published config and any documented events/hooks over patching vendor files. The v2.2.1 config-merge fix is a reminder that the config surface is still being actively corrected — pin the version in composer.json (^2.2.1) and read patch notes before bumping.