import { CSSResultGroup, PropertyValues } from "lit"; import { SigveloElement } from "@mcp-b/wc-support/base/sigvelo-element"; //#region src/components/search-list/search-list.d.ts /** * * * @summary Queries a collection of items based on their content and keywords. * @tag sigvelo-search-list * @documentation https://design-system.sigvelo.com/docs/components/search-list * @status stable * @since 1.0 * * @slot - One or more elements to be searched. Each element must be a direct descendent of the host, i.e. do not wrap * items in other containers. If desired, you can apply flex and grid styles to the `items` part to control how items * appear in the list. By default, items will be displayed in a flex column. * @slot controller - A `` or `` element that will control the search list. * @slot initial - Optional content to display when no search query has been entered. * @slot empty - Optional content to display when the search yields no results. * * @csspart items - The container that wraps the slotted items. Displays as a flex column by default. * * @cssstate empty - Applied when a query is entered and no matching results are found. * @cssstate initial - Applied when the query is empty and the `initial` slot is showing. * * @example Default * Search Lists provide real-time filtering of on-page content as the user types, supporting exact or fuzzy matching, custom keywords, and customizable empty states. The component works with just about any type of content and can be customized with different layouts and styling. * * ```html * * * * * * * * * *
*

Meowy McGee

*
Freedom's just another word for nothing left to lose.
*
* * * * * * * *
*

Wonder Whiskers

*
Living my best nine lives, one nap at a time.
*
* * * * * * * *
*

Maine Attraction

*
Big fluff, bigger personality.
*
* * * * * * * *
*

Sir Pounce-a-lot

*
Professional sunbeam chaser and nap enthusiast.
*
* * * * * * * * *

No matching results

* * * * * ``` * * @example Providing a controller and items * Every search list must have a search box, or _controller_, that maintains the query. Controllers can be `` or native `` elements. To link a controller, place it in the search list's `controller` slot or assign an external one. Make sure to add a label and description to ensure it's accessible. * * Searchable items can be just about any element, but they _must_ be direct descendants of the `` element. By default, an item's text content will be used to determine a match, but you can also specify keywords. A case-insensitive search is performed by default, but basic fuzzy matching and custom matching are also available. * * As the user types in the controller, the search list will update and show the matching results. When no query is entered, all items are shown. An optional empty state can be provided to show a custom message when a query is entered and no matches are found. * * A minimal implementation looks something like this. Note the use of `label` and `description`, which are important for accessibility. * * ```html * * * * * *
Item 1
*
Item 2
*
Item 3
* * ``` * * Here's an example using a native `` element. * * ```html * * * * * * *
Item 1
*
Item 2
*
Item 3
* * ``` * * Items aren't given any styles by the component — that part is up to you! The item's container, however, is styled as a flex column container by default. To change the layout, apply the desired CSS using the `::part(items)` selector. Both flex and grid layouts work really well here. * * Here is the example from above, modified with example styles. * * ```html * * * *
Item 1
*
Item 2
*
Item 3
* * * * ``` * * **Note:** Search lists are designed to listen for user input dispatched by their controllers. As such, canceling the controller's `input` event or programmatically modifying its value will cause the search list to get out of sync. In that case, you can use the `setQuery()` method to programmatically update the search list. * * @example Fuzzy matching * By default, the search list shows results based on case-insensitive, exact matches. For a more permissive search, add `match="fuzzy"` which is more forgiving to typos. * * ```html * * * * * * * *
Luna
*
Oliver
*
Bella
*
Whiskers
*
Maple
*
Sushi
*
Pepper
*
Mittens
*
Shadow
*
Oreo
*
Mochi
*
Nova
*
Tiger
*
Ziggy
* * * * ``` * * **Note:** For even more control over the matching algorithm, you can specific a [custom match function](#using-a-custom-match-function). * * @example Adding keywords * Add the `data-keywords` attribute to any item to include additional keywords the search list should match by. This is useful for adding terms you'd like the item to match on even when the term doesn't appear in regular content. * * ```html * * * * * * * * An orange kitten meows while perched on a stone wall * A multicolored cat walking through the grass stops to look at the camera * A white fluffy kitten lays comfortably on the arm of a chair * A gray tabby lays in a bed and looks out past the camera * A black and white kitten lays on its bed and looks at the camera * A young gray tabby lays on the steps and yawns * A multi-colored kitten poses for a picture * A young tabby rests its eyes while playfully putting its paw up * A brown cat looks up at the camera * * * * ``` * * @example Providing an initial state * To change what users see before they enter a query, use the `initial` slot. When provided, this content will appear instead of the items when no query is entered. Once the user starts typing, the matching items or the empty state will be shown. * * ```html * * * * * * * * * *

Ready to Meet Some Cats?

*

Start typing to discover our adorable cats

* * * * * *
*

Meowy McGee

*
Freedom's just another word for nothing left to lose.
*
* * * * * * * *
*

Wonder Whiskers

*
Living my best nine lives, one nap at a time.
*
* * * * * * * *
*

Maine Attraction

*
Big fluff, bigger personality.
*
* * * * * * * *
*

Sir Pounce-a-lot

*
Professional sunbeam chaser and nap enthusiast.
*
* * * * * * * * *

No Cats Found

*

Try different search terms to find your match

* * * * * ``` * * **Note:** The initial state will only be shown when the `initial` slot is provided and no query has been entered. * * @example Providing an empty state * An optional empty state will be shown when no results are found. Use the `empty` slot to add text, icons, or illustrations to it. Empty state content is not styled by the component, so feel free to bring your own look to it. * * ```html * * * * * * * *
Luna
*
Oliver
*
Bella
*
Whiskers
*
Maple
*
Sushi
*
Pepper
*
Mittens
*
Shadow
*
Oreo
*
Mochi
*
Nova
*
Tiger
*
Ziggy
* * * * * No matching results * * * * * ``` * * @example Using a custom match function * For more control over the matching algorithm, set the `match` attribute to `custom` and provide a callback using the `isMatch` property. The function runs on each item whenever the search query changes. * * The callback receives three arguments: `query` (the current search term), `content` (the element's searchable content, including its `textContent` and `data-keywords`), and `el` (a reference to the element being searched). Return `true` if the element is a match and `false` otherwise. * * ```html * * * * * * * *
*

Luna

*

Sweet and friendly, loves window watching

*
* *
*

Oliver

*

Adventurous explorer, loves the garden

*
* *
*

Milo

*

Gentle soul who loves napping in sunbeams

*
* *
*

Bella

*

Free spirit, enjoys climbing trees

*
* *
*

Charlie

*

Playful cat who chases laser pointers

*
* *
*

Lucy

*

Independent nature lover, great hunter

*
* * * * *

No cats match your search

*

Try searching by name or using the @indoor or @outdoor tags

* * * * * * * ``` * * @example Using an external controller * In some cases, the controller might need to exist outside of the component. In this case, give the controller an ID and set the search list's `controller` attribute to match. * * ```html * * * *
Item 1
*
Item 2
*
Item 3
* * * * ``` * * **Note:** When using an external controller, make sure the position of it makes sense in reference to the search list. It should usually come immediately before the search list to ensure all users can interact with it properly. */ declare class SigveloSearchList extends SigveloElement { static observeSlots: boolean; static styles: CSSResultGroup; /** * Items are whatever the consumer slotted in — "just about any element", including SVG. That rules out anything * `HTMLElement`-only when filtering them: `dataset` and `hidden` both exist on `HTMLElement` but not on `Element`, * and writing `hidden` on an SVG item only creates a dead expando. Filtering goes through the `data-keywords` and * `hidden` content attributes instead, which every element carries, and the stylesheet hides the marked ones. */ private items; private debounceTimeout; private localize; private resultsTimeout; results: HTMLElement; query: string; /** * Whether any slotted item survived the current filter. Not the `empty` state — that one also needs a query. * Public like its siblings because Lit keys `changedProperties` on `keyof this`, which excludes private members. */ hasVisibleItems: boolean; isInitial: boolean; resultsMessage: string; /** * In most cases, you should slot the controller into the `controller` slot. However, when the controller must exist * outside the search list, you can set this property to the ID of an external `` or `` * element instead. */ controller: string; /** * The search behavior to use when finding a matching item. The `exact` search is case-insensitive but requires an * exact match. The `fuzzy` search is more forgiving to typos. When using `custom`, you can set the `isMatch` property * to a custom function to determine if the provided query matches the element's content. */ match: "exact" | "fuzzy" | "custom"; /** The time in milliseconds to use for debouncing the search results while the user types. */ debounce: number; /** * A custom search function you can provide to change the search behavior. The function is applied to each item when * the search query changes. The `query` argument is the current search term, `content` is a string containing the * element's searchable content, including its `textContent` and `data-keywords"`, and `el` is the element being * searched. Property only. */ isMatch: (query: string, content: string, el: Element) => boolean; connectedCallback(): void; disconnectedCallback(): void; updated(changedProperties: PropertyValues): void; /** Gets the controller or returns `null` if one can't be found. */ private getController; private handleDefaultSlotChange; private handleControllerSlotChange; /** Updates results when the controller's value changes. */ private handleControllerInput; /** Listens to all `input` events on the document and responds only to controller events. */ private handleDocumentInput; private updateResults; /** Sets the search query and updates the results. To clear the search, set this to an empty string. */ setQuery(searchQuery?: string): void; render(): import("lit-html").TemplateResult<1>; } declare global { interface HTMLElementTagNameMap { "sigvelo-search-list": SigveloSearchList; } } //#endregion export { SigveloSearchList as t };