@ozdao/martyrs 0.2.564 → 0.2.566

package/src/modules/LAYOUT.MD

@@ -0,0 +1,767 @@
+# МЕХАНИЗМ РАБОТЫ ЛЕЙАУТОВ OZDAO.DEV
+
+**На основе реальных computed styles с localhost:8041**
+
+---
+
+## ИЕРАРХИЯ И COMPUTED VALUES
+
+### Структура от корня к элементам
+
+```
+#app-wrapper (Root Container)
+  ↓
+#screen (Screen Section)
+  ↓
+Parent wrapper (grid container для scrollview)
+  ↓
+#scrollview (скроллируемая область)
+  ↓
+Page container
+  ↓
+Sections/Blocks
+  ↓
+Components
+```
+
+---
+
+## LEVEL 1: #app-wrapper
+
+**Классы:**
+```
+flex flex-column h-100 w-100 pos-relative o-hidden
+```
+
+**Computed styles:**
+```css
+display: flex
+flex-direction: column
+position: relative
+width: 1200px          /* viewport width */
+height: 692px          /* viewport height */
+overflow: hidden
+overflow-x: hidden
+overflow-y: hidden
+z-index: auto
+box-sizing: border-box
+```
+
+### Как это работает:
+
+**width: 1200px** - не 100% в процентах, а вычисленное значение viewport width в пикселях. Класс `.w-100` в CSS определен как `width: 100%`, но браузер вычисляет это как фактическую ширину viewport.
+
+**height: 692px** - аналогично, вычисленная высота viewport.
+
+**overflow: hidden** - это свойство применяется к контейнеру, чтобы предотвратить появление скроллбара на корневом элементе. Скролл будет только внутри `#scrollview`.
+
+**flex-direction: column** - дочерние элементы укладываются вертикально (header → screen → footer).
+
+---
+
+## LEVEL 2: #screen
+
+**Классы:**
+```
+flex flex-nowrap h-100 pos-relative o-hidden transition-ease-in-out
+```
+
+**Computed styles:**
+```css
+display: flex
+flex-direction: row           /* горизонтальный flex */
+flex-wrap: nowrap
+position: relative
+width: 1200px
+height: 632.148px             /* меньше родителя! */
+overflow: hidden
+overflow-x: hidden
+overflow-y: hidden
+transition: 0.33s cubic-bezier(0.42, 0, 0.58, 1)
+z-index: auto
+```
+
+### Как это работает:
+
+**height: 632.148px** - меньше чем родитель (692px). Разница ~60px ушла на header/navigationbar.
+
+Вычисление: родитель flex-column → дочерние элементы делят высоту → если header занимает ~60px, screen получает остаток.
+
+**flex-direction: row** - sidebar и content располагаются горизонтально.
+
+**overflow: hidden** - скрывает всё что выходит за границы. Скролла здесь нет.
+
+---
+
+## LEVEL 3: #scrollview и его parent
+
+**Parent классы:**
+```
+rows-1-min0_max1 z-index-1 pos-relative w-100 h-100
+```
+
+**Parent computed:**
+```css
+display: grid
+grid-template-rows: 632.148px    /* одна строка фиксированной высоты */
+position: relative
+width: 1152px
+height: 632.148px
+z-index: 10
+```
+
+**#scrollview классы:**
+```
+o-y-scroll o-x-hidden h-100
+```
+
+**#scrollview computed:**
+```css
+display: block
+position: static
+width: 1152px
+height: 632.148px
+overflow: hidden scroll         /* x: hidden, y: scroll */
+overflow-x: hidden
+overflow-y: scroll
+box-sizing: border-box
+z-index: auto
+```
+
+### Как это работает:
+
+**Parent использует grid** с `grid-template-rows: 632.148px`. Класс `rows-1-min0_max1` создаёт одну строку grid с `minmax(0, 1fr)`.
+
+Почему так: grid с одной строкой позволяет дочернему элементу (`#scrollview`) получить точную высоту родителя, при этом контент внутри `#scrollview` может быть любой высоты и скроллиться.
+
+**#scrollview имеет overflow-y: scroll** - это единственное место в приложении где работает вертикальный скролл. Весь контент страниц находится внутри этого элемента.
+
+**width: 1152px** - меньше чем `#screen` (1200px). Разница ~48px ушла на sidebar.
+
+---
+
+## LEVEL 4: Page Container
+
+**Классы:**
+```
+h-min-100 pos-relative w-100
+```
+
+**Computed:**
+```css
+display: block
+position: relative
+padding: 0px
+width: 1152px              /* = родитель (#scrollview) */
+height: 2013.8px           /* больше viewport - auto height */
+box-sizing: border-box
+```
+
+### Как это работает:
+
+**height: 2013.8px** - высота контента, не ограничена. Браузер вычисляет автоматически на основе дочерних элементов.
+
+**width: 1152px** - наследуется от родителя (#scrollview). Класс `.w-100` даёт `width: 100%`, что вычисляется как 1152px.
+
+**position: relative** - создаёт positioning context для дочерних элементов с `position: absolute`.
+
+---
+
+## FLEX CONTAINERS
+
+### Пример: кнопки в header
+
+**Классы:**
+```
+flex flex-center flex-nowrap gap-thin
+```
+
+**Computed:**
+```css
+display: flex
+flex-direction: row
+gap: 8px                     /* gap-thin = 0.5rem = 8px */
+justify-content: center
+align-items: center
+flex-wrap: nowrap
+width: 1048.97px
+```
+
+### Как это работает:
+
+**gap: 8px** - браузер вычисляет из `0.5rem`. Base font-size = 16px → 0.5 * 16 = 8px.
+
+**justify-content: center** - дочерние элементы центрируются по главной оси (горизонтально).
+
+**align-items: center** - дочерние элементы центрируются по поперечной оси (вертикально).
+
+**width: 1048.97px** - вычисленная ширина на основе родителя и других стилей. Не круглое число из-за вычислений браузера с sub-pixel precision.
+
+### Button внутри flex
+
+**Классы:**
+```
+hover-bg-light transition-quint-out w-100 flex radius-small flex-nowrap flex-v-center pd-thin
+```
+
+**Computed:**
+```css
+display: flex
+padding: 8px                 /* pd-thin = 0.5rem = 8px */
+border-radius: 12px          /* radius-small */
+background-color: rgba(0, 0, 0, 0)
+transition: 0.33s cubic-bezier(0.22, 1, 0.36, 1)
+```
+
+### Как это работает:
+
+Кнопка сама является flex контейнером для своего контента (иконка + текст).
+
+**padding: 8px** - одинаковый со всех сторон. Вычислено из `pd-thin`.
+
+**border-radius: 12px** - вычислено из `radius-small`. В CSS может быть определено в rem, браузер конвертирует в px.
+
+---
+
+## GRID LAYOUTS
+
+### Пример: .cols-2 на странице альбома
+
+**Классы:**
+```
+cols-2 mobile:cols-1 gap-big
+```
+
+**Computed (desktop):**
+```css
+display: grid
+grid-template-columns: 538px 538px
+gap: 52px                    /* gap-big = 3.25rem = 52px */
+position: static
+width: 1128px                /* (538 * 2) + 52 = 1128 */
+```
+
+### Как это работает:
+
+**grid-template-columns: 538px 538px** - две колонки равной ширины.
+
+Вычисление: родитель имеет ширину (возможно с padding), браузер вычисляет: `(parent_width - gap) / 2`.
+
+Пример: если parent = 1128px, gap = 52px → `(1128 - 52) / 2 = 538px`.
+
+**gap: 52px** - промежуток между колонками. Вычислено: 3.25rem * 16px = 52px.
+
+**width: 1128px** - вычисленная ширина grid контейнера из родителя (возможно с учётом padding родителя).
+
+### Left column (sticky)
+
+**Классы:**
+```
+pos-sticky pos-t-0 mobile:pos-relative album-cover-section
+```
+
+**Computed:**
+```css
+display: block
+position: sticky
+top: 0px
+width: 538px                 /* = grid column width */
+max-width: none
+grid-column: auto
+```
+
+### Как это работает:
+
+**position: sticky** - элемент ведёт себя как `relative` пока не достигнет порога скролла, затем как `fixed` относительно scrolling container.
+
+**top: 0px** - порог: когда элемент достигает 0px от верха scrolling container (в данном случае `#scrollview`), он "прилипает".
+
+Sticky работает только если:
+1. Есть scrolling parent (у нас `#scrollview` с `overflow-y: scroll`)
+2. Есть достаточно контента для скролла
+3. Position не `static`
+
+**width: 538px** - наследуется от grid column. Grid child автоматически получает ширину своей колонки.
+
+### Right column
+
+**Классы:**
+```
+album-details-section
+```
+
+**Computed:**
+```css
+display: block
+position: static
+width: 538px                 /* = grid column width */
+grid-column: auto
+```
+
+Вторая колонка. При скролле контента правой колонки, левая (sticky) остаётся видимой в viewport.
+
+---
+
+## UTILITY КЛАССЫ И ИХ COMPUTED VALUES
+
+### Размеры
+
+| Класс | CSS определение | Computed (16px base) | Пример элемента |
+|-------|----------------|---------------------|------------------|
+| `.gap-thin` | `gap: 0.5rem` | `gap: 8px` | flex containers |
+| `.gap-small` | `gap: 0.75rem` | `gap: 12px` | - |
+| `.gap-medium` | `gap: 1.5rem` | `gap: 24px` | - |
+| `.gap-big` | `gap: 3.25rem` | `gap: 52px` | .cols-2 |
+| `.pd-thin` | `padding: 0.5rem` | `padding: 8px` | buttons |
+| `.pd-small` | `padding: 0.75rem` | `padding: 12px` | cards |
+| `.pd-medium` | `padding: 1.5rem` | `padding: 24px` | sections |
+| `.w-100` | `width: 100%` | `width: 1200px` | #app-wrapper |
+| `.h-100` | `height: 100%` | `height: 692px` | #app-wrapper |
+
+### Как работает конверсия rem → px:
+
+1. Браузер имеет base font-size (обычно 16px)
+2. CSS: `gap: 3.25rem`
+3. Браузер вычисляет: `3.25 * 16 = 52px`
+4. Computed value: `52px`
+
+На разных viewport base font-size может меняться (responsive typography), поэтому computed values будут разными:
+- Desktop 16px base: `gap: 52px`
+- Tablet 24px base: `gap: 78px`
+
+### Процентные значения
+
+**Класс `.w-100`:**
+- CSS: `width: 100%`
+- Родитель (#app-wrapper): viewport width
+- Вычисление: `100% от viewport width`
+- Computed: `width: 1200px` (если viewport = 1200px)
+
+Процент всегда вычисляется относительно родителя.
+
+---
+
+## POSITION И STACKING CONTEXT
+
+### Stacking Context
+
+**Что создаёт stacking context:**
+- `position: relative/absolute/fixed/sticky` + `z-index: <не auto>`
+- `opacity: < 1`
+- `transform: <не none>`
+- И другие свойства
+
+**Пример:**
+
+```html
+<div style="position: relative; z-index: 1">
+  <!-- Stacking context A -->
+  <div style="position: absolute; z-index: 100">Child A</div>
+</div>
+
+<div style="position: relative; z-index: 2">
+  <!-- Stacking context B -->
+  <div style="position: absolute; z-index: 1">Child B</div>
+</div>
+```
+
+**Результат:** Child B будет поверх Child A, несмотря на то что у Child A z-index больше (100 vs 1).
+
+**Почему:** Child A находится внутри stacking context A (z-index: 1), Child B внутри context B (z-index: 2). Context B выше context A, поэтому всё содержимое B будет выше A.
+
+### Position: sticky механизм
+
+**Computed на левой колонке альбома:**
+```css
+position: sticky
+top: 0px
+```
+
+**Как работает:**
+
+1. Элемент в normal flow (как `position: relative`)
+2. Скролл начинается
+3. Когда элемент достигает `top: 0px` от края scrolling container
+4. Элемент "прилипает" и ведёт себя как `position: fixed` относительно scrolling container
+5. Когда скролл доходит до конца parent element, sticky "отлипает" и уходит вместе с родителем
+
+**Scrolling container** для sticky в проекте: `#scrollview` с `overflow-y: scroll`.
+
+---
+
+## OVERFLOW И SCROLLING
+
+### Цепочка overflow
+
+```
+#app-wrapper: overflow: hidden
+  ↓
+#screen: overflow: hidden
+  ↓
+parent wrapper: display: grid (нет overflow)
+  ↓
+#scrollview: overflow-y: scroll  ← СКРОЛЛ ЗДЕСЬ
+  ↓
+page content: height > viewport
+```
+
+### Как это работает:
+
+**Overflow: hidden на #app-wrapper и #screen** - предотвращает появление скроллбара на этих уровнях. Даже если контент внутри больше, он будет обрезан, но скроллбар не появится.
+
+**Overflow-y: scroll на #scrollview** - создаёт scrolling context. Контент внутри может быть любой высоты, появится вертикальный скроллбар.
+
+**Grid parent** - не имеет overflow, но имеет фиксированную высоту через `grid-template-rows: 632.148px`. Это ограничивает высоту `#scrollview`, а внутри scrollview контент скроллится.
+
+---
+
+## АДАПТИВНОСТЬ (mobile: prefix)
+
+### Пример: .cols-2.mobile:cols-1
+
+**Desktop computed:**
+```css
+grid-template-columns: 538px 538px
+```
+
+**Mobile computed:**
+```css
+grid-template-columns: 1fr
+```
+
+### Как это работает:
+
+В CSS определены media queries:
+
+```css
+@media (max-width: 640px) {
+  .mobile\:cols-1 {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+На узком viewport (≤640px) применяется `.mobile:cols-1`, который перезаписывает `grid-template-columns`.
+
+**Computed на mobile:** браузер видит одну колонку `1fr`, которая занимает всю доступную ширину.
+
+### Пример: .pos-sticky.mobile:pos-relative
+
+**Desktop computed:**
+```css
+position: sticky
+top: 0px
+```
+
+**Mobile computed:**
+```css
+position: relative
+top: 0px  /* игнорируется для relative */
+```
+
+**Почему так:** На mobile нет смысла в sticky sidebar, т.к. layout превращается в одну колонку (стэк). Sticky превращается в обычный relative элемент.
+
+---
+
+## FLEX VS GRID: КАК БРАУЗЕР ВЫБИРАЕТ РАЗМЕРЫ
+
+### Flex sizing
+
+**Flex container:**
+```css
+display: flex
+gap: 8px
+```
+
+**Flex child (без классов flex-*):**
+```css
+flex: 0 1 auto  /* flex-grow: 0, flex-shrink: 1, flex-basis: auto */
+```
+
+**Вычисление:**
+1. `flex-basis: auto` → берётся content width
+2. `flex-grow: 0` → элемент не растёт
+3. `flex-shrink: 1` → элемент сжимается если нужно
+
+**Flex child с .flex-child-1:**
+```css
+flex: 1  /* flex-grow: 1, flex-shrink: 1, flex-basis: 0% */
+```
+
+**Вычисление:**
+1. `flex-basis: 0%` → элемент начинает с нулевой ширины
+2. `flex-grow: 1` → элемент растёт и занимает доступное пространство
+3. Если несколько детей с `flex: 1`, они делят пространство поровну
+
+### Grid sizing
+
+**Grid container:**
+```css
+display: grid
+grid-template-columns: 538px 538px
+gap: 52px
+```
+
+**Вычисление ширины grid:**
+```
+width = column1 + column2 + gap
+width = 538 + 538 + 52 = 1128px
+```
+
+**Grid child:**
+- Автоматически получает ширину своей колонки (538px)
+- Не нужно указывать width явно
+
+**Если grid-template-columns: 1fr 1fr:**
+```
+available_width = parent_width - gap
+column_width = available_width / 2
+```
+
+Пример: parent = 1128px, gap = 52px
+```
+available = 1128 - 52 = 1076px
+column = 1076 / 2 = 538px
+```
+
+**Вычисление в обратную сторону:**
+
+Браузер смотрит на parent width, вычитает gap, делит на количество `1fr`, получает ширину каждой колонки, затем конвертирует `1fr` в конкретные px значения.
+
+Поэтому в computed styles всегда px, а не `1fr`.
+
+---
+
+## КАК ВЫЧИСЛЯЮТСЯ РАЗМЕРЫ (CASCADE)
+
+### Пример: кнопка
+
+**HTML:**
+```html
+<button class="pd-thin radius-small flex gap-thin">
+  <Icon />
+  <span>Text</span>
+</button>
+```
+
+**CSS (упрощённо):**
+```css
+.pd-thin { padding: 0.5rem; }
+.radius-small { border-radius: 0.75rem; }
+.flex { display: flex; }
+.gap-thin { gap: 0.5rem; }
+```
+
+**Computed:**
+```css
+display: flex
+padding: 8px
+border-radius: 12px
+gap: 8px
+```
+
+**Процесс:**
+1. Браузер читает классы: `pd-thin`, `radius-small`, `flex`, `gap-thin`
+2. Находит соответствующие CSS правила
+3. Применяет их (в порядке специфичности/каскада)
+4. Вычисляет rem → px (base = 16px)
+   - `0.5rem` → `8px`
+   - `0.75rem` → `12px`
+5. Сохраняет в computed styles
+
+**Если есть конфликт:**
+```css
+.pd-thin { padding: 0.5rem; }
+.custom-button { padding: 1rem; }
+```
+
+```html
+<button class="pd-thin custom-button">
+```
+
+**Computed:** `padding: 16px` (выиграло `.custom-button` если оно определено позже в CSS или имеет большую специфичность)
+
+---
+
+## ПОЧЕМУ COMPUTED ЗНАЧЕНИЯ В PX, А НЕ REM
+
+Браузер всегда конвертирует относительные единицы (rem, em, %) в абсолютные (px) для рендеринга.
+
+**CSS:**
+```css
+.gap-big { gap: 3.25rem; }
+```
+
+**Computed:**
+```css
+gap: 52px
+```
+
+**Процесс:**
+1. Браузер видит `3.25rem`
+2. Смотрит на root element font-size (обычно 16px)
+3. Вычисляет: `3.25 * 16 = 52`
+4. Сохраняет в computed styles как `52px`
+5. Использует это значение для layout
+
+DevTools показывает computed styles - финальные значения после всех вычислений.
+
+---
+
+## VIEWPORT WIDTH/HEIGHT И ПРОЦЕНТНЫЕ ЗНАЧЕНИЯ
+
+### .w-100 и .h-100
+
+**CSS:**
+```css
+.w-100 { width: 100%; }
+.h-100 { height: 100%; }
+```
+
+**На #app-wrapper:**
+```html
+<div id="app-wrapper" class="w-100 h-100">
+```
+
+**Computed:**
+```css
+width: 1200px
+height: 692px
+```
+
+**Процесс:**
+1. Браузер видит `width: 100%`
+2. Ищет parent element для вычисления процента
+3. Parent = viewport (browser window)
+4. Viewport width = 1200px
+5. Вычисляет: `100% от 1200px = 1200px`
+6. Computed: `width: 1200px`
+
+**На вложенном элементе:**
+```html
+<div id="app-wrapper" style="width: 1200px">
+  <div class="w-100">Child</div>
+</div>
+```
+
+**Child computed:**
+```css
+width: 1200px  /* 100% от родителя */
+```
+
+---
+
+## ЧТО ПРОИСХОДИТ ПРИ RESIZE VIEWPORT
+
+**Начальное состояние (viewport 1200px):**
+```
+#app-wrapper: width: 1200px
+.cols-2: grid-template-columns: 538px 538px
+```
+
+**После resize (viewport 800px):**
+```
+#app-wrapper: width: 800px
+.cols-2: grid-template-columns: 374px 374px
+```
+
+**Процесс:**
+1. Viewport изменился
+2. Браузер пересчитывает все `width: 100%` элементы
+3. #app-wrapper получает новую ширину (800px)
+4. Grid пересчитывает колонки: `(800 - gap) / 2 = 374px`
+5. Layout обновляется
+
+**На mobile (viewport ≤640px):**
+
+Media query активируется:
+```css
+@media (max-width: 640px) {
+  .mobile\:cols-1 { grid-template-columns: 1fr; }
+}
+```
+
+Grid меняется с 2 колонок на 1:
+```
+grid-template-columns: 1fr
+```
+
+Вычисленная ширина одной колонки = вся доступная ширина.
+
+---
+
+## DEBUGGING: КАК ЧИТАТЬ COMPUTED STYLES
+
+**DevTools → Elements → Computed tab**
+
+### Что смотреть:
+
+**display:**
+- `flex` → элемент flex container
+- `grid` → элемент grid container
+- `block` → обычный блочный элемент
+
+**flex-direction:** (если flex)
+- `row` → горизонтальное направление
+- `column` → вертикальное направление
+
+**grid-template-columns:** (если grid)
+- `538px 538px` → две колонки по 538px
+- `1fr` → одна колонка на всю ширину
+
+**gap:**
+- Промежуток между flex/grid items в px
+
+**position:**
+- `static` → обычный flow
+- `relative` → смещение от обычной позиции
+- `absolute` → позиционирование относительно positioned parent
+- `sticky` → прилипающий элемент
+- `fixed` → фиксированный относительно viewport
+
+**width/height:**
+- Финальные вычисленные размеры в px
+
+**overflow-x/overflow-y:**
+- `hidden` → контент обрезается
+- `scroll` → скроллбар всегда
+- `auto` → скроллбар при необходимости
+
+---
+
+## РЕЗЮМЕ: КЛЮЧЕВЫЕ МЕХАНИЗМЫ
+
+### 1. Иерархия контейнеров
+- Root → Screen → Scrollview parent (grid) → Scrollview → Page → Sections → Components
+
+### 2. Overflow chain
+- Root и Screen: `overflow: hidden` (нет скролла)
+- Scrollview: `overflow-y: scroll` (единственный скролл)
+
+### 3. Flex/Grid sizing
+- Flex: `flex-grow`, `flex-shrink`, `flex-basis` определяют размер
+- Grid: browser вычисляет px значения колонок из `fr` или других единиц
+
+### 4. Position: sticky
+- Работает внутри scrolling container (#scrollview)
+- Элемент "прилипает" при достижении порога (top/bottom)
+
+### 5. Stacking context
+- Создаётся position + z-index
+- Дочерние z-index работают только внутри своего контекста
+
+### 6. Computed values всегда в px
+- rem → px (через base font-size)
+- % → px (через parent размер)
+- fr → px (grid вычисляет)
+
+### 7. Responsive (mobile:)
+- Media queries перезаписывают стили на узких viewport
+- Grid меняется с 2 колонок на 1
+- Sticky превращается в relative
+
+---
+
+**Дата:** 2025-01-20
+**Источник:** Computed styles с http://localhost:8041
+**Viewport:** 1200x692px desktop