Core Element

/**
 * Base element class that manages element properties and attributes, and
 * renders a lit-html template.
 */
class LitElement extends ReactiveElement {
  /**
   * Readonly render options for configuring lit-html rendering
   */
  readonly renderOptions: RenderOptions;

  /**
   * Creates the render root for the element (typically shadow root)
   * @returns Element or ShadowRoot where content will be rendered
   */
  protected createRenderRoot(): Element | ShadowRoot;

  /**
   * Updates the element. This method reflects property values to attributes
   * and calls render to render DOM via lit-html
   * @param changedProperties Map of changed properties with old values
   */
  protected update(changedProperties: PropertyValues): void;

  /**
   * Invoked on each update to perform rendering tasks. Should return
   * any value renderable by lit-html's ChildPart
   * @returns Template result, string, number, or other renderable value
   */
  protected render(): unknown;

  /**
   * Invoked when the component is added to the document's DOM
   */
  connectedCallback(): void;

  /**
   * Invoked when the component is removed from the document's DOM
   */
  disconnectedCallback(): void;
}

import { LitElement, html, css } from "lit-element";

class MyElement extends LitElement {
  static styles = css`
    :host {
      display: block;
      padding: 16px;
    }
  `;

  render() {
    return html`<p>Hello from LitElement!</p>`;
  }
}

customElements.define("my-element", MyElement);

/**
 * Base class for creating reactive custom elements
 */
class ReactiveElement extends HTMLElement {
  /**
   * Static property declarations for reactive properties
   */
  static properties: PropertyDeclarations;

  /**
   * Static styles applied to the element's shadow root
   */
  static styles?: CSSResultGroup;

  /**
   * Element lifecycle callback for when element is connected to DOM
   */
  connectedCallback(): void;

  /**
   * Element lifecycle callback for when element is disconnected from DOM
   */
  disconnectedCallback(): void;

  /**
   * Element lifecycle callback for when element is moved to new document
   */
  adoptedCallback(): void;

  /**
   * Element lifecycle callback for when attributes change
   */
  attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;

  /**
   * Requests an update which will trigger the update lifecycle
   */
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: RequestUpdateOptions): void;

  /**
   * Performs the update, calling lifecycle methods and rendering
   */
  protected performUpdate(): void | Promise<unknown>;

  /**
   * Override point for modification before property values are used in update
   */
  protected willUpdate(changedProperties: PropertyValues): void;

  /**
   * Override point for modification after update has completed
   */
  protected updated(changedProperties: PropertyValues): void;

  /**
   * Override point for determining if update should proceed
   */
  protected shouldUpdate(changedProperties: PropertyValues): boolean;

  /**
   * Creates render root (shadow root by default)
   */
  protected createRenderRoot(): Element | ShadowRoot;

  /**
   * Returns array of styles to apply to render root
   */
  protected getStyles(): CSSResultGroup | undefined;
}

interface RenderOptions {
  /**
   * Host object for event listeners and other contextual data
   */
  host?: object;

  /**
   * Node before which to render content
   */
  renderBefore?: ChildNode | null;

  /**
   * Whether the template is connected to the live DOM
   */
  isConnected?: boolean;

  /**
   * Scope name for ShadyCSS compatibility
   */
  scope?: string;
}

/**
 * Map of property changes with property names as keys and old values as values
 */
interface PropertyValues extends Map<PropertyKey, unknown> {
  /**
   * Get the old value for a property
   */
  get(key: PropertyKey): unknown;

  /**
   * Check if a property has changed
   */
  has(key: PropertyKey): boolean;

  /**
   * Iterate over changed properties
   */
  [Symbol.iterator](): IterableIterator<[PropertyKey, unknown]>;
}

/**
 * Called when element is connected to DOM
 */
connectedCallback(): void;

/**
 * Called when element is disconnected from DOM
 */
disconnectedCallback(): void;

/**
 * Called when element is moved to new document
 */
adoptedCallback(): void;

/**
 * Called when observed attributes change
 */
attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;

/**
 * Called before update to allow property modification
 */
protected willUpdate(changedProperties: PropertyValues): void;

/**
 * Called after update has completed
 */
protected updated(changedProperties: PropertyValues): void;

/**
 * Called to determine if update should proceed
 */
protected shouldUpdate(changedProperties: PropertyValues): boolean;

import { LitElement, html, PropertyValues } from "lit-element";

class MyElement extends LitElement {
  connectedCallback() {
    super.connectedCallback();
    console.log("Element connected to DOM");
    this.addEventListener("click", this._handleClick);
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    console.log("Element disconnected from DOM");
    this.removeEventListener("click", this._handleClick);
  }

  protected willUpdate(changedProperties: PropertyValues) {
    console.log("About to update:", Array.from(changedProperties.keys()));
  }

  protected updated(changedProperties: PropertyValues) {
    console.log("Updated:", Array.from(changedProperties.keys()));
  }

  protected shouldUpdate(changedProperties: PropertyValues): boolean {
    // Only update if specific properties changed
    return changedProperties.has("importantProperty");
  }

  private _handleClick(e: Event) {
    console.log("Element clicked");
  }

  render() {
    return html`<p>Lifecycle example</p>`;
  }
}

/**
 * Interface for objects that can host Reactive Controllers
 */
interface ReactiveControllerHost {
  /**
   * Registers a controller to participate in the element's lifecycle
   */
  addController(controller: ReactiveController): void;

  /**
   * Removes a controller from the host
   */
  removeController(controller: ReactiveController): void;

  /**
   * Requests an update of the host element
   */
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: object): void;

  /**
   * Promise that resolves when the host has completed updating
   */
  readonly updateComplete: Promise<boolean>;
}

/**
 * Interface for objects that participate in the lifecycle of a ReactiveElement
 */
interface ReactiveController {
  /**
   * Called when the host is connected to the DOM
   */
  hostConnected?(): void;

  /**
   * Called when the host is disconnected from the DOM
   */
  hostDisconnected?(): void;

  /**
   * Called during the host's update, before the host's own update
   */
  hostUpdate?(): void;

  /**
   * Called after the host has updated
   */
  hostUpdated?(): void;
}

import { LitElement, html, ReactiveController, ReactiveControllerHost } from "lit-element";

class TimerController implements ReactiveController {
  private host: ReactiveControllerHost;
  private intervalId?: number;
  
  value = 0;

  constructor(host: ReactiveControllerHost, private interval = 1000) {
    this.host = host;
    host.addController(this);
  }

  hostConnected() {
    this.intervalId = window.setInterval(() => {
      this.value++;
      this.host.requestUpdate();
    }, this.interval);
  }

  hostDisconnected() {
    if (this.intervalId) {
      clearInterval(this.intervalId);
      this.intervalId = undefined;
    }
  }
}

class MyElement extends LitElement {
  private timer = new TimerController(this);

  render() {
    return html`<p>Timer: ${this.timer.value}</p>`;
  }
}