framework-ui-internals

Files (1)

• SKILL.md

SKILL.md (first lines)

# Внутрішнє життя client/ui-kit

Скіл про **цей репозиторій**, а не про застосунок на фреймворку. У пакет
`@altera/skills` не їде. Прикладні правила оформлення екранів — окремо, у
[screen-design-rules](../screen-design-rules/SKILL.md).

Тут зібране те, що вже одного разу коштувало пошуків.

## 1. Тема безшарова — вона перебиває все

`client/styles/theme.css` написана **поза `@layer`** і підключається після
Tailwind і daisyUI. Безшарове правило перебиває будь-який шар незалежно від
специфічності. Звідси три наслідки, і кожен уже спрацьовував:

**Пиши `background-color`, а не `background`.** Скорочення мовчки обнуляє
`background-image`, а ним daisyUI малює частину компонента — так зникла стрілка
в `.select`, і поле вибору стало не відрізнити від інпута.

**Структурні змінні daisyUI треба оголошувати.** Компоненти (`checkbox`, `radio`,
`toggle`) читають `--border`, `--size-selector` тощо **без фолбеків**:
невизначена змінна анулює всю декларацію рамки, і разом з `appearance: none`
контрол стає невидимим. Так зникали чекбокси.

**Стани не приходять самі.** `.btn` і `.input` у темі задають `background` і
`color` беззастережно — отже штатне оформлення `:disabled` з daisyUI до контрола
не доходить взагалі. Кожен стан, який має бути видно, тема мусить описати сама.
Це виявилося аж на скарзі «вимкнена кнопка не відрізняється від звичайної».

**Варіант, названий у розмітці, теж не приходить.** `btn-ghost` (шар компонентів)
і `text-error` (шар utilities) стояли на кнопці видалення рядка табличної частини
з самого початку — і не діяли: `.btn` теми задає `background`, `border` і `color`
беззастережно. Кнопка виглядала звичайною сірою, хоча код казав «без рамки,
червона». Лікується як `btn-square`: правилом у темі із селектором з двох класів
(`.btn.btn-ghost`), щоб виграти в самої `.btn`. Тобто **клас у розмітці — це
намір, а не результат**: якщо тема чіпає ту саму властивість, варіант треба
описати в темі.

Друга половина того ж випадку варта окремої уваги: `text-error` так і лишився
невиконаним — **навмисно**. Щойно його ввімкнули, у табличній частині вишикувалося
двадцять червоних значків підряд, і червоне перестало означати «обережно».
Мертвий клас у чужій розмітці — привід перевірити, чи його справді хотіли, а не
привід механічно оживити.

Правило: **усе, що має перебити тему, пиши в тому ж файлі нижче за неї**, а не
класами в розмітці.

І зворотний бік тієї ж сили — нею ж і користуються. Розмір іконок був
розсипаний атрибутами `width`/`height` по двох десятках файлів (12, 13, 14 —
хто як вирішив), тож «зробити іконки більшими» не виходило: правка одного місця
нічого не міняла. Лікується одним правилом теми — `.btn > svg`, `.input > svg`
з токеном `--icon-size`: **звичайна CSS-декларація сильніша за презентаційний
атрибут завжди**, незалежно від специфічності. Атрибут лишається значенням для
гліфа поза контролом (значок стану в колонці списку, іконка діалогу).
Коли те саме число мусить жити у двох місцях, назви його в обох: `--icon-size`
у темі й `ICON` в `icons.ts`.

## 2. Контраст рахують, а не дивляться

Приглушені тони, підібрані на око на хорошому моніторі, систематично не
дотягували: `text-base-content/50` — 2.82:1, `/40` — 2.22:1, рамка поля
`#b8c3cc` — 1.79:1 при потрібних 3:1.

Перед тим як міняти колір теми, порахуй пари «текст на фоні». Це десяток рядків
у `deno eval` (відносна яскравість + `(L1+0.05)/(L2+0.05)`), і воно ловить те,
чого око не бачить.

Пороги: **4.5:1** звичайний текст, **3:1** великий текст, межі контролів і
графіка (WCAG 1.4.11). Вимкнений контрол формально виведений з-під вимоги — але
підпис кнопки й ЗНАЧЕННЯ поля це різні речі: значення в режимі перегляду читають,
тож там усе одно 4.5.

Перевіряй на **всіх** фонах, де текст трапляється: білому, зебрі (`#fbfcfd`) і
рядку під курсором (`#dcebf8`) — останній найтемніший, і саме на ньому падає те,
що пройшло на білому.

## 3. Граф чанків: `import type` стирається, значення — ні

Найдорожча помилка цього розділу коштувала 36 kB на кожному відкритті діалога
підбору: `ModelPickerBase` імпортував `listRootSchema`, `alignClass`, `cellStyle`
**з `model-list-base.ts`** — значеннями. Через це чанк пікера тягнув чанк списку
разом із побічно підключеним `<ui-group-tree>` і статичним `xlsx`.

Правила:

- **спільним модулем робиться те, що НЕ тягне поведінки** — типи й чисті
  функції (`table-contract.ts`), не класи й не компоненти;
- **побічний імпорт (`import "./ui-component.ts"`) не вибивається tree-shaking
  ніколи** — він реєструє custom element, тобто має ефект;
- основа табличних форм **не має права знати про компоненти ui-kit**. Саме тому
  фільтри не мають декларативних видів: умій `QueryTableBase` малювати `period`,
  вона б статично імпортувала `<ui-period>`, і за нього платив би кожен список і
  кожен пікер. Розмітку дає екран.

Перевіряти — збіркою, а не міркуванням:

```bash
deno task build:front
grep -o 'from"[^"]*"' dist/assets/model-picker-base-*.js | sort -u
```

## 4. Пастки Lit і TypeScript у базових класах

**Ім'я protected-методу може зіткнутися з властивістю DOM.** `protected
ariaSort(col)` не компілюється взагалі: `ariaSort` — властивість `ARIAMixin` на
`HTMLElement`, і TS каже «defines instance member property, but extended class
defines it as instance member function». Лікується приватним `#ariaSort`. Те саме
чекає на будь-яке ім'я з `aria*`, `title`, `hidden`, `translate`.

**Поле не можна перекрити гетером і навпаки.** Якщо основа оголошує
`protected selectable = false` (полем — щоб екран міг написати `override
selectable = true`), нащадок не може зробити з нього гетер. Коли значення
залежить від властивості, що приходить пізніше (`multiple` у пікера) —
присвоюй у `willUpdate()`.

**Вміст `<svg>` будується тегом `svg`, а не `html`.** Тег `html` створює елементи
в HTML-просторі імен, тож інтерпольований усередину `<svg>` шаблон `html` дає
`<path>`, якого браузер не знає:

```ts

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03