@mcp-b/web-components 0.2.0

package/dist/color-picker-wQw8bPsq.d.ts

@@ -0,0 +1,360 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/color-picker/color-picker.d.ts
+/**
+ * <sigvelo-color-picker>
+ *
+ * @summary Provides a customizable interface for selecting a color.
+ * @tag sigvelo-color-picker
+ * @documentation https://design-system.sigvelo.com/docs/components/color-picker
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-button
+ * @dependency sigvelo-copy
+ * @dependency sigvelo-slider
+ * @dependency sigvelo-text-field
+ *
+ * @event sigvelo-change - Emitted when the user commits changes to the color picker's value.
+ * @event sigvelo-input - Emitted when the color picker receives input. This can fire very frequently during dragging, so
+ *  avoid doing expensive operations in the handler. If you don't live feedback, use the `sigvelo-change` event instead.
+ *
+ * @csspart picker - The element the wraps the color picker.
+ * @csspart color-slider - The 2d color slider.
+ * @csspart color-slider-thumb - The color slider's thumb.
+ * @csspart controls - The container that wraps the sliders and preview.
+ * @csspart sliders - The container that wraps the hue and alpha slider.
+ * @csspart hue-slider - The slider that controls the color's hue.
+ * @csspart hue-slider__label - The hue slider's `label` part.
+ * @csspart hue-slider__description - The hue slider's `description` part.
+ * @csspart hue-slider__slider - The hue slider's `slider` part.
+ * @csspart hue-slider__track - The hue slider's `track` part.
+ * @csspart hue-slider__indicator - The hue slider's `indicator` part.
+ * @csspart hue-slider__thumb - The hue slider's `thumb` part.
+ * @csspart alpha-slider - The slider that controls the color's opacity.
+ * @csspart alpha-slider__label - The alpha slider's `label` part.
+ * @csspart alpha-slider__description - The alpha slider's `description` part.
+ * @csspart alpha-slider__slider - The alpha slider's `slider` part.
+ * @csspart alpha-slider__track - The alpha slider's `track` part.
+ * @csspart alpha-slider__indicator - The alpha slider's `indicator` part.
+ * @csspart alpha-slider__thumb - The alpha slider's `thumb` part.
+ * @csspart eye-dropper-button - The eye dropper button, a `<sigvelo-button>` element.
+ * @csspart preview-button - The button that shows a preview of the current color, a `<sigvelo-button>` element.
+ * @csspart color-input - The color input text field, a `<sigvelo-text-field>` element.
+ * @csspart color-input__visual-box - The element that wraps the internal text box.
+ * @csspart color-input__text-box - The internal text box, an `<input>` element.
+ * @csspart swatches - The element that contains swatches.
+ * @csspart swatch - Each individual swatch.
+ *
+ * @cssstate disabled - Applied when the color picker is disabled.
+ * @cssstate focused - Applied when the color picker has focus.
+ *
+ * @example Default
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="#7578c5"
+ *   with-input
+ *   with-alpha
+ *   with-eye-dropper
+ *   swatches="
+ *     #09090b; #71717a; #ef4444; #f97316;
+ *     #f59e0b; #eab308; #84cc16; #22c55e;
+ *     #10b981; #14b8a6; #06b6d4; #3b82f6;
+ *     #6366f1; #a855f7; #d946ef; #ec4899
+ *   "
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * **Note:** This component is a primitive for enabling color selection. It is not a form control, so it will not submit a value to a form. See [color input](/docs/components/color-input) for a color picker suitable for using with forms.
+ *
+ * @example Labels
+ * Use the `label` attribute to provide an accessible label for the color picker. This won't be visible, but it will be read to assistive devices.
+ *
+ * ```html
+ * <sigvelo-color-picker label="Select a color"></sigvelo-color-picker>
+ * ```
+ *
+ * @example Setting an initial value
+ * Use the `value` attribute to provide an initial value for the color picker. You can specify values in a variety of formats as well as CSS colors names. Parsing of color values is very permissive. See the TinyColor docs for more details on acceptable color formats.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="#71e0f3"
+ * >
+ * </sigvelo-color-picker>
+ * ```
+ *
+ * @example Enabling alpha
+ * Add the `with-alpha` attribute to allow the user to adjust opacity.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="#ce238088"
+ *   with-alpha
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * @example Enabling the eye dropper
+ * Add the `with-eye-dropper` attribute to show the eye dropper button, which allows the user to select a color from anywhere on the screen.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   with-eye-dropper
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * **Warning:** The [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is only available in [supportive browsers](https://caniuse.com/?search=eyedropper%20API).
+ *
+ * @example Enabling the color input
+ * Add the `with-input` attribute to show the color input, a text field the user can type into.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="#4716ce"
+ *   with-input
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * @example Showing swatches
+ * Set the `swatches` attribute to one or more semicolon-delimited colors to show as preset swatches below the color picker. You can use any valid CSS color format including hex colors, RGB, HSL, named colors, and more. This is useful for providing users with access to recent colors or a predefined color palette.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   swatches="
+ *     #09090b; #71717a; #ef4444; #f97316;
+ *     #f59e0b; #eab308; #84cc16; #22c55e;
+ *     #10b981; #14b8a6; #06b6d4; #3b82f6;
+ *     #6366f1; #a855f7; #d946ef; #ec4899
+ *   "
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * You can also use any CSS color format in the swatches:
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   swatches="
+ *     rgb(255 0 0);
+ *     hsl(120, 100%, 50%);
+ *     rgb(0 0 255 / 0.5);
+ *     lightblue;
+ *     #ff00ff
+ *   "
+ * ></sigvelo-color-picker>
+ * ```
+ *
+ * @example Setting the format
+ * Use the `format` attribute to set the format of the value. Valid options include `hex` (default), `rgb,` and `hsl`.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="#ffcc00"
+ *   format="rgb"
+ *   with-input
+ *   id="color-picker__format"
+ * ></sigvelo-color-picker>
+ *
+ * <script>
+ *   const colorPicker = document.getElementById('color-picker__format');
+ *
+ *   // This will output an RGB string when the color changes
+ *   colorPicker.addEventListener('sigvelo-change', () => {
+ *     console.log(colorPicker.value);
+ *   });
+ * </script>
+ * ```
+ *
+ * **Note:** You can set the color picker's value using any format and it will automatically be converted to the format specified by the `format` attribute.
+ *
+ * @example Getting the value programmatically
+ * If you need to access the value in a specific format, use the `getValueAs()` method. You can pass `rgb` (default), `hsl`, `hex`, or `hex8` to get a corresponding value.
+ *
+ * For `rgb`, an object with `{ r, g, b, a }` properties will be returned where `r`, `g`, and `b` range from 0-255 and `a` (alpha) ranges from 0–1. For `hsl`, an object with `{ h, s, l, a }` properties will be returned where `h` ranges from 0–360 and `s`, `l`, and `a` range from 0–1. For `hex` and `hex8`, a string in the format of `#RRGGBB` and `#RRGGBBAA` will be returned, respectively.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   value="tomato"
+ *   format="rgb"
+ *   id="color-picker__object"
+ * ></sigvelo-color-picker>
+ *
+ * <script>
+ *   const colorPicker = document.getElementById('color-picker__object');
+ *
+ *   // Outputs two objects when the color changes
+ *   colorPicker.addEventListener('sigvelo-change', () => {
+ *     console.log(
+ *       colorPicker.getValueAs('rgb'),
+ *       colorPicker.getValueAs('hex'),
+ *       colorPicker.getValueAs('hex8'),
+ *       colorPicker.getValueAs('hsl')
+ *     );
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change the color pickers's size.
+ *
+ * ```html
+ * <sigvelo-select label="Select a size" style="max-width: 18rem; margin-block-end: 2rem;">
+ *   <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>
+ *
+ * <sigvelo-color-picker
+ *   size="xs"
+ *   label="Color picker sizes"
+ *   swatches="
+ *     #09090b; #71717a; #ef4444; #f97316;
+ *     #f59e0b; #eab308; #84cc16; #22c55e;
+ *     #10b981; #14b8a6; #06b6d4; #3b82f6;
+ *     #6366f1; #a855f7; #d946ef; #ec4899
+ *   "
+ *   with-input
+ *   with-alpha
+ *   with-eye-dropper
+ *   id="color-picker__size"
+ * ></sigvelo-color-picker>
+ *
+ * <script>
+ *   const colorPicker = document.getElementById('color-picker__size');
+ *   const select = colorPicker.previousElementSibling;
+ *
+ *   select.addEventListener('sigvelo-change', () => {
+ *     colorPicker.size = select.value;
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Disabling
+ * To disable a color picker, add the `disabled` attribute.
+ *
+ * ```html
+ * <sigvelo-color-picker
+ *   label="Select a color"
+ *   disabled
+ *   value="#6366f1"
+ *   with-alpha
+ *   with-input
+ *   with-eye-dropper
+ *   swatches="
+ *     #09090b; #71717a; #ef4444; #f97316;
+ *     #f59e0b; #eab308; #84cc16; #22c55e;
+ *     #10b981; #14b8a6; #06b6d4; #3b82f6;
+ *     #6366f1; #a855f7; #d946ef; #ec4899
+ *   "
+ * ></sigvelo-color-picker>
+ * ```
+ */
+declare class SigveloColorPicker extends SigveloElement {
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  private colorSliderBoundingClientRect;
+  private draggableThumb;
+  private isDragging;
+  private localize;
+  private valueWhenDraggingStarted;
+  private wasValueSetInternally;
+  protected get focusableAnchor(): HTMLElement;
+  private colorSlider;
+  private colorSliderThumb;
+  h: number;
+  s: number;
+  v: number;
+  a: number;
+  colorSliderThumbX: number;
+  colorSliderThumbY: number;
+  hasFocus: boolean;
+  isChangingV: boolean;
+  isChangingS: boolean;
+  inputIsFocused: boolean;
+  displayValue: string;
+  hadUserInteraction: boolean;
+  /**
+   * The color picker's label. This won't be visible, but it will be read to assistive devices so you should always
+   * include one.
+   */
+  label: string;
+  /** The color picker's value. */
+  value: string;
+  /** The format to use for the color's value. */
+  format: "hex" | "rgb" | "hsl";
+  /** Disables the color picker. */
+  disabled: boolean;
+  /** The color picker's size. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /**
+   * One or more semicolon-delimited colors (any valid CSS color format or name) to show as preset swatches below the
+   * color picker.
+   */
+  swatches: string;
+  /** Enables the alpha slider. */
+  withAlpha: boolean;
+  /**
+   * Enables the eye dropper button. Only available in
+   * [supportive browsers](https://caniuse.com/?search=eyedropper%20API).
+   */
+  withEyeDropper: boolean;
+  /** Enables the color value text field. */
+  withInput: boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  private formatHue;
+  private formatAlpha;
+  private handleColorInputBlur;
+  private handleColorInputFocus;
+  private handleColorInputInput;
+  private handleColorSliderBlur;
+  private handleColorSliderThumbKeyDown;
+  private handleEyeDropperClick;
+  private handleFocusIn;
+  private handleFocusOut;
+  private handleHueSliderInput;
+  private handleAlphaSliderInput;
+  /** Sets the color when a swatch is clicked. */
+  private handleSwatchClick;
+  /**
+   * Parses an arbitrary color string and sets the corresponding HSVA values.
+   */
+  private setColorFromString;
+  /** Sets the S and V value based on the pointer's x and y coordinates. */
+  private setColorFromCoordinates;
+  /** Prevent custom events that bubble from propagating outside of the component */
+  private stopPropagation;
+  /** Updates the color slider's thumb position based on S and V. */
+  private updateColorSliderThumbPosition;
+  /** Sets focus to the color picker. */
+  focus(): void;
+  /** Removes focus from the color picker. */
+  blur(): void;
+  /**
+   * Gets the current value as a hex string, a hex8 string, an RGB object, or an HSL object. RBG objects have `r`, `g`,
+   * and `b` properties ranging from 0–255 and an `a` property (representing opacity) that ranges from 0-1. HSL objects
+   * have an `h` property ranging from `0-359` and `s`, `l`, and `a` properties ranging from 0–1.
+   */
+  getValueAs(format?: "hex" | "hex8" | "hsl" | "rgb"): string | import("@ctrl/tinycolor").Numberify<import("@ctrl/tinycolor").HSLA> | import("@ctrl/tinycolor").Numberify<import("@ctrl/tinycolor").RGBA>;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-color-picker": SigveloColorPicker;
+  }
+}
+//#endregion
+export { SigveloColorPicker as t };