@financial-times/custom-code-component 2.0.14 → 2.0.16

package/dist/custom-element.d.ts

@@ -38,35 +38,147 @@ export declare interface CustomCodeComponent extends ContentTree.Node {
 }
 
 declare class FTCustomCodeComponent extends HTMLElement {
+    /**
+     * The component renderer, resolved from dynamic import
+     */
     app?: typeof BaseRenderer.prototype.render;
+    /**
+     * Set whether component is "open" or "closed". Defaults to "open".
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#mode
+     */
     mode: "closed" | "open";
+    /**
+     * Reserved attributes we don't pass to the child component
+     */
     RESERVED_ATTRS: Set<string>;
+    /**
+     * URI of component module for CCC webcomponent to load
+     */
     source?: string;
+    /**
+     * OTracking config
+     */
     tracking?: Tracking;
+    /**
+     * Alternative base URL, used for testing
+     */
     testUrl?: URL;
+    /**
+     * ComponentPath instance with `org`, `repo`, `name` and `versionRange` attributes
+     */
     component: ComponentPath;
+    /**
+     * Logger instance. Set log level using `this.log.setLogLevel(string|number|null)`.
+     */
     log: Logger;
+    /**
+     * IntersectionObserver that dispatches CCCViewportEvents
+     */
     observer: IntersectionObserver;
+    /**
+     * Custom Element constructor.
+     *
+     * n.b., attributes and ShadowDOM aren't available in custom element constructors.
+     * Use connectedCallback() and other lifecycle methods if you want to eg. this.getAttribute()
+     */
     constructor();
+    /**
+     * connectedCallback() CE lifecycle callback
+     *
+     * Called whenever a <custom-code-component> element is mounted to the DOM.
+     */
     connectedCallback(): Promise<void>;
+    /**
+     * Error handler. Decorates errors for easier ingestion.
+     *
+     * @param error
+     */
     emitError(error: Error): void;
+    /**
+     * disconnectedCallback() CE lifecycle event.
+     *
+     * Called when a <custom-code-component> element is removed from DOM.
+     */
     disconnectedCallback(): void;
+    /**
+     * MessageChannel interface.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
+     */
     channel: MessageChannel;
-    onmessage(): void;
+    /**
+     * MessageChannel postMessage callback
+     *
+     * @param e
+     */
+    onmessage(e?: any): void;
+    /**
+     * This error handler is called by the child component on e.g. unrecoverable error.
+     * It then calls unmount(), which restores the fallback.
+     *
+     * @param e
+     */
     onunmount(e: Error): void;
+    /**
+     * onready event callback.
+     * Called by mount() after kicking off initial component render.
+     *
+     * @param app
+     */
     onready(app: Promise<void>): Promise<void>;
+    /**
+     * MessageChannel postMessage handler.
+     * This can be used for inter-CCC communication.
+     * @param event
+     */
     postMessage(event: any): void;
+    /**
+     * Initial mounting behaviour.
+     *
+     * Attaches ShadowDOM if needed, dispatches ccc:connected event, adds component base styles,
+     * generates fallback template element if one doesn't exist already, initialises tracking,
+     * then kicks off component rendering. Passes component render promise to onready().
+     *
+     * @param prerendered
+     */
     mount(prerendered?: ShadowRoot | null): Promise<void>;
+    /**
+     * Called in top-level error handler or by child component on unhandled error.
+     * Replace shadow root with either <slot> or template[data-component-fallback]
+     * slot on failure
+     *
+     * @param e
+     */
     unmount(e: Error): void;
-    load(): Promise<(shadowRoot: ShadowRoot, props: any, ssr?: boolean, onErrorCallback?: Function) => {
+    /**
+     * Asynchronously loads the CCC child component.
+     *
+     * @returns Promise resolving to component renderer function
+     */
+    load(): Promise<(shadowRoot: ShadowRoot, props: any, ssr?: boolean, onErrorCallback?: Function, log?: Logger) => {
         onmessage: {
             (...data: any[]): void;
             (message?: any, ...optionalParams: any[]): void;
         };
         ready: Promise<void>;
     }>;
+    /**
+     * Initialises OTracking
+     */
     initTracking: () => Promise<void>;
+    /**
+     * Injects Vite HMR scripts during dev environment usage
+     */
     injectViteScripts: () => void;
+    /**
+     * Called whenever the <custom-code-component>'s attributes are changed.
+     * Currently only used to dynamically set log level.
+     *
+     * @param name
+     * @param oldValue
+     * @param newValue
+     */
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
 }
 export { FTCustomCodeComponent as CCCHTMLElement }
 export { FTCustomCodeComponent }
@@ -81,6 +193,7 @@ declare class Logger {
     info(...args: any[]): void;
     warn(...args: any[]): void;
     error(...args: any[]): void;
+    setLogLevel(level: string | number | null): void;
 }
 
 declare class Tracking {