Drawer Laravel Package

Getting Started

• Install with composer require mrshanebarron/drawer and confirm auto-discovery — check php artisan about or bootstrap/cache/packages.php. If the provider is not listed there, nothing else will work.
• Publish the config and any views/assets in one pass: php artisan vendor:publish --provider="MrShaneBarron\Drawer\DrawerServiceProvider" (or --tag=sb-config if a tag is registered). Since v1.0.1 the published file uses the sb- prefix — expect config/sb-drawer.php, not config/drawer.php.
• Look at the config file first, not the README. It tells you the config key namespace (config('sb-drawer.*')), the default position/size/overlay settings, and the component class names the package exposes. The README may still reference a pre-1.0.1 filename.
• Then look at the published Blade components (typically under resources/views/vendor/drawer/ or the package's resources/views/components/). This is the package's entire API surface — there is no service class to resolve or driver to configure, so reading the component is reading the documentation.
• First use case: a single static drawer in one Blade view. Drop it into a layout, add a trigger button, load the page, and confirm the overlay, position, and close behavior. That single render verifies provider registration, view namespace resolution, config defaults, and asset publishing all at once.
• Only after that, wire it into a real spot — a mobile nav in layouts/app.blade.php, or a filter panel on an index page.

Implementation Patterns

• Trigger and target are separate. The conventional pattern is a trigger element (button with a data- attribute or a dedicated component) that targets a drawer by id. Give every drawer on a page a unique id and keep the trigger next to it in the same partial so they move together. Orphaned IDs are the #1 source of "the drawer doesn't open."
• Slot composition over content arguments. Use named slots for header, body, and footer rather than passing HTML through a prop. That keeps the markup diffable in Blade and lets you swap the header per instance (e.g., a title plus a close button for nav, a title plus a "clear filters" link for filters).
• One partial per drawer, included where it belongs. resources/views/components/drawers/cart.blade.php (or partials/drawers/cart.blade.php) that takes only the slots it needs. Include it in the layout for persistent drawers (nav, cart) and in a specific view for page-local ones (filters, row details).
• Config for defaults, props for per-instance overrides. Set position (right/left), size, and overlay behavior in config/sb-drawer.php as the app-wide default. Override per drawer via props on the component (<x-drawer position="left" size="lg" …>). Never edit the component source to change a default — you'll lose it on the next vendor:publish --force.
• Multiple drawers per page is the normal case. Nav (left) + cart (right) + filters (right) is a realistic layout. Plan z-index and body-scroll-lock stacking before you ship the third one; a second drawer opening on top of the first is the first thing that breaks.
• Livewire/Alpine integration. Wrap the trigger in your own Alpine directive if you need programmatic open/close ($dispatch('open-drawer', { id: 'cart' }) and a listener inside a small wrapper). Don't fork the package component — put the wrapper in your app and let the package handle markup.
• Testing. Blade component tests are the right level: $this->blade('<x-drawer id="cart" position="left"><x-slot:header>Cart</x-slot:header>Body</x-drawer>') and assert assertSee('cart', false), the position class, and that the slot contents render. Add one smoke test per drawer in your layout so a broken publish is caught in CI rather than in staging.
• Styling hooks. Target the package's generated class names (or the id) from your own CSS layer rather than editing the published Blade. If the package ships Tailwind classes, ensure your content config scans the published view path (./resources/views/vendor/drawer/**/*.blade.php) or those classes will be purged.
• Deployment. Add the published config and views to version control so the diff is reviewable. Run php artisan view:clear && php artisan config:clear in the deploy pipeline; a cached config built before the sb- file was published will silently fall back to package defaults.

Gotchas and Tips

• The v1.0.1 rename is the one to know about. If you published under the pre-1.0.1 filename, the package will not read it. On upgrade, git mv your customized config to config/sb-drawer.php rather than re-publishing — vendor:publish will not overwrite, so you'll end up with both files and only one of them being read. Then php artisan config:clear.
• Filename vs key namespace. The file is sb-drawer.php; keys are read as config('sb-drawer.position'). A typo in either half returns null with no error and the component silently uses its built-in default. Assert your config values in tinker (config('sb-drawer')) early rather than debugging styling later.
• vendor:publish never overwrites. After every upgrade, run ls resources/views/vendor | grep drawer and ls config | grep sb-. A re-publish leaves your old customized file in place and the new one absent — so a component fix ships to the package but never reaches your app.
• Trigger/target ID drift. Refactoring a drawer's id without updating the trigger (or vice versa) is silent: the page renders, the button just does nothing. Grep for the ID on both sides when you rename one.
• Body scroll lock. The package almost certainly toggles a body class or overflow style when open. Nesting a drawer inside another (or opening a modal from a drawer) can leave scroll locked after close. Test close-by-overlay-click, close-by-Esc, and close-by-button separately, and check document.body classes after each.
• Overlay click-to-close on data-entry drawers. Filters and carts are fine; a settings drawer with unsaved form fields is not. Disable overlay-dismiss for those and require an explicit cancel button — otherwise a stray click discards the user's input.
• Z-index collisions with your existing nav, modals, toasts, and any datepicker/popover libraries. Decide once where drawers sit in the stack (--z-drawer: 40, overlay 39) and make everything else respect it.
• Accessibility is likely on you. Verify Esc-to-close, focus move into the drawer on open, and focus return to the trigger on close. A slide-out that traps focus in the page behind it is a real accessibility bug; if the package doesn't do it, add it in a wrapper rather than waiting for an upstream patch.
• Responsive mismatch. A left nav drawer that's great on mobile is usually wrong on desktop where the sidebar is already visible. Gate the drawer trigger with a breakpoint (md:hidden) rather than showing both.
• Pin the version ("mrshanebarron/drawer": "^1.0") and diff the published config/view stub after each release. A patch-level rename like v1.0.1 is a consumer-visible change that automated dependency tooling won't flag.
• Debugging order: (1) is the provider discovered, (2) does the view namespace resolve (<x-drawer> renders anything at all), (3) does the published config override the packaged default, (4) do the trigger and drawer IDs match. Almost every "nothing happens" report is step 1 or 4.