igniteui-webcomponents 6.5.1 → 7.0.0

package/components/icon/icon-state.broadcast.js

@@ -1,45 +1,55 @@
 import { createIconDefaultMap } from './registry/default-map.js';
 import { ActionType } from './registry/types.js';
 export class IconsStateBroadcast {
-    static { this.origin = 'igniteui-webcomponents'; }
-    constructor(collections, refsCollection) {
-        this.collections = collections;
-        this.refsCollection = refsCollection;
-        this.create();
-        globalThis.addEventListener('pageshow', () => this.create());
-        globalThis.addEventListener('pagehide', () => this.dispose());
+    static { this._origin = 'igniteui-webcomponents'; }
+    constructor(iconsCollection, iconReferences) {
+        this._channel = null;
+        this._iconsCollection = iconsCollection;
+        this._iconReferences = iconReferences;
+        globalThis.addEventListener('pageshow', this);
+        globalThis.addEventListener('pagehide', this);
+        this._create();
     }
     send(data) {
-        if (this.channel) {
-            this.channel.postMessage(data);
+        this._channel?.postMessage(data);
+    }
+    handleEvent(event) {
+        switch (event.type) {
+            case 'message':
+                this._syncState(event);
+                break;
+            case 'pageshow':
+                this._create();
+                break;
+            case 'pagehide':
+                this._dispose();
+                break;
         }
     }
-    handleEvent({ data }) {
-        if (data.actionType !== ActionType.SyncState ||
-            data.origin === IconsStateBroadcast.origin) {
+    _syncState({ data: { actionType, origin }, }) {
+        if (actionType !== ActionType.SyncState ||
+            origin === IconsStateBroadcast._origin) {
             return;
         }
         this.send({
             actionType: ActionType.SyncState,
-            collections: this.getUserSetCollection(this.collections).toMap(),
-            references: this.getUserRefsCollection(this.refsCollection).toMap(),
-            origin: IconsStateBroadcast.origin,
+            collections: this._getUserSetCollection(this._iconsCollection),
+            references: this._getUserRefsCollection(this._iconReferences),
+            origin: IconsStateBroadcast._origin,
         });
     }
-    create() {
-        if (!this.channel) {
-            this.channel = new BroadcastChannel('ignite-ui-icon-channel');
-            this.channel.addEventListener('message', this);
+    _create() {
+        if (!this._channel) {
+            this._channel = new BroadcastChannel('ignite-ui-icon-channel');
+            this._channel.addEventListener('message', this);
         }
     }
-    dispose() {
-        if (this.channel) {
-            this.channel.removeEventListener('message', this);
-            this.channel.close();
-            this.channel = null;
-        }
+    _dispose() {
+        this._channel?.removeEventListener('message', this);
+        this._channel?.close();
+        this._channel = null;
     }
-    getUserRefsCollection(collections) {
+    _getUserRefsCollection(collections) {
         const userSetIcons = createIconDefaultMap();
         for (const [collectionKey, collection] of collections.entries()) {
             for (const [iconKey, icon] of collection.entries()) {
@@ -50,7 +60,7 @@ export class IconsStateBroadcast {
         }
         return userSetIcons;
     }
-    getUserSetCollection(collections) {
+    _getUserSetCollection(collections) {
         const userSetIcons = createIconDefaultMap();
         for (const [collectionKey, collection] of collections.entries()) {
             if (collectionKey === 'internal') {

package/components/icon/icon-state.broadcast.js.map

@@ -1 +1 @@
-{"version":3,"file":"icon-state.broadcast.js","sourceRoot":"","sources":["../../../src/components/icon/icon-state.broadcast.ts"],"names":[],"mappings":"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","sourcesContent":["import { createIconDefaultMap } from './registry/default-map.js';\nimport type {\n  BroadcastIconsChangeMessage,\n  IconMeta,\n  IconsCollection,\n  SvgIcon,\n} from './registry/types.js';\nimport { ActionType } from './registry/types.js';\n\nexport class IconsStateBroadcast {\n  private channel!: BroadcastChannel | null;\n  private collections: IconsCollection<SvgIcon>;\n  private refsCollection: IconsCollection<IconMeta>;\n  private static readonly origin = 'igniteui-webcomponents';\n\n  constructor(\n    collections: IconsCollection<SvgIcon>,\n    refsCollection: IconsCollection<IconMeta>\n  ) {\n    this.collections = collections;\n    this.refsCollection = refsCollection;\n    this.create();\n\n    globalThis.addEventListener('pageshow', () => this.create());\n    globalThis.addEventListener('pagehide', () => this.dispose());\n  }\n\n  public send(data: BroadcastIconsChangeMessage) {\n    if (this.channel) {\n      this.channel.postMessage(data);\n    }\n  }\n\n  public handleEvent({ data }: MessageEvent<BroadcastIconsChangeMessage>) {\n    // no need to sync with other wc icon services, just with angular elements\n    if (\n      data.actionType !== ActionType.SyncState ||\n      data.origin === IconsStateBroadcast.origin\n    ) {\n      return;\n    }\n\n    this.send({\n      actionType: ActionType.SyncState,\n      collections: this.getUserSetCollection(this.collections).toMap(),\n      references: this.getUserRefsCollection(this.refsCollection).toMap(),\n      origin: IconsStateBroadcast.origin,\n    });\n  }\n\n  private create() {\n    if (!this.channel) {\n      this.channel = new BroadcastChannel('ignite-ui-icon-channel');\n      this.channel.addEventListener('message', this);\n    }\n  }\n\n  /* c8 ignore next 7 */\n  private dispose() {\n    if (this.channel) {\n      this.channel.removeEventListener('message', this);\n      this.channel.close();\n      this.channel = null;\n    }\n  }\n\n  private getUserRefsCollection(collections: IconsCollection<IconMeta>) {\n    const userSetIcons = createIconDefaultMap<string, IconMeta>();\n    for (const [collectionKey, collection] of collections.entries()) {\n      for (const [iconKey, icon] of collection.entries()) {\n        if (icon.external) {\n          userSetIcons.getOrCreate(collectionKey).set(iconKey, icon);\n        }\n      }\n    }\n    return userSetIcons;\n  }\n\n  private getUserSetCollection(collections: IconsCollection<SvgIcon>) {\n    const userSetIcons = createIconDefaultMap<string, SvgIcon>();\n\n    for (const [collectionKey, collection] of collections.entries()) {\n      if (collectionKey === 'internal') {\n        continue;\n      }\n      for (const [iconKey, icon] of collection.entries()) {\n        userSetIcons.getOrCreate(collectionKey).set(iconKey, icon);\n      }\n    }\n    return userSetIcons;\n  }\n}\n"]}
+{"version":3,"file":"icon-state.broadcast.js","sourceRoot":"","sources":["../../../src/components/icon/icon-state.broadcast.ts"],"names":[],"mappings":"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","sourcesContent":["import { createIconDefaultMap } from './registry/default-map.js';\nimport type {\n  BroadcastIconsChangeMessage,\n  IconMeta,\n  IconsCollection,\n  SvgIcon,\n} from './registry/types.js';\nimport { ActionType } from './registry/types.js';\n\ntype IconBroadcastEvent =\n  | MessageEvent<BroadcastIconsChangeMessage>\n  | PageTransitionEvent;\n\n/**\n * Manages cross-context synchronization of icon state using the BroadcastChannel API.\n *\n * @remarks\n * This class enables icon registry state to be shared between different browsing contexts\n * (e.g., iframes, tabs) within the same origin. It specifically handles synchronization\n * with Angular elements that may be running in separate contexts.\n *\n * The broadcast channel is automatically created on page show and disposed on page hide\n * to properly handle bfcache (back/forward cache) scenarios.\n */\nexport class IconsStateBroadcast {\n  private static readonly _origin = 'igniteui-webcomponents';\n\n  private readonly _iconsCollection: IconsCollection<SvgIcon>;\n  private readonly _iconReferences: IconsCollection<IconMeta>;\n\n  private _channel: BroadcastChannel | null = null;\n\n  /**\n   * Creates an instance of IconsStateBroadcast.\n   *\n   * @param iconsCollection - The collection of registered SVG icons.\n   * @param iconReferences - The collection of icon references/aliases.\n   */\n  constructor(\n    iconsCollection: IconsCollection<SvgIcon>,\n    iconReferences: IconsCollection<IconMeta>\n  ) {\n    this._iconsCollection = iconsCollection;\n    this._iconReferences = iconReferences;\n\n    globalThis.addEventListener('pageshow', this);\n    globalThis.addEventListener('pagehide', this);\n\n    this._create();\n  }\n\n  /**\n   * Sends a message to other browsing contexts via the broadcast channel.\n   */\n  public send(data: BroadcastIconsChangeMessage): void {\n    this._channel?.postMessage(data);\n  }\n\n  /** @internal */\n  public handleEvent(event: IconBroadcastEvent): void {\n    switch (event.type) {\n      case 'message':\n        this._syncState(event as MessageEvent<BroadcastIconsChangeMessage>);\n        break;\n      case 'pageshow':\n        this._create();\n        break;\n      case 'pagehide':\n        this._dispose();\n        break;\n    }\n  }\n\n  private _syncState({\n    data: { actionType, origin },\n  }: MessageEvent<BroadcastIconsChangeMessage>): void {\n    // no need to sync with other wc icon services, just with angular elements\n    if (\n      actionType !== ActionType.SyncState ||\n      origin === IconsStateBroadcast._origin\n    ) {\n      return;\n    }\n\n    this.send({\n      actionType: ActionType.SyncState,\n      collections: this._getUserSetCollection(this._iconsCollection),\n      references: this._getUserRefsCollection(this._iconReferences),\n      origin: IconsStateBroadcast._origin,\n    });\n  }\n\n  private _create(): void {\n    if (!this._channel) {\n      this._channel = new BroadcastChannel('ignite-ui-icon-channel');\n      this._channel.addEventListener('message', this);\n    }\n  }\n\n  private _dispose(): void {\n    this._channel?.removeEventListener('message', this);\n    this._channel?.close();\n    this._channel = null;\n  }\n\n  private _getUserRefsCollection(\n    collections: IconsCollection<IconMeta>\n  ): IconsCollection<IconMeta> {\n    const userSetIcons = createIconDefaultMap<string, IconMeta>();\n\n    for (const [collectionKey, collection] of collections.entries()) {\n      for (const [iconKey, icon] of collection.entries()) {\n        if (icon.external) {\n          userSetIcons.getOrCreate(collectionKey).set(iconKey, icon);\n        }\n      }\n    }\n\n    return userSetIcons;\n  }\n\n  private _getUserSetCollection(\n    collections: IconsCollection<SvgIcon>\n  ): IconsCollection<SvgIcon> {\n    const userSetIcons = createIconDefaultMap<string, SvgIcon>();\n\n    for (const [collectionKey, collection] of collections.entries()) {\n      if (collectionKey === 'internal') {\n        continue;\n      }\n      for (const [iconKey, icon] of collection.entries()) {\n        userSetIcons.getOrCreate(collectionKey).set(iconKey, icon);\n      }\n    }\n\n    return userSetIcons;\n  }\n}\n"]}

package/components/icon/icon.d.ts

@@ -1,41 +1,112 @@
-import { LitElement } from 'lit';
+import { LitElement, type PropertyValues } from 'lit';
 import type { IconMeta } from './registry/types.js';
 /**
  * The icon component allows visualizing collections of pre-registered SVG icons.
  *
  * @element igc-icon
  *
+ * @remarks
+ * The icon component renders SVG icons from registered icon collections. Icons can be:
+ * - Loaded from the internal collection (built-in icons)
+ * - Registered dynamically using `registerIcon` or `registerIconFromText`
+ * - Referenced by aliases that resolve differently based on the active theme
  *
+ * Icons automatically adapt to the current theme when used within an `igc-theme-provider`.
+ * The component subscribes to the icon registry and updates automatically when icons
+ * are registered or references are updated.
+ *
+ * @example
+ * ```html
+ * <!-- Use a built-in icon -->
+ * <igc-icon name="star"></igc-icon>
+ *
+ * <!-- Use an icon from a specific collection -->
+ * <igc-icon name="search" collection="material"></igc-icon>
+ *
+ * <!-- Mirror the icon for RTL layouts -->
+ * <igc-icon name="arrow-forward" mirrored></igc-icon>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Register a custom icon
+ * import { registerIconFromText } from 'igniteui-webcomponents';
+ *
+ * const customIconSvg = '<svg viewBox="0 0 24 24">...</svg>';
+ * registerIconFromText('custom-icon', customIconSvg, 'my-collection');
+ * ```
  */
 export default class IgcIconComponent extends LitElement {
     static readonly tagName = "igc-icon";
     static styles: import("lit").CSSResult[];
     static register(): void;
     private readonly _internals;
-    private svg;
+    private readonly _theming;
+    private _boundIconLoaded?;
+    private _svg;
     /**
      * The name of the icon glyph to draw.
-     * @attr
+     *
+     * @attr name
+     *
+     * @remarks
+     * The icon name can be:
+     * - A direct reference to a registered icon in the specified collection
+     * - An alias that resolves to different icons based on the current theme
+     *
+     * When the icon name or collection changes, the component automatically
+     * fetches and renders the new icon.
      */
     name: string;
     /**
      * The name of the registered collection for look up of icons.
-     * Defaults to `default`.
-     * @attr
+     *
+     * @attr collection
+     * @default "default"
+     *
+     * @remarks
+     * Collections allow organizing icons into logical groups. The "default"
+     * collection is used for most icons.
+     * Custom collections can be created by registering icons with a specific collection name.
      */
     collection: string;
     /**
-     * Whether to flip the icon. Useful for RTL layouts.
-     * @attr
+     * Whether to flip the icon horizontally. Useful for RTL (right-to-left) layouts.
+     *
+     * @attr mirrored
+     * @default false
+     *
+     * @remarks
+     * When true, the icon is flipped horizontally using CSS transform.
+     * This is particularly useful for directional icons (arrows, chevrons)
+     * in right-to-left language contexts.
      */
     mirrored: boolean;
-    constructor();
+    /** @internal */
     connectedCallback(): void;
+    /** @internal */
     disconnectedCallback(): void;
-    protected iconChanged(prev: string, curr: string): void;
-    private _themeChangedCallback;
-    private iconLoaded;
-    private getIcon;
+    protected update(props: PropertyValues<this>): void;
+    /**
+     * Callback invoked when an icon is registered or updated in the registry.
+     * Re-fetches the icon if it matches this component's name and collection.
+     *
+     * @param name - The name of the registered icon
+     * @param collection - The collection of the registered icon
+     */
+    private _iconLoaded;
+    /**
+     * Fetches and updates the icon from the registry.
+     *
+     * @remarks
+     * This method:
+     * 1. Resolves the icon reference based on the current theme
+     * 2. Retrieves the SVG content from the registry
+     * 3. Updates the component's rendered SVG
+     * 4. Sets the appropriate ARIA label from the icon's title
+     *
+     */
+    private _getIcon;
     protected render(): import("lit-html").TemplateResult<1>;
     protected registerIcon(name: string, url: string, collection?: string): Promise<void>;
     protected registerIconFromText(name: string, iconText: string, collection?: string): void;

package/components/icon/icon.js

@@ -10,60 +10,60 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { addThemingController } from '../../theming/theming-controller.js';
 import { addInternalsController } from '../common/controllers/internals.js';
 import { blazorInclude } from '../common/decorators/blazorInclude.js';
-import { watch } from '../common/decorators/watch.js';
 import { registerComponent } from '../common/definitions/register.js';
 import { getIconRegistry, registerIcon as registerIcon_impl, registerIconFromText as registerIconFromText_impl, setIconRef as setIconRef_impl, } from './icon.registry.js';
 import { styles } from './themes/icon.base.css.js';
 import { styles as shared } from './themes/shared/icon.common.css.js';
 import { all } from './themes/themes.js';
 export default class IgcIconComponent extends LitElement {
-    static { this.tagName = 'igc-icon'; }
-    static { this.styles = [styles, shared]; }
-    static register() {
-        registerComponent(IgcIconComponent);
-    }
     constructor() {
-        super();
+        super(...arguments);
         this._internals = addInternalsController(this, {
             initialARIA: { role: 'img' },
         });
-        this.svg = '';
+        this._theming = addThemingController(this, all, {
+            themeChange: this._getIcon,
+        });
+        this._svg = '';
         this.name = '';
         this.collection = 'default';
         this.mirrored = false;
-        this.iconLoaded = (name, collection) => {
-            if (this.name === name && this.collection === collection) {
-                this.getIcon();
-            }
-        };
-        addThemingController(this, all, {
-            themeChange: this._themeChangedCallback,
-        });
+    }
+    static { this.tagName = 'igc-icon'; }
+    static { this.styles = [styles, shared]; }
+    static register() {
+        registerComponent(IgcIconComponent);
     }
     connectedCallback() {
         super.connectedCallback();
-        getIconRegistry().subscribe(this.iconLoaded);
+        this._boundIconLoaded = this._iconLoaded.bind(this);
+        getIconRegistry().subscribe(this._boundIconLoaded);
     }
     disconnectedCallback() {
-        getIconRegistry().unsubscribe(this.iconLoaded);
+        if (this._boundIconLoaded) {
+            getIconRegistry().unsubscribe(this._boundIconLoaded);
+        }
         super.disconnectedCallback();
     }
-    iconChanged(prev, curr) {
-        if (prev !== curr) {
-            this.getIcon();
+    update(props) {
+        if (props.has('name') || props.has('collection')) {
+            this._getIcon();
         }
+        super.update(props);
     }
-    _themeChangedCallback(theme) {
-        getIconRegistry().setRefsByTheme(theme);
+    _iconLoaded(name, collection) {
+        if (this.name === name && this.collection === collection) {
+            this._getIcon();
+        }
     }
-    getIcon() {
-        const { name, collection } = getIconRegistry().getIconRef(this.name, this.collection);
-        const { svg, title } = getIconRegistry().get(name, collection) ?? {};
-        this.svg = svg ?? '';
-        this._internals.setARIA({ ariaLabel: title ?? null });
+    _getIcon() {
+        const { name, collection } = getIconRegistry().getIconRef(this.name, this.collection, this._theming.theme);
+        const { svg = '', title = null } = getIconRegistry().get(name, collection) ?? {};
+        this._svg = svg;
+        this._internals.setARIA({ ariaLabel: title });
     }
     render() {
-        return html `${unsafeSVG(this.svg)}`;
+        return html `${unsafeSVG(this._svg)}`;
     }
     async registerIcon(name, url, collection = 'default') {
         await registerIcon_impl(name, url, collection);
@@ -77,7 +77,7 @@ export default class IgcIconComponent extends LitElement {
 }
 __decorate([
     state()
-], IgcIconComponent.prototype, "svg", void 0);
+], IgcIconComponent.prototype, "_svg", void 0);
 __decorate([
     property()
 ], IgcIconComponent.prototype, "name", void 0);
@@ -87,10 +87,6 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], IgcIconComponent.prototype, "mirrored", void 0);
-__decorate([
-    watch('name'),
-    watch('collection')
-], IgcIconComponent.prototype, "iconChanged", null);
 __decorate([
     blazorInclude()
 ], IgcIconComponent.prototype, "registerIcon", null);

package/components/icon/icon.js.map

@@ -1 +1 @@
-{"version":3,"file":"icon.js","sourceRoot":"","sources":["../../../src/components/icon/icon.ts"],"names":[],"mappings":"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","sourcesContent":["import { html, LitElement } from 'lit';\nimport { property, state } from 'lit/decorators.js';\nimport { unsafeSVG } from 'lit/directives/unsafe-svg.js';\n\nimport { addThemingController } from '../../theming/theming-controller.js';\nimport type { Theme } from '../../theming/types.js';\nimport { addInternalsController } from '../common/controllers/internals.js';\nimport { blazorInclude } from '../common/decorators/blazorInclude.js';\nimport { watch } from '../common/decorators/watch.js';\nimport { registerComponent } from '../common/definitions/register.js';\nimport {\n  getIconRegistry,\n  registerIcon as registerIcon_impl,\n  registerIconFromText as registerIconFromText_impl,\n  setIconRef as setIconRef_impl,\n} from './icon.registry.js';\nimport type { IconMeta } from './registry/types.js';\nimport { styles } from './themes/icon.base.css.js';\nimport { styles as shared } from './themes/shared/icon.common.css.js';\nimport { all } from './themes/themes.js';\n\n/**\n * The icon component allows visualizing collections of pre-registered SVG icons.\n *\n * @element igc-icon\n *\n *\n */\nexport default class IgcIconComponent extends LitElement {\n  public static readonly tagName = 'igc-icon';\n  public static override styles = [styles, shared];\n\n  /* blazorSuppress */\n  public static register(): void {\n    registerComponent(IgcIconComponent);\n  }\n\n  private readonly _internals = addInternalsController(this, {\n    initialARIA: { role: 'img' },\n  });\n\n  @state()\n  private svg = '';\n\n  /* alternateName: iconName */\n  /**\n   * The name of the icon glyph to draw.\n   * @attr\n   */\n  @property()\n  public name = '';\n\n  /**\n   * The name of the registered collection for look up of icons.\n   * Defaults to `default`.\n   * @attr\n   */\n  @property()\n  public collection = 'default';\n\n  /**\n   * Whether to flip the icon. Useful for RTL layouts.\n   * @attr\n   */\n  @property({ type: Boolean, reflect: true })\n  public mirrored = false;\n\n  constructor() {\n    super();\n    addThemingController(this, all, {\n      themeChange: this._themeChangedCallback,\n    });\n  }\n\n  public override connectedCallback() {\n    super.connectedCallback();\n    getIconRegistry().subscribe(this.iconLoaded);\n  }\n\n  public override disconnectedCallback() {\n    getIconRegistry().unsubscribe(this.iconLoaded);\n    super.disconnectedCallback();\n  }\n\n  @watch('name')\n  @watch('collection')\n  protected iconChanged(prev: string, curr: string) {\n    if (prev !== curr) {\n      this.getIcon();\n    }\n  }\n\n  private _themeChangedCallback(theme: Theme) {\n    getIconRegistry().setRefsByTheme(theme);\n  }\n\n  private iconLoaded = (name: string, collection: string) => {\n    if (this.name === name && this.collection === collection) {\n      this.getIcon();\n    }\n  };\n\n  private getIcon() {\n    const { name, collection } = getIconRegistry().getIconRef(\n      this.name,\n      this.collection\n    );\n    const { svg, title } = getIconRegistry().get(name, collection) ?? {};\n\n    this.svg = svg ?? '';\n    this._internals.setARIA({ ariaLabel: title ?? null });\n  }\n\n  protected override render() {\n    return html`${unsafeSVG(this.svg)}`;\n  }\n\n  /* c8 ignore next 8 */\n  @blazorInclude()\n  protected async registerIcon(\n    name: string,\n    url: string,\n    collection = 'default'\n  ) {\n    await registerIcon_impl(name, url, collection);\n  }\n\n  /* c8 ignore next 8 */\n  @blazorInclude()\n  protected registerIconFromText(\n    name: string,\n    iconText: string,\n    collection = 'default'\n  ) {\n    registerIconFromText_impl(name, iconText, collection);\n  }\n\n  /* c8 ignore next 4 */\n  @blazorInclude()\n  protected setIconRef(name: string, collection: string, icon: IconMeta) {\n    setIconRef_impl(name, collection, icon);\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'igc-icon': IgcIconComponent;\n  }\n}\n"]}
+{"version":3,"file":"icon.js","sourceRoot":"","sources":["../../../src/components/icon/icon.ts"],"names":[],"mappings":"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","sourcesContent":["import { html, LitElement, type PropertyValues } from 'lit';\nimport { property, state } from 'lit/decorators.js';\nimport { unsafeSVG } from 'lit/directives/unsafe-svg.js';\n\nimport { addThemingController } from '../../theming/theming-controller.js';\nimport { addInternalsController } from '../common/controllers/internals.js';\nimport { blazorInclude } from '../common/decorators/blazorInclude.js';\nimport { registerComponent } from '../common/definitions/register.js';\nimport {\n  getIconRegistry,\n  registerIcon as registerIcon_impl,\n  registerIconFromText as registerIconFromText_impl,\n  setIconRef as setIconRef_impl,\n} from './icon.registry.js';\nimport type { IconCallback, IconMeta } from './registry/types.js';\nimport { styles } from './themes/icon.base.css.js';\nimport { styles as shared } from './themes/shared/icon.common.css.js';\nimport { all } from './themes/themes.js';\n\n/**\n * The icon component allows visualizing collections of pre-registered SVG icons.\n *\n * @element igc-icon\n *\n * @remarks\n * The icon component renders SVG icons from registered icon collections. Icons can be:\n * - Loaded from the internal collection (built-in icons)\n * - Registered dynamically using `registerIcon` or `registerIconFromText`\n * - Referenced by aliases that resolve differently based on the active theme\n *\n * Icons automatically adapt to the current theme when used within an `igc-theme-provider`.\n * The component subscribes to the icon registry and updates automatically when icons\n * are registered or references are updated.\n *\n * @example\n * ```html\n * <!-- Use a built-in icon -->\n * <igc-icon name=\"star\"></igc-icon>\n *\n * <!-- Use an icon from a specific collection -->\n * <igc-icon name=\"search\" collection=\"material\"></igc-icon>\n *\n * <!-- Mirror the icon for RTL layouts -->\n * <igc-icon name=\"arrow-forward\" mirrored></igc-icon>\n * ```\n *\n * @example\n * ```typescript\n * // Register a custom icon\n * import { registerIconFromText } from 'igniteui-webcomponents';\n *\n * const customIconSvg = '<svg viewBox=\"0 0 24 24\">...</svg>';\n * registerIconFromText('custom-icon', customIconSvg, 'my-collection');\n * ```\n */\nexport default class IgcIconComponent extends LitElement {\n  public static readonly tagName = 'igc-icon';\n  public static override styles = [styles, shared];\n\n  /* blazorSuppress */\n  public static register(): void {\n    registerComponent(IgcIconComponent);\n  }\n\n  private readonly _internals = addInternalsController(this, {\n    initialARIA: { role: 'img' },\n  });\n\n  private readonly _theming = addThemingController(this, all, {\n    themeChange: this._getIcon,\n  });\n\n  private _boundIconLoaded?: IconCallback;\n\n  @state()\n  private _svg = '';\n\n  /* alternateName: iconName */\n  /**\n   * The name of the icon glyph to draw.\n   *\n   * @attr name\n   *\n   * @remarks\n   * The icon name can be:\n   * - A direct reference to a registered icon in the specified collection\n   * - An alias that resolves to different icons based on the current theme\n   *\n   * When the icon name or collection changes, the component automatically\n   * fetches and renders the new icon.\n   */\n  @property()\n  public name = '';\n\n  /**\n   * The name of the registered collection for look up of icons.\n   *\n   * @attr collection\n   * @default \"default\"\n   *\n   * @remarks\n   * Collections allow organizing icons into logical groups. The \"default\"\n   * collection is used for most icons.\n   * Custom collections can be created by registering icons with a specific collection name.\n   */\n  @property()\n  public collection = 'default';\n\n  /**\n   * Whether to flip the icon horizontally. Useful for RTL (right-to-left) layouts.\n   *\n   * @attr mirrored\n   * @default false\n   *\n   * @remarks\n   * When true, the icon is flipped horizontally using CSS transform.\n   * This is particularly useful for directional icons (arrows, chevrons)\n   * in right-to-left language contexts.\n   */\n  @property({ type: Boolean, reflect: true })\n  public mirrored = false;\n\n  /** @internal */\n  public override connectedCallback(): void {\n    super.connectedCallback();\n    this._boundIconLoaded = this._iconLoaded.bind(this);\n    getIconRegistry().subscribe(this._boundIconLoaded);\n  }\n\n  /** @internal */\n  public override disconnectedCallback(): void {\n    if (this._boundIconLoaded) {\n      getIconRegistry().unsubscribe(this._boundIconLoaded);\n    }\n    super.disconnectedCallback();\n  }\n\n  protected override update(props: PropertyValues<this>): void {\n    if (props.has('name') || props.has('collection')) {\n      this._getIcon();\n    }\n\n    super.update(props);\n  }\n\n  /**\n   * Callback invoked when an icon is registered or updated in the registry.\n   * Re-fetches the icon if it matches this component's name and collection.\n   *\n   * @param name - The name of the registered icon\n   * @param collection - The collection of the registered icon\n   */\n  private _iconLoaded(name: string, collection: string): void {\n    if (this.name === name && this.collection === collection) {\n      this._getIcon();\n    }\n  }\n\n  /**\n   * Fetches and updates the icon from the registry.\n   *\n   * @remarks\n   * This method:\n   * 1. Resolves the icon reference based on the current theme\n   * 2. Retrieves the SVG content from the registry\n   * 3. Updates the component's rendered SVG\n   * 4. Sets the appropriate ARIA label from the icon's title\n   *\n   */\n  private _getIcon(): void {\n    const { name, collection } = getIconRegistry().getIconRef(\n      this.name,\n      this.collection,\n      this._theming.theme\n    );\n    const { svg = '', title = null } =\n      getIconRegistry().get(name, collection) ?? {};\n\n    this._svg = svg;\n    this._internals.setARIA({ ariaLabel: title });\n  }\n\n  protected override render() {\n    return html`${unsafeSVG(this._svg)}`;\n  }\n\n  /* c8 ignore next 8 */\n  @blazorInclude()\n  protected async registerIcon(\n    name: string,\n    url: string,\n    collection = 'default'\n  ) {\n    await registerIcon_impl(name, url, collection);\n  }\n\n  /* c8 ignore next 8 */\n  @blazorInclude()\n  protected registerIconFromText(\n    name: string,\n    iconText: string,\n    collection = 'default'\n  ) {\n    registerIconFromText_impl(name, iconText, collection);\n  }\n\n  /* c8 ignore next 4 */\n  @blazorInclude()\n  protected setIconRef(name: string, collection: string, icon: IconMeta) {\n    setIconRef_impl(name, collection, icon);\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'igc-icon': IgcIconComponent;\n  }\n}\n"]}

package/components/icon/icon.registry.d.ts

@@ -1,24 +1,232 @@
 import type { Theme } from '../../theming/types.js';
 import type { IconCallback, IconMeta, IconReferencePair, SvgIcon } from './registry/types.js';
+/**
+ * Global singleton registry for managing SVG icons and their references.
+ *
+ * @remarks
+ * The IconsRegistry class handles:
+ * - Registration and storage of SVG icons in collections
+ * - Icon reference/alias management with theme-based resolution
+ * - Notification of icon changes to subscribed components
+ * - Cross-context synchronization via BroadcastChannel
+ * - Batched notifications for performance optimization
+ *
+ * This is a singleton managed via Symbol.for to ensure a single instance
+ * across the entire application, even with multiple bundle instances.
+ *
+ * @internal This class is not directly exposed. Use the exported functions instead.
+ */
 declare class IconsRegistry {
-    private parser;
-    private collections;
-    private references;
-    private listeners;
-    private theme;
-    private broadcast;
-    constructor();
+    /** Set of callbacks subscribed to icon change notifications */
+    private readonly _listeners;
+    /** Set of pending icon:collection keys awaiting notification */
+    private readonly _pendingNotifications;
+    /** Map of icon references/aliases by collection and name */
+    private readonly _references;
+    /** Map of registered SVG icons by collection and name */
+    private readonly _collections;
+    /** Parser for converting SVG text to icon metadata */
+    private readonly _svgIconParser;
+    /** Broadcast channel manager for cross-context synchronization */
+    private readonly _broadcast;
+    /** Flag indicating if a notification microtask is scheduled */
+    private _notificationScheduled;
+    /**
+     * Registers an SVG icon in the registry.
+     *
+     * @param name - The unique name for the icon within its collection
+     * @param iconText - The SVG markup as a string
+     * @param collection - The collection to register the icon in (default: 'default')
+     *
+     * @remarks
+     * This method:
+     * 1. Parses the SVG text into icon metadata
+     * 2. Stores the icon in the specified collection
+     * 3. Broadcasts the registration to other contexts
+     * 4. Notifies subscribed components (batched)
+     *
+     * @throws Will throw if the SVG text is malformed
+     */
     register(name: string, iconText: string, collection?: string): void;
+    /**
+     * Subscribes a callback to icon change notifications.
+     *
+     * @param callback - Function to call when icons are registered or updated
+     *
+     * @remarks
+     * The callback receives the icon name and collection when changes occur.
+     * Notifications are batched using microtasks for performance.
+     */
     subscribe(callback: IconCallback): void;
+    /**
+     * Unsubscribes a callback from icon change notifications.
+     *
+     * @param callback - The previously subscribed callback to remove
+     */
     unsubscribe(callback: IconCallback): void;
-    setRefsByTheme(theme: Theme): void;
+    /**
+     * Sets an icon reference/alias.
+     *
+     * @param options - Configuration for the icon reference
+     *
+     * @remarks
+     * Icon references allow icons to be aliased with different names.
+     * They can be:
+     * - User-set (external: true) - higher priority, synced across contexts
+     * - System-set (external: false) - used internally, not synced
+     *
+     * When overwrite is true, the reference is stored and subscribers are notified.
+     * When external is true, the reference is broadcast to other contexts.
+     */
     setIconRef(options: IconReferencePair): void;
-    getIconRef(name: string, collection: string): IconMeta;
+    /**
+     * Gets the icon reference, resolving aliases based on the provided theme.
+     *
+     * @param name - The icon name or alias
+     * @param collection - The collection name
+     * @param theme - The theme to use for resolving aliases
+     * @returns The resolved icon metadata (without the internal 'external' flag)
+     */
+    getIconRef(name: string, collection: string, theme?: Theme): IconMeta;
+    /**
+     * Retrieves an icon from the registry.
+     *
+     * @param name - The icon name
+     * @param collection - The collection name (default: 'default')
+     * @returns The SVG icon metadata, or undefined if not found
+     *
+     * @remarks
+     * Use `getIconRef` first to resolve aliases before calling this method.
+     */
     get(name: string, collection?: string): SvgIcon | undefined;
-    private notifyAll;
+    /**
+     * Schedules a batched notification for icon changes.
+     *
+     * @param name - The icon name that changed
+     * @param collection - The collection name
+     *
+     * @remarks
+     * Notifications are batched in a microtask queue to avoid excessive
+     * listener calls when multiple icons are registered synchronously.
+     * Duplicate icon:collection pairs are automatically deduplicated.
+     *
+     * @internal
+     */
+    private _notifyAll;
+    /**
+     * Flushes pending notifications to all subscribed listeners.
+     *
+     * @remarks
+     * This method is called as a microtask after icons are registered.
+     * It processes all pending icon:collection pairs and notifies listeners.
+     *
+     * @internal
+     */
+    private _flushNotifications;
 }
+/**
+ * Gets the global icon registry singleton instance.
+ *
+ * @returns The IconsRegistry singleton
+ *
+ * @remarks
+ * This function ensures only one instance of the registry exists globally,
+ * even across multiple bundle instances. The registry is stored on globalThis
+ * using a well-known Symbol.
+ *
+ * @example
+ * ```typescript
+ * const registry = getIconRegistry();
+ * registry.subscribe((name, collection) => {
+ *   console.log(`Icon ${name} changed in ${collection}`);
+ * });
+ * ```
+ */
 export declare function getIconRegistry(): IconsRegistry;
+/**
+ * Registers an icon by fetching it from a URL.
+ *
+ * @param name - The unique name for the icon
+ * @param url - The URL to fetch the SVG icon from
+ * @param collection - The collection to register the icon in (default: 'default')
+ *
+ * @returns A promise that resolves when the icon is registered
+ *
+ * @throws If the HTTP request fails or returns a non-OK status
+ *
+ * @remarks
+ * This function fetches SVG content from the provided URL and registers it
+ * in the icon registry. The icon becomes immediately available to all icon
+ * components in the application.
+ *
+ * @example
+ * ```typescript
+ * // Register an icon from a URL
+ * await registerIcon('custom-icon', '/assets/icons/custom.svg');
+ *
+ * // Use in HTML
+ * // <igc-icon name="custom-icon"></igc-icon>
+ * ```
+ */
 export declare function registerIcon(name: string, url: string, collection?: string): Promise<void>;
+/**
+ * Registers an icon from SVG text content.
+ *
+ * @param name - The unique name for the icon
+ * @param iconText - The SVG markup as a string
+ * @param collection - The collection to register the icon in (default: 'default')
+ *
+ * @throws If the SVG text is malformed or doesn't contain an SVG element
+ *
+ * @remarks
+ * This is the preferred method for registering icons when you have the SVG
+ * content directly (e.g., from a bundled asset or inline string). The icon
+ * becomes immediately available to all icon components.
+ *
+ * The SVG text is parsed to extract viewBox, title, and other metadata.
+ *
+ * @example
+ * ```typescript
+ * const iconSvg = '<svg viewBox="0 0 24 24"><path d="..."/></svg>';
+ * registerIconFromText('my-icon', iconSvg, 'custom');
+ *
+ * // Use in HTML
+ * // <igc-icon name="my-icon" collection="custom"></igc-icon>
+ * ```
+ */
 export declare function registerIconFromText(name: string, iconText: string, collection?: string): void;
+/**
+ * Sets an icon reference/alias that points to another icon.
+ *
+ * @param name - The alias name
+ * @param collection - The collection for the alias
+ * @param icon - The target icon metadata (name and collection)
+ *
+ * @remarks
+ * Icon references allow you to create aliases that point to other icons.
+ * This is useful for:
+ * - Creating semantic names (e.g., 'close' → 'x')
+ * - Overriding default icon mappings
+ * - Providing fallbacks for missing icons
+ *
+ * User-set references are marked as external and have higher priority than
+ * theme-based aliases. They are also synchronized across browsing contexts.
+ *
+ * @example
+ * ```typescript
+ * // Register target icon
+ * registerIconFromText('x-mark', '<svg>...</svg>');
+ *
+ * // Create an alias
+ * setIconRef('close', 'default', {
+ *   name: 'x-mark',
+ *   collection: 'default'
+ * });
+ *
+ * // Both work the same way:
+ * // <igc-icon name="close"></igc-icon>
+ * // <igc-icon name="x-mark"></igc-icon>
+ * ```
+ */
 export declare function setIconRef(name: string, collection: string, icon: IconMeta): void;
 export {};