igniteui-webcomponents 7.3.0-beta.0 → 7.3.0

package/components/color-picker/color-picker.d.ts

@@ -0,0 +1,261 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { IgcBaseComboBoxComponent } from '#internals/mixins/combo-box.js';
+import type { AbstractConstructor } from '#internals/mixins/constructor.js';
+import type { ColorFormat, ColorPickerMode } from '../types.js';
+export interface IgcColorPickerEventMap {
+    igcOpening: CustomEvent<void>;
+    igcOpened: CustomEvent<void>;
+    igcClosing: CustomEvent<void>;
+    igcClosed: CustomEvent<void>;
+    igcInput: CustomEvent<string>;
+    igcChange: CustomEvent<string>;
+}
+declare const IgcColorPickerComponent_base: import("#internals/mixins/constructor.js").Constructor<import("../../internals/mixins/forms/types.js").FormRequiredInterface & import("../../internals/mixins/forms/types.js").FormAssociatedElementInterface> & import("#internals/mixins/constructor.js").Constructor<import("#internals/mixins/event-emitter.js").EventEmitterInterface<IgcColorPickerEventMap>> & AbstractConstructor<IgcBaseComboBoxComponent>;
+/**
+ * Color input component.
+ *
+ * The user picks a color with the HSV saturation/value canvas, the hue slider
+ * and the optional alpha slider. The user can also type a color string: hex,
+ * rgb(a), hsl(a) or a named CSS color.
+ *
+ * The component supports pre-defined swatches and the native EyeDropper API,
+ * where the browser provides one. The anchor is a trigger button
+ * (`mode="default"`) or an editable text field (`mode="input"`).
+ *
+ * @element igc-color-picker
+ *
+ * @slot value-missing - Renders content when the required validation fails.
+ * @slot custom-error - Renders content when setCustomValidity(message) is set.
+ * @slot invalid - Renders content when the component is in invalid state (validity.valid = false).
+ * @slot helper-text - Renders content below the picker.
+ *
+ * @fires igcOpening - Emitted just before the picker dropdown is open.
+ * @fires igcOpened - Emitted after the picker dropdown is open.
+ * @fires igcClosing - Emitted just before the picker dropdown is closed.
+ * @fires igcClosed - Emitted after closing the picker dropdown.
+ * @fires igcInput - Emitted when the value of the component is changed.
+ * @fires igcChange - Emitted when the value of the component is committed.
+ *
+ * @csspart anchor - The trigger element that opens the picker (the button in default mode, or the swatch prefix in input mode).
+ * @csspart empty - Applied alongside `anchor` when no color value is set, rendering a checkered background.
+ * @csspart label - The label rendered above the anchor in default mode.
+ * @csspart picker - The popover container holding the canvas, sliders, inputs and swatches.
+ * @csspart main-row - The row containing the hue slider and the copy/eyedropper buttons.
+ * @csspart alpha-row - The row containing the alpha slider and input, rendered when `show-alpha` is set.
+ * @csspart inputs-row - The row containing the format select and the color value input.
+ * @csspart buttons - The wrapper around the copy and eyedropper buttons.
+ * @csspart hue - The hue slider.
+ * @csspart alpha - The alpha slider.
+ * @csspart copy - The button that copies the current color value to the clipboard.
+ * @csspart eye-dropper - The button that activates the EyeDropper API.
+ * @csspart format-select - The select control used to switch the color string format.
+ * @csspart swatches - The container of the pre-defined color swatches.
+ * @csspart swatch - An individual color swatch button.
+ */
+export default class IgcColorPickerComponent extends IgcColorPickerComponent_base {
+    static readonly tagName = "igc-color-picker";
+    static styles: import("lit").CSSResult[];
+    static register(): void;
+    protected get __validators(): import("../../internals/validators.js").Validator<IgcColorPickerComponent>[];
+    protected readonly _slots: import("#internals/controllers/slot.js").SlotController<"invalid" | "helper-text" | "[default]" | "value-missing" | "custom-error">;
+    protected readonly _rootClickController: import("#internals/controllers/root-click.js").RootClickController;
+    protected readonly _formValue: import("#internals/mixins/forms/form-value.js").FormValue<string>;
+    private readonly _alphaRef;
+    private readonly _alphaInputRef;
+    private readonly _canvasRef;
+    private readonly _hueRef;
+    private readonly _anchorRef;
+    private readonly _supportsEyeDropper;
+    private _color;
+    private _oldValue;
+    /** The last value written for each host custom property. */
+    private readonly _appliedProperties;
+    private readonly _helperText;
+    private get _isInputMode();
+    /**
+     * The label of the component.
+     *
+     * In `mode="input"` the component forwards the label to the anchor input.
+     * In `mode="default"` it renders the label as a separate element.
+     * @attr label
+     */
+    label?: string;
+    /**
+     * The value of the component as a CSS color string. Accepts hex, rgb(a),
+     * hsl(a) and named colors.
+     *
+     * An empty, whitespace-only or invalid string clears the value.
+     *
+     * @attr value
+     */
+    set value(value: string);
+    get value(): string;
+    /**
+     * Sets the color format of the string value.
+     *
+     * A format change renders `value` in the new notation. The color does not
+     * change, so the component emits no `igcInput` or `igcChange`.
+     *
+     * @attr format
+     * @default 'hex'
+     */
+    format: ColorFormat;
+    /**
+     * Whether to hide the format picker buttons.
+     *
+     * @attr hide-formats
+     * @default false
+     */
+    hideFormats: boolean;
+    /**
+     * Whether to show the alpha slider and input.
+     *
+     * @attr show-alpha
+     * @default false
+     */
+    showAlpha: boolean;
+    /**
+     * The mode of the color picker.
+     *
+     * In `"default"` mode the anchor is a trigger button. In `"input"` mode the
+     * anchor is an editable text field with a color swatch prefix. The prefix
+     * also opens the picker.
+     *
+     * @attr mode
+     * @default 'default'
+     */
+    mode: ColorPickerMode;
+    /**
+     * Pre-defined color strings. The component renders them as clickable
+     * swatches below the picker controls. A click on a swatch commits its color
+     * as the value.
+     */
+    swatches: string[];
+    constructor();
+    protected update(props: PropertyValues<this>): void;
+    protected updated(props: PropertyValues<this>): void;
+    protected formResetCallback(): void;
+    private _handleClosing;
+    private _handleKeyboardClosing;
+    private _handleFocusIn;
+    private _handleFocusOut;
+    private _handleCanvasColorPicked;
+    private _handleHueValueChange;
+    private _handleAlphaSliderValueChange;
+    /**
+     * Rewrites the alpha field as `<digits>%` after each edit.
+     *
+     * The `%` is part of the value and not a suffix element, so the browser
+     * treats it as editable text. This handler normalizes the result of an edit
+     * instead of a filter on the keystrokes in `beforeinput`. The `%` then
+     * behaves as a literal for each way that text reaches the field: typing,
+     * paste, drop, composition, undo and autofill. Of these, `beforeinput`
+     * carries `data` only for typing.
+     */
+    private _handleAlphaInputEdit;
+    /**
+     * Keeps the caret and the selection inside the digits.
+     *
+     * The trailing `%` is a literal. Without this handler the caret goes after
+     * the `%` on focus, on a click past the text, and after a shifted selection
+     * extends over it. The handler therefore runs on `keyup` as well as on
+     * `focusin` and `click`. Text after the `%` falls outside the number, and the
+     * parse discards it.
+     */
+    private _handleAlphaInputCaret;
+    /**
+     * Steps the alpha by one percent.
+     *
+     * The step applies to the color and not to the text of the field. This keeps
+     * a held arrow key correct. The key downs repeat faster than a render, so the
+     * text of the field can be stale.
+     *
+     * The handler writes the new text and does not leave it to the render, so
+     * that the caret does not move. A value assignment puts the caret behind the
+     * `%`. A write from the render applies one frame after the keypress, which
+     * the user sees as a jump forward and back.
+     */
+    private _handleAlphaInputSpin;
+    /**
+     * Holds the caret at the `%`. Without this handler the caret steps past the
+     * `%`, and `keyup` pulls it back. This is the frame-late jump that
+     * {@link _handleAlphaInputSpin} describes.
+     */
+    private _handleAlphaInputCaretForward;
+    private _handleAlphaInputChange;
+    private _handleFormatChange;
+    private _handleColorInputChange;
+    private _handleEyeDropperClick;
+    private _handleCopy;
+    private _handleSwatchClick;
+    /**
+     * The current color with its alpha, in a notation that is independent of
+     * `format`.
+     */
+    private get _alphaColor();
+    /**
+     * The current color with an opaque alpha channel.
+     *
+     * The swatch preview paints this color over one half of its surface, and
+     * {@link _alphaColor} over the other half. A translucent color is then shown
+     * next to its opaque form. At full alpha the two halves are identical and the
+     * split is invisible, so opaque colors need no separate branch.
+     *
+     * This value is defined also with no color value. An empty color is white,
+     * which is where the alpha ramp and the canvas marker belong before the first
+     * pick. The anchor keeps its "no color" mark, because {@link _previewStyle}
+     * uses {@link _alphaColor}, which stays empty.
+     */
+    private get _opaqueColor();
+    /** The alpha channel as the whole percentage that both alpha controls use. */
+    private get _alphaPercent();
+    /** The pure hue that the saturation/value plane and the hue thumb use. */
+    private get _currentColor();
+    /**
+     * Mirrors the colors that the stylesheet needs onto the host.
+     *
+     * `update()` drives this, and not the handlers that change the color. It
+     * therefore also runs for the first render. A picker with no value calls none
+     * of those handlers, and the plane would keep the stylesheet fallback instead
+     * of its actual hue.
+     */
+    private _applyColorProperties;
+    /**
+     * Replaces the whole text of the alpha field and puts the caret in front of
+     * the `%` by default.
+     */
+    private _writeAlphaText;
+    private _setAlpha;
+    private _updateColor;
+    private _syncCanvasPosition;
+    private _emitInputEvent;
+    private _renderCanvasGradient;
+    private _renderHueSlider;
+    private _renderIconButton;
+    private _renderPickerButtons;
+    private _renderAlphaRow;
+    private _renderSelect;
+    private _renderInputsRow;
+    private _renderSwatches;
+    private get _anchorParts();
+    /**
+     * The swatch preview style that both anchors use.
+     *
+     * `--_color-preview` paints the opaque color over the left half.
+     * `--_alpha-preview` paints the color with its real alpha over the whole
+     * surface. Do not transpose the two. See the `swatch-preview` mixin.
+     */
+    private _previewStyle;
+    private _renderButtonAnchor;
+    private _renderInputAnchor;
+    private _renderAnchor;
+    private _renderHelperText;
+    private _renderPicker;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'igc-color-picker': IgcColorPickerComponent;
+    }
+}
+export {};