@cell-x/caniuse-embed-element/dist/caniuse-embed-element.d.ts

A custom web component that embeds caniuse.com browser compatibility data for a specific feature.

import { LitElement } from 'lit';
/**
 * Props for configuring the CaniuseEmbed component.
 *
 * @property feature - The identifier of the feature to display support data for (e.g., 'flexbox').
 * @property past - Number of past browser versions to display (0-5). Controls the historical data shown.
 * @property future - Number of future browser versions to display (0-3). Controls the preview of upcoming support.
 * @property origin - The origin URL to use for embedding, useful for specifying a custom or proxied caniuse.com endpoint.
 * @property theme - The color theme of the embed. Can be 'auto' (match system), 'light', or 'dark'.
 * @property meta - Additional metadata or configuration string for advanced customization.
 */
export interface CaniuseEmbedElementProps {
    feature?: string;
    past?: 0 | 1 | 2 | 3 | 4 | 5;
    future?: 0 | 1 | 2 | 3;
    origin?: string;
    theme?: 'auto' | 'light' | 'dark';
    loading?: 'eager' | 'lazy';
    meta?: string;
}
/**
 * A custom web component that embeds caniuse.com browser compatibility data for a specific feature.
 *
 * This element displays an interactive iframe showing browser support information from caniuse.com.
 * It dynamically adjusts its height based on the content and provides customization options for
 * theme, time range, and data source.
 *
 * @example
 * ```html
 * <caniuse-embed feature="css-grid" theme="dark"></caniuse-embed>
 * ```
 */
export declare class CaniuseEmbedElement extends LitElement {
    /**
     * The name of the feature to display browser compatibility data for.
     * This should match a feature identifier from caniuse.com.
     * @example "css-grid", "flexbox", "es6-arrow-functions"
     */
    feature: string;
    /**
     * Number of past major browser versions to display in the compatibility table.
     * Controls how far back in browser history the data extends.
     * @default 2
     */
    past: 0 | 1 | 2 | 3 | 4 | 5;
    /**
     * Number of future major browser versions to display in the compatibility table.
     * Controls how far into future browser versions the data extends.
     * @default 1
     */
    future: 0 | 1 | 2 | 3;
    /**
     * The base URL of the caniuse embed service.
     * Can be customized to use a different caniuse mirror or service.
     * @default "https://caniuse.lruihao.cn"
     */
    origin: string;
    /**
     * The color theme for the embedded content.
     * - 'auto': Follows system preference
     * - 'light': Light theme
     * - 'dark': Dark theme
     * @default "auto"
     */
    theme: 'auto' | 'light' | 'dark';
    /**
     * The loading strategy for the embedded iframe.
     * - 'eager': Loads immediately
     * - 'lazy': Loads when in viewport
     * @default "lazy"
     */
    loading: 'eager' | 'lazy';
    /**
     * A unique identifier for this embed instance.
     * Used to match messages from the iframe to this specific component instance.
     * Automatically generated on creation.
     */
    meta: string;
    /**
     * Indicates whether the iframe content has finished loading.
     * Used to control the visibility of loading state and iframe content.
     * This property is used via CSS attribute selectors through the reflect: true option.
     * @private
     */
    private loaded;
    /**
     * The current height of the embedded iframe in pixels.
     * Automatically updated based on content size via postMessage communication.
     * @private
     */
    private _iframeHeight;
    /**
     * Called when the element is added to the DOM.
     * Sets up the message listener for iframe communication.
     */
    connectedCallback(): void;
    /**
     * Called when the element is removed from the DOM.
     * Cleans up the message event listener to prevent memory leaks.
     */
    disconnectedCallback(): void;
    /**
     * Sets up the global message event listener for iframe communication.
     * This allows the component to receive height updates from the embedded iframe.
     * @private
     */
    private setupMessageListener;
    /**
     * Handles incoming postMessage events from the embedded iframe.
     * Updates the iframe height when a valid message is received from the correct iframe instance.
     * @param ev - The MessageEvent containing data from the iframe
     * @private
     */
    private handleMessage;
    /**
     * Handles iframe load event as a fallback for setting loaded state.
     * @private
     */
    private handleIframeLoad;
    /**
     * Safely parses incoming message data, handling both string and object formats.
     * @param data - The raw data from a postMessage event
     * @returns Parsed data object or empty object if parsing fails
     * @private
     */
    private parseData;
    /**
     * Generates the iframe source URL based on current component properties.
     * Constructs the URL with feature, meta, theme, and past version parameters.
     * @returns The complete URL for the iframe source, or empty string if no feature is specified
     * @private
     */
    private generateSource;
    /**
     * Renders the component's HTML template.
     * Shows either an iframe with caniuse data or a placeholder message when no feature is specified.
     * @returns The HTML template for this component
     */
    render(): import('lit').TemplateResult<1>;
    /**
     * CSS styles for the component.
     * Defines styling for the host element, iframe, and empty state message.
     */
    static styles: import('lit').CSSResult;
}
declare global {
    interface Window {
        CaniuseEmbedElement: typeof CaniuseEmbedElement;
    }
    interface HTMLElementTagNameMap {
        'caniuse-embed': CaniuseEmbedElement;
    }
    interface HTMLElementPropsMap {
        'caniuse-embed': CaniuseEmbedElementProps;
    }
}