@mcp-b/web-components 0.2.0

package/dist/slide-activator-D7bBz69E.d.ts

@@ -0,0 +1,429 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/slide-activator/slide-activator.d.ts
+/**
+ * <sigvelo-slide-activator>
+ *
+ * @summary Gives users a draggable thumb that must be moved to the end of its track to trigger an action.
+ * @tag sigvelo-slide-activator
+ * @documentation https://design-system.sigvelo.com/docs/components/slide-activator
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ *
+ * @slot label - The slide activator's label. For plain-text labels, you can use the `label` attribute instead.
+ * @slot activated-label - The label to show when activated. For plain-text labels, you can use the `activated-label`
+ *  attribute instead.
+ * @slot thumb - The thumb element that users drag. Defaults to a double chevron icon if not provided.
+ *
+ * @event sigvelo-before-activate - Emitted when the control will activate. Calling `event.preventDefault()` will prevent
+ *  the activation from occurring.
+ * @event sigvelo-activate - Emitted immediately after the control is activated.
+ * @event sigvelo-before-deactivate - Emitted when the control will deactivate. Calling `event.preventDefault()` will
+ *  prevent the deactivation from occurring.
+ * @event sigvelo-deactivate - Emitted immediately after the control is deactivated.
+ * @event sigvelo-progress - Emitted as the slider progresses. Use `event.details.percent` to see how far along it is.
+ *
+ * @csspart thumb - The slide activator's thumb.
+ * @csspart label - The slide activator's label.
+ *
+ * @cssproperty [--border-radius=var(--sigvelo-radius-lg)] - The control's border radius. We use a CSS custom
+ *  property so we can properly calculate the inset border radius for the thumb.
+ * @cssproperty [--thumb-width=4em] - The thumb's width.
+ * @cssproperty [--thumb-inset=0.125em] - The thumb's inset from the host element.
+ * @cssproperty [--shimmer-color] - The color to use as a base for the shimmer animation.
+ * @cssproperty [--thumb-position=(read-only)] - A read-only property that moves from 0 to 1 as the user slides the
+ *  thumb to activate the control. Useful as a hook to transition background styles based on the thumb's position.
+ *
+ * @cssstate activated - Applied briefly when the slide activator has been activated.
+ * @cssstate dragging - Applied when the slide activator is dragging.
+ * @cssstate pressing - Applied when the user is pressing a key to activate the slide activator.
+ * @cssstate disabled - Applied when the slide activator is disabled.
+ *
+ * @example Default
+ * Slide activators are unidirectional. Once activated by the user, they can only be reset programmatically. The deliberate friction in activation, followed by a locked state, helps prevent accidental triggering and ensures intentional actions are committed.
+ *
+ * ```html
+ * <sigvelo-slide-activator
+ *   label="Slide to activate"
+ *   activated-label="Activated"
+ *   attention="shimmer"
+ *   id="slide-activator__overview"
+ *   style="max-width: 340px;"
+ * >
+ * </sigvelo-slide-activator>
+ *
+ * <script>
+ *   const slideActivator = document.getElementById('slide-activator__overview');
+ *
+ *   // When the component is activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     // Deactivate it for the demo after two seconds
+ *     setTimeout(() => slideActivator.activated = false, 2000);
+ *   });
+ * </script>
+ * ```
+ *
+ * **Note:** For demonstration purposes, most of the examples on this page reset themselves shortly after activation.
+ *
+ * @example Handling activation
+ * You should always provide a label using the `label` attribute to describe the control to users. In most cases, you'll also want to show a separate label when the control is activated. Use the `activated-label` attribute to do this. For labels that require HTML, use the respective slots instead.
+ *
+ * When the control is activated, a `sigvelo-before-activate` event will be emitted. You can call `event.preventDefault()` to prevent the activation if needed. Once the control is finally activated, a subsequent `sigvelo-activate` event will be emitted. If you deactivate the control programmatically, the corresponding `sigvelo-before-deactivate` and `sigvelo-deactivate` events will be emitted.
+ *
+ * You can use these events to execute code to run on activation and deactivation.
+ *
+ * ```html
+ * <div id="slide-activator__activation">
+ *   <sigvelo-slide-activator
+ *     label="Slide to activate"
+ *     activated-label="Activated"
+ *   ></sigvelo-slide-activator>
+ *
+ *   <sigvelo-button disabled>Deactivate</sigvelo-button>
+ * </div>
+ *
+ * <script>
+ *   const container = document.getElementById('slide-activator__activation');
+ *   const slideActivator = container.querySelector('sigvelo-slide-activator');
+ *   const button = container.querySelector('sigvelo-button');
+ *
+ *   // Deactivate it
+ *   button.addEventListener('click', () => {
+ *     slideActivator.activated = false;
+ *   });
+ *
+ *   // Update the button state when activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     button.disabled = false;
+ *   });
+ *
+ *   // Update the button state when deactivated
+ *   slideActivator.addEventListener('sigvelo-deactivate', () => {
+ *     button.disabled = true;
+ *   });
+ * </script>
+ *
+ * <style>
+ *   #slide-activator__activation {
+ *     sigvelo-slide-activator {
+ *       max-width: 340px;
+ *       margin-bottom: 1rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * @example Tracking slide progress
+ * The readonly `--thumb-position` custom property will be set to a value between 0 and 1 on the host element, representing how far the user has slid the thumb toward activation. You can use this to transition styles at different thresholds.
+ *
+ * Additionally, a `sigvelo-progress` event will be emitted while the user slides the thumb. This event contains an `event.detail.percent` payload with a corresponding number between 0 and 1.
+ *
+ * ```html
+ * <div id="slide-activator__progress">
+ *   <sigvelo-slide-activator
+ *     label="Slide to place order"
+ *     activated-label="Order received"
+ *   ></sigvelo-slide-activator>
+ *   Progress: <sigvelo-number number="0" type="percent"></sigvelo-number>
+ * </div>
+ *
+ * <script>
+ *   const container = document.getElementById('slide-activator__progress');
+ *   const slideActivator = container.querySelector('sigvelo-slide-activator');
+ *   const progress = container.querySelector('sigvelo-number');
+ *
+ *   // Update progress as the user drags
+ *   slideActivator.addEventListener('sigvelo-progress', event => {
+ *     progress.number = event.detail.percent * 100;
+ *   });
+ *
+ *   // Update the label and reset the demo when component is activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     // Deactivate it for the demo after two seconds
+ *     setTimeout(() => slideActivator.activated = false, 2000);
+ *   });
+ * </script>
+ *
+ * <style>
+ *   #slide-activator__progress {
+ *     sigvelo-slide-activator {
+ *       max-width: 340px;
+ *       margin-bottom: 1rem;
+ *       transition: none;
+ *
+ *       <!-- Change the background color as the user slides the thumb -->
+ *       background-color:
+ *         color-mix(
+ *           in oklab,
+ *           var(--sigvelo-color-neutral-bg-muted) calc((1 - var(--thumb-position)) * 100%),
+ *           var(--sigvelo-color-success-bg) calc(var(--thumb-position) * 100%)
+ *         );
+ *
+ *       <!-- Change the text color when activated -->
+ *       &:state(activated) {
+ *         color: var(--sigvelo-color-success-text-on-bg);
+ *       }
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * @example Customizing icons
+ * Use the `thumb` slot to provide your own icon(s) for the thumb. If you want to change the icon depending on the activation state, use the `:state(activated)` selector to show/hide the respective icons with CSS.
+ *
+ * ```html
+ * <sigvelo-slide-activator
+ *   label="Slide to unlock"
+ *   activated-label="Unlocked"
+ *   id="slide-activator__icons"
+ * >
+ *   <sigvelo-icon slot="thumb" name="lock"></sigvelo-icon>
+ *   <sigvelo-icon slot="thumb" name="lock-open-2"></sigvelo-icon>
+ * </sigvelo-slide-activator>
+ *
+ * <script>
+ *   const slideActivator = document.getElementById('slide-activator__icons');
+ *
+ *   // When the component is activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     // Deactivate it for the demo after two seconds
+ *     setTimeout(() => slideActivator.activated = false, 2000);
+ *   });
+ * </script>
+ *
+ * <style>
+ *   sigvelo-slide-activator#slide-activator__icons {
+ *     max-width: 340px;
+ *
+ *     <!-- Show locked until activated, then show unlocked -->
+ *     &:state(activated) sigvelo-icon[name="lock"],
+ *     &:not(:state(activated)) sigvelo-icon[name="lock-open-2"] {
+ *       display: none;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * @example Drawing attention
+ * Set the `attention` attribute to `shimmer` to provide a subtle visual hint via animation. The animation pauses when the slide activator is activated.
+ *
+ * ```html
+ * <sigvelo-slide-activator
+ *   label="Slide to release cats"
+ *   activated-label="Releasing cats…"
+ *   attention="shimmer"
+ *   id="slide-activator__attention"
+ * >
+ *   <sigvelo-icon slot="thumb" name="cat"></sigvelo-icon>
+ * </sigvelo-slide-activator>
+ *
+ * <script>
+ *   const slideActivator = document.getElementById('slide-activator__attention');
+ *
+ *   // When the component is activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     // Deactivate it for the demo after two seconds
+ *     setTimeout(() => slideActivator.activated = false, 2000);
+ *   });
+ * </script>
+ *
+ * <style>
+ *   sigvelo-slide-activator#slide-activator__attention {
+ *     max-width: 340px;
+ *
+ *     <!-- Head tilt-->
+ *     sigvelo-icon {
+ *       transition: 300ms rotate ease-out;
+ *     }
+ *
+ *     &:state(activated) sigvelo-icon {
+ *       rotate: 20deg;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * @example Disabling
+ * Use the `disabled` attribute to disable the slide activator. The control cannot be activated or focused while disabled.
+ *
+ * ```html
+ * <sigvelo-slide-activator
+ *   label="Slide to activate"
+ *   disabled
+ *   style="max-width: 340px;"
+ * ></sigvelo-slide-activator>
+ * ```
+ *
+ * @example Styling slide activators
+ * Slide activators come with a simple, minimal appearance. Feel free to customize them with your own styles, icons, and animations.
+ *
+ * ```html
+ * <sigvelo-slide-activator
+ *   label="Empty the box"
+ *   activated-label="Emptying…"
+ *   attention="shimmer"
+ *   id="slide-activator__styling"
+ * >
+ *   <sigvelo-icon slot="thumb" name="arrow-right"></sigvelo-icon>
+ *   <sigvelo-spinner slot="thumb"></sigvelo-spinner>
+ * </sigvelo-slide-activator>
+ *
+ * <script>
+ *   const slideActivator = document.getElementById('slide-activator__styling');
+ *
+ *   // When the component is activated
+ *   slideActivator.addEventListener('sigvelo-activate', () => {
+ *     // Deactivate it for the demo after two seconds
+ *     setTimeout(() => slideActivator.activated = false, 2000);
+ *   });
+ * </script>
+ *
+ * <style>
+ *   sigvelo-slide-activator#slide-activator__styling {
+ *     --border-radius: var(--sigvelo-radius-full);
+ *     --thumb-width: 5rem;
+ *     --thumb-inset: 0.25rem;
+ *     --shimmer-color: #fff2;
+ *     --current-color:
+ *       color-mix(
+ *         in oklab,
+ *         firebrick calc(var(--thumb-position) * 100%),
+ *         #0284c7 calc((1 - var(--thumb-position)) * 100%)
+ *       );
+ *     height: 4rem;
+ *     max-width: 340px;
+ *     background-color: var(--current-color);
+ *     font-weight: var(--sigvelo-font-weight-semibold);
+ *     color: white;
+ *
+ *     &:focus-within {
+ *       outline-color: var(--current-color) !important;
+ *     }
+ *
+ *     <!-- Animate when activated -->
+ *     &:state(activated) {
+ *       animation: pulse 0.6s ease-out forwards;
+ *     }
+ *
+ *     <!-- Slightly bigger icons -->
+ *     sigvelo-icon {
+ *       font-size: 1.5rem;
+ *     }
+ *
+ *     sigvelo-spinner {
+ *       --indicator-color: firebrick;
+ *       --track-color: color-mix(in oklab, firebrick, transparent 80%);
+ *     }
+ *
+ *     <!-- Show arrow icon until activated, then show trash -->
+ *     &:state(activated) sigvelo-icon[name="arrow-right"],
+ *     &:not(:state(activated)) sigvelo-spinner {
+ *       display: none;
+ *     }
+ *
+ *     <!-- Bounce animation for fun -->
+ *     sigvelo-icon[name="arrow-right"] {
+ *       animation: bounce-right 1s infinite;
+ *
+ *       <!-- Flip for RTL -->
+ *       &:dir(rtl) {
+ *         scale: -1;
+ *       }
+ *     }
+ *   }
+ *
+ *   @keyframes bounce-right {
+ *     0%, 100% {
+ *       transform: translateX(0);
+ *     }
+ *     50% {
+ *       transform: translateX(6px);
+ *     }
+ *   }
+ *
+ *   @keyframes pulse {
+ *     0% {
+ *       transform: scale(1);
+ *       filter: brightness(1);
+ *     }
+ *     20% {
+ *       transform: scale(1.05);
+ *       filter: brightness(1.2);
+ *     }
+ *     40% {
+ *       transform: scale(0.95);
+ *       filter: brightness(0.9);
+ *     }
+ *     60% {
+ *       transform: scale(1.02);
+ *       filter: brightness(1.1);
+ *     }
+ *     80% {
+ *       transform: scale(0.98);
+ *       filter: brightness(0.95);
+ *     }
+ *     100% {
+ *       transform: scale(1);
+ *       filter: brightness(1);
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloSlideActivator extends SigveloElement {
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  private draggableThumb;
+  private dragStartX;
+  private hostBoundingClientRect;
+  private lastDispatchedPercentage;
+  private localize;
+  private isKeyPressStale;
+  private keyPressInterval;
+  private keyPressTimeout;
+  thumb: HTMLElement;
+  isDragging: boolean;
+  isPressing: boolean;
+  thumbPosition: number;
+  /**
+   * The label to show in the slide activator's track. If you need to provide HTML in the label, use the `label` slot
+   * instead.
+   */
+  label: string;
+  /**
+   * The label to show when the control is activated. If omitted, the regular label will be shown. If you need to
+   * provide HTML in the label, use the `label` slot instead.
+   */
+  activatedLabel: string;
+  /** Reflects when the control is activated. Remove this attribute to deactivate it. */
+  activated: boolean;
+  /** Disables the control. */
+  disabled: boolean;
+  /** Draws attention to the track by adding a subtle animation. */
+  attention: "shimmer";
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  /** Attempts to activate the component. */
+  private activate;
+  /** Restores the control to its original deactivated state. */
+  private deactivate;
+  private cleanupTimers;
+  /** Updates the thumb position from a pointer's x coordinate */
+  private handleDrag;
+  private handleKeyDown;
+  private handleKeyUp;
+  /** Updates the thumb position and dispatches the `sigvelo-progress` event. */
+  private setThumbPosition;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-slide-activator": SigveloSlideActivator;
+  }
+}
+//#endregion
+export { SigveloSlideActivator as t };