carbon-components-angular/icon/icon.service.d.ts

Next generation components

/**
 *
 * carbon-angular v0.0.0 | icon.service.d.ts
 *
 * Copyright 2014, 2024 IBM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0

 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


import * as i0 from "@angular/core";
/**
 * An object that represents a parsed icon
 */
export interface IconDescriptor {
    /**
     * The element to render. For the root this is `svg`
     */
    elem: string;
    /**
     * An object of attributes to apply to the element.
     *
     * The type here is non-exhaustive.
     */
    attrs: {
        xmlns: string;
        viewBox: string;
        fill: string;
        width: string;
        height: string;
        [x: string]: string;
    };
    /**
     * The content (children) of the element as an array of `IconDescriptor`s
     * (usually without a few fields, namely `name` and `size`)
     */
    content: IconDescriptor[];
    /**
     * The name of the icon.
     *
     * Needed by the icon service.
     */
    name: string;
    /**
     * The size of the icon in pixels.
     *
     * Needed by the icon service.
     */
    size: number;
    /**
     * Optional. A string representation of the compiled svg.
     * If missing the icon service will add this.
     */
    svg?: string;
}
/**
 * Abstract class that represent a cache of icons.
 *
 * The actual caching mechanism will be implementation specific,
 * but it's likely a good idea to key by the icons name and/or size.
 * Icon name and size will always be strings, and they will be the two consistent
 * identifiers of an icon. For the purposes of storage additonal descriptor properties may
 * be used, but the name and size are the only ones guarenteed to be passed for lookup purposes.
 */
export declare abstract class IconCache {
    /**
     * Finds and returns an icon based on it's name and size
     */
    abstract get(name: string, size: string): object;
    /**
     * stores an icon descriptor to the cache
     */
    abstract set(name: string, size: string, descriptor: object): void;
}
/**
 * Custom error for when a name can't be found
 */
export declare class IconNameNotFoundError extends Error {
    constructor(name: string);
}
/**
 * Custom error for when a specific size can't be found
 */
export declare class IconSizeNotFoundError extends Error {
    constructor(size: string, name: string);
}
/**
 * Concrete implementation of `IconCache` as a simple in memory cache
 */
export declare class IconMemoryCache extends IconCache {
    private iconMap;
    get(name: string, size: string): object;
    set(name: string, size: string, descriptor: object): void;
}
/**
 * The icon service is a singleton service responsible for registering and retriving icons from `@carbon/icons`.
 *
 * It's important to register icons before use. It's reccommended to register your icons early, likely in your app.component.
 *
 * To allow for improved tree shaking _do not_ import all the icons from `@carbon/icons` and register them.
 * Instead register only the icons in use by your application. If your application makes use of lazy loaded
 * modules you may also lazy load the icons used in that module by registering them early on in that module.
 *
 * `ngOnInit` should be sufficiantly early to register icons.
 *
 * Example:
 * ```
 * import { Accessibility16 } from "@carbon/icons";
 *
 * // ...
 *
 * class MyComponent implements OnInit {
 * 	constructor(protected iconService: IconService) {}
 *
 * 	// ...
 *
 * 	ngOnInit() {
 * 		this.iconService.register(Accessibility16);
 * 	}
 *
 * 	// ...
 * }
 * ```
 *
 * If needed it is possible to register an icon under a different name, via `registerAs`.
 */
export declare class IconService {
    private iconCache;
    /**
     * Registers an array of icons based on the metadata provided by `@carbon/icons`
     */
    registerAll(descriptors: object[]): void;
    /**
     * Registers an icon based on the metadata provided by `@carbon/icons`
     */
    register(descriptor: object): void;
    /**
     * Registers an icon based on a uniqe name and metadata provided by `@carbon/icons`
     */
    registerAs(name: string, descriptor: object): void;
    /**
     * Gets an icon, converts it to a string, and caches the result
     */
    get(name: string, size: string): IconDescriptor;
    /**
     * Configure various service settings (caching strategy ...)
     */
    configure(options: {
        cache: IconCache;
    }): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<IconService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<IconService>;
}