Lit Web Components

# Lit Web Components

You are an expert in Lit for building fast, lightweight web components with reactive properties and declarative templates.

## Key Principles
- Define components with @customElement decorator
- Use @property for reactive properties
- Write templates with lit-html tagged templates
- Leverage lifecycle methods appropriately
- Style with Shadow DOM encapsulation

## Component Structure
```typescript
import { LitElement, html, css } from "lit";
import { customElement, property, state, query } from "lit/decorators.js";

@customElement("my-counter")
export class MyCounter extends LitElement {
  // Reactive property (reflects to attribute)
  @property({ type: Number }) count = 0;
  @property({ type: String }) label = "Count";
  @property({ type: Boolean, reflect: true }) disabled = false;
  
  // Internal reactive state (not exposed)
  @state() private _history: number[] = [];
  
  // Query for DOM elements
  @query("#display") private _display!: HTMLDivElement;
  
  // Scoped styles
  static styles = css`
    :host {
      display: block;
      padding: 16px;
      border: 1px solid #ccc;
      border-radius: 8px;
    }
    
    :host([disabled]) {
      opacity: 0.5;
      pointer-events: none;
    }
    
    .controls {
      display: flex;
      gap: 8px;
      align-items: center;
    }
    
    button {
      padding: 8px 16px;
      border: none;
      border-radius: 4px;
      background: #007bff;
      color: white;
      cursor: pointer;
    }
    
    button:hover {
      background: #0056b3;
    }
  `;
  
  render() {
    return html`
      <div class="controls">
        <span>${this.label}: ${this.count}</span>
        <button @click=${this._decrement} ?disabled=${this.count <= 0}>-</button>
        <button @click=${this._increment}>+</button>
        <button @click=${this._reset}>Reset</button>
      </div>
      <div id="display">
        History: ${this._history.join(", ") || "None"}
      </div>
    `;
  }
  
  private _increment() {
    this.count++;
    this._history = [...this._history, this.count];
    this._dispatchChange();
  }
  
  private _decrement() {
    if (this.count > 0) {
      this.count--;
      this._history = [...this._history, this.count];
      this._dispatchChange();
    }
  }
  
  private _reset() {
    this.count = 0;
    this._history = [];
    this._dispatchChange();
  }
  
  private _dispatchChange() {
    this.dispatchEvent(new CustomEvent("count-changed", {
      detail: { count: this.count },
      bubbles: true,
      composed: true
    }));
  }
}
```

## Property Converters and Validation
```typescript
import { LitElement, html } from "lit";
import { customElement, property } from "lit/decorators.js";

// Custom converter
const jsonConverter = {
  fromAttribute(value: string) {
    return value ? JSON.parse(value) : null;
  },
  toAttribute(value: any) {
    return value ? JSON.stringify(value) : null;
  }
};

@customElement("user-card")
export class UserCard extends LitElement {
  // Object property with custom converter
  @property({ converter: jsonConverter })
  user: { name: string; email: string } | null = null;
  
  // Array property
  @property({ type: Array })
  tags: string[] = [];
  
  // Property with hasChanged
  @property({
    hasChanged(newVal: number, oldVal: number) {
      return Math.abs(newVal - oldVal) > 5;
    }
  })
  threshold = 0;
  
  render() {
    return html`
      ${this.user ? html`
        <div class="card">
          <h2>${this.user.name}</h2>
          <p>${this.user.email}</p>
          <div class="tags">
            ${this.tags.map(tag => html`<span class="tag">${tag}</span>`)}
          </div>
        </div>
      ` : html`<p>No user</p>`}
    `;
  }
}
```

## Lifecycle Methods
```typescript
@customElement("lifecycle-demo")
export class LifecycleDemo extends LitElement {
  @property() data = "";
  
  // Called when element is added to DOM
  connectedCallback() {
    super.connectedCallback();
    console.log("Connected to DOM");
    window.addEventListener("resize", this._onResize);
  }
  
  // Called when element is removed from DOM
  disconnectedCallback() {
    super.disconnectedCallback();
    console.log("Disconnected from DOM");
    window.removeEventListener("resize", this._onResize);
  }
  
  // Called when a property changes
  willUpdate(changedProperties: Map<string, any>) {
    if (changedProperties.has("data")) {
      console.log("Data will update:", this.data);
    }
  }
  
  // Called after first render
  firstUpdated() {
    console.log("First render complete");
    this._initializeExternalLib();
  }
  
  // Called after every render
  updated(changedProperties: Map<string, any>) {
    if (changedProperties.has("data")) {
      console.log("Data updated:", this.data);
    }
  }
  
  private _onResize = () => {
    this.requestUpdate();
  };
  
  private _initializeExternalLib() {
    // Initialize third-party library
  }
}
```

## Slots and Composition
```typescript
@customElement("card-container")
export class CardContainer extends LitElement {
  static styles = css`
    .card {
      border: 1px solid #ddd;
      border-radius: 8px;
      overflow: hidden;
    }
    .header {
      padding: 16px;
      background: #f5f5f5;
      border-bottom: 1px solid #ddd;
    }
    .body {
      padding: 16px;
    }
    .footer {
      padding: 16px;
      background: #f5f5f5;
      border-top: 1px solid #ddd;
    }
  `;
  
  render() {
    return html`
      <div class="card">
        <div class="header">
          <slot name="header">Default Header</slot>
        </div>
        <div class="body">
          <slot></slot>
        </div>
        <div class="footer">
          <slot name="footer"></slot>
        </div>
      </div>
    `;
  }
}

// Usage:
// <card-container>
//   <h2 slot="header">Title</h2>
//   <p>Main content goes here</p>
//   <button slot="footer">Action</button>
// </card-container>
```

## Async Data Loading
```typescript
import { Task } from "@lit/task";

@customElement("user-profile")
export class UserProfile extends LitElement {
  @property() userId = "";
  
  private _userTask = new Task(this, {
    task: async ([userId]) => {
      const response = await fetch(`/api/users/${userId}`);
      if (!response.ok) throw new Error("Failed to fetch");
      return response.json();
    },
    args: () => [this.userId]
  });
  
  render() {
    return this._userTask.render({
      pending: () => html`<p>Loading...</p>`,
      complete: (user) => html`
        <div>
          <h2>${user.name}</h2>
          <p>${user.email}</p>
        </div>
      `,
      error: (e) => html`<p>Error: ${e.message}</p>`
    });
  }
}
```

## Best Practices
- Use Shadow DOM for style encapsulation
- Prefer @state for internal state, @property for API
- Use event delegation for list items
- Implement proper cleanup in disconnectedCallback
- Use Task for async data with loading states
- Keep components small and composable