vite-awesome-svg-loader/vanilla-integration/index.d.ts

Imports SVGs as source code, base64 and data URI. Preserves stroke width, replaces colors with currentColor. Optimizes SVGs with SVGO. Creates SVG sprites.

import { onSrcUpdate } from 'integration-utils';

export declare type ElementOrSelector = Element | string;

/**
 * Appends given element to the given container
 * @param el Element to append
 * @param to Container
 * @returns Container
 */
export declare function mount(el: Element, to: ElementOrSelector): Element | undefined;

/**
 * Sets attributes of an element
 * @param el Element to set attributes of
 * @param attrs Attributes object
 * @param clear If `true`, all element attributes will be cleared
 */
export declare function setAttrs(el: Element, attrs: Record<string, any>, clear?: boolean): void;

/**
 * Sets style properties, works with CSS variables
 * @param el Element to set property of
 * @param prop Property to set, for example: `minHeight`, `--my-var`
 * @param value Value of a property
 */
export declare function setStyleProperty(el: HTMLElement, prop: string, value: string | undefined): void;

/**
 * Basic SVG icon, extends {@link SvgImage}.
 *
 * Usage:
 *
 * ```ts
 * import iconSrc from "./path/to/icon.svg";
 *
 * const icon = new SvgIcon(iconSrc, ".my-container") // Create and mount icon
 *   .setContainerAttrs({ title: "My icon" }) // Set container attributes
 *   .setColor("red") // Set icon color to red
 *   .setColorTransition("0.2s ease-out"); // Change icon color transition
 * ```
 *
 * ### Internal API
 *
 * You can use this API to extend `SvgIcon`. This API is the same as in {@link SvgImage}, but with additional methods.
 *
 * Use {@link SvgIcon._updateWrapperBeforeUserAttrsSet}, {@link SvgIcon._updateWrapperAfterUserAttrsSet} to set custom
 * wrapper (`<span>`) attributes.
 *
 * {@link SvgIcon._updateSvgBeforeUserAttrsSet} should call `super._updateSvgBeforeUserAttrsSet()`.
 */
export declare class SvgIcon extends SvgImage {
    protected _span: HTMLSpanElement;
    protected _size: string | undefined;
    protected _color: string | undefined;
    protected _colorTransition: string | undefined;
    constructor(src: string, mountTo?: ElementOrSelector);
    mount(to: ElementOrSelector): this;
    unmount(): this;
    protected _updateSvgBeforeUserAttrsSet(): void;
    /**
     * Sets wrapper (`<span>`) element attributes.
     *
     * **Warning**: you can't change class, size, color and color transition using this method
     *
     * @param attrs Attributes to set
     * @returns this
     */
    setWrapperAttrs(attrs: Record<string, any>): this;
    /**
     * Called before user-provided attributes are set. You can use this function to set custom wrapper (`<span>`) attributes.
     */
    protected _updateWrapperBeforeUserAttrsSet(): void;
    /**
     * Called after user-provided attributes are set. You can use this function to set custom wrapper (`<span>`) attributes.
     */
    protected _updateWrapperAfterUserAttrsSet(): void;
    protected _setWrapperClass(): void;
    /**
     * @returns Wrapper (`<span>`) element
     */
    getWrapper(): HTMLSpanElement;
    /**
     * Sets icon size. Empty string or `undefined` unsets size.
     * @param size Size to set, for example: `"24px"`, `"1rem"`
     * @returns this
     */
    setSize(size: string | undefined): this;
    /**
     * @returns Current icon size or empty string, if size is unset
     */
    getSize(): string;
    /**
     * Sets icon color. Empty string or `undefined` unsets color.
     * @param color  Color to set, for example: `"red"`, `"var(--icon-color)"`.
     * @returns this
     */
    setColor(color: string | undefined): this;
    /**
     * @returns Current icon color or empty string, if color is unset
     */
    getColor(): string;
    /**
     * Sets icon color transition. This transition is applied when icon color is changed.
     * @param transition Transition to set, for example: `"0.3s linear"`, `"var(--icon-transition)"`
     * @returns this
     */
    setColorTransition(transition?: string): this;
    /**
     * @returns Current icon color transition or empty string, if transition is unset
     */
    getColorTransition(): string;
}

/**
 * Basic SVG image. Implements SVG sprites.
 *
 * Will create `<svg>` element that contains all symbols, add passed source code to it and reuse it later.
 *
 * ### Basic usage
 *
 * ```ts
 * import imageSrc from "./path/to/image.svg";
 * import anotherImageSrc from "./path/to/another/image.svg";
 * import { SvgImage } from "vite-awesome-svg-loader/vanilla-integration";
 *
 * const container = document.createElement("div"); // Where to mount SVG
 * const image = new SvgImage(imageSrc, container); // Create image and mount it to the container
 * image.setSvgElAttrs({ id: "my-svg-symbol" }); // Change <svg> element attributes
 * image.setUseElAttrs({ className: "my-svg-symbol-use-el" }); // Change <use> element attributes
 * image.setSrc(anotherImageSrc); // Change SVG source code
 * console.log(image.getSrc()); // Get and print image source code
 * console.log(image.getContainer()); // Get and print image container
 * console.log(image.getSvgEl()); // Get and print image <svg> element
 * console.log(image.getUseEl()); // Get and print image <use> element
 * image.unmount(); // Remove image from the container
 *
 * // All operations are chainable, so you can do this:
 *
 * const image2 = new SvgImage(imageSrc)
 *   .mount(container)
 *   .setSvgElAttrs({ id: "my-svg-symbol" })
 *   .setUseElAttrs({ className: "my-svg-symbol-use-el" });
 * ```
 *
 * ### Internal API
 *
 * You can use this API to extend `SvgImage`.
 *
 * Use `constructor()` and {@link SvgImage#mount} to change component markup.
 *
 * Use {@link SvgImage._updateSvgBeforeUserAttrsSet},
 * {@link SvgImage._updateSvgAfterUserAttrsSet},
 * {@link SvgImage._updateUseElBeforeUserAttrsSet},
 * {@link SvgImage._updateUseElAfterUserAttrsSet} hooks to set custom elements attributes.
 *
 * You probably don't need to override required element's attributes. If you actually need to do so, override
 * {@link SvgImage._updateSvgEl}
 *
 * @param src SVG source code
 * @param mountTo Element or selector of an element to mount image to. If not provided, image won't be mounted.
 */
export declare class SvgImage {
    /**
     * User-provided source code
     */
    protected _src: string | undefined;
    protected _container: Element | undefined;
    protected readonly _svgEl: SVGElement;
    protected readonly _useEl: SVGUseElement;
    /**
     * User-provided attributes
     */
    protected _svgAttrs: Record<string, any>;
    /**
     * User-provided attributes
     */
    protected _useElAttrs: Record<string, any>;
    /**
     * Last src update result
     */
    protected _updateSrcRes: ReturnType<typeof onSrcUpdate>;
    constructor(src: string, mountTo?: ElementOrSelector);
    /**
     * Mounts image to the given element
     * @param to Element or selector of an element to mount image to
     * @returns this
     */
    mount(to: ElementOrSelector): this;
    /**
     * Removes image from the container
     * @returns this
     */
    unmount(): this;
    /**
     * Sets `<svg>` element attributes. It won't remove id, class and style.
     * @param attrs Attributes to set
     * @returns this
     */
    setSvgElAttrs(attrs: Record<string, any>): this;
    /**
     * Updates SVG element: sets SVG source code, clears previous attributes, sets new attributes
     * @returns this
     */
    protected _updateSvgEl(): this;
    /**
     * Called before user-provided attributes are set. You can use this function to set custom SVG element attributes.
     */
    protected _updateSvgBeforeUserAttrsSet(): void;
    /**
     * Called after user-provided attributes are set. You can use this function to set custom SVG element attributes.
     */
    protected _updateSvgAfterUserAttrsSet(): void;
    /**
     * Sets `<use>` element attributes. It won't remove id, class and style.
     * @param attrs Attributes to set
     * @returns this
     */
    setUseElAttrs(attrs: Record<string, any>): this;
    /**
     * Updates `<use>` element attributes
     * @returns this
     */
    protected _updateUseEl(): this;
    /**
     * Called before user-provided attributes are set. You can use this function to set custom `<use>` element attributes.
     */
    protected _updateUseElBeforeUserAttrsSet(): void;
    /**
     * Called after user-provided attributes are set. You can use this function to set custom `<use>` element attributes.
     */
    protected _updateUseElAfterUserAttrsSet(): void;
    /**
     * Sets SVG source code
     * @param src SVG source code
     * @returns this
     */
    setSrc(src: string): this;
    /**
     * @returns SVG source code
     */
    getSrc(): string | undefined;
    /**
     * @returns A container of this image, or `undefined`, if image is not mounted
     */
    getContainer(): Element | undefined;
    /**
     * Returns `<svg>` element.
     *
     * To assign attributes, use {@link setSvgElAttrs} instead.
     *
     * @returns `<svg>` element
     */
    getSvgEl(): SVGElement;
    /**
     * Returns `<use>` element.
     *
     * To assign attributes, use {@link setSvgElAttrs} instead.
     *
     * @returns `<use>` element
     */
    getUseEl(): SVGUseElement;
}

export { }