@mcp-b/web-components 0.2.0

package/dist/rating-4xNsWumY.d.ts

@@ -0,0 +1,369 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/rating/rating.d.ts
+/**
+ * <sigvelo-rating>
+ *
+ * @summary Allows users to provide feedback based on their satisfaction with a product or service.
+ * @tag sigvelo-rating
+ * @documentation https://design-system.sigvelo.com/docs/components/rating
+ * @status stable
+ * @since 1.0
+ *
+ * @slot label - The rating's label. For plain-text labels, you can use the `label` attribute instead.
+ * @slot description - The rating's description. For plain-text descriptions, you can use the `description` attribute
+ *  instead.
+ *
+ * @event sigvelo-blur - Emitted when the rating loses focus. This event does not bubble.
+ * @event sigvelo-change - Emitted when the user commits changes to the rating's value.
+ * @event sigvelo-focus - Emitted when the rating receives focus. This event does not bubble.
+ * @event sigvelo-input - Emitted when the rating receives input.
+ *
+ * @csspart label - The element that contains the ratings's label.
+ * @csspart description - The element that contains the rating's description.
+ * @csspart rating - The element that wraps all of the rating's symbols.
+ * @csspart symbol - The container that holds the selected and unselected version of each symbol.
+ *
+ * @cssstate disabled - Applied when the rating is disabled.
+ * @cssstate focused - Applied when the rating has focus.
+ * @cssstate user-valid - Applied when the rating is valid and the user has sufficiently interacted with it.
+ * @cssstate user-invalid - Applied when the rating is invalid and the user has sufficiently interacted with it.
+ *
+ * @example Default
+ * ```html
+ * <sigvelo-rating
+ *   label="Rate my cat"
+ *   description="Leave her some stars."
+ *   name="cat"
+ *   value="4"
+ * >
+ * </sigvelo-rating>
+ * ```
+ *
+ * @example Labels and descriptions
+ * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the rating. If you want to provide HTML, use the `label` and `description` slots instead.
+ *
+ * ```html
+ * <sigvelo-rating name="name" label="How would you rate our catnip?">
+ *   <span slot="description">
+ *     For details, please <a href="https://example.com/" target="_blank">visit our website</a>.
+ *   </span>
+ * </sigvelo-rating>
+ * ```
+ *
+ * @example Providing an initial value
+ * Use the `value` attribute to provide an initial value for the rating.
+ *
+ * ```html
+ * <sigvelo-rating
+ *   name="food"
+ *   label="Food quality"
+ *   value="3"
+ * ></sigvelo-rating>
+ * ```
+ *
+ * @example Changing the scale
+ * Ratings use a scale of 1–5 by default. You can change this by setting the `max` attribute.
+ *
+ * ```html
+ * <sigvelo-rating
+ *   name="litter"
+ *   label="Cleanliness of litter box area"
+ *   max="3"
+ *   value="3"
+ * ></sigvelo-rating>
+ * ```
+ *
+ * @example Fractional values
+ * You can enable fractional values by setting the `step` attribute. For example, `0.5` will allow half-star ratings.
+ *
+ * ```html
+ * <sigvelo-rating
+ *   name="stars"
+ *   label="Half-stars are fine"
+ *   step=".5"
+ *   value="2.5"
+ * ></sigvelo-rating>
+ * ```
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change the rating's size.
+ *
+ * ```html
+ * <sigvelo-rating size="xs" label="Extra small"></sigvelo-rating><br>
+ * <sigvelo-rating size="sm" label="Small"></sigvelo-rating><br>
+ * <sigvelo-rating size="md" label="Medium"></sigvelo-rating><br>
+ * <sigvelo-rating size="lg" label="Large"></sigvelo-rating><br>
+ * <sigvelo-rating size="xl" label="Extra large"></sigvelo-rating>
+ * ```
+ *
+ * @example Using custom symbols
+ * To customize the symbols shown, use JavaScript to set the `symbolFormatter` property to a function that returns the HTML for each symbol. The function will receive the `value` and `isSelected` arguments that you can use to customize the symbol based on specific values or whether the symbol is in the selected state.
+ *
+ * ```html
+ * <sigvelo-rating
+ *   label="Show some love"
+ *   id="rating__custom-symbols"
+ *   value="3"
+ *   style="
+ *     --active-color: deeppink;
+ *     --inactive-color: gray;
+ *   "
+ * ></sigvelo-rating>
+ *
+ * <script>
+ *   const rating = document.getElementById('rating__custom-symbols');
+ *
+ *   rating.symbolFormatter = (value, isSelected) => {
+ *     return isSelected ?
+ *       `<sigvelo-icon family="filled" name="heart"></sigvelo-icon>` :
+ *       `<sigvelo-icon family="outline" name="heart"></sigvelo-icon>`;
+ *   }
+ * </script>
+ * ```
+ *
+ * ```html
+ * <sigvelo-rating
+ *   label="How satisfied are you?"
+ *   id="rating__numbers"
+ *   value="3"
+ *   style="--active-color: dodgerblue;"
+ * ></sigvelo-rating>
+ *
+ * <script>
+ *   const rating = document.getElementById('rating__numbers');
+ *
+ *   rating.symbolFormatter = (value, isSelected) => {
+ *     const family = isSelected ? 'filled' : 'outline';
+ *     return `<sigvelo-icon family="${family}" name="square-number-${value}"></sigvelo-icon>`
+ *   }
+ * </script>
+ * ```
+ *
+ * ```html
+ * <sigvelo-rating
+ *   label="How satisfied are you?"
+ *   id="rating__diamonds"
+ *   value="3"
+ *   style="--active-color: #2bb7d1;"
+ * ></sigvelo-rating>
+ *
+ * <script>
+ *   const rating = document.getElementById('rating__diamonds');
+ *
+ *   rating.symbolFormatter = (value, isSelected) => {
+ *     const family = isSelected ? 'filled' : 'outline';
+ *     const name = isSelected ? 'diamond' : 'point'
+ *     return `<sigvelo-icon family="${family}" name="${name}"></sigvelo-icon>`
+ *   }
+ * </script>
+ * ```
+ *
+ * **Warning:** You should only return trusted HTML from the `symbolFormatter()` function, otherwise you may become vulnerable to XSS exploits.
+ *
+ * @example Readonly ratings
+ * Use the `readonly` attribute to make the rating read-only.
+ *
+ * ```html
+ * <sigvelo-rating label="Read-only" value="4" readonly></sigvelo-rating>
+ * ```
+ *
+ * @example Disabling
+ * Use the `disabled` attribute to disable the rating.
+ *
+ * ```html
+ * <sigvelo-rating label="Disabled" value="4" disabled></sigvelo-rating>
+ * ```
+ *
+ * @example Validation
+ * The `required` attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until a non-zero value is selected.
+ *
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank">
+ *   <sigvelo-rating name="required" label="Required" required></sigvelo-rating><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 rating 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="rating__custom-validation">
+ *   <sigvelo-rating
+ *     name="food"
+ *     label="Food quality"
+ *     value="3"
+ *   ></sigvelo-rating>
+ *   <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('rating__custom-validation');
+ *   const rating = form.querySelector('sigvelo-rating');
+ *
+ *   rating.setCustomValidity('Not so fast, bubba!');
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid ratings using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="rating__validation-pseudo">
+ *   <sigvelo-rating
+ *     name="food"
+ *     label="Food quality"
+ *     description="This field is required."
+ *     required
+ *   ></sigvelo-rating>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .rating__validation-pseudo {
+ *     sigvelo-rating:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-rating: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="rating__validation-custom">
+ *   <sigvelo-rating
+ *     name="food"
+ *     label="Food quality"
+ *     description="This field is required."
+ *     required
+ *   ></sigvelo-rating>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .rating__validation-custom {
+ *     sigvelo-rating:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-rating:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloRating extends SigveloFormControlElement {
+  static formAssociated: boolean;
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  private didDragOverOthers;
+  private draggableRating;
+  private localize;
+  private ratingBoundingClientRect;
+  private valueWhenDraggingStarted;
+  protected get focusableAnchor(): HTMLElement;
+  rating: HTMLElement;
+  isInvalid: boolean;
+  hadUserInteraction: boolean;
+  wasSubmitted: boolean;
+  /**
+   * The rating's label. If you need to provide HTML in the label, use the `label` slot instead.
+   */
+  label: string;
+  /**
+   * The rating's description. If you need to provide HTML in the description, use the `description` slot instead.
+   */
+  description: string;
+  /** The name of the rating. This will be submitted with the form as a name/value pair. */
+  name: string;
+  /** The rating's value. */
+  value: number;
+  /** Disables the rating. */
+  disabled: boolean;
+  /** Makes the rating a read-only field. */
+  readonly: boolean;
+  /** The rating's size. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /**
+   * 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 rating required. Form submission will not be allowed when this is set and the rating is empty. */
+  required: boolean;
+  /** The maximum value allowed. */
+  max: number;
+  /** The granularity the value must adhere to when incrementing and decrementing. */
+  step: number;
+  /** Tells the browser to focus the rating when the page loads or a dialog is shown. */
+  autofocus: boolean;
+  /**
+   * A function that returns the HTML for each symbol. The function will receive the `value` and `isSelected` arguments
+   * that you can use to customize the symbol based on specific values or whether the symbol is in the selected state.
+   * You should only return trusted HTML from this function, otherwise you may become vulnerable to XSS exploits.
+   */
+  symbolFormatter: (step: number, isSelected: boolean) => string;
+  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;
+  /** Clamps a number to min/max while ensuring it's a valid step interval. */
+  private clampAndCeilToStep;
+  private handleBlur;
+  private handleFocus;
+  private handleHostInvalid;
+  private handleKeyDown;
+  private handleLabelPointerDown;
+  private setValueFromCoordinates;
+  /** Sets the form control's validity */
+  private updateValidity;
+  /** Sets focus to the rating. */
+  focus(): void;
+  /** Removes focus from the rating. */
+  blur(): void;
+  /**
+   * Decreases the rating's value by `step`. This is a programmatic change, so `input` and `change` events will not be
+   * emitted when this is called.
+   */
+  stepDown(): void;
+  /**
+   * Increases the rating'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-rating": SigveloRating;
+  }
+}
+//#endregion
+export { SigveloRating as t };