@mcp-b/web-components 0.2.0

package/dist/select-CkZK2jJn.d.ts

@@ -0,0 +1,506 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/select/select.d.ts
+/**
+ * <sigvelo-select>
+ *
+ * @summary Allows users to choose an option from a predefined list of options.
+ * @tag sigvelo-select
+ * @documentation https://design-system.sigvelo.com/docs/components/select
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ *
+ * @slot label - The select's label. For plain-text labels, you can use the `label` attribute instead.
+ * @slot description - The select's description. For plain-text descriptions, you can use the `description` attribute
+ *  instead.
+ * @slot start - An icon or similar element to place before the label. Works great with `<sigvelo-icon>`.
+ * @slot end - An icon or similar element to place after the label. Works great with `<sigvelo-icon>`.
+ *
+ * @event sigvelo-blur - Emitted when the select loses focus. This event does not bubble.
+ * @event sigvelo-change - Emitted when the user commits changes to the select's value.
+ * @event sigvelo-focus - Emitted when the select receives focus. This event does not bubble.
+ * @event sigvelo-input - Emitted when the select receives input.
+ *
+ * @csspart label - The element that contains the select's label.
+ * @csspart description - The element that contains the select's description.
+ * @csspart visual-box - The element that wraps the internal text box.
+ * @csspart text-box - The internal text box, a `<select>` element.
+ * @csspart chevron - The chevron icon, a `<sigvelo-icon>` element.
+ * @csspart chevron__svg - The chevron icon's `<svg>` part.
+ *
+ * @cssstate disabled - Applied when the select is disabled.
+ * @cssstate blank - Applied when the select has no selected option.
+ * @cssstate focused - Applied when the select has focus.
+ * @cssstate user-valid - Applied when the select is valid and the user has sufficiently interacted with it.
+ * @cssstate user-invalid - Applied when the select is invalid and the user has sufficiently interacted with it.
+ *
+ * @example Default
+ * This component works very similar to the `<select>` element. You can add `<option>`, `<optgroup>`, and `<hr>` elements to it to group and provide options, which are then copied into the component's shadow root.
+ *
+ * ```html
+ * <sigvelo-select
+ *   name="cat"
+ *   label="Wild cats"
+ *   description="Select your favorite type of cat from the wild"
+ * >
+ *   <optgroup label="Small cats">
+ *     <option value="bobcat">Bobcat</option>
+ *     <option value="sand-cat">Sand cat</option>
+ *     <option value="serval">Serval</option>
+ *   </optgroup>
+ *   <optgroup label="Big cats">
+ *     <option value="cheetah">Cheetah</option>
+ *     <option value="lion">Lion</option>
+ *     <option value="tiger">Tiger</option>
+ *   </optgroup>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Labels and descriptions
+ * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the select. If you want to provide HTML, use the `label` and `description` slots instead.
+ *
+ * ```html
+ * <sigvelo-select name="zzz" label="Where to sleep">
+ *   <span slot="description">
+ *     For more information, <a href="https://example.com/" target="_blank">visit our website</a>.
+ *   </span>
+ *   <option value="box">Cardboard box</option>
+ *   <option value="floor">Floor</option>
+ *   <option value="laundry">Laundry</option>
+ *   <option value="pillow">Pillow</option>
+ *   <option value="sunbeam">Sunbeam</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Providing an initial value
+ * Use the `value` attribute to provide an initial value for the select.
+ *
+ * ```html
+ * <sigvelo-select name="size" label="Select a size" value="md">
+ *   <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>
+ * ```
+ *
+ * **Note:** This behavior is different from native selects that use the option's `selected` attribute to set the value. With `<sigvelo-select>`, always use the `value` attribute to set the value.
+ *
+ * @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-select name="account" label="Account type">
+ *   <sigvelo-icon slot="start" name="user"></sigvelo-icon>
+ *   <option value="owner">Owner</option>
+ *   <option value="admin">Administrator</option>
+ *   <option value="user">User</option>
+ *   <option value="guest">Guest</option>
+ * </sigvelo-select>
+ *
+ * <br>
+ *
+ * <sigvelo-select name="contact" label="Preferred method of contact">
+ *   <sigvelo-icon slot="end" name="mail"></sigvelo-icon>
+ *   <option value="email">Email</option>
+ *   <option value="phone">Phone</option>
+ *   <option value="mail">Regular Mail</option>
+ *   <option value="text">Text Message</option>
+ *   <option value="none">None</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Filled and unstyled selects
+ * Set the `variant` attribute to `normal`, `filled`, or `unstyled` to change the select's variant.
+ *
+ * ```html
+ * <sigvelo-select variant="normal" label="Normal select" value="normal">
+ *   <option value="normal">Normal</option>
+ *   <option value="filled">Filled</option>
+ *   <option value="unstyled">Unstyled</option>
+ * </sigvelo-select><br>
+ *
+ * <sigvelo-select variant="filled" label="Filled select" value="filled">
+ *   <option value="normal">Normal</option>
+ *   <option value="filled">Filled</option>
+ *   <option value="unstyled">Unstyled</option>
+ * </sigvelo-select><br>
+ *
+ * <sigvelo-select variant="unstyled" label="Unstyled select" value="unstyled">
+ *   <option value="normal">Normal</option>
+ *   <option value="filled">Filled</option>
+ *   <option value="unstyled">Unstyled</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Pill-shaped selects
+ * Selects can be rendered with pill-shaped edges by adding the `pill` attribute.
+ *
+ * ```html
+ * <sigvelo-select pill label="Pill-shaped">
+ *   <option value="1">One</option>
+ *   <option value="2">Two</option>
+ *   <option value="3">Three</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change the select's size.
+ *
+ * ```html
+ * <sigvelo-select size="xs" label="Extra small" value="xs">
+ *   <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><br>
+ *
+ * <sigvelo-select size="sm" label="Small" value="sm">
+ *   <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><br>
+ *
+ * <sigvelo-select size="md" label="Medium" value="md">
+ *   <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><br>
+ *
+ * <sigvelo-select size="lg" label="Large" value="lg">
+ *   <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><br>
+ *
+ * <sigvelo-select size="xl" label="Extra large" value="xl">
+ *   <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>
+ * ```
+ *
+ * @example Adding option groups
+ * Use `<optgroup>` elements to add option groups. Set the `label` attribute to an appropriate label.
+ *
+ * ```html
+ * <sigvelo-select name="cat" label="Wild cats">
+ *   <optgroup label="Small cats">
+ *     <option value="bobcat">Bobcat</option>
+ *     <option value="sand-cat">Sand cat</option>
+ *     <option value="serval">Serval</option>
+ *   </optgroup>
+ *   <optgroup label="Big cats">
+ *     <option value="cheetah">Cheetah</option>
+ *     <option value="lion">Lion</option>
+ *     <option value="tiger">Tiger</option>
+ *   </optgroup>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Adding dividers
+ * Use `<hr>` to add dividers between options.
+ *
+ * ```html
+ * <sigvelo-select name="animal" label="Animal">
+ *   <option value="bird">Bird</option>
+ *   <option value="cat">Cat</option>
+ *   <option value="dog">Dog</option>
+ *   <option value="lizard">Lizard</option>
+ *   <hr>
+ *   <option value="other">Other</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Disabling options
+ * Use the `disabled` attribute to disable individual options.
+ *
+ * ```html
+ * <sigvelo-select label="Disabled options">
+ *   <option value="bird">Bird</option>
+ *   <option value="cat">Cat</option>
+ *   <option value="dog" disabled>Dog</option>
+ *   <option value="lizard">Lizard</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Disabling option groups
+ * Use the `disabled` attribute to disable an option group.
+ *
+ * ```html
+ * <sigvelo-select label="Disabled option groups">
+ *   <optgroup label="Group one">
+ *     <option value="morning-1">Morning</option>
+ *     <option value="afternoon-1">Afternoon</option>
+ *     <option value="evening-1">Evening</option>
+ *   </optgroup>
+ *   <optgroup label="Group two" disabled>
+ *     <option value="morning-2">Morning</option>
+ *     <option value="afternoon-2">Afternoon</option>
+ *     <option value="evening-2">Evening</option>
+ *   </optgroup>
+ * </sigvelo-select>
+ * ```
+ *
+ * **Warning:** Disabled option groups [don't currently work](https://bugs.webkit.org/show_bug.cgi?id=227042) in iOS Safari.
+ *
+ * @example Disabling selects
+ * Use the `disabled` attribute to disable the select.
+ *
+ * ```html
+ * <sigvelo-select label="Disabled" disabled>
+ *   <option value="bird">Bird</option>
+ *   <option value="cat">Cat</option>
+ *   <option value="dog">Dog</option>
+ *   <option value="lizard">Lizard</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @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 select. You can control the width of the label by setting the `--label-width` custom property.
+ *
+ * ```html
+ * <sigvelo-select
+ *   class="sigvelo-side-label"
+ *   style="--label-width: 8ch;"
+ *   name="quantity"
+ *   label="Quantity"
+ *   description="How many do you need?"
+ * >
+ *   <option value="1">1</option>
+ *   <option value="2">2</option>
+ *   <option value="3">3</option>
+ *   <option value="4">4</option>
+ *   <option value="5">5</option>
+ * </sigvelo-select>
+ * <br>
+ * <sigvelo-select
+ *   class="sigvelo-side-label"
+ *   style="--label-width: 8ch;"
+ *   name="delivery"
+ *   label="Delivery"
+ *   description="How soon do you need it?"
+ * >
+ *   <option value="next">Next-day</option>
+ *   <option value="priority">Priority</option>
+ *   <option value="ground">Ground</option>
+ * </sigvelo-select>
+ * ```
+ *
+ * @example Validation
+ * The `required` attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until an option with a non-empty value is selected.
+ *
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank">
+ *   <sigvelo-select name="required" label="Required" required>
+ *     <option value=""></option>
+ *     <option value="bird">Bird</option>
+ *     <option value="cat">Cat</option>
+ *     <option value="dog">Dog</option>
+ *     <option value="lizard">Lizard</option>
+ *   </sigvelo-select>
+ *   <br>
+ *   <sigvelo-button type="submit">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ * ```
+ *
+ * @example Using custom validation
+ * Use the `setCustomValidity()` method to make the select invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" id="select__custom-validation">
+ *   <sigvelo-select
+ *     name="animal"
+ *     label="Animal"
+ *     description="This field will be invalid until custom validation is removed"
+ *   >
+ *     <option value="bird">Bird</option>
+ *     <option value="cat">Cat</option>
+ *     <option value="dog">Dog</option>
+ *     <option value="lizard">Lizard</option>
+ *   </sigvelo-select>
+ *   <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('select__custom-validation');
+ *   const select = form.querySelector('sigvelo-select');
+ *
+ *   select.setCustomValidity('Not so fast, bubba!');
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid selects using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="select__validation-pseudo">
+ *   <sigvelo-select
+ *     name="animal"
+ *     label="Animal"
+ *     description="This field is required"
+ *     required
+ *   >
+ *     <option value=""></option>
+ *     <option value="bird">Bird</option>
+ *     <option value="cat">Cat</option>
+ *     <option value="dog">Dog</option>
+ *     <option value="lizard">Lizard</option>
+ *   </sigvelo-select>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .select__validation-pseudo {
+ *     sigvelo-select:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-select: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 fill out 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="select__validation-custom">
+ *   <sigvelo-select
+ *     name="animal"
+ *     label="Animal"
+ *     description="This field is required"
+ *     required
+ *   >
+ *     <option value=""></option>
+ *     <option value="bird">Bird</option>
+ *     <option value="cat">Cat</option>
+ *     <option value="dog">Dog</option>
+ *     <option value="lizard">Lizard</option>
+ *   </sigvelo-select>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .select__validation-custom {
+ *     sigvelo-select:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-select:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloSelect extends SigveloFormControlElement {
+  static formAssociated: boolean;
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  protected get focusableAnchor(): HTMLSelectElement;
+  private defaultSlot;
+  private textBox;
+  isInvalid: boolean;
+  hadUserInteraction: boolean;
+  wasSubmitted: boolean;
+  options: string;
+  /**
+   * The select's label. If you need to provide HTML in the label, use the `label` slot instead.
+   */
+  label: string;
+  /**
+   * The select's description. If you need to provide HTML in the description, use the `description` slot instead.
+   */
+  description: string;
+  /** The name of the select. This will be submitted with the form as a name/value pair. */
+  name: string;
+  /** The select's value. */
+  value: string;
+  /** Disables the select. */
+  disabled: boolean;
+  /** Makes the select a read-only field. */
+  readonly: boolean;
+  /** The type of select to render. */
+  variant: "normal" | "filled" | "unstyled";
+  /** The select's size. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Draws the select in a pill shape. */
+  pill: boolean;
+  /**
+   * The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of
+   * this attribute must be an ID of a form in the same document or shadow root.
+   */
+  form: string;
+  /**
+   * Makes the select required. Form submission will not be allowed when this is set and the select is blank.
+   */
+  required: boolean;
+  /**
+   * Tells the browser how to autocomplete the select. See [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete)
+   * for available values.
+   */
+  autocomplete: string;
+  /** Sets the enter key label on virtual keyboards. */
+  enterkeyhint: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  /** @internal Called when a containing fieldset is disabled. */
+  formDisabledCallback(isDisabled: boolean): void;
+  /** @internal Called when the form is reset. */
+  formResetCallback(): void;
+  private handleBlur;
+  private handleVisualBoxPointerDown;
+  private handleChange;
+  private handleFocus;
+  private handleHostInvalid;
+  private handleInput;
+  private syncOptions;
+  /** Sets the form control's validity */
+  private updateValidity;
+  /** Sets focus to the select. */
+  focus(): void;
+  /** Removes focus from the select. */
+  blur(): void;
+  /** Shows the picker in supportive browsers. */
+  showPicker(): void;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-select": SigveloSelect;
+  }
+}
+//#endregion
+export { SigveloSelect as t };