Design Laravel Kit Laravel Package

Getting Started

This package is a Blade component + asset kit (layout, navigation, form controls, SPID button, script directive). Start by publishing its config and assets, then render one page through the layout component.

1. Install and publish:

   composer require <vendor>/design-laravel-kit
   php artisan vendor:publish --tag=design-laravel-kit-config
   php artisan vendor:publish --tag=design-laravel-kit-assets
   

   (Check the README for exact tag names in v0.5.x — the PublishAssetsCommandTest change in this release confirms assets land in resources/dist and that publishing is a first-class, tested path.)
2. Put @designLaravelKitScripts in your base template just before </body> (or in the <head> if the kit documents it as deferred — the directive is now CSP-aware, so keep it as the single entry point for kit JS).
3. Wrap your first page in the layout component and verify the shell renders:

   <x-design-laravel-kit::layout title="Dashboard">
       <h1>Dashboard</h1>
   </x-design-laravel-kit::layout>
   

4. First real use case: a minimal login page. This is the exact scenario showFooter was added for in v0.5.2:

   <x-design-laravel-kit::layout :showFooter="false">
       ...
   </x-design-laravel-kit::layout>
   

Where to look first: the README's new "parametri principali" section (added in v0.5.2) — it now documents the non-trivial component APIs per component, which is faster than reading the Blade source. Then config/design-laravel-kit.php for CSP and global defaults, then the URL policy document before you pass any user-supplied URL into a component.

Implementation Patterns

Layout as the single shell. Keep one layout invocation per page and control chrome through props rather than duplicating templates. showFooter (default true) is the escape hatch for auth screens, print views, and embedded/iframe pages. If you need several flavours, wrap it in your own component with your defaults baked in and let callers override only what matters.

Select options: prefer the slot. v0.5.2 adds slot-based options, which is the Blade-idiomatic path and keeps markup readable:

<x-design-laravel-kit::select name="status" :placeholderDisabled="false">
    <option value="">Tutti</option>
    <option value="open">Aperto</option>
    <option value="closed">Chiuso</option>
</x-design-laravel-kit::select>

Use :placeholderDisabled="false" specifically for filter forms, where the empty option is a meaningful choice ("all"). Leave the default (true) on required create/edit forms so users can't submit an empty selection.

CSP: configure the nonce once, not per call. Choose one of the two supported mechanisms:

// config/design-laravel-kit.php
'csp_nonce' => null, // or wire to your CSP generator

or pass it inline when the nonce is request-scoped and you generate it in middleware:

@designLaravelKitScripts($nonce)

The inline argument wins for per-request nonces; the config value is the right choice when you have a single global policy source. Don't do both — you'll get confused about which one is actually being applied.

Navigation and megamenu. Megamenu detection is now explicit (v0.5.2 replaced HTML str_contains sniffing with a flag). Mark megamenu items with the documented flag/attribute rather than relying on class names or label text. If you have a menu item whose label or markup happens to contain dropdown megamenu, this release is why it should now render as a normal item — verify it after upgrading.

SPID button. Build the provider list as structured data (each entry needs at least name and url). Invalid entries now throw an explicit exception. Prefer sourcing providers from config or a service class and asserting the shape in a test, so a missing url fails in CI rather than in production at render time.

Testing integration. The package now isolates its asset-publishing tests from the real resources/dist, so you can run php artisan test in a package/app without side effects. Mirror that pattern in your own tests: assert rendered component output rather than filesystem state, and snapshot a layout with showFooter=false plus a filter select with placeholderDisabled=false as your two regression cases.

Gotchas and Tips

• showFooter is a footer toggle, not a full layout mode. It hides the footer only; header/nav/container behaviour is unchanged. For truly minimal layouts you may still need to skip the layout component entirely.
• placeholderDisabled defaults to true. If you're migrating filter forms from 0.4, your "all" option may now be unselectable. Audit every filter select after upgrading — this is a silent behaviour difference, not an error.
• Nonce order of precedence. The directive argument beats csp_nonce in config. If scripts are silently blocked under a strict policy, first check whether a stale config value is winning, then inspect the emitted <script> tags for the nonce attribute.
• URL policy is enforced, and the docs were expanded in 0.5.2. Read the scheme allow/deny list before passing dynamic URLs (javascript:, data:, protocol-relative). Don't assume a value that rendered fine in 0.4 will still pass in 0.5 — the migration notes flag validation as the 0.4 → 0.5 change to review.
• SPID validation throws. Wrap provider-list construction where the data is remote/config-driven, and surface the exception as a config error rather than catching and swallowing it — the whole point of the change is a clear failure.
• Megamenu false positives are gone, but your CSS may not be. If you had styled a menu item that accidentally matched the old str_contains heuristic, it will now render as a standard dropdown. Check nav styling after the bump.
• Publishing assets is destructive-ish. The rewritten PublishAssetsCommandTest deliberately avoids touching the real resources/dist; your CI shouldn't either. Publish to a temp path in tests, and never run asset publishing against a directory with hand-edited files.
• Extension points: the config file (global defaults, CSP) and the Blade component slots/props are the stable surface. Avoid subclassing components or copying their markup — the megamenu and select internals both changed within a minor release, which is a fair signal that internals aren't API.
• Minor version, but read the migration section. 0.5.2 is additive, yet it lands on top of 0.5's URL-validation changes; if you're coming from 0.4, treat the whole 0.4 → 0.5 step as a review item, not a patch bump.