lit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Lit Web Components — правила цього проекту

## Критичне правило: атрибути camelCase → kebab-case

**Проблема:** Lit за замовчуванням перетворює camelCase назви властивостей на lowercase без дефісів:
- `showClear` → атрибут `showclear` (НЕ `show-clear`)
- `displayField` → атрибут `displayfield` (НЕ `display-field`)
- `listSize` → атрибут `listsize` (НЕ `list-size`)

Це мовчазна помилка — компонент просто ігнорує атрибут, без попереджень.

**Рішення:** Для будь-якої camelCase властивості завжди вказувати `attribute` явно:

```ts
// Правильно
@property({ type: String, attribute: "label-position" }) labelPosition: "top" | "left" = "top";
@property({ type: Boolean, attribute: "show-clear" }) showClear = false;
@property({ type: Number, attribute: "list-size" }) listSize = 10;
@property({ type: String, attribute: "display-field" }) displayField = "name";
@property({ type: String, attribute: "id-field" }) idField = "id";
@property({ type: Object, attribute: "picker-params" }) pickerParams = {};
@property({ type: Object, attribute: "fetch-params" }) fetchParams = {};

// Однословні — attribute не потрібний (lowercase вже збігається)
@property({ type: String }) label = "";
@property({ type: String }) placeholder = "";
@property({ type: Boolean }) disabled = false;
@property({ type: String }) url = "";
@property({ type: String }) width = "";
@property({ type: Boolean }) visible = true;
```

**Правило:** якщо назва властивості містить велику літеру — обов'язково додай `attribute: "kebab-case-name"`.

## Boolean атрибути в Lit-шаблонах

Для boolean властивостей використовувати `?` прив'язку:

```ts
// Правильно
html`<ui-picker ?show-clear=${this.readonly}></ui-picker>`
html`<button ?disabled=${!this.canSave}>Зберегти</button>`

// Неправильно — передає рядок "show-clear", не true/false
html`<ui-picker show-clear></ui-picker>`
```

Виняток: статичний boolean атрибут без виразу (завжди true) — можна без `?`:
```ts
html`<input required>`  // OK — завжди true
```

## `<select>`: вибране позначає ПУНКТ, а не `.value` на списку

`.value=${…}` на `<select>` у шаблоні лита **не працює** — і мовчки.

```ts
// Неправильно — показує ПЕРШИЙ пункт, що б не лежало у value
html`<select .value=${this.accountType} @change=${…}>
  <option value="active">Активний</option>
  <option value="passive">Пасивний</option>
</select>`

// Правильно — вибране на самому пункті, від порядку не залежить
html`<select @change=${…}>
  <option value="active"  ?selected=${this.accountType === "active"}>Активний</option>
  <option value="passive" ?selected=${this.accountType === "passive"}>Пасивний</option>
</select>`
```

**Чому.** Лит комітить прив'язки елемента раніше, ніж додає його дітей, тож
`.value` присвоюється, коли жодного `<option>` ще немає. Браузер таке значення
відкидає — вибирати нема з чого, — а щойно пункти з'являються, стає на перший.
На наступних рендерах лит `.value` уже не чіпає: воно дорівнює тому, що він сам
поставив минулого разу. Контрол лишається на першому пункті назавжди.

**Чому це помічають пізно і не тим боком.** Помилка видна ЛИШЕ коли збережене
значення не збігається з першим пунктом, а в половини списків перший пункт —
найчастіший («20%», «покупка», «активний»). Тобто екран виглядає правильним,
доки хтось не вибере інше; а коли вибере — побачить не «показано не те», а **«не
збереглося»**: після взаємодії контрол тримає вибране, і різниця вилазить аж
після перезаходу. Шукати підуть у праві доступу, payload і SQL — усе справне.

**У власному компоненті** з програмною зміною значення (кнопка очищення,
перезавантаження запису) `?selected` мало: атрибут діє, лише доки в `<option>`
не зведено прапорець «брудності», а взаємодія його зводить. Там значення
доставляють властивістю після рендера — див. `ui-select` у ядрі:

```ts
protected override updated(changed: Map<string, unknown>) {
  super.updated?.(changed);
  const select = this.renderRoot.querySelector("select");
  if (select && select.value !== this.value) select.value = this.value;
}
```

Порядок властивостей у ВИКЛИКУ (`.options` перед `.value`) не рятує: значення
виставляє сам компонент у своєму шаблоні.

## Shadow DOM та Tailwind CSS

Компоненти, що наслідують `GlobalStyledLitElement`, отримують зібраний Tailwind через
спільний `CSSStyleSheet` (`tw` із `@client/shared/styles.ts`), який адоптується в кожен
shadow root. Аркуш порожній, доки застосунок його не заповнить — це робить
`app/styles/app-styles.ts`.  
Але Tailwind генерує тільки класи, що використовуються у файлах зі списку `@source`.

Збірка одна, і вона в застосунку: `app/styles/tailwind.css`. Бібліотека Tailwind не
компілює — вона віддає тему плоским CSS, а дописує її `setAppStyles()` сам, уже після
зібраного Tailwind: правила теми безшарові й мусять перебивати utilities, і код це
гарантує надійніше за порядок рядків.

Якщо додаєш Tailwind-класи в новий каталог — додай `@source` до `app/styles/tailwind.css`.
Шлях там реальний, не аліас і не ім'я пакета: сканер Tailwind читає директиву з диска,
повз бандлер.
```css
@source "../../vendor/jsr.io/@altera";   /* ← вже додано: класи з шаблонів ui-kit */
```
Авто-детекція сканує сам застосунок, але `vendor/` виключає — звідси цей рядок.

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03