@mcp-b/web-components 0.2.0

package/dist/toggle-icon-DlwMMWZL.d.ts

@@ -0,0 +1,359 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/toggle-icon/toggle-icon.d.ts
+/**
+ * <sigvelo-toggle-icon>
+ *
+ * @summary Similar to checkboxes, except with icons to represent the checked and unchecked states.
+ * @tag sigvelo-toggle-icon
+ * @documentation https://design-system.sigvelo.com/docs/components/toggle-icon
+ * @status stable
+ * @since 1.0
+ *
+ * @slot checked - The icon to show when checked. Works best with a `<sigvelo-icon>` element.
+ * @slot unchecked - The default icon to show when unchecked. Works best with a `<sigvelo-icon>` element.
+ *
+ * @event sigvelo-blur - Emitted when the toggle icon loses focus. This event does not bubble.
+ * @event sigvelo-change - Emitted when the user commits changes to the toggle's value.
+ * @event sigvelo-focus - Emitted when the checkbox receives focus. This event does not bubble.
+ * @event sigvelo-input - Emitted when the checkbox receives input.
+ *
+ * @csspart button - The internal button that contains the toggle icons, a `<button>` element.
+ *
+ * @cssproperty [--animation-speed=300ms] - The animation speed to use when effects are selected.
+ * @cssproperty [--checked-color=#f59e0b] - The color to use for checked toggle icons.
+ * @cssproperty [--unchecked-color=var(--sigvelo-color-neutral-bg)] - The color to use for unchecked toggle icons.
+ *
+ * @cssstate checked - Applied when the toggle icon is active.
+ * @cssstate disabled - Applied when the toggle icon is disabled.
+ * @cssstate focused - Applied when the toggle icon has focus.
+ * @cssstate user-valid - Applied when the toggle icon is valid and the user has sufficiently interacted with it.
+ * @cssstate user-invalid - Applied when the toggle icon is invalid and the user has sufficiently interacted with it.
+ *
+ * @example Default
+ * Toggle icons can be used just like checkboxes and switches to turn features on and off. You can listen for state changes with the `sigvelo-input` event and submit them with forms by adding `name` and `value` attributes.
+ *
+ * Assistive devices will recognize toggle icons as toggle buttons. The default icon is a star, but you can customize it with any icon you want.
+ *
+ * ```html
+ * <sigvelo-toggle-icon
+ *   label="Star this"
+ *   effect="fade"
+ * ></sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Save to favorites"
+ *   effect="scale"
+ *   style="--checked-color: crimson;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="heart" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="heart" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Like this post"
+ *   effect="flip-x"
+ *   style="--checked-color: dodgerblue;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="thumb-up" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="thumb-up" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Play / pause"
+ *   effect="scale"
+ *   style="
+ *     --checked-color: var(--sigvelo-color-neutral-bg);
+ *     --unchecked-color: var(--sigvelo-color-neutral-bg);
+ *   "
+ * >
+ *   <sigvelo-icon slot="unchecked" name="player-pause" family="filled"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="player-play" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Checked initially
+ * Add the `checked` attribute to check the toggle icon initially.
+ *
+ * ```html
+ * <sigvelo-toggle-icon
+ *   label="Star this"
+ *   name="favorite"
+ *   value="1"
+ *   checked
+ * ></sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Custom icons
+ * Place a `<sigvelo-icon>` into the default slot to show a custom unchecked state. Place one into the `checked` slot to show a custom checked state.
+ *
+ * You can use any icon you want for each state, but `outline` for unchecked icons and `filled` for checked icons usually work best. Use the `--unchecked-color` and `--checked-color` custom properties to change colors.
+ *
+ * ```html
+ * <sigvelo-toggle-icon
+ *   label="Save to favorites"
+ *   style="--checked-color: crimson;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="heart" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="heart" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Like this post"
+ *   style="--checked-color: dodgerblue;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="thumb-up" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="thumb-up" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Enable filter"
+ *   style="--checked-color: blueviolet;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="filter" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="filter" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Changing the effect
+ * Set the `effect` attribute to change the toggle icon's animation. This works great with custom icons.
+ *
+ * ```html
+ * <sigvelo-toggle-icon
+ *   label="Star this"
+ *   effect="fade"
+ * ></sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Love this"
+ *   effect="scale"
+ *   style="--checked-color: crimson;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="heart" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="heart" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Mark as complete"
+ *   effect="flip-x"
+ *   style="--checked-color: cadetblue;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="clipboard" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="clipboard-check" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Secure this"
+ *   effect="flip-y"
+ *   style="--checked-color: forestgreen;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="shield" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="shield-check" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Ship this"
+ *   effect="translate-x"
+ *   style="--checked-color: blueviolet;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="truck" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="truck" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ *
+ * <sigvelo-toggle-icon
+ *   label="Enable reader mode"
+ *   effect="translate-y"
+ *   style="--checked-color: dodgerblue;"
+ * >
+ *   <sigvelo-icon slot="unchecked" name="eyeglass" family="outline"></sigvelo-icon>
+ *   <sigvelo-icon slot="checked" name="eyeglass" family="filled"></sigvelo-icon>
+ * </sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Sizes
+ * Use the `size` attribute to change the size of the toggle icon.
+ *
+ * ```html
+ * <sigvelo-toggle-icon size="xs"></sigvelo-toggle-icon>
+ * <sigvelo-toggle-icon size="sm"></sigvelo-toggle-icon>
+ * <sigvelo-toggle-icon size="md"></sigvelo-toggle-icon>
+ * <sigvelo-toggle-icon size="lg"></sigvelo-toggle-icon>
+ * <sigvelo-toggle-icon size="xl"></sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Disabling
+ * Use the `disabled` attribute to disable the toggle icon.
+ *
+ * ```html
+ * <sigvelo-toggle-icon disabled></sigvelo-toggle-icon>
+ * <sigvelo-toggle-icon checked disabled></sigvelo-toggle-icon>
+ * ```
+ *
+ * @example Validation
+ * The `required` attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until the toggle icon is checked.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank">
+ *   <sigvelo-toggle-icon
+ *     label="Star this"
+ *     name="star"
+ *     value="1"
+ *     required
+ *   ></sigvelo-toggle-icon>
+ *   <br><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 toggle icon 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="toggle__custom-validation">
+ *   <sigvelo-toggle-icon
+ *     label="Star this"
+ *     name="star"
+ *     value="1"
+ *     required
+ *   ></sigvelo-toggle-icon>
+ *   <br><br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <script type="module">
+ *   import { allDefined } from '/dist/sigvelo.js';
+ *
+ *   await allDefined();
+ *
+ *   const form = document.getElementById('toggle__custom-validation');
+ *   const toggleIcon = form.querySelector('sigvelo-toggle-icon');
+ *
+ *   toggleIcon.setCustomValidity('Not so fast, bubba!');
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid toggle icons using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="toggle__validation-pseudo">
+ *   <sigvelo-toggle-icon
+ *     label="Star this"
+ *     name="star"
+ *     value="1"
+ *     required
+ *   ></sigvelo-toggle-icon>
+ *   <br><br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .toggle__validation-pseudo {
+ *     sigvelo-toggle-icon:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-toggle-icon: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="toggle__validation-custom">
+ *   <sigvelo-toggle-icon
+ *     label="Star this"
+ *     name="star"
+ *     value="1"
+ *     required
+ *   ></sigvelo-toggle-icon>
+ *   <br><br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .toggle__validation-custom {
+ *     sigvelo-toggle-icon:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-toggle-icon:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloToggleIcon extends SigveloFormControlElement {
+  static shadowRootOptions: {
+    delegatesFocus: boolean;
+    clonable?: boolean;
+    customElementRegistry?: CustomElementRegistry | null;
+    mode: ShadowRootMode;
+    serializable?: boolean;
+    slotAssignment?: SlotAssignmentMode;
+  };
+  static formAssociated: boolean;
+  static styles: CSSResultGroup;
+  protected get focusableAnchor(): HTMLButtonElement;
+  button: HTMLButtonElement;
+  isInvalid: boolean;
+  hadUserInteraction: boolean;
+  wasSubmitted: boolean;
+  /** The toggle icon's label. The label won't be displayed, but it will be announced by assistive devices. */
+  label: string;
+  /** The name of the toggle icon. This will be submitted with the form as a name/value pair. */
+  name: string;
+  /** The toggle icon's value. */
+  value: string;
+  /** The toggle icon's checked state. */
+  checked: boolean;
+  /** Disables the toggle icon. */
+  disabled: boolean;
+  /** The checkbox's size. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** The animation to use when toggling. */
+  effect: "fade" | "scale" | "flip-x" | "flip-y" | "translate-x" | "translate-y" | "none";
+  /**
+   * 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 toggle icon required. Form submission will not be allowed until the toggle icon is checked.
+   */
+  required: 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 handleClick;
+  private handleFocus;
+  private handleHostInvalid;
+  /** Sets the form control's validity */
+  private updateValidity;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-toggle-icon": SigveloToggleIcon;
+  }
+}
+//#endregion
+export { SigveloToggleIcon as t };