@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-color-picker.d.ts

@@ -0,0 +1,442 @@
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import * as _angular_core from '@angular/core';
+import { AfterViewInit, OnInit, ElementRef, Signal } from '@angular/core';
+import { MlvSignalFormControlBase } from '@malva-ui/core/form-utils';
+import { BooleanInput } from '@angular/cdk/coercion';
+
+/**
+ * Represents a color in HSL + Alpha space.
+ * All values are stored internally in this format for canvas rendering.
+ */
+interface MlvHsla {
+    /** Hue: 0–360 */
+    h: number;
+    /** Saturation: 0–100 */
+    s: number;
+    /** Lightness: 0–100 */
+    l: number;
+    /** Alpha: 0–1 */
+    a: number;
+}
+/** Represents a color in RGBA space. */
+interface MlvRgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The color input mode for the text tabs. */
+type MlvColorInputMode = 'hex' | 'rgb' | 'hsl';
+/**
+ * Clamps a number to the range [min, max].
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Rounds a number to a given number of decimal places.
+ */
+declare function round(value: number, decimals?: number): number;
+/**
+ * Converts HSL (0-360, 0-100, 0-100) to RGB (0-255 each).
+ */
+declare function hslToRgb(h: number, s: number, l: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Converts RGB (0-255) to HSL (0-360, 0-100, 0-100).
+ */
+declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+/**
+ * Converts a hex string (#RRGGBB or #RRGGBBAA) to RGBA.
+ * Returns null if the hex string is invalid.
+ */
+declare function hexToRgba(hex: string): MlvRgba | null;
+/**
+ * Converts RGBA to a hex string.
+ * Includes alpha channel as #RRGGBBAA if alpha < 1.
+ */
+declare function rgbaToHex(r: number, g: number, b: number, a: number): string;
+/**
+ * Converts an HSLa object to a CSS color string.
+ * Produces hsla() when alpha < 1, otherwise hsl().
+ */
+declare function hslaToString(color: MlvHsla): string;
+/**
+ * Converts an HSLa object to an RGBA object.
+ */
+declare function hslaToRgba(color: MlvHsla): MlvRgba;
+/**
+ * Converts an HSLa object to a hex string (#RRGGBB or #RRGGBBAA).
+ */
+declare function hslaToHex(color: MlvHsla): string;
+/**
+ * Strictly parses a supported concrete CSS color string into an HSLa object.
+ * Supports: #RGB, #RGBA, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), hsla().
+ * Returns `null` when parsing fails.
+ *
+ * CSS custom-property references are intentionally not resolved here because
+ * their value depends on an element's computed cascade. Use
+ * {@link isCssColorValue} when validating editable color text.
+ */
+declare function tryParseCssColor(css: string): MlvHsla | null;
+/**
+ * Returns whether a string is a supported concrete color or a syntactically
+ * valid CSS custom-property color reference.
+ *
+ * An unresolved `var(--name)` is valid editable input: the browser resolves it
+ * later against the element's computed cascade. Optional fallbacks are
+ * validated recursively, including nested `var(...)` references.
+ */
+declare function isCssColorValue(css: string): boolean;
+/**
+ * Parses any supported concrete CSS color string into an HSLa object.
+ * Returns a default black color if parsing fails.
+ */
+declare function parseCssColor(css: string): MlvHsla;
+/**
+ * Converts an HSLa object to a CSS color string in the specified mode.
+ */
+declare function hslaToModeString(color: MlvHsla, mode: MlvColorInputMode): string;
+/**
+ * Converts an HSLa color to a CSS rgba() string (used internally for canvas rendering).
+ */
+declare function hslaToRgbaString(color: MlvHsla): string;
+
+/**
+ * The MlvColorPicker provides an HSL/HEX/RGB color picker with:
+ * - A 2D saturation-lightness canvas (pointer-draggable)
+ * - A hue slider
+ * - An opacity slider
+ * - Input mode tabs for HEX, RGB, and HSL
+ * - Signal, reactive, and template-driven forms integration producing a CSS color string
+ */
+declare class MlvColorPicker extends MlvSignalFormControlBase<string> implements AfterViewInit, OnInit {
+    private static readonly _ALL_FORMATS;
+    /** The CSS color string used by all Angular forms APIs. */
+    readonly value: _angular_core.ModelSignal<string>;
+    /** @protected Injected i18n translations for the color picker. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvColorPickerI18n>;
+    /** Whether to show the opacity slider. Defaults to true. */
+    readonly showOpacity: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** The default input mode displayed when the picker opens. */
+    readonly defaultMode: _angular_core.InputSignal<MlvColorInputMode>;
+    /** Available color formats, in display order. */
+    readonly supportedFormats: _angular_core.InputSignal<readonly MlvColorInputMode[]>;
+    /** Emits the CSS color string whenever the color changes. */
+    readonly colorChange: _angular_core.OutputEmitterRef<string>;
+    /** @private Current color in HSLA space. */
+    protected readonly _hsla: _angular_core.WritableSignal<MlvHsla>;
+    /** @private Current input mode for the text inputs. */
+    protected readonly _inputMode: _angular_core.WritableSignal<MlvColorInputMode>;
+    /** Formats normalized to supported unique values, preserving caller order. */
+    protected readonly _supportedFormats: _angular_core.Signal<readonly MlvColorInputMode[]>;
+    /** @private The current raw hex input string (kept separate to avoid cursor-jump on typing). */
+    protected readonly _hexInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw red channel input. */
+    protected readonly _rgbRInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw green channel input. */
+    protected readonly _rgbGInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw blue channel input. */
+    protected readonly _rgbBInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw alpha input for RGB mode. */
+    protected readonly _rgbAInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw hue input for HSL mode. */
+    protected readonly _hslHInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw saturation input for HSL mode. */
+    protected readonly _hslSInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw lightness input for HSL mode. */
+    protected readonly _hslLInput: _angular_core.WritableSignal<string>;
+    /** @private The current raw alpha input for HSL mode. */
+    protected readonly _hslAInput: _angular_core.WritableSignal<string>;
+    /** @private Whether the canvas pointer is currently being dragged. */
+    protected readonly _canvasDragging: _angular_core.WritableSignal<boolean>;
+    /**
+     * @private Computed CSS string for the hue thumb gradient stop.
+     * Used to show the pure hue color on the canvas gradient background.
+     */
+    protected readonly _hueColor: _angular_core.Signal<string>;
+    /**
+     * @private Computed CSS color for the opacity slider checkerboard preview.
+     */
+    protected readonly _rgbaString: _angular_core.Signal<string>;
+    /** @private Reference to the canvas element. */
+    protected readonly _canvasRef: _angular_core.Signal<ElementRef<HTMLCanvasElement> | undefined>;
+    /** @private Reference to the canvas container for size calculation. */
+    protected readonly _canvasContainerRef: _angular_core.Signal<ElementRef<HTMLDivElement> | undefined>;
+    /** @private DestroyRef for cleanup. */
+    private readonly _destroyRef;
+    /**
+     * @private The canvas bounding rect captured once at pointerdown and reused
+     * for every pointermove of that drag, avoiding a forced layout read
+     * (`getBoundingClientRect`) on every move. Cleared on pointerup.
+     */
+    private _dragRect;
+    constructor();
+    ngOnInit(): void;
+    ngAfterViewInit(): void;
+    /** Whether the control holds a clearable value — The picker always holds a colour, so a clearable X (if enabled) is always actionable. */
+    readonly hasValue: _angular_core.Signal<boolean>;
+    /** @private Synchronizes the color editor from an external value. */
+    private _applyValue;
+    /**
+     * @private Draws the 2D saturation-lightness canvas for the current hue.
+     * The canvas shows a gradient from white (top-left) to the pure hue (top-right)
+     * to black (bottom).
+     */
+    protected _drawCanvas(): void;
+    /**
+     * @private Handles pointer down on the SL canvas.
+     * Begins drag and updates color immediately.
+     */
+    protected _onCanvasPointerDown(event: PointerEvent): void;
+    /**
+     * @private Converts a pointer position on the canvas to saturation/lightness values.
+     */
+    private _updateColorFromCanvas;
+    /**
+     * @private Handles hue slider input change.
+     */
+    protected _onHueChange(event: Event): void;
+    /**
+     * @private Handles opacity slider input change.
+     */
+    protected _onOpacityChange(event: Event): void;
+    /**
+     * @private Switches the active input mode tab.
+     */
+    protected _setInputMode(mode: string): void;
+    /**
+     * @private Handles hex input changes.
+     */
+    protected _onHexInput(event: Event): void;
+    /** @private Updates red channel from input. */
+    protected _onRgbRInput(event: Event): void;
+    /** @private Updates green channel from input. */
+    protected _onRgbGInput(event: Event): void;
+    /** @private Updates blue channel from input. */
+    protected _onRgbBInput(event: Event): void;
+    /** @private Updates alpha channel from RGB mode input. */
+    protected _onRgbAInput(event: Event): void;
+    /**
+     * @private Parses all RGB inputs and updates the internal HSLA state.
+     */
+    private _applyRgbInputs;
+    /** @private Updates hue from HSL input. */
+    protected _onHslHInput(event: Event): void;
+    /** @private Updates saturation from HSL input. */
+    protected _onHslSInput(event: Event): void;
+    /** @private Updates lightness from HSL input. */
+    protected _onHslLInput(event: Event): void;
+    /** @private Updates alpha from HSL mode input. */
+    protected _onHslAInput(event: Event): void;
+    /**
+     * @private Parses all HSL inputs and updates internal state.
+     */
+    private _applyHslInputs;
+    /**
+     * @private Refreshes the in-progress text-mirror signals for the requested
+     * channels from the canonical `_hsla()` state. Called after every external
+     * mutation (canvas drag, hue slider, opacity slider, external value write) to
+     * keep the unfocused channels in sync without clobbering the channel the
+     * user is currently typing into.
+     */
+    private _syncFromHsla;
+    /**
+     * @private Emits the current color through the forms model and colorChange output.
+     */
+    private _emitChange;
+    /**
+     * @private Returns the current CSS color string for a given mode.
+     * Used by the template to display the color in the active mode.
+     */
+    protected _getColorString(mode: MlvColorInputMode): string;
+    /**
+     * @private Returns opacity value as 0-100 integer for the opacity slider.
+     */
+    protected _getOpacityPercent(): number;
+    /**
+     * @private Returns the hue value for the hue slider.
+     */
+    protected _getHue(): number;
+    /**
+     * @private Canvas thumb left position.
+     * The canvas uses HSV space (x = HSV saturation, y = 1 − HSV value).
+     * Converts the stored HSL to HSV to get the correct x coordinate.
+     */
+    protected _getThumbLeft(): string;
+    /**
+     * @private Canvas thumb top position.
+     * y = 1 − HSV value (top = bright/white, bottom = black).
+     */
+    protected _getThumbTop(): string;
+    /**
+     * @private Converts the current HSLA state to HSV (saturation + value),
+     * matching the coordinate system used by the SL canvas gradient.
+     *
+     * The canvas draws:
+     *   - Horizontal: white (left) → pure hue (right)  → x = HSV saturation
+     *   - Vertical:   full brightness (top) → black (bottom) → y = 1 − HSV value
+     *
+     * HSL → HSV:
+     *   V  = L + S · min(L, 1−L)
+     *   Sv = V > 0 ? 2·(1 − L/V) : 0
+     */
+    private _hslToHsv;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvColorPicker, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvColorPicker, "mlv-color-picker", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "showOpacity": { "alias": "showOpacity"; "required": false; "isSignal": true; }; "defaultMode": { "alias": "defaultMode"; "required": false; "isSignal": true; }; "supportedFormats": { "alias": "supportedFormats"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "colorChange": "colorChange"; }, never, never, true, never>;
+}
+
+/**
+ * Input-like CSS color control that opens the full `mlv-color-picker` in a
+ * connected popup with a light-dismiss backdrop.
+ *
+ * The editable draft stays separate from the committed forms value. Valid
+ * concrete colors and `var(--custom-property)` references commit on blur or
+ * popup close by default; `live` publishes every valid draft immediately.
+ * Invalid drafts roll back to the most recent valid draft.
+ */
+declare class MlvColorPickerPopup extends MlvSignalFormControlBase<string> {
+    /** The committed CSS color string used by all Angular forms APIs. */
+    readonly value: _angular_core.ModelSignal<string>;
+    /** Visual trigger presentation. Field mode preserves the input-like control. */
+    readonly presentation: _angular_core.InputSignal<"field" | "swatch" | "icon">;
+    /** Two-way bindable connected-overlay state. */
+    readonly opened: _angular_core.ModelSignal<boolean>;
+    /** Emits after the detached picker panel has opened. */
+    readonly afterOpened: _angular_core.OutputEmitterRef<void>;
+    /** Emits after the detached picker panel has closed and torn down. */
+    readonly afterClosed: _angular_core.OutputEmitterRef<void>;
+    /** Whether to show the opacity slider inside the picker. */
+    readonly showOpacity: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** The default input mode for the picker's text tabs. */
+    readonly defaultMode: _angular_core.InputSignal<MlvColorInputMode>;
+    /** Available picker formats, in display order. */
+    readonly supportedFormats: _angular_core.InputSignal<readonly MlvColorInputMode[]>;
+    /** Whether every valid draft is published immediately. */
+    readonly live: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Emits when user interaction commits a new CSS color string. */
+    readonly colorChange: _angular_core.OutputEmitterRef<string>;
+    /** Whether the committed value is non-empty and can be cleared. */
+    readonly hasValue: Signal<boolean>;
+    /**
+     * Suppresses the wrapper-owned clear affordance while readonly. Disabled
+     * wrappers already suppress pointer interaction through their shared state.
+     */
+    readonly ownsClearButton: Signal<boolean>;
+    /** @protected Injected i18n translations for the color picker. */
+    protected readonly _i18n: Signal<_malva_ui_i18n.MlvColorPickerI18n>;
+    /** @protected Localized copy used by the swatch-mode clear action. */
+    protected readonly _formI18n: Signal<_malva_ui_i18n.MlvFormUtilsI18n>;
+    /** @private Resolver for ICU parameterized i18n strings. */
+    private readonly _resolver;
+    /** @protected Whether the connected popup is open. */
+    /** Keep the wrapper focus treatment active while its popup is visible. */
+    readonly focused: Signal<boolean>;
+    /** @protected Editable text that has not necessarily been committed. */
+    protected readonly _draftValue: _angular_core.WritableSignal<string>;
+    /** @private Most recent valid draft used for invalid-input rollback. */
+    private readonly _lastValidDraft;
+    /** @protected Concrete color used to initialize the visual picker. */
+    protected readonly _pickerValue: _angular_core.WritableSignal<string>;
+    /** @protected Stable id linked from the input's `aria-controls`. */
+    protected readonly _panelId: string;
+    /** @protected Stable id used by the input's `aria-describedby`. */
+    /**
+     * @protected Resolved accessible name for the swatch button, e.g.
+     * "Pick color: #ff0000".
+     */
+    protected readonly _pickColorLabel: Signal<string>;
+    /** @private Native input used for synchronous rollback of invalid drafts. */
+    private readonly _inputRef;
+    /** @private Rounded color square used for computed CSS-variable resolution. */
+    private readonly _fieldSwatchColorRef;
+    /** @private Swatch-only presentation color layer. */
+    private readonly _swatchTriggerColorRef;
+    /** @private Field-mode swatch button used for keyboard focus restoration. */
+    private readonly _fieldSwatchButtonRef;
+    /** @private Swatch-mode Malva trigger used by detached composition. */
+    private readonly _swatchTriggerRef;
+    /** @private Field-mode detached picker surface. */
+    private readonly _fieldPanelRef;
+    /** @private Swatch-mode detached picker surface. */
+    private readonly _swatchPanelRef;
+    /** Public trigger element for toolbar/composite registration. */
+    readonly triggerElement: Signal<HTMLElement | null>;
+    /** Public detached panel element for overlay ownership registration. */
+    readonly panelElement: Signal<HTMLElement | null>;
+    /** @private Locates the first tabbable picker control for keyboard opening. */
+    private readonly _tabbable;
+    /** @private Whether the next completed close should restore swatch focus. */
+    private _restoreSwatchFocus;
+    /** @private Whether `afterOpened` should transfer focus into the picker. */
+    private _focusPickerAfterOpen;
+    /** @private Whether the shared overlay is attached or playing its leave animation. */
+    private _popupAttached;
+    /** @private Previous open state used to detect every close request once. */
+    private _wasOpen;
+    /** @private Reopens after a click/focus that occurs during the leave animation. */
+    private _reopenAfterClose;
+    constructor();
+    /** @protected Stores text input without publishing a partial forms value. */
+    protected _onInput(event: Event): void;
+    /** @protected Opens the popup when the editable field receives focus. */
+    protected _onInputFocus(): void;
+    /**
+     * @protected Reopens after Escape when the input retained focus (and thus
+     * cannot emit another native focus event).
+     */
+    protected _onInputClick(): void;
+    /** @protected Commits or rolls back the draft when focus leaves the input. */
+    protected _onInputBlur(): void;
+    /** @protected Closes the popup from the input on Escape. */
+    protected _onInputKeydown(event: KeyboardEvent): void;
+    /**
+     * @protected Opens from the rounded square. Keyboard activation opts into
+     * focus transfer; pointer activation leaves focus on the trigger.
+     */
+    protected _openFromSwatch(focusPicker?: boolean): void;
+    /** @private Opens the connected popup and refreshes the picker's color. */
+    private _open;
+    /** @protected Performs post-attach focus work requested by keyboard opening. */
+    protected _onPopupOpened(): void;
+    /** @protected Restores swatch focus only for keyboard/panel close flows. */
+    protected _onPopupClosed(): void;
+    /** @protected Closes from the panel and commits the current draft. */
+    protected _onPanelEscape(event: Event): void;
+    /** @protected Clears the committed forms value through the shared X button. */
+    protected _clearValue(): void;
+    /** @protected Updates the picker draft and optionally publishes it live. */
+    protected _onColorChange(cssColor: string): void;
+    /** @private Commits valid/empty input or the most recent valid draft. */
+    private _commitDraft;
+    /**
+     * @private Restores local state from the committed value without publishing.
+     */
+    private _restoreCommittedValue;
+    /** @private Synchronizes all visual draft consumers without committing. */
+    private _setDraftValue;
+    /** @private Publishes one committed user change across forms and output. */
+    private _commitValue;
+    /**
+     * @private Initializes the visual picker without replacing the committed
+     * source string. Concrete formats pass through. CSS variables are resolved
+     * from the swatch's computed background in the trigger's cascade.
+     */
+    private _syncPickerValue;
+    /** @private Moves focus into the picker after a keyboard swatch activation. */
+    private _focusPicker;
+    /** @private Current presentation's rendered colour layer. */
+    private _swatchColorElement;
+    /** @private Whether disabled/readonly state blocks all user mutation. */
+    private _isInert;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvColorPickerPopup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvColorPickerPopup, "mlv-color-picker-popup", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "presentation": { "alias": "presentation"; "required": false; "isSignal": true; }; "opened": { "alias": "opened"; "required": false; "isSignal": true; }; "showOpacity": { "alias": "showOpacity"; "required": false; "isSignal": true; }; "defaultMode": { "alias": "defaultMode"; "required": false; "isSignal": true; }; "supportedFormats": { "alias": "supportedFormats"; "required": false; "isSignal": true; }; "live": { "alias": "live"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "opened": "openedChange"; "afterOpened": "afterOpened"; "afterClosed": "afterClosed"; "colorChange": "colorChange"; }, never, ["*"], true, never>;
+}
+
+export { MlvColorPicker, MlvColorPickerPopup, clamp, hexToRgba, hslToRgb, hslaToHex, hslaToModeString, hslaToRgba, hslaToRgbaString, hslaToString, isCssColorValue, parseCssColor, rgbToHsl, rgbaToHex, round, tryParseCssColor };
+export type { MlvColorInputMode, MlvHsla, MlvRgba };