@mcp-b/web-components 0.2.0

package/dist/number-field-odk4lKXM.d.ts

@@ -0,0 +1,422 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/number-field/number-field.d.ts
+/**
+ * <sigvelo-number-field>
+ *
+ * @summary Allows users to input and edit numbers.
+ * @tag sigvelo-number-field
+ * @documentation https://design-system.sigvelo.com/docs/components/number-field
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ *
+ * @slot label - The number field's label. For plain-text labels, you can use the `label` attribute instead.
+ * @slot description - The number field'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 number field loses focus. This event does not bubble.
+ * @event sigvelo-change - Emitted when the user commits changes to the number field's value.
+ * @event sigvelo-focus - Emitted when the number field receives focus. This event does not bubble.
+ * @event sigvelo-input - Emitted when the number field receives input.
+ *
+ * @csspart label - The element that contains the number field's label.
+ * @csspart description - The element that contains the number field's description.
+ * @csspart visual-box - The element that wraps the internal text box.
+ * @csspart text-box - The internal text box, an `<input>` element.
+ * @csspart stepper - The up and down stepper buttons.
+ * @csspart stepper-up - The up stepper button.
+ * @csspart stepper-down - The down stepper button.
+ *
+ * @cssstate disabled - Applied when the number field is disabled.
+ * @cssstate blank - Applied when the number field has a blank value.
+ * @cssstate focused - Applied when the number field has focus.
+ * @cssstate user-valid - Applied when the number field is valid and the user has sufficiently interacted with it.
+ * @cssstate user-invalid - Applied when the number field is invalid and the user has sufficiently interacted with it.
+ *
+ * @example Default
+ * ```html
+ * <sigvelo-number-field
+ *   name="name"
+ *   label="Lives"
+ *   value="9"
+ *   style="max-width: 200px;"
+ * ></sigvelo-number-field>
+ * ```
+ *
+ * @example Labels and descriptions
+ * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the text field. If you want to provide HTML, use the `label` and `description` slots instead.
+ *
+ * ```html
+ * <sigvelo-number-field name="name" label="Kitten age (months)" style="max-width: 200px;">
+ *   <span slot="description">
+ *     <a href="https://example.com/" target="_blank">How to determine age</a>
+ *   </span>
+ * </sigvelo-number-field>
+ * ```
+ *
+ * @example Providing an initial value
+ * Use the `value` attribute to provide an initial value for the text field.
+ *
+ * ```html
+ * <sigvelo-number-field
+ *   name="name"
+ *   label="Treats given today"
+ *   value="2"
+ *   style="max-width: 200px;"
+ * >
+ * </sigvelo-number-field>
+ * ```
+ *
+ * @example Setting min, max, and step
+ * Use the `min` and `max` attributes to set a minimum and maximum value for the number field. Use the `step` attribute to change the granularity the value must adhere to.
+ *
+ * ```html
+ * <sigvelo-number-field
+ *   name="donation"
+ *   label="Monthly shelter donation"
+ *   description="Amount in dollars (5-100)"
+ *   min="5"
+ *   max="100"
+ *   step="5"
+ *   value="25"
+ *   style="max-width: 200px;"
+ * ></sigvelo-number-field>
+ * ```
+ *
+ * @example Adding a placeholder
+ * Use the `placeholder` attribute to show a placeholder in the text field when it's empty.
+ *
+ * ```html
+ * <sigvelo-number-field
+ *   type="number"
+ *   label="Weight"
+ *   description="Measured in pounds"
+ *   min="0"
+ *   step="0.5"
+ *   placeholder="10.5"
+ *   style="max-width: 200px;"
+ * ></sigvelo-number-field>
+ * ```
+ *
+ * @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
+ * <div style="max-width: 200px;">
+ *   <sigvelo-number-field type="number" value="100" name="adoption" label="Adoption fee">
+ *     <span slot="start">$</span>
+ *   </sigvelo-number-field>
+ *
+ *   <br>
+ *
+ *   <sigvelo-number-field type="number" value="30" name="playtime" label="Playtime minutes">
+ *     <sigvelo-icon slot="end" name="clock"></sigvelo-icon>
+ *   </sigvelo-number-field>
+ *
+ *   <br>
+ *
+ *   <sigvelo-number-field name="treats" value="2" label="Daily treats">
+ *     <sigvelo-icon slot="start" name="cat"></sigvelo-icon>
+ *     <sigvelo-icon slot="end" name="cookie"></sigvelo-icon>
+ *   </sigvelo-number-field>
+ * </sigvelo-number-field>
+ * ```
+ *
+ * @example Filled and unstyled number fields
+ * Set the `variant` attribute to `normal`, `filled`, or `unstyled` to change the text field's variant.
+ *
+ * ```html
+ * <div style="max-width: 200px;">
+ *   <sigvelo-number-field variant="normal" label="Normal number field" placeholder="Enter number" style="max-width: 200px;"></sigvelo-number-field><br>
+ *   <sigvelo-number-field variant="filled" label="Filled number field" placeholder="Enter number" style="max-width: 200px;"></sigvelo-number-field><br>
+ *   <sigvelo-number-field variant="unstyled" label="Unstyled number field" placeholder="Enter number" style="max-width: 200px;"></sigvelo-number-field>
+ * </div>
+ * ```
+ *
+ * @example Pill-shaped number fields
+ * Text fields can be rendered with pill-shaped edges by adding the `pill` attribute.
+ *
+ * ```html
+ * <sigvelo-number-field pill label="Whiskers count" style="max-width: 200px;"></sigvelo-number-field>
+ * ```
+ *
+ * @example Without steppers
+ * Add the `without-steppers` attribute to remove the stepper buttons.
+ *
+ * ```html
+ * <sigvelo-number-field
+ *   name="name"
+ *   label="Purrs per minute"
+ *   value="25"
+ *   without-steppers
+ *   style="max-width: 200px;"
+ * ></sigvelo-number-field>
+ * ```
+ *
+ * **Note:** This will remove the stepper buttons, but keyboard users can still modify the value using the arrow keys.
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change the text field's size.
+ *
+ * ```html
+ * <div style="max-width: 200px;">
+ *   <sigvelo-number-field size="xs" label="Hairball count (xs)"></sigvelo-number-field><br>
+ *   <sigvelo-number-field size="sm" label="Meows per hour (sm)"></sigvelo-number-field><br>
+ *   <sigvelo-number-field size="md" label="Zoomies today (md)"></sigvelo-number-field><br>
+ *   <sigvelo-number-field size="lg" label="Treats budget (lg)"></sigvelo-number-field><br>
+ *   <sigvelo-number-field size="xl" label="Seconds until empty bowl (xl)"></sigvelo-number-field>
+ * </div>
+ * ```
+ *
+ * @example Disabling
+ * Use the `disabled` attribute to disable the text field.
+ *
+ * ```html
+ * <sigvelo-number-field label="Limit reached (no more cats!)" disabled style="max-width: 200px;"></sigvelo-number-field>
+ * ```
+ *
+ * @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 text field. You can control the width of the label by setting the `--label-width` custom property.
+ *
+ * ```html
+ * <div style="max-width: 300px;">
+ *   <sigvelo-number-field
+ *     class="sigvelo-side-label"
+ *     style="--label-width: 12ch;"
+ *     name="name"
+ *     label="Age"
+ *     description="How old is your feline friend?"
+ *   ></sigvelo-number-field>
+ *   <br>
+ *   <sigvelo-number-field
+ *     class="sigvelo-side-label"
+ *     style="--label-width: 12ch;"
+ *     type="number"
+ *     name="email"
+ *     label="Weight"
+ *     description="In pounds, please be honest!"
+ *   ></sigvelo-number-field>
+ * </div>
+ * ```
+ *
+ * @example Validation
+ * A number of attributes can be used to enable validation using the Constraint Validation API. These include `required`, `pattern`, `minlength`, `maxlength`, `min`, `max`, and `step`. They work exactly like their native counterparts.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" style="max-width: 200px;">
+ *   <sigvelo-number-field name="required" label="Number of cats" required></sigvelo-number-field><br>
+ *   <sigvelo-number-field name="min" label="Minimum cats (min 3)" required min="3"></sigvelo-number-field><br>
+ *   <sigvelo-number-field name="max" label="Maximum cats (max 10)" required max="10"></sigvelo-number-field><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 text field 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="number-field__custom-validation">
+ *   <sigvelo-number-field
+ *     name="name"
+ *     label="Happiness level (1-10)"
+ *     description="This field will be invalid until custom validation is removed"
+ *     style="max-width: 200px;"
+ *   ></sigvelo-number-field>
+ *   <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('number-field__custom-validation');
+ *   const textField = form.querySelector('sigvelo-number-field');
+ *
+ *   textField.setCustomValidity('Not so fast, bubba!');
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid text fields using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="number-field__validation-pseudo">
+ *   <sigvelo-number-field
+ *     name="name"
+ *     label="Toy budget"
+ *     description="Must be at least $50"
+ *     min="50"
+ *     required
+ *     style="max-width: 200px;"
+ *   ></sigvelo-number-field>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .number-field__validation-pseudo {
+ *     sigvelo-number-field:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-number-field: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="number-field__validation-custom">
+ *   <sigvelo-number-field
+ *     name="name"
+ *     label="Cat videos watched"
+ *     description="Be honest…"
+ *     required
+ *     style="max-width: 200px;"
+ *     value="1000"
+ *   ></sigvelo-number-field>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .number-field__validation-custom {
+ *     sigvelo-number-field:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-number-field:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloNumberField extends SigveloFormControlElement {
+  static formAssociated: boolean;
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  private localize;
+  protected get focusableAnchor(): HTMLInputElement;
+  private textBox;
+  isInvalid: boolean;
+  hadUserInteraction: boolean;
+  wasSubmitted: boolean;
+  isPasswordVisible: boolean;
+  /**
+   * The number field's label. If you need to provide HTML in the label, use the `label` slot instead.
+   */
+  label: string;
+  /**
+   * The number field's description. If you need to provide HTML in the description, use the `description` slot instead.
+   */
+  description: string;
+  /** The name of the number field. This will be submitted with the form as a name/value pair. */
+  name: string;
+  /** The number field's value. */
+  value: string;
+  /** A placeholder to show in the number field when it's blank. */
+  placeholder: string;
+  /** Disables the number field. */
+  disabled: boolean;
+  /** Makes the number field a read-only field. */
+  readonly: boolean;
+  /** The type of number field to render. */
+  variant: "normal" | "filled" | "unstyled";
+  /** The number field's size. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Draws the number field 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 number field required. Form submission will not be allowed when this is set and the number field is blank.
+   */
+  required: boolean;
+  /** A regular expression the value should match to be considered valid. */
+  pattern: string;
+  /** The minimum value for date/time types. */
+  min: number;
+  /** The maximum value for date/time types. */
+  max: number;
+  /** The granularity the value must adhere to when incrementing and decrementing. */
+  step: number | "any";
+  /**
+   * Tells the browser how to autocomplete the number field. See [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete)
+   * for available values.
+   */
+  autocomplete: string;
+  /** Tells the browser to focus the number field when the page loads or a dialog is shown. */
+  autofocus: boolean;
+  /** Sets the enter key label on virtual keyboards. */
+  enterkeyhint: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
+  /** When true, the add/subtract steppers won't be displayed. */
+  withoutSteppers: boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): 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 handleChange;
+  private handleFocus;
+  private handleHostInvalid;
+  private handleDecrease;
+  private handleIncrease;
+  private maintainFocusOnPointerDown;
+  private handleInput;
+  private handleKeyDown;
+  private handleVisualBoxPointerDown;
+  /** Sets the form control's validity */
+  private updateValidity;
+  /** Sets focus to the number field. */
+  focus(): void;
+  /** Removes focus from the number field. */
+  blur(): void;
+  /** Selects all text in the number field. */
+  select(): void;
+  /** Sets the start and end positions of the current text selection in the number field. */
+  setSelectionRange(start: number, end: number, direction?: "forward" | "backward" | "none"): void;
+  /** Replaces a range of text in the number field with a new string. */
+  setRangeText(replacement: string, start?: number, end?: number, selectMode?: "select" | "start" | "end" | "preserve"): void;
+  /**
+   * When a supported `type` is used, this method will decrease the number field's value by `step`. This is a programmatic
+   * change, so `input` and `change` events will not be emitted when this is called.
+   */
+  stepDown(): void;
+  /**
+   * When a supported `type` is used, this method will increase the number field's value by `step`. This is a programmatic
+   * change, so `input` and `change` events will not be emitted when this is called.
+   */
+  stepUp(): void;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-number-field": SigveloNumberField;
+  }
+}
+//#endregion
+export { SigveloNumberField as t };