@mcp-b/web-components 0.2.0

package/dist/combobox-item-D2H1CMxC.d.ts

@@ -0,0 +1,714 @@
+import { CSSResultGroup, PropertyValues, TemplateResult } from "lit";
+import { SigveloElement, SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/combobox/combobox.d.ts
+/**
+ * <sigvelo-combobox>
+ *
+ * @summary Allows users to select from a list of options with type-ahead search.
+ * @tag sigvelo-combobox
+ * @documentation https://design-system.sigvelo.com/docs/components/combobox
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ * @dependency sigvelo-combobox-item
+ *
+ * @slot - One or more `<sigvelo-combobox-item>` elements to show as options.
+ * @slot label - The combobox's label. For plain-text labels, use the `label` attribute instead.
+ * @slot description - The combobox's description. For plain-text descriptions, use the `description` attribute instead.
+ * @slot start - An icon or similar element to place before the input. Works great with `<sigvelo-icon>`.
+ * @slot end - An icon or similar element to place after the input. Works great with `<sigvelo-icon>`.
+ *
+ * @event sigvelo-blur - Emitted when the combobox loses focus.
+ * @event sigvelo-change - Emitted when the user commits changes to the combobox's value.
+ * @event sigvelo-focus - Emitted when the combobox receives focus.
+ * @event sigvelo-input - Emitted when the combobox receives input.
+ * @event sigvelo-before-open - Emitted when the dropdown is instructed to open but before it is shown.
+ * @event sigvelo-open - Emitted when the dropdown opens.
+ * @event sigvelo-before-close - Emitted when the dropdown is instructed to close but before it is hidden.
+ * @event sigvelo-close - Emitted when the dropdown closes.
+ *
+ * @csspart label - The element that contains the combobox's label.
+ * @csspart description - The element that contains the combobox's description.
+ * @csspart visual-box - The element that wraps the internal text box.
+ * @csspart input-area - The wrapper surrounding tags and the internal text box.
+ * @csspart tag - Individual tag elements.
+ * @csspart tag-remove - The remove button for tags.
+ * @csspart text-box - The internal text box, an `<input>` element.
+ * @csspart chevron - The chevron icon, a `<sigvelo-icon>` element.
+ * @csspart chevron__svg - The chevron icon's `<svg>` part.
+ * @csspart clear-button - The clear button.
+ * @csspart dropdown - The dropdown container.
+ *
+ * @cssstate open - Applied when the dropdown is open.
+ * @cssstate disabled - Applied when the combobox is disabled.
+ * @cssstate focused - Applied when the combobox has focus.
+ * @cssstate blank - Applied when the combobox has no value.
+ * @cssstate user-valid - Applied when valid after user interaction.
+ * @cssstate user-invalid - Applied when invalid after user interaction.
+ *
+ * @cssproperty [--text-box-min-width=12ch] - The minimum width of the input field when shown next to tags. Only
+ *  available in `multiple` mode.
+ * @cssproperty [--show-duration=50ms] - The duration of the show/hide animation for the dropdown.
+ *
+ * @example Default
+ * Comboboxes implement the ARIA APG combobox pattern for roles and keyboard navigation, with enhanced screen reader announcements via ARIA live regions for improved context while navigating options.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Select a cat breed"
+ *   description="Type to search or select from the list"
+ *   placeholder="Search breeds"
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="persian">Persian</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="siamese">Siamese</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tabby">Tabby</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="ragdoll">Ragdoll</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="bengal">Bengal</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="sphynx">Sphynx</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="calico">Calico</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="russian">Russian Blue</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Labels and descriptions
+ * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the combobox. If you want to provide HTML, use the `label` and `description` slots instead.
+ *
+ * ```html
+ * <sigvelo-combobox placeholder="Type to search">
+ *   <span slot="label">Choose your <strong>purrfect</strong> companion</span>
+ *   <span slot="description">
+ *     Browse our available cats or <a href="https://example.com/" target="_blank">schedule a visit</a>.
+ *   </span>
+ *   <sigvelo-combobox-item value="luna">Luna (Tabby, 2 years)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="milo">Milo (Orange, 1 year)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="bella">Bella (Calico, 3 years)</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Providing options
+ * Create combobox options by adding `<sigvelo-combobox-item>` elements inside the combobox. Each item should have a `value` attribute that will be submitted with the form. If no value is provided, the text content is used.
+ *
+ * ```html
+ * <sigvelo-combobox label="Cat personalities" placeholder="Search personalities">
+ *   <sigvelo-combobox-item value="playful">Playful and Energetic</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="cuddly">Cuddly Lap Cat</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="independent">Independent Spirit</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="social">Social Butterfly</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="curious">Curious Explorer</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * Combobox items can have structured content with icons and details.
+ *
+ * ```html
+ * <sigvelo-combobox label="Adoption status" placeholder="Filter by status" id="combobox__structured">
+ *   <sigvelo-combobox-item value="available">
+ *     <sigvelo-icon slot="icon" name="circle-check" color="success"></sigvelo-icon>
+ *     <span>Available Now</span>
+ *     <span slot="details">Ready for adoption</span>
+ *   </sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="pending">
+ *     <sigvelo-icon slot="icon" name="clock" color="informative"></sigvelo-icon>
+ *     <span>Adoption Pending</span>
+ *     <span slot="details">Application in review</span>
+ *   </sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="medical">
+ *     <sigvelo-icon slot="icon" name="heart" color="critical"></sigvelo-icon>
+ *     <span>Medical Hold</span>
+ *     <span slot="details">Recovering from treatment</span>
+ *   </sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="foster">
+ *     <sigvelo-icon slot="icon" name="home" color="primary"></sigvelo-icon>
+ *     <span>Foster Only</span>
+ *     <span slot="details">Temporary care needed</span>
+ *   </sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <style>
+ *   #combobox__structured {
+ *     sigvelo-combobox-item {
+ *       padding-block: 0.75rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * **Warning:** Avoid placing interactive elements such as buttons and links inside the combobox item, as this will hinder accessibility and can lead to unexpected behaviors.
+ *
+ * @example Providing an initial value
+ * Add the `selected` attribute to the combobox item you want to select initially. When using `multiple`, you can apply `selected` to more than one option.
+ *
+ * ```html
+ * <sigvelo-combobox label="Preferred feeding time" placeholder="Select a time">
+ *   <sigvelo-combobox-item value="morning">Morning (6-9 AM)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="noon" selected>Noon (11 AM-1 PM)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="evening">Evening (5-7 PM)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="night">Night (8-10 PM)</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Getting and setting the value
+ * The combobox's value can be accessed and modified through JavaScript. For single selection, use the `value` property. For multiple selection, `value` will be an array.
+ *
+ * ```js
+ * // Single selection
+ * const combobox = document.querySelector('sigvelo-combobox');
+ * console.log(combobox.value); // "persian"
+ * combobox.value = 'siamese';
+ *
+ * // Multiple selection
+ * const multiCombobox = document.querySelector('sigvelo-combobox[multiple]');
+ * console.log(multiCombobox.value); // ["persian", "siamese"]
+ * multiCombobox.value = ['bengal', 'ragdoll'];
+ * ```
+ *
+ * @example Adding a clear button
+ * Add the `with-clear` attribute to show a clear button when the combobox has a value. This allows users to quickly clear their selection.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="With clear button"
+ *   placeholder="Select and then clear"
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="yes" selected>Yes, I want treats!</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="no">No treats needed</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="maybe">Maybe later</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Multiple selection
+ * Use the `multiple` attribute to enable multi-selection mode. Selected items appear as tags in the input area. Users can remove tags by clicking the × button or pressing Backspace.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Cat behaviors"
+ *   description="Select all behaviors your cat exhibits"
+ *   placeholder="Search behaviors"
+ *   multiple
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="purring" selected>Purring</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="kneading">Kneading (Making Biscuits)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="chirping" selected>Chirping at Birds</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="head-bunting">Head Bunting</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="slow-blinking">Slow Blinking</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="zoomies">Midnight Zoomies</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="bringing-gifts">Bringing "Gifts"</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="chattering">Teeth Chattering</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * **Note:** In multiple mode, the dropdown stays open after selecting an item, allowing users to quickly select multiple options. Press Escape or click outside to close the dropdown.
+ *
+ * @example Start and end content
+ * Use the `start` and `end` slots to add presentational icons or text. Avoid interactive elements such as buttons, links, etc. Works well with `<sigvelo-icon>` and `<svg>` elements.
+ *
+ * ```html
+ * <sigvelo-combobox name="breed" label="Cat breed" with-clear>
+ *   <sigvelo-icon slot="start" name="cat"></sigvelo-icon>
+ *   <sigvelo-combobox-item value="persian">Persian</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="siamese">Siamese</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tabby">Tabby</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="ragdoll">Ragdoll</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <br>
+ *
+ * <sigvelo-combobox name="toy" label="Cat toy" placeholder="Choose a toy" with-clear>
+ *   <sigvelo-icon slot="end" name="gift"></sigvelo-icon>
+ *   <sigvelo-combobox-item value="feather-wand">Feather Wand</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="laser-pointer">Laser Pointer</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="catnip-mouse">Catnip Mouse</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="puzzle-feeder">Puzzle Feeder</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <br>
+ *
+ * <sigvelo-combobox name="vet-visit" label="Visit type" multiple with-clear>
+ *   <sigvelo-icon slot="start" name="cat"></sigvelo-icon>
+ *   <sigvelo-icon slot="end" name="clipboard-heart"></sigvelo-icon>
+ *   <sigvelo-combobox-item value="checkup">Annual Checkup</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="vaccination">Vaccination</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="dental">Dental Cleaning</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="grooming">Grooming</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Filled and unstyled comboboxes
+ * Use the `variant` attribute to change the visual style of the combobox. Options are `normal` (default), `filled`, and `unstyled`.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Normal appearance"
+ *   variant="normal"
+ *   placeholder="Select one"
+ * >
+ *   <sigvelo-combobox-item value="1">Fluffy</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="2">Sleek</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="3">Short-haired</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <br>
+ *
+ * <sigvelo-combobox
+ *   label="Filled appearance"
+ *   variant="filled"
+ *   placeholder="Select one"
+ * >
+ *   <sigvelo-combobox-item value="1">Fluffy</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="2">Sleek</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="3">Short-haired</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <br>
+ *
+ * <sigvelo-combobox
+ *   label="Unstyled appearance"
+ *   variant="unstyled"
+ *   placeholder="Select one"
+ * >
+ *   <sigvelo-combobox-item value="1">Fluffy</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="2">Sleek</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="3">Short-haired</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Pill-shaped comboboxes
+ * Add the `pill` attribute to give the combobox rounded edges.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Cat's favorite treat"
+ *   placeholder="Choose a treat"
+ *   pill
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="salmon">Salmon Bites</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="chicken">Chicken Strips</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tuna">Tuna Flakes</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="catnip">Catnip Cookies</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="cheese">Cheese Cubes</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * When using `multiple`, tags become pill-shaped and the combobox will curve to wrap around them.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Cat's daily activities"
+ *   description="Select all that apply"
+ *   placeholder="What does your cat enjoy?"
+ *   pill
+ *   multiple
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="window-watching" selected>Bird Watching</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="sunbathing" selected>Sunbathing</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="toy-hunting" selected>Toy Hunting</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="box-sitting" selected>Box Sitting</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="treat-begging" selected>Treat Begging</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="midnight-racing" selected>Midnight Racing</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="lap-napping" selected>Lap Napping</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change the combobox's size. Available sizes are `xs`, `sm`, `md` (default), `lg`, and `xl`.
+ *
+ * ```html
+ * <sigvelo-select label="Select a size" value="xs" style="max-width: 18rem; margin-block-end: 2rem;">
+ *   <option value="xs">Extra small</option>
+ *   <option value="sm">Small</option>
+ *   <option value="md">Medium</option>
+ *   <option value="lg">Large</option>
+ *   <option value="xl">Extra large</option>
+ * </sigvelo-select>
+ *
+ * <sigvelo-combobox
+ *   size="xs"
+ *   label="Cat coat pattern"
+ *   description="Size changes dynamically based on selection above"
+ *   placeholder="Search patterns"
+ *   id="combobox__size"
+ *   with-clear
+ * >
+ *   <sigvelo-combobox-item value="solid">Solid Color</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tabby">Tabby Stripes</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="calico">Calico</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tortoiseshell">Tortoiseshell</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="tuxedo">Tuxedo</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="pointed">Pointed (Siamese)</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ *
+ * <script>
+ *   const combobox = document.getElementById('combobox__size');
+ *   const select = combobox.previousElementSibling;
+ *
+ *   select.addEventListener('sigvelo-change', () => {
+ *     combobox.size = select.value;
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Disabling the combobox
+ * Add the `disabled` attribute to disable the entire combobox.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   label="Grooming services"
+ *   description="Currently unavailable"
+ *   placeholder="Service selection disabled"
+ *   disabled
+ * >
+ *   <sigvelo-combobox-item value="bath">Bath & Blow-dry</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="trim" selected>Nail Trim</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="full">Full Grooming</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Disabling items
+ * Add the `disabled` attribute to individual combobox items to make them non-selectable. Disabled items will still appear in search results but cannot be selected.
+ *
+ * ```html
+ * <sigvelo-combobox label="Veterinary services" placeholder="Select service">
+ *   <sigvelo-combobox-item value="checkup">Annual Checkup</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="vaccination">Vaccination</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="spay-neuter" disabled>Spay/Neuter (Fully booked)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="dental">Dental Cleaning</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="emergency" disabled>Emergency Care (Call first)</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Showing labels on the side
+ * With the `sigvelo-side-label` utility, you can show labels on the side instead of on top of the combobox. You can control the width of the label by setting the `--label-width` custom property.
+ *
+ * ```html
+ * <sigvelo-combobox
+ *   class="sigvelo-side-label"
+ *   style="--label-width: 12ch;"
+ *   name="age"
+ *   label="Cat's age"
+ *   description="How old is your cat?"
+ *   placeholder="Select age range"
+ * >
+ *   <sigvelo-combobox-item value="kitten">Kitten (0-1 year)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="young">Young (1-3 years)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="adult">Adult (3-7 years)</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="senior">Senior (7+ years)</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * <br>
+ * <sigvelo-combobox
+ *   class="sigvelo-side-label"
+ *   style="--label-width: 12ch;"
+ *   name="activity"
+ *   label="Activity level"
+ *   description="How active is your cat?"
+ *   placeholder="Select activity"
+ * >
+ *   <sigvelo-combobox-item value="low">Couch Potato</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="moderate">Moderately Active</sigvelo-combobox-item>
+ *   <sigvelo-combobox-item value="high">Very Energetic</sigvelo-combobox-item>
+ * </sigvelo-combobox>
+ * ```
+ *
+ * @example Validation
+ * The `required` attribute can be used to enable validation using the Constraint Validation API.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank">
+ *   <sigvelo-combobox
+ *     name="emergency-contact"
+ *     label="Emergency vet contact"
+ *     placeholder="Select a veterinarian"
+ *     required
+ *   >
+ *     <sigvelo-combobox-item value="dr-smith">Dr. Smith - City Animal Hospital</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="dr-jones">Dr. Jones - Pet Emergency Center</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="dr-brown">Dr. Brown - 24/7 Pet Care</sigvelo-combobox-item>
+ *   </sigvelo-combobox>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ * ```
+ *
+ * @example Using custom validation
+ * Use the `setCustomValidity()` method to make the combobox invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, call the method with an empty string.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" id="combobox__custom-validation">
+ *   <sigvelo-combobox
+ *     name="special-diet"
+ *     label="Special dietary needs"
+ *     description="This field demonstrates custom validation"
+ *     placeholder="Select diet"
+ *   >
+ *     <sigvelo-combobox-item value="regular">Regular Diet</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="grain-free">Grain-Free</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="prescription">Prescription Diet</sigvelo-combobox-item>
+ *   </sigvelo-combobox>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ * </form>
+ *
+ * <script type="module">
+ *   import { allDefined } from '/dist/sigvelo.js';
+ *
+ *   await allDefined();
+ *
+ *   const form = document.getElementById('combobox__custom-validation');
+ *   const combobox = form.querySelector('sigvelo-combobox');
+ *
+ *   combobox.setCustomValidity('Please consult with your vet first!');
+ *
+ *   // Clear validation after user selects an option
+ *   combobox.addEventListener('sigvelo-change', () => {
+ *     combobox.setCustomValidity('');
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid comboboxes using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="combobox__validation-pseudo">
+ *   <sigvelo-combobox
+ *     name="chip-id"
+ *     label="Microchip ID"
+ *     description="Required for registration"
+ *     placeholder="Enter or select chip ID"
+ *     required
+ *   >
+ *     <sigvelo-combobox-item value="chip-12345">CHIP-12345</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="chip-67890">CHIP-67890</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="chip-24680">CHIP-24680</sigvelo-combobox-item>
+ *   </sigvelo-combobox>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .combobox__validation-pseudo {
+ *     sigvelo-combobox:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-combobox:invalid {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * However, these selectors will match even before the user has had a chance to interact with the form. More often than not, you'll want to use the `user-valid` and `user-invalid` custom states instead. This way, validation styles are only shown _after_ the user interacts with the form control or when the form is submitted.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="combobox__validation-custom">
+ *   <sigvelo-combobox
+ *     name="insurance"
+ *     label="Pet insurance provider"
+ *     description="Select your insurance company"
+ *     placeholder="Search providers"
+ *     required
+ *   >
+ *     <sigvelo-combobox-item value="pawguard-plus">PawGuard Plus</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="furry-shield">Furry Shield</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="petcare-prime">PetCare Prime</sigvelo-combobox-item>
+ *     <sigvelo-combobox-item value="whiskers-wellness">Whiskers Wellness</sigvelo-combobox-item>
+ *   </sigvelo-combobox>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .combobox__validation-custom {
+ *     sigvelo-combobox:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-combobox:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloCombobox extends SigveloFormControlElement {
+  static formAssociated: boolean;
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  private cleanup;
+  private optionIdCounter;
+  private liveRegionTimeoutId;
+  private localize;
+  private navigationDebounceId;
+  protected get focusableAnchor(): HTMLInputElement;
+  private dropdown;
+  private textBox;
+  open: boolean;
+  inputValue: string;
+  private activeItem;
+  private selectedItems;
+  private filteredItems;
+  private inputWidth;
+  private isInvalid;
+  private hadUserInteraction;
+  private wasSubmitted;
+  private liveAnnouncement;
+  /** The combobox's label. */
+  label: string;
+  /** The combobox's description. */
+  description: string;
+  /** The name of the combobox for form submission. */
+  name: string;
+  /** The combobox's value(s). */
+  value: string | string[];
+  /** Placeholder text for the input. */
+  placeholder: string;
+  /** Disables the combobox. */
+  disabled: boolean;
+  /** Makes the combobox required. */
+  required: boolean;
+  /** Enables multiple selection. */
+  multiple: boolean;
+  /** Adds a clear button when not blank. */
+  withClear: boolean;
+  /** The visual variant of the combobox. */
+  variant: "normal" | "filled" | "unstyled";
+  /** The size of the combobox. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Draws the combobox in a pill shape. */
+  pill: boolean;
+  /** The dropdown's placement relative to the input. */
+  placement: "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end";
+  /** The distance of the dropdown from the input. */
+  distance: number;
+  /** The offset of the dropdown along the input. */
+  offset: number;
+  /** The form to associate with. */
+  form: string;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  formDisabledCallback(disabled: boolean): void;
+  formResetCallback(): void;
+  /** Gets all <sigvelo-combobox-item> elements that aren't disabled (by default). */
+  private getItems;
+  private updateItems;
+  private syncSelectedItems;
+  private findMatchingItem;
+  private filterItems;
+  private setActiveItem;
+  private navigateItems;
+  private clearInvalidInput;
+  private selectItem;
+  private deselectItem;
+  private removeTag;
+  private clearAnnouncementTimers;
+  private announceChange;
+  private announceOption;
+  private announceFilterResults;
+  private showDropdown;
+  private hideDropdown;
+  private positionDropdown;
+  private isBlank;
+  private updateFormValue;
+  private updateValidity;
+  private updateInputWidth;
+  private handleInput;
+  private handleFocus;
+  private handleInputClick;
+  private handleBlur;
+  private handleKeyDown;
+  private handleDocumentClick;
+  private handleDocumentKeyDown;
+  private handleVisualBoxClick;
+  private handleClear;
+  private handleSlotChange;
+  private handleItemClick;
+  private handleItemPointerMove;
+  private handleHostInvalid;
+  /**
+   * A custom function for rendering tag content. By default, this function returns the item's full `textContent`. You
+   * can override it to customize the content that gets rendered in tags in `multiple` mode.
+   */
+  getTagContent(item: SigveloComboboxItem): TemplateResult;
+  /** Sets focus to the combobox. */
+  focus(): void;
+  /** Removes focus from the combobox. */
+  blur(): void;
+  render(): TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-combobox": SigveloCombobox;
+  }
+}
+//#endregion
+//#region src/components/combobox-item/combobox-item.d.ts
+/**
+ * <sigvelo-combobox-item>
+ *
+ * @summary An item that can be selected from a combobox control.
+ * @tag sigvelo-combobox-item
+ * @documentation https://design-system.sigvelo.com/docs/components/combobox-item
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ *
+ * @slot - The item's label.
+ * @slot icon - An optional icon to display at the start of the item.
+ * @slot details - Optional details to display at the end of the item.
+ *
+ * @csspart icon - The container that wraps the icon slot.
+ * @csspart label - The container that wraps the item's label.
+ * @csspart details - The container that wraps the details slot.
+ * @csspart checkmark - The checkmark icon shown when selected in multiple mode.
+ *
+ * @cssstate selected - Applied when the item is selected.
+ * @cssstate disabled - Applied when the item is disabled.
+ * @cssstate active - Applied when the item is active (keyboard navigation).
+ *
+ * @example Default
+ * This component must only be used within a combobox. You can see some examples of combobox items being used in the combobox documentation.
+ */
+declare class SigveloComboboxItem extends SigveloElement {
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  defaultSlot: HTMLSlotElement;
+  /** The value to submit when this item is selected. If not provided, the text content is used. */
+  value: string;
+  /** Disables the item. */
+  disabled: boolean;
+  /** @internal Whether the item is currently selected. */
+  selected: boolean;
+  /** @internal Whether the item is currently active (keyboard navigation). */
+  active: boolean;
+  /** @internal Reference to the parent combobox */
+  combobox: SigveloCombobox | null;
+  connectedCallback(): void;
+  /** Gets the text content from the combobox item's label. */
+  getLabelText(): string;
+  updated(changedProperties: PropertyValues<this>): void;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-combobox-item": SigveloComboboxItem;
+  }
+}
+//#endregion
+export { SigveloCombobox as n, SigveloComboboxItem as t };