@cute-widgets/base 20.0.1

package/icon/index.d.ts

@@ -0,0 +1,477 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, AfterViewChecked, OnDestroy, ErrorHandler, Optional } from '@angular/core';
+import { CuteBaseControl } from '@cute-widgets/base/abstract';
+import { RichThemeColor, RelativeSize3, toColorCssClass } from '@cute-widgets/base/core';
+import { HttpClient } from '@angular/common/http';
+import { SafeResourceUrl, SafeHtml, DomSanitizer } from '@angular/platform-browser';
+import { Observable } from 'rxjs';
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+/** Default options for `cute-icon`.  */
+interface CuteIconDefaultOptions {
+    /** Default color of the icon. */
+    color?: RichThemeColor;
+    /** Font set that the icon is a part of. */
+    fontSet?: string;
+}
+/** Injection token to be used to override the default options for `cute-icon`. */
+declare const CUTE_ICON_DEFAULT_OPTIONS: InjectionToken<CuteIconDefaultOptions>;
+/**
+ * Injection token used to provide the current location to `CuteIcon`.
+ * Used to handle server-side rendering and to stub out during unit tests.
+ */
+declare const CUTE_ICON_LOCATION: InjectionToken<CuteIconLocation>;
+/**
+ * Stubbed out location for `CuteIcon`.
+ */
+interface CuteIconLocation {
+    getPathname: () => string;
+}
+/** @docs-private */
+declare function CUTE_ICON_LOCATION_FACTORY(): CuteIconLocation;
+/**
+ * Component to display an icon. It can be used in the following ways:
+ *
+ * - Specify the svgIcon input to load an SVG icon from a URL previously registered with the
+ *   addSvgIcon, addSvgIconInNamespace, addSvgIconSet, or addSvgIconSetInNamespace methods of
+ *   CuteIconRegistry. If the svgIcon value contains a colon, it is assumed to be in the format
+ *   "[namespace]:[name]", if not, the value will be the name of an icon in the default namespace.
+ *   Examples:
+ *     `<cute-icon svgIcon="left-arrow"></cute-icon>
+ *     <cute-icon svgIcon="animals:cat"></cute-icon>`
+ *
+ * - Use a font ligature as an icon by putting the ligature text in the `fontIcon` attribute or the
+ *   content of the `<cute-icon>` component. If you register a custom font class, remember to also
+ *   include the special class `cute-ligature-font`. It is recommended to use the attribute alternative
+ *   to prevent the ligature text from being selectable and to appear in search engine results.
+ *   By default, the `bootstrap-icons` font family is used as described at
+ *   https://icons.getbootstrap.com#install. You can specify an
+ *   alternate font by setting the fontSet input to either the CSS class to apply to use the
+ *   desired font, or to an alias previously registered with CuteIconRegistry.registerFontClassAlias.
+ *   Examples:
+ *     `<cute-icon fontIcon="home"></cute-icon>
+ *     <cute-icon>home</cute-icon>
+ *     <cute-icon fontSet="myfont" fontIcon="sun"></cute-icon>
+ *     <cute-icon fontSet="myfont">sun</cute-icon>`
+ *     <cute-icon fontIcon="myFont:sun"></cute-icon>
+ *
+ * - Specify a font glyph to be included via CSS rules by setting the fontSet input to specify the
+ *   font, and the fontIcon input to specify the icon. Typically, the fontIcon will specify a
+ *   CSS class which causes the glyph to be displayed via a :before selector, as in
+ *   https://fortawesome.github.io/Font-Awesome/examples/
+ *   Example:
+ *     `<cute-icon fontSet="fa-solid" fontIcon="fa-user"></cute-icon>`
+ */
+declare class CuteIcon extends CuteBaseControl implements AfterViewChecked {
+    private _iconRegistry;
+    private _location;
+    private readonly _errorHandler;
+    protected _textContentChanged: boolean;
+    /**
+     * Whether the icon should be inlined, automatically sizing the icon to match the font size of
+     * the element the icon is contained in.
+     */
+    get inline(): boolean;
+    set inline(inline: boolean);
+    private _inline;
+    /** Name of the icon in the SVG icon set. */
+    get svgIcon(): string | undefined;
+    set svgIcon(value: string | undefined);
+    private _svgIcon;
+    /** Font set that the icon is a part of. */
+    get fontSet(): string | undefined;
+    set fontSet(value: string | undefined);
+    private _fontSet;
+    /** Name of an icon within a font set. */
+    get fontIcon(): string | undefined;
+    set fontIcon(value: string | undefined);
+    private _fontIcon;
+    /** Should the font icon name be automatically prefixed if it is not explicitly specified for not `cute-ligature-font` fonts. */
+    autoPrefix: boolean;
+    /** Angle of rotation in degrees. */
+    rotation: number;
+    /** Whether to display an icon as a rounded square feature icon. */
+    featureIcon: RelativeSize3 | "" | undefined;
+    private _previousFontSetClass;
+    private _previousFontIconClass;
+    protected _fontIconPrefixed: string | undefined;
+    _svgName: string | null;
+    _svgNamespace: string | null;
+    /** Keeps track of the current page path. */
+    private _previousPath?;
+    /** Keeps track of the elements and attributes that we've prefixed with the current path. */
+    private _elementsWithExternalReferences?;
+    /** Subscription to the current in-progress SVG icon request. */
+    private _currentIconFetch;
+    constructor(...args: unknown[]);
+    protected generateId(): string;
+    /**
+     * Splits an svgIcon binding value into its icon set and icon name components.
+     * Returns a 2-element array of [(icon set), (icon name)].
+     * The separator for the two fields is ':'. If there is no separator, an empty
+     * string is returned for the icon set and the entire value is returned for
+     * the icon name. If the argument is falsy, returns an array of two empty strings.
+     * Throws an error if the name contains two or more ':' separators.
+     * Examples:
+     *   `'social:cake' -> ['social', 'cake']
+     *   'penguin' -> ['', 'penguin']
+     *   null -> ['', '']
+     *   'a:b:c' -> (throws Error)`
+     */
+    private _splitIconName;
+    ngOnInit(): void;
+    ngAfterViewChecked(): void;
+    ngOnDestroy(): void;
+    protected _usingFontIcon(): boolean;
+    private _setSvgElement;
+    private _clearSvgElement;
+    private _updateFontIconClasses;
+    /**
+     * Cleans up a value to be used as a fontIcon or fontSet.
+     * Since the value ends up being assigned as a CSS class, we
+     * have to trim the value and omit space-separated values.
+     */
+    private _cleanupFontValue;
+    /**
+     * Prepends the current path to all elements that have an attribute pointing to a `FuncIRI`
+     * reference. This is required because WebKit browsers require references to be prefixed with
+     * the current path if the page has a `base` tag.
+     */
+    private _prependPathToReferences;
+    /**
+     * Caches the children of an SVG element that have `url()`
+     * references that we need to prefix with the current path.
+     */
+    private _cacheChildrenWithExternalReferences;
+    /** Sets a new SVG icon with a particular name. */
+    private _updateSvgIcon;
+    protected readonly toColorCssClass: typeof toColorCssClass;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteIcon, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CuteIcon, "cute-icon", ["cuteIcon"], { "color": { "alias": "color"; "required": false; }; "inline": { "alias": "inline"; "required": false; }; "svgIcon": { "alias": "svgIcon"; "required": false; }; "fontSet": { "alias": "fontSet"; "required": false; }; "fontIcon": { "alias": "fontIcon"; "required": false; }; "autoPrefix": { "alias": "autoPrefix"; "required": false; }; "rotation": { "alias": "rotation"; "required": false; }; "featureIcon": { "alias": "featureIcon"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ngAcceptInputType_inline: unknown;
+    static ngAcceptInputType_autoPrefix: unknown;
+    static ngAcceptInputType_rotation: unknown;
+}
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+/** Material icons font CSS classes */
+declare const FS_MATERIAL_ICONS: string[];
+/** Bootstrap icons font CSS classes */
+declare const FS_BOOTSTRAP_ICONS: string[];
+/** FontAwesome icons font CSS classes */
+declare const FS_FONTAWESOME_ICONS: string[];
+/** FontAwesome solid icons font CSS classes */
+declare const FS_FONTAWESOME_SOLID: string[];
+/** FontAwesome regular icons font CSS classes */
+declare const FS_FONTAWESOME_REGULAR: string[];
+/** FontAwesome brand icons font CSS classes */
+declare const FS_FONTAWESOME_BRAND: string[];
+/**
+ * Returns an exception to be thrown in the case when attempting to
+ * load an icon with a name that cannot be found.
+ */
+declare function getCuteIconNameNotFoundError(iconName: string): Error;
+/**
+ * Returns an exception to be thrown when the consumer attempts to use
+ * `<cute-icon>` without including @angular/common/http.
+ */
+declare function getCuteIconNoHttpProviderError(): Error;
+/**
+ * Returns an exception to be thrown when a URL couldn't be sanitized.
+ * @param url URL that was attempted to be sanitized.
+ */
+declare function getCuteIconFailedToSanitizeUrlError(url: SafeResourceUrl): Error;
+/**
+ * Returns an exception to be thrown when a HTML string couldn't be sanitized.
+ * @param literal HTML that was attempted to be sanitized.
+ */
+declare function getCuteIconFailedToSanitizeLiteralError(literal: SafeHtml): Error;
+/** Options that can be used to configure how an icon or the icons in an icon set are presented. */
+interface IconOptions {
+    /** View box to set on the icon. */
+    viewBox?: string;
+    /** Whether to fetch the icon or icon set using HTTP credentials. */
+    withCredentials?: boolean;
+    /** The horizontal size of the icon. */
+    width?: string;
+    /** The vertical size of the icon. */
+    height?: string;
+}
+/**
+ * Function that will be invoked by the icon registry when trying to resolve the
+ * URL from which to fetch an icon. The returned URL will be used to make a request for the icon.
+ */
+type IconResolver = (name: string, namespace: string) => SafeResourceUrl | SafeResourceUrlWithIconOptions | null;
+/** Object that specifies a URL from which to fetch an icon and the options to use for it. */
+interface SafeResourceUrlWithIconOptions {
+    url: SafeResourceUrl;
+    options: IconOptions;
+}
+/**
+ * Service to register and display icons used by the `<cute-icon>` component.
+ * - Registers icon URLs by namespace and name.
+ * - Registers icon set URLs by namespace.
+ * - Registers aliases for CSS classes, for use with icon fonts.
+ * - Loads icons from URLs and extracts individual icons from icon sets.
+ */
+declare class CuteIconRegistry implements OnDestroy {
+    private _httpClient;
+    private _sanitizer;
+    private readonly _errorHandler;
+    private _document;
+    /**
+     * URLs and cached SVG elements for individual icons. Keys are of the format "[namespace]:[icon]".
+     */
+    private _svgIconConfigs;
+    /**
+     * SvgIconConfig objects and cached SVG elements for icon sets, keyed by namespace.
+     * Multiple icon sets can be registered under the same namespace.
+     */
+    private _iconSetConfigs;
+    /** Cache for icons loaded by direct URLs. */
+    private _cachedIconsByUrl;
+    /** In-progress icon fetches. Used to coalesce multiple requests to the same URL. */
+    private _inProgressUrlFetches;
+    /** Map from font identifiers to their CSS class names. Used for icon fonts. */
+    private _fontCssClassesByAlias;
+    /** Registered icon resolver functions. */
+    private _resolvers;
+    /**
+     * The CSS classes to apply when a `<cute-icon>` component has no icon name, url, or font
+     * specified. The default 'bootstrap-icons' value assumes that the bootstrap's icon font has been
+     * loaded as described at https://icons.getbootstrap.com/?q=home#usage
+     */
+    private _defaultFontSetClass;
+    constructor(_httpClient: HttpClient, _sanitizer: DomSanitizer, document: any, _errorHandler: ErrorHandler);
+    /**
+     * Registers an icon by URL in the default namespace.
+     * @param iconName Name under which the icon should be registered.
+     * @param url A value that's safe to use as a URL to load SVG icon
+     * @param options Icon's configuration options
+     */
+    addSvgIcon(iconName: string, url: SafeResourceUrl, options?: IconOptions): this;
+    /**
+     * Registers an icon using an HTML string in the default namespace.
+     * @param iconName Name under which the icon should be registered.
+     * @param literal SVG source of the icon.
+     * @param options Icon's configuration options
+     */
+    addSvgIconLiteral(iconName: string, literal: SafeHtml, options?: IconOptions): this;
+    /**
+     * Registers an icon by URL in the specified namespace.
+     * @param namespace Namespace in which the icon should be registered.
+     * @param iconName Name under which the icon should be registered.
+     * @param url A value that's safe to use as a URL to load SVG icon
+     * @param options Icon's configuration options
+     */
+    addSvgIconInNamespace(namespace: string, iconName: string, url: SafeResourceUrl, options?: IconOptions): this;
+    /**
+     * Registers an icon resolver function with the registry. The function will be invoked with the
+     * name and namespace of an icon when the registry tries to resolve the URL from which to fetch
+     * the icon. The resolver is expected to return a `SafeResourceUrl` that points to the icon,
+     * an object with the icon URL and icon options, or `null` if the icon is not supported. Resolvers
+     * will be invoked in the order in which they have been registered.
+     * @param resolver Resolver function to be registered.
+     */
+    addSvgIconResolver(resolver: IconResolver): this;
+    /**
+     * Registers an icon using an HTML string in the specified namespace.
+     * @param namespace Namespace in which the icon should be registered.
+     * @param iconName Name under which the icon should be registered.
+     * @param literal SVG source of the icon.
+     * @param options Configurable options for the icon
+     */
+    addSvgIconLiteralInNamespace(namespace: string, iconName: string, literal: SafeHtml, options?: IconOptions): this;
+    /**
+     * Registers an icon set by URL in the default namespace.
+     * @param url URL of an icon set
+     * @param options Configurable options
+     */
+    addSvgIconSet(url: SafeResourceUrl, options?: IconOptions): this;
+    /**
+     * Registers an icon set using an HTML string in the default namespace.
+     * @param literal SVG source of the icon set.
+     * @param options Configurable options
+     */
+    addSvgIconSetLiteral(literal: SafeHtml, options?: IconOptions): this;
+    /**
+     * Registers an icon set by URL in the specified namespace.
+     * @param namespace Namespace in which to register the icon set.
+     * @param url URL of an icon set
+     * @param options
+     */
+    addSvgIconSetInNamespace(namespace: string, url: SafeResourceUrl, options?: IconOptions): this;
+    /**
+     * Registers an icon set using an HTML string in the specified namespace.
+     * @param namespace Namespace in which to register the icon set.
+     * @param literal SVG source of the icon set.
+     * @param options
+     */
+    addSvgIconSetLiteralInNamespace(namespace: string, literal: SafeHtml, options?: IconOptions): this;
+    /**
+     * Defines an alias for CSS class names to be used for icon fonts. Creating a `cuteIcon`
+     * component with the alias as the `fontSet` input will cause the class name to be applied
+     * to the `<cute-icon>` element.
+     *
+     * If the registered font is a ligature font, then remember to also include the special
+     * class `cute-ligature-font` to allow the usage via attribute. So register like this:
+     *
+     * ```ts
+     * iconRegistry.registerFontClassAlias('f1', 'font1 cute-ligature-font');
+     * ```
+     *
+     * And use like this:
+     *
+     * ```html
+     * <cute-icon fontSet="f1" fontIcon="home"></cute-icon>
+     * ```
+     *
+     * @param alias Alias for the font.
+     * @param classNames Class names override to be used instead of the alias.
+     */
+    registerFontClassAlias(alias: string, classNames?: string): this;
+    /**
+     * Returns the CSS class name associated with the alias by a previous call to
+     * registerFontClassAlias. If no CSS class has been associated, returns the alias unmodified.
+     */
+    classNameForFontAlias(alias: string): string;
+    /**
+     * Sets the CSS classes to be used for icon fonts when a `<cute-icon>` component does not
+     * have a fontSet input value, and is not loading an icon by name or URL.
+     */
+    setDefaultFontSetClass(...classNames: string[]): this;
+    /**
+     * Returns the CSS classes to be used for icon fonts when a `<cute-icon>` component does not
+     * have a fontSet input value, and is not loading an icon by name or URL.
+     */
+    getDefaultFontSetClass(): string[];
+    /**
+     * Returns an Observable that produces the icon (as an `<svg>` DOM element) from the given URL.
+     * The response from the URL may be cached so this will not always cause an HTTP request, but
+     * the produced element will always be a new copy of the originally fetched icon. (That is,
+     * it will not contain any modifications made to elements previously returned).
+     *
+     * @param safeUrl URL from which to fetch the SVG icon.
+     */
+    getSvgIconFromUrl(safeUrl: SafeResourceUrl): Observable<SVGElement>;
+    /**
+     * Returns an Observable that produces the icon (as an `<svg>` DOM element) with the given name
+     * and namespace. The icon must have been previously registered with addIcon or addIconSet;
+     * if not, the Observable will throw an error.
+     *
+     * @param name Name of the icon to be retrieved.
+     * @param namespace Namespace in which to look for the icon.
+     */
+    getNamedSvgIcon(name: string, namespace?: string): Observable<SVGElement>;
+    ngOnDestroy(): void;
+    /**
+     * Returns the cached icon for a SvgIconConfig if available, or fetches it from its URL if not.
+     */
+    private _getSvgFromConfig;
+    /**
+     * Attempts to find an icon with the specified name in any of the SVG icon sets.
+     * First search the available cached icons for a nested element with a matching name, and
+     * if found copies the element to a new `<svg>` element. If not found, fetches all icon sets
+     * that have not been cached, and searches again after all fetches are completed.
+     * The returned Observable produces the SVG element if possible, and throws
+     * an error if no icon with the specified name can be found.
+     */
+    private _getSvgFromIconSetConfigs;
+    /**
+     * Searches the cached SVG elements for the given icon sets for a nested icon element whose "id"
+     * tag matches the specified name. If found, copies the nested element to a new SVG element and
+     * returns it. Returns null if no matching element is found.
+     */
+    private _extractIconWithNameFromAnySet;
+    /**
+     * Loads the content of the icon URL specified in the SvgIconConfig and creates an SVG element
+     * from it.
+     */
+    private _loadSvgIconFromConfig;
+    /**
+     * Loads the content of the icon set URL specified in the
+     * SvgIconConfig and attaches it to the config.
+     */
+    private _loadSvgIconSetFromConfig;
+    /**
+     * Searches the cached element of the given SvgIconConfig for a nested icon element whose "id"
+     * tag matches the specified name. If found, copies the nested element to a new SVG element and
+     * returns it. Returns null if no matching element is found.
+     */
+    private _extractSvgIconFromSet;
+    /**
+     * Creates a DOM element from the given SVG string.
+     */
+    private _svgElementFromString;
+    /**
+     * Converts an element into an SVG node by cloning all of its children.
+     */
+    private _toSvgElement;
+    /**
+     * Sets the default attributes for an SVG element to be used as an icon.
+     */
+    private _setSvgAttributes;
+    /**
+     * Returns an Observable which produces the string contents of the given icon. Results may be
+     * cached, so future calls with the same URL may not cause another HTTP request.
+     */
+    private _fetchIcon;
+    /**
+     * Registers an icon config by name in the specified namespace.
+     * @param namespace Namespace in which to register the icon config.
+     * @param iconName Name under which to register the config.
+     * @param config Config to be registered.
+     */
+    private _addSvgIconConfig;
+    /**
+     * Registers an icon set config in the specified namespace.
+     * @param namespace Namespace in which to register the icon config.
+     * @param config Config to be registered.
+     */
+    private _addSvgIconSetConfig;
+    /** Parses a config's text into an SVG element. */
+    private _svgElementFromConfig;
+    /** Tries to create an icon config through the registered resolver functions. */
+    private _getIconConfigFromResolvers;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteIconRegistry, [{ optional: true; }, null, { optional: true; }, null]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CuteIconRegistry>;
+}
+/** @docs-private */
+declare function CUTE_ICON_REGISTRY_PROVIDER_FACTORY(parentRegistry: CuteIconRegistry, httpClient: HttpClient, sanitizer: DomSanitizer, errorHandler: ErrorHandler, document?: any): CuteIconRegistry;
+/** @docs-private */
+declare const CUTE_ICON_REGISTRY_PROVIDER: {
+    provide: typeof CuteIconRegistry;
+    deps: (Optional[] | typeof DomSanitizer | typeof ErrorHandler)[];
+    useFactory: typeof CUTE_ICON_REGISTRY_PROVIDER_FACTORY;
+};
+
+declare class CuteIconModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteIconModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<CuteIconModule, never, [typeof CuteIcon], [typeof CuteIcon]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<CuteIconModule>;
+}
+
+export { CUTE_ICON_DEFAULT_OPTIONS, CUTE_ICON_LOCATION, CUTE_ICON_LOCATION_FACTORY, CUTE_ICON_REGISTRY_PROVIDER, CUTE_ICON_REGISTRY_PROVIDER_FACTORY, CuteIcon, CuteIconModule, CuteIconRegistry, FS_BOOTSTRAP_ICONS, FS_FONTAWESOME_BRAND, FS_FONTAWESOME_ICONS, FS_FONTAWESOME_REGULAR, FS_FONTAWESOME_SOLID, FS_MATERIAL_ICONS, getCuteIconFailedToSanitizeLiteralError, getCuteIconFailedToSanitizeUrlError, getCuteIconNameNotFoundError, getCuteIconNoHttpProviderError };
+export type { CuteIconDefaultOptions, CuteIconLocation, IconOptions, IconResolver, SafeResourceUrlWithIconOptions };

package/index.d.ts

@@ -0,0 +1,3 @@
+declare const CUTE_WIDGETS_VERSION: string;
+
+export { CUTE_WIDGETS_VERSION };