igniteui-webcomponents
Version:
Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.
125 lines (124 loc) • 4.43 kB
TypeScript
/**
* Reactive controller for adopting document-level styles into Shadow DOM.
*
* This controller enables web components to access and apply styles from the
* document's stylesheets within their Shadow DOM, effectively bridging the
* style encapsulation boundary when needed.
*
* @example
* ```typescript
* class MyComponent extends LitElement {
* private readonly _adoptedStyles = addAdoptedStylesController(this);
*
* protected override update(props: PropertyValues): void {
* if (props.has('shouldAdopt')) {
* this._adoptedStyles.shouldAdoptStyles(this.shouldAdopt);
* }
* super.update(props);
* }
* }
* ```
*/
import { type LitElement, type ReactiveController, type ReactiveControllerHost } from 'lit';
/**
* Controller that manages the adoption of document-level styles into a
* component's Shadow DOM.
*
* This controller provides:
* - Automatic caching of cloned stylesheets per document
* - Efficient adoption and removal of document styles
* - Cache invalidation for theme changes
* - Automatic cleanup on component disconnection
*/
declare class AdoptedStylesController implements ReactiveController {
private static _cachedSheets;
private static _invalidateCache;
private readonly _host;
private _hasAdoptedStyles;
/**
* Indicates whether document styles have been adopted into the host's Shadow DOM.
*/
get hasAdoptedStyles(): boolean;
constructor(host: ReactiveControllerHost & LitElement);
/**
* Conditionally adopts or clears document styles based on the provided condition.
*
* @param condition - If true, adopts document styles; if false, clears adopted styles
*
* @example
* ```typescript
* this._adoptedStyles.shouldAdoptStyles(this.options?.adoptRootStyles);
* ```
*/
shouldAdoptStyles(condition: boolean): void;
/**
* Invalidates the stylesheet cache for the specified document.
*
* This should be called when the document's stylesheets change (e.g., theme changes)
* to ensure the next adoption uses the updated styles.
*
* @param doc - The document whose cache to invalidate. Defaults to the global document.
*
* @example
* ```typescript
* // Invalidate cache on theme change
* this._adoptedStyles.invalidateCache(this.ownerDocument);
* ```
*/
invalidateCache(doc?: Document): void;
/**
* Lifecycle callback invoked when the host component is disconnected.
* Automatically clears adopted styles to prevent memory leaks.
* @internal
*/
hostDisconnected(): void;
/**
* Adopts document-level styles into the host's Shadow DOM.
*
* This method:
* 1. Checks the cache for previously cloned stylesheets
* 2. Clones document stylesheets if not cached
* 3. Applies both component styles and cloned document styles to the Shadow Root
*/
private _adoptRootStyles;
/**
* Removes previously adopted document styles from the Shadow DOM.
*
* Only removes stylesheets that were added by this controller, preserving
* the component's original styles.
*/
private _clearAdoptedStyles;
/**
* Clones all accessible stylesheets from the document into constructable stylesheets.
*
* This method:
* - Iterates through all document stylesheets
* - Skips cross-origin stylesheets (CORS restrictions)
* - Skips @import rules (cannot be cloned into constructable stylesheets)
* - Creates new CSSStyleSheet instances with cloned rules
*
* @param ownerDocument - The document whose stylesheets should be cloned
* @returns An array of cloned CSSStyleSheet objects
*/
private _cloneDocumentStyleSheets;
}
/**
* Creates and attaches an AdoptedStylesController to a Lit component.
*
* @param host - The Lit component that will host the controller
* @returns The created AdoptedStylesController instance
*
* @example
* ```typescript
* class MyComponent extends LitElement {
* private readonly _adoptedStyles = addAdoptedStylesController(this);
*
* connectedCallback() {
* super.connectedCallback();
* this._adoptedStyles.shouldAdoptStyles(true);
* }
* }
* ```
*/
export declare function addAdoptedStylesController(host: ReactiveControllerHost & LitElement): AdoptedStylesController;
export type { AdoptedStylesController };