Розробка бібліотеки Web Components (Lit)

Розробка бібліотеки Web Components (Lit)

Lit — бібліотека від Google для створення Web Components. Важить ~5kb gzipped, будується поверх нативних API (Custom Elements, Shadow DOM, Templates), додаючи реактивні властивості, декларативні шаблони через tagged template literals та автоматичні оновлення DOM.

Вибір Lit проти «голих» Custom Elements виправданий, коли компонентів більше 3–5: Lit видаляє шаблонний код ручного оновлення DOM, реактивних атрибутів та керування життєвим циклом.

Встановлення та структура проекту

npm create vite@latest my-components -- --template lit-ts
cd my-components
npm install

Або в існуючий проект:

npm install lit

Типова структура бібліотеки:

src/
├── components/
│   ├── button/
│   │   ├── button.ts
│   │   ├── button.styles.ts
│   │   └── button.test.ts
│   ├── modal/
│   └── tooltip/
├── styles/
│   └── tokens.css      ← CSS custom properties
├── index.ts            ← реекспорт всіх компонентів
└── types.ts

Базовий компонент

import { LitElement, html, css, PropertyValues } from 'lit'
import { customElement, property, state, query } from 'lit/decorators.js'
import { classMap } from 'lit/directives/class-map.js'
import { ifDefined } from 'lit/directives/if-defined.js'

@customElement('ui-button')
export class UiButton extends LitElement {
  // Реактивні властивості — зміна викликає перерендер
  @property({ type: String })
  variant: 'primary' | 'secondary' | 'ghost' = 'primary'

  @property({ type: String })
  size: 'sm' | 'md' | 'lg' = 'md'

  @property({ type: Boolean, reflect: true })
  disabled = false

  @property({ type: Boolean })
  loading = false

  @property({ type: String })
  type: 'button' | 'submit' | 'reset' = 'button'

  // Внутрішній стан — не атрибут, не публічна властивість
  @state()
  private _focused = false

  // Доступ до DOM елемента всередині shadow
  @query('button')
  private _button!: HTMLButtonElement

  static styles = css`
    :host {
      display: inline-flex;
    }

    button {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      gap: 8px;
      border: none;
      cursor: pointer;
      font-family: inherit;
      font-weight: 600;
      border-radius: var(--ui-radius, 8px);
      transition: background 0.15s, opacity 0.15s, transform 0.1s;
    }

    button:disabled {
      opacity: 0.5;
      cursor: not-allowed;
    }

    button:active:not(:disabled) {
      transform: scale(0.97);
    }

    /* Варіанти */
    :host([variant="primary"]) button,
    button.variant--primary {
      background: var(--ui-color-primary, #7000ff);
      color: #fff;
    }

    :host([variant="secondary"]) button,
    button.variant--secondary {
      background: transparent;
      border: 1.5px solid var(--ui-color-primary, #7000ff);
      color: var(--ui-color-primary, #7000ff);
    }

    :host([variant="ghost"]) button,
    button.variant--ghost {
      background: transparent;
      color: var(--ui-color-primary, #7000ff);
    }

    /* Розміри */
    .size--sm { padding: 6px 14px;  font-size: 13px; }
    .size--md { padding: 10px 22px; font-size: 15px; }
    .size--lg { padding: 14px 30px; font-size: 17px; }

    /* Loading spinner */
    .spinner {
      width: 1em;
      height: 1em;
      border: 2px solid transparent;
      border-top-color: currentColor;
      border-radius: 50%;
      animation: spin 0.6s linear infinite;
    }

    @keyframes spin {
      to { transform: rotate(360deg); }
    }
  `

  render() {
    const classes = classMap({
      [`variant--${this.variant}`]: true,
      [`size--${this.size}`]: true,
      'is-loading': this.loading,
    })

    return html`
      <button
        class=${classes}
        type=${this.type}
        ?disabled=${this.disabled || this.loading}
        aria-disabled=${this.disabled || this.loading}
        @focus=${() => { this._focused = true }}
        @blur=${() => { this._focused = false }}
      >
        ${this.loading ? html`<span class="spinner" aria-hidden="true"></span>` : ''}
        <slot name="icon-start"></slot>
        <slot></slot>
        <slot name="icon-end"></slot>
      </button>
    `
  }

  // Lifecycle: після першого рендеру
  protected firstUpdated() {
    this._button.addEventListener('click', this._handleClick)
  }

  // Lifecycle: після кожного оновлення
  protected updated(changedProps: PropertyValues) {
    if (changedProps.has('disabled')) {
      this.setAttribute('aria-disabled', String(this.disabled))
    }
  }

  private _handleClick = (e: Event) => {
    if (this.disabled || this.loading) {
      e.preventDefault()
      e.stopPropagation()
      return
    }

    // Кастомна подія, що спливає
    this.dispatchEvent(new CustomEvent('ui-click', {
      bubbles: true,
      composed: true,
      detail: { originalEvent: e },
    }))
  }

  // Публічний метод (викликається ззовні)
  focus() {
    this._button?.focus()
  }

  disconnectedCallback() {
    super.disconnectedCallback()
    this._button?.removeEventListener('click', this._handleClick)
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'ui-button': UiButton
  }
}

Реактивні властивості детальніше

@customElement('ui-tabs')
export class UiTabs extends LitElement {
  // reflect: true — синхронізує JS властивість з HTML атрибутом
  @property({ type: Number, reflect: true })
  activeIndex = 0

  // converter — кастомне перетворення рядка атрибута на тип
  @property({
    converter: {
      fromAttribute: (value: string | null) =>
        value ? value.split(',').map(Number) : [],
      toAttribute: (value: number[]) => value.join(','),
    }
  })
  selectedIds: number[] = []

  // hasChanged — пропуск зайвих оновлень
  @property({
    hasChanged: (newVal: object, oldVal: object) =>
      JSON.stringify(newVal) !== JSON.stringify(oldVal),
  })
  config: Record<string, unknown> = {}
}

Directives у шаблонах

import { repeat } from 'lit/directives/repeat.js'
import { cache } from 'lit/directives/cache.js'
import { asyncReplace } from 'lit/directives/async-replace.js'
import { ref } from 'lit/directives/ref.js'

render() {
  return html`
    <!-- repeat з key для ефективного diff -->
    <ul>
      ${repeat(
        this.items,
        (item) => item.id,  // key
        (item) => html`<li>${item.name}</li>`
      )}
    </ul>

    <!-- cache — не знищує DOM при переключенні -->
    ${cache(this.showDetails
      ? html`<details-panel></details-panel>`
      : html`<summary-view></summary-view>`
    )}

    <!-- ref — доступ до DOM елемента -->
    <canvas ${ref(this._canvasRef)}></canvas>
  `
}

Контролери (Reactive Controllers)

Переіспользуємо логіка, незалежна від компонента:

// controllers/mouse-controller.ts
import { ReactiveController, ReactiveControllerHost } from 'lit'

export class MouseController implements ReactiveController {
  host: ReactiveControllerHost
  x = 0
  y = 0

  constructor(host: ReactiveControllerHost) {
    this.host = host
    host.addController(this)
  }

  hostConnected() {
    window.addEventListener('mousemove', this._onMouseMove)
  }

  hostDisconnected() {
    window.removeEventListener('mousemove', this._onMouseMove)
  }

  private _onMouseMove = (e: MouseEvent) => {
    this.x = e.clientX
    this.y = e.clientY
    this.host.requestUpdate()  // спусковує перерендер компонента
  }
}

// Використання в компоненті
@customElement('cursor-tracker')
class CursorTracker extends LitElement {
  private mouse = new MouseController(this)

  render() {
    return html`
      <p>Курсор: ${this.mouse.x}, ${this.mouse.y}</p>
    `
  }
}

Збірка бібліотеки для публікації

// package.json
{
  "name": "@myorg/ui-components",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/components/button/button.js",
      "types": "./dist/components/button/button.d.ts"
    }
  },
  "files": ["dist"],
  "customElements": "custom-elements.json"
}

// vite.config.ts для бібліотеки
export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      formats: ['es'],
      fileName: 'index',
    },
    rollupOptions: {
      external: ['lit'],  // не бандлити Lit — peer dependency
    },
  },
})

Терміни

3–5 компонентів з Lit, декораторами та базовою збіркою — 1 тиждень. Повна бібліотека з 10–15 компонентів із контролерами, типами, storybook-документацією, тестами (Playwright) та npm-публікацією — 3–5 тижнів.