Components Laravel Package

Getting Started

• Install the package with Composer and follow the README’s publish/config steps. For 2.2.0, start by confirming your Tailwind 4 setup and the package’s documented component paths.
• Set the footer owner value via the app.owner config key. If the footer renders empty, this is the first thing to check.
• Ensure your Tailwind theme defines the required primary, info, success, and danger color scales. The package components depend on these tokens.
• Make sure Tailwind scans the package Blade views, or use the documented Tailwind 4 @source/content configuration, so component classes are generated.
• First practical use case: build a dashboard page with <x-card>, <x-widget>, <x-descriptionList.item>, <x-links.internal>, <x-sidebar.item>, and the table/form components. Pass declared props explicitly and use slots for content.

Implementation Patterns

• Treat the package as a Blade UI kit: compose pages from cards, widgets, description lists, links, sidebars, tables, and forms rather than recreating markup.
• Pass component props in the documented way. For example, use the title prop on cards and the route prop on internal links; do not expect those values to appear as HTML attributes in the rendered DOM.
• Use slots for rich content inside cards, widgets, and list items. Keep structural markup in the package and put page-specific content in slots.
• Use active on sidebar items for navigation state. Since active is now a declared prop, style/state should come from the component’s rendered classes, not from an active HTML attribute.
• For internal navigation, prefer the package’s route prop so route generation stays consistent. For external links, use the package’s external-link component and pass the URL through its documented prop.
• Set app.owner once in configuration and let the footer consume it. This keeps ownership/branding consistent across layouts.
• With Tailwind 4, define the required color scales in your CSS theme and verify the generated CSS includes the package’s component classes. If you use a custom design system, map primary, info, success, and danger to your existing tokens.
• Heroicons are bundled with the package; use the package’s icon component/API instead of adding a separate Heroicons dependency unless you need icons outside the package.
• For delete confirmations, rely on the package’s form/button behavior. The redundant form.submit() was removed, so avoid adding JavaScript that assumes a double-submit path.
• If you need app-specific markup, publish and override the package views sparingly. Prefer wrapping package components over forking them, so upgrades remain manageable.

Gotchas and Tips

• Behavioral change in 2.2.0: card.card, widget, descriptionList.item, links.external, links.internal, and sidebar.item now declare their props, so values like title, route, icon, and active are no longer emitted as HTML attributes. Audit custom CSS, JavaScript selectors, tooltips, and tests that relied on those attributes.
• A card title previously rendered as an HTML title attribute and could appear as a browser tooltip. If you need a tooltip now, add it deliberately on an inner element or wrapper rather than relying on the card prop.
• Use data-* attributes for JavaScript hooks. Declared props will not fall through to the DOM, but non-prop attributes generally still can.
• Missing primary, info, success, or danger color scales in Tailwind 4 can leave components partially unstyled or produce missing utility classes. Check the compiled CSS after setup and after upgrading.
• If component styles are missing, verify Tailwind is scanning the vendor package views. In Tailwind 4 this often means adding the package view path via @source or the equivalent documented content configuration.
• After publishing views or upgrading, run php artisan view:clear and inspect the rendered HTML. The new render tests in the package reduce regressions, but app-level snapshot or DOM assertions are still useful around customized components.
• The footer depends on app.owner; if it is unset, expect blank or incomplete footer output. Set it in config rather than hard-coding owner text in layouts.
• The table footer now closes with @endisset; this is an internal fix, but re-check custom published table views if you maintain overrides.
• The delete confirmation button no longer calls form.submit() redundantly. If you have custom JavaScript around delete buttons, confirm it still submits exactly once and does not depend on the old behavior.
• When overriding published views, track upstream changes between releases. Component prop declarations and Tailwind class changes are easy to miss in a fork.
• Use the package’s render tests as a signal of quality, but still do a visual pass on cards, links, sidebars, tables, forms, and the footer after upgrading from 2.1.x.