Static Templates

/**
 * Creates static HTML templates with compile-time optimization
 * Static parts are identified at build time for better performance
 */
function html(
  strings: TemplateStringsArray,
  ...values: unknown[]
): StaticValue;

import { html } from "lit/static-html.js";
import { LitElement } from "lit";

class StaticComponent extends LitElement {
  @property() title = "Welcome";
  @property() content = "Hello World";
  
  render() {
    // Static structure with dynamic content
    return html`
      <div class="container">
        <header>
          <h1>${this.title}</h1>
        </header>
        <main>
          <p>${this.content}</p>
        </main>
      </div>
    `;
  }
}

/**
 * Creates static SVG templates with compile-time optimization
 * Automatically sets SVG namespace context
 */
function svg(
  strings: TemplateStringsArray,
  ...values: unknown[]
): StaticValue;

import { html, svg } from "lit/static-html.js";

class IconComponent extends LitElement {
  @property() size = 24;
  @property() color = "currentColor";
  
  render() {
    return html`
      <div class="icon-wrapper">
        ${svg`
          <svg width="${this.size}" height="${this.size}" viewBox="0 0 24 24">
            <path 
              d="M12 2L2 7v10c0 5.55 3.84 9.74 9 11 5.16-1.26 9-5.45 9-11V7l-10-5z"
              fill="${this.color}"
            />
          </svg>
        `}
      </div>
    `;
  }
}

/**
 * Creates static MathML templates with compile-time optimization
 * Automatically sets MathML namespace context
 */
function mathml(
  strings: TemplateStringsArray,
  ...values: unknown[]
): StaticValue;

import { html, mathml } from "lit/static-html.js";

class MathComponent extends LitElement {
  @property() a = "2";
  @property() b = "3";
  @property() result = "5";
  
  render() {
    return html`
      <div class="math-equation">
        ${mathml`
          <math>
            <mrow>
              <mi>${this.a}</mi>
              <mo>+</mo>
              <mi>${this.b}</mi>
              <mo>=</mo>
              <mi>${this.result}</mi>
            </mrow>
          </math>
        `}
      </div>
    `;
  }
}

/**
 * Creates static values that bypass Lit's safety checks
 * WARNING: Only use with trusted content to avoid XSS vulnerabilities
 */
function unsafeStatic(value: string): StaticValue;

import { html, unsafeStatic } from "lit/static-html.js";

class DynamicTagComponent extends LitElement {
  @property() tagName = "div";
  @property() content = "Dynamic content";
  
  render() {
    // Dynamically create element tags (use with caution)
    const openTag = unsafeStatic(`<${this.tagName}>`);
    const closeTag = unsafeStatic(`</${this.tagName}>`);
    
    return html`
      ${openTag}
        ${this.content}
      ${closeTag}
    `;
  }
}

// Better approach using literal for tag names
class SaferDynamicTag extends LitElement {
  @property() level = 1;
  @property() content = "Heading content";
  
  render() {
    const tag = unsafeStatic(`h${this.level}`);
    return html`<${tag}>${this.content}</${tag}>`;
  }
}

/**
 * Creates literal template parts for values known at compile time
 * More efficient than regular template expressions for static content
 */
function literal(
  strings: TemplateStringsArray,
  ...values: unknown[]
): StaticValue;

import { html, literal } from "lit/static-html.js";

class LiteralComponent extends LitElement {
  @property() variant: "primary" | "secondary" = "primary";
  
  render() {
    // Use literal for compile-time known class names
    const buttonClass = literal`btn btn-${this.variant}`;
    
    return html`
      <button class="${buttonClass}">
        <slot></slot>
      </button>
    `;
  }
}

/**
 * Wraps template tag functions with static template support
 * Enables static optimization for custom template functions
 */
function withStatic<T extends TemplateTagFunction>(
  tagFn: T
): StaticTemplateTagFunction<T>;

/** Template tag function type */
type TemplateTagFunction = (
  strings: TemplateStringsArray,
  ...values: unknown[]
) => unknown;

/** Static template tag function type */
type StaticTemplateTagFunction<T extends TemplateTagFunction> = T & {
  withStatic: T;
};

import { html as baseHtml, withStatic } from "lit/static-html.js";

// Create static-optimized version of custom template function
const customHtml = withStatic((strings, ...values) => {
  // Custom template processing logic
  return baseHtml(strings, ...values);
});

class CustomTemplateComponent extends LitElement {
  render() {
    return customHtml`
      <div class="custom-template">
        <p>This uses a custom template function with static optimization</p>
      </div>
    `;
  }
}

/** Static value interface for compile-time optimized content */
interface StaticValue {
  /** Internal marker for static values */
  _$litStatic$: unknown;
  
  /** Raw string value */
  rawValue: string;
  
  /** String representation */
  toString(): string;
}

/** Template tag function signature */
type TemplateTagFunction = (
  strings: TemplateStringsArray,
  ...values: unknown[]
) => unknown;

/** Static template tag function with static support */
type StaticTemplateTagFunction<T extends TemplateTagFunction> = T & {
  /** Static version of the template function */
  withStatic: T;
};

/** Static HTML template result */
interface StaticHTMLTemplateResult extends TemplateResult {
  /** Static type marker */
  _$litType$: 1;
  
  /** Static parts information */
  _$static?: StaticValue[];
}

/** Static SVG template result */
interface StaticSVGTemplateResult extends TemplateResult {
  /** Static type marker */
  _$litType$: 2;
  
  /** Static parts information */
  _$static?: StaticValue[];
}

/** Static MathML template result */
interface StaticMathMLTemplateResult extends TemplateResult {
  /** Static type marker */
  _$litType$: 3;
  
  /** Static parts information */
  _$static?: StaticValue[];
}

// Good: Template structure is mostly static
return html`
  <div class="card">
    <h2>${this.title}</h2>
    <p>${this.description}</p>
  </div>
`;

// Good: Large amounts of static markup
return html`
  <form class="complex-form">
    <fieldset>
      <legend>User Information</legend>
      <label>Name: <input name="name" value="${this.name}"></label>
      <label>Email: <input name="email" value="${this.email}"></label>
    </fieldset>
  </form>
`;

// Better with regular templates: Highly dynamic structure
return html`
  ${this.items.map(item => html`
    <div class="${item.type}">
      ${item.content}
    </div>
  `)}
`;

// NEVER do this with user input
const userInput = this.getUserInput();
const dangerous = unsafeStatic(userInput); // XSS vulnerability!

// ONLY use with trusted, compile-time known values
const safeTagName = "div";
const safe = unsafeStatic(`<${safeTagName}>`); // OK