Support Laravel Package

Getting Started

1. Install / upgrade

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

2. Look here first (v1.1.0 changed these):
   • config/<package>.php → the global-search module configuration block (channels, terms_operator, button/result-page options).
   • The package's CSS entry index.css and the new utilities.css (published into public/vendor/<package>/ or your Vite input).
   • Any view/component you previously customised that referenced sn-* classes in index.css.
3. First use case: open the global search box, confirm results render, then wire one module to your own model and add a placeholder + explicit search button on its result page. That exercises every new v1.1.0 feature end-to-end (module config merge, term splitting, result page options) in one pass.

If you have an existing install, treat v1.1.0 as "rebuild assets + re-check search config" rather than a drop-in patch — see Gotchas.

Implementation Patterns

Module-level search configuration (preferred over global config). Because v1.1.0 unifies channel overrides per module, define search behaviour next to the module rather than in a catch-all block. Each module's channels and search options should be self-contained, so a later module addition doesn't silently inherit another module's channel list.

// config/<package>.php
'modules' => [
    'orders' => [
        'search' => [
            'channels'      => ['admin', 'api'],   // explicit per-module override
            'terms_operator'=> 'AND',              // see Gotchas: combined terms
            'placeholder'   => 'Search orders, customers, SKUs…',
            'explicit_search' => true,             // render the unified search button
        ],
    ],
],

Multi-word queries: design for terms_operator. The new term-splitting behaviour means a query like acme invoice 2024 becomes multiple terms combined by the configured operator. Two practical patterns:

• Use AND for structured lookup screens (order ID + customer), where precision matters.
• Use OR (or the package's default) for a global command-bar style search where recall matters more than precision.
• If a module needs both, expose two search entry points (a "quick jump" vs. "advanced find") pointing at the same module with different operators rather than trying to branch inside one config.

Unified search button for non-keyboard users. explicit_search (the 一体化搜索按钮) means the search is no longer purely submit-on-Enter. When enabling it:

• Ensure the button and the input live in the same form/component so the button submits the same payload as Enter.
• Keep the button disabled/aria-disabled while a request is in flight to avoid duplicate queries; the package handles rendering, not your debounce/throttle.

Result pages as first-class views. With placeholder and explicit search now supported on the result page, mirror the module's placeholder text from the header search so users see continuity. Pass the query through to the result view and re-render the input with the active term — otherwise the placeholder overwrites the visible query on back-navigation.

Integration tip — asset pipeline. Split CSS means you now import two files. If you compile package CSS through Vite rather than using published assets:

// resources/css/app.css
@import '<package>/css/utilities.css';  // sn-* utility classes
@import '<package>/css/index.css';      // entry + component styles

Import order matters: utilities first, component styles second, so component-level rules win without !important.

Gotchas and Tips

• CSS layer split is the most likely upgrade break. Any selector you added or overrode inside the published index.css may now be gone or moved to utilities.css. Diff your published copy against the new one before overwriting, and move custom sn-* overrides into your own file loaded after both package files.
• Don't edit utilities.css in place. It's the shared layer; regenerate it on upgrade. Put app-specific utility tweaks in your own stylesheet keyed to the same class names.
• Cache-bust the assets. After the split, browsers holding the old index.css will render partially unstyled components. Run your usual php artisan <package>:publish --force (or npm run build) and clear view/asset caches.
• Config merge semantics. Package-level module defaults are merged with your published config; a module that omits channels typically inherits the global channel list rather than "all channels". Be explicit in every module if channel visibility is security-relevant — this is a permission boundary, not just a UI filter.
• terms_operator + wildcards. Term splitting happens before your query builder sees the terms; %/_ inside a term will still behave as SQL wildcards unless the package escapes them. Sanitise, or wrap terms with where(fn ($q) => ...) per term, if user input reaches a raw like.
• Debugging empty search results: check (1) the module's channels includes the current guard/panel, (2) terms were split as expected (AND with a stop-word-ish term returns nothing), (3) the result page received the query parameter — a missing placeholder/explicit-search config can make the page look "broken" when it's actually just unconfigured.
• Extension points to prefer: publish and override the search result view / component, and add modules via config rather than subclassing internals. Since a minor release already reshuffled CSS and search wiring, internals are the least stable surface.
• Semver read: v1.1.0 is additive and cosmetic-leaning, but the CSS move is a de facto breaking change for anyone with published assets or selector overrides. Pin the version and test the search+styles together before rolling out.