Nova4 Multiselect Laravel Package

Getting Started

• Install the package via Composer and publish its assets/config in one pass:

  composer require <vendor>/<package>
  php artisan vendor:publish --tag=<package>-assets
  

• Look first at the package's rendered output in a scratch Blade view. Because 1.3.0 replaced the whole component style, the fastest way to build a correct mental model is to render a few representative components (a form control, a table, a modal) and inspect the resulting markup and CSS classes before touching anything else.
• Verify dark mode is wired up before styling anything custom. 1.3.0 adds dark mode support, so check how the package expects the theme to be toggled (likely a dark class on <html>, a data-theme attribute, or a Tailwind darkMode config entry) and confirm it alongside your app's existing dark-mode strategy.
• First use case: drop a single component onto a page that already has your app's layout and typography. Confirm the new style doesn't fight your global reset, then progressively add more components. Starting with one component makes it obvious whether the restyle is scoped to the package or bleeding into global styles.

Implementation Patterns

• Treat the new style as the baseline, not a skin. Since the entire component style changed, the intended workflow is to consume the package's default look and customise via its documented extension points (CSS variables, theme config, published views) rather than overriding selectors. Rebuild any bespoke overrides on top of 1.3.0's class names instead of porting the old ones.
• Drive theming through the package's theme layer. Use the published config/CSS variables for brand colours and radii so that both light and dark variants are derived from one source. Avoid hard-coding hex values in your own stylesheets — that is exactly what will break when dark mode kicks in.
• Toggle dark mode at the root, once. Implement a single theme switch (user preference + prefers-color-scheme fallback) at the layout level so every component instance responds consistently. If you persist the choice, apply it before first paint (inline script in <head>) to avoid a light-to-dark flash.
• Wrap components rather than fork them. If you need app-specific behaviour, create thin Blade/React/Vue wrappers around the package component and pass props through. This keeps the upgrade path clean when the style changes again.
• Integrate with your existing design system deliberately. If the app already ships Tailwind/Bootstrap, verify the package's CSS layer sits where you expect (and that your build includes it) so utilities you add in your own views win predictably over the package's defaults.
• Visual regression coverage pays off immediately. Snapshot key pages in both light and dark mode. A package whose style changes wholesale between minor versions is a strong argument for screenshot tests on the components you actually use.

Gotchas and Tips

• "Change whole component style" is a de facto breaking change. The version bump is 1.3.0 (minor), but any custom CSS, selector overrides, or hard-coded spacing/markup assumptions tied to the old style will break. Review your overrides before upgrading and re-test every screen that uses the package.
• Don't port old overrides forward blindly. Prefer deleting your overrides and re-applying only what's still necessary against the new defaults. Carrying legacy CSS forward is the main source of "why does this look wrong after upgrade" bugs.
• Dark mode is opt-in until proven otherwise. Confirm whether components pick up dark styling automatically (via a root class/attribute) or require per-component props. Then audit every page in dark mode — contrast issues, images/logos that only work on light backgrounds, and third-party widgets that ignore your theme are the usual offenders.
• Cache-bust your assets after upgrading. Published CSS/JS and any compiled bundles need a rebuild and a cache clear (php artisan optimize:clear, asset versioning). Stale compiled assets are a frequent cause of "the upgrade did nothing."
• Check the changelog against the source. Release notes are two lines for a change that touched every component. Diff the published views/CSS or skim the commit history to find renamed classes, removed props, or changed slots that the notes don't mention.
• Pin the version while you validate. Lock to the exact 1.3.x release in composer.json until your visual regression pass is green, then loosen the constraint.
• Extension points to prefer: published config and CSS custom properties are the stable surface; internal class names and markup structure are not. If you find yourself writing selectors that mirror the package's DOM, raise it upstream as a theming gap.