itube-specs 0.0.921 → 0.0.923

package/DOCS/CONVENTIONS.md

@@ -0,0 +1,44 @@
+# Conventions
+
+Layer + every site. From an app: `node_modules/itube-specs/DOCS/CONVENTIONS.md`. Styles → `DOCS/STYLES.md`.
+Human-facing rationale → the layer's `README.md` (Russian).
+
+## Components
+
+`pathPrefix: true` → name = folder path + filename, repeated segments deduped by Nuxt. Folder is the
+namespace; filename must not repeat it.
+
+- `ui/icon.vue` → `<UiIcon>` · `player/core.vue` → `<PlayerCore>` · `info/grid.vue` → `<InfoGrid>` (not
+  `<InfoInfoGrid>`)
+- Folder root: `index.vue` when the deduped name is already multi-word (`card/video/index.vue` →
+  `<CardVideo>`); `main.vue` only when `index.vue` would give one word (`filter/main.vue` → `<FilterMain>`).
+  Never a single-word name — clashes with HTML elements.
+- BEM root class = kebab-case of the name: `<CardVideo>` → `.card-video`
+- `pathPrefix: true` mandatory — layers break component exports under `false` (nuxt/nuxt#30099)
+
+**App override:** an app defining the same name outranks the layer and wins auto-import; callers untouched.
+Don't fork a component when a prop expresses the difference.
+
+## Markup
+
+`<div>` is the fallback, not the default.
+
+| Need | Tag |
+|---|---|
+| text | `<span>` inline, `<p>` paragraph — never bare `<div>` |
+| structure | `header`, `nav`, `main`, `aside`, `footer`, `section`, `article` |
+| sequence of similar items | `<ul>`/`<ol>` + `<li>` — chip rows and tag clouds included |
+| action / navigation / collapsible | `<button>` / `<a>` / `<details>`+`<summary>` |
+| forms | `<label>`, `<fieldset>`, `<legend>`, native `<input>` types |
+| emphasis, figures | `<em>`/`<strong>`, `<figure>`/`<figcaption>` — not style-only spans |
+
+## TypeScript
+
+- Semicolons always. No code comments unless asked.
+- Domain string sets: `as const` PascalCase objects in `runtime/constants/`, type via
+  `typeof X[keyof typeof X]`. Never `enum` — it survives into the bundle, and `import type` erases it so
+  `X.Member` is `undefined` at runtime in a published layer; you also can't assign a raw API/URL/cookie string
+  to an enum. String values, not numeric (`0` is falsy — `if (spotType)` misreads member `0` as absent;
+  `AdSpotType` is numeric, a wart, don't copy). Framework unions (Nuxt status) stay unions.
+- `.vue` templates are NOT typechecked — `tsc` doesn't read them, `vue-tsc` isn't a gate. A clean `tsc` says
+  nothing about template expressions. Read them, or `npx vue-tsc --noEmit` ad hoc past pre-existing noise.

package/DOCS/STYLES.md

@@ -0,0 +1,127 @@
+# Styles
+
+Canonical for every itube site — the layer owns 100% of the SCSS; apps have an empty `assets/scss/` override
+slot. Read before touching any `<style lang="scss">`, `assets/scss/**`, or a theme token. Paths are
+layer-relative; from an app: `node_modules/itube-specs/DOCS/STYLES.md`. Human-facing version → `README.md`.
+
+## Co-location
+
+- Component and page styles in the SFC's own `<style lang="scss">`. **No `scoped`** — flat BEM isolates.
+- Nothing per-component or per-page in `assets/scss/`.
+- Tree: `assets/scss/` → `vars/` (palette, vars, tokens, z-index), `themes/`, `mixins/`, `base/`, `layout/`,
+  `main.scss`. `css` entry is `main.scss`, loads only `vars/tokens`, `base`, `layout`.
+- **Never `@use 'vars'`/`'mixins'` in an SFC block** — auto-injected by the *app's*
+  `vite.css.preprocessorOptions.scss.additionalData` + `loadPaths`.
+- Sass-loaded global partials: `@use` relatively within their own root, bare specifiers across roots
+  (layer↔app) so `loadPaths` resolves.
+- The layer has no `sass` package — layer styles compile only inside an app, never in the layer's vitest.
+
+## Themes
+
+Dir per theme: `assets/scss/themes/<name>/_theme.scss`. App picks one via `theme:` in its
+`config/site.config.ts` (read by its `nuxt.config.ts` *and* `app.config.ts` — `useAppConfig()` doesn't exist at
+config time), appends `themes/<theme>/` to `loadPaths`; `@forward 'theme'` in `vars/_index.scss` resolves
+there because no `_theme.scss` sits beside it.
+
+**Dir-per-theme is load-bearing** — Sass needs a literal `@use`/`@forward` path, so only the folder can vary.
+
+`loadPaths = [<app>/assets/scss, <layer>/assets/scss/themes/<theme>, <layer>/assets/scss]`. App first → a site
+overrides any partial by name (its `vars/_theme.scss` wins over loadPaths).
+
+**Every token must exist in every theme** — a missing one is a hard Sass error that kills the app build. Two
+guards, both pre-commit + CI:
+
+| Script | Proves | Blind spot |
+|---|---|---|
+| `check:themes` | themes declare the same top-level `$name:` set (`$surfaces` / `$button-variant-overrides` contents ignored — a theme may leave either empty) | token declared in **no** theme |
+| `check:styles` | every `<style>` block compiles against every theme, same preamble + loadPaths as Vite; names the failing theme (~1.5s) | — |
+
+## BEM
+
+`.block {}`, `.block__element {}`, `.block.--modifier {}` — modifier prefix `--`.
+
+**No nesting**, every selector flat with its full class name. `&` only for pseudo-classes, pseudo-elements,
+state modifiers (`&::after`, `&:focus-visible`, `&.--open`).
+
+```scss
+.layout-header {}
+.layout-header__logo {}   // not .layout-header { &__logo {} }
+```
+
+## Hover
+
+**Always `@include hover(<properties>)`, never `&:hover`.** Wraps in `@media (hover: hover)` (on touch a hover
+sticks after a tap), declares `--transition` for the listed properties, pairs `:hover` with `:focus-visible`.
+
+```scss
+.ui-btn.--muted {
+  @include hover(background-color, border) { background-color: $button-muted-bg--hover; }
+}
+```
+
+Applies to the current selector only, so hovering one element to restyle another is written flat inside your
+own media query:
+
+```scss
+@media (hover: hover) {
+  .card-round:is(:hover, :focus-visible) .card-round__img { transform: scale(1.05); }
+}
+```
+
+## Tokens
+
+Never hardcode a color, size or z-index.
+
+| File | Holds | Type |
+|---|---|---|
+| `vars/_palette.scss` | `$color-indigo-600` — raw palette | SCSS var |
+| `themes/<theme>/_theme.scss` | `$chips-text`, `$button-bg--hover` — colors, one per theme | SCSS var |
+| `vars/_vars.scss` | `$radius-*`, `$blur-*`, `$spacing` — static non-color | SCSS var |
+| `vars/_tokens.scss` | `--header-height` — changes at a breakpoint or set via JS | CSS custom prop |
+
+- Changes at a breakpoint or set via JS → CSS custom property. Everything else → SCSS var.
+- **Palette is private**, consumed only by theme files. A component must never use `$color-*` — add the token
+  to **every** theme first.
+- **No semantic tier** (`$text-muted`, `$role-border-subtle`) — themes reference palette directly.
+- Theme files hold **colors only**; radius/blur/static → `vars/_vars.scss`.
+
+### Context-dependent colors
+
+Never a theme flag in a component. Two mixins, driven from the theme file:
+
+- `surface($name)` — block declares itself an island (`.ui-popup { @include surface(overlay); }`), contents
+  pick up colors by cascade. Theme supplies deltas via `$surfaces`; no differentiation → `$surfaces: ()`.
+  Components read `var(--input-bg, #{$input-bg})`, so a single color can still be overridden directly.
+- `button-variant($key)` — place asks, theme answers by name via `$button-variant-overrides`. The element's
+  class still reflects the `theme=` prop, so the mixin prints `--button-variant` as a DevTools marker.
+
+`appConfig.theme` — structural differences only (different element, extra icon, `v-if`).
+
+### Naming
+
+`$<block>-<element>?-<modifier>?-<property>-<state>?`
+
+- block = component root · element = BEM element, optional · modifier = variant, optional
+- property — always present, always short: `bg`, `text`, `border`, `radius`, `icon`, `shadow`. Never the full
+  CSS name (`$button-background` → `$button-bg`, `$input-border-radius` → `$input-radius`). `color` is banned
+  as a property — ambiguous, use `text`.
+- state — last, after `--`: `hover`, `active`, `focus`, `disabled`, `checked`, `current`, `error`
+
+State goes last even when it reads worse: `$video-playlist-card-bg--active`, NOT
+`$video-playlist-card-active-bg`. A state-looking word can be a sub-element: `$filter-popup-active-chip-bg` is
+`active-chip`.
+
+Text-only elements (`title`, `name`, `subtext`, `description`, `label`, `count`) may drop `-text`:
+`$video-card-title`.
+
+## Typography and breakpoints
+
+- Type: `@include font-sm` (14/20), `font-xs` (12/16), `font-base` (16/24) — never raw
+  `font-size`/`line-height`.
+- Breakpoints: `@include from-br(sm)`, `to-br(xs)`. Container: `from-cq($bp)`. JS mirror of `$brkpnts` in
+  `config/`, guarded by `check:breakpoints`.
+
+**All mixins** (auto-injected, never `@use`): `font-4xs|3xs|xs|2xs|sm|md|base|lg|xl|2xl|3xl|4xl`,
+`from-br|to-br`, `from-cq|to-cq`, `hover`, `surface`, `button-variant`, `page|page-title|page-footer-links`,
+`video-card|video-card-grid|video-card-poster`, `area-point`. Signatures — SCSS-mixins table in the app's
+`DOCS/CATALOG.md`.

package/README.md

@@ -143,6 +143,12 @@ assets/scss/themes/dark/_theme.scss
 подставляет приложение, и компилирует по разу на тему. То же, что делает Vite, — значит ловит и неизвестные
 миксины, и неверные аргументы `@include`, и показывает, в какой теме падает.
 
+**Промежуточного семантического слоя нет** — темы ссылаются на палитру напрямую, без тира вида
+`$text-muted` / `$role-border-subtle`. Сайты форкаются с принципиально разными схемами, и каждому
+селектору может понадобиться произвольный цвет, а не одна из горстки ролей. Такой слой либо оброс бы
+ролью на селектор (и перестал быть семантическим), либо компоненты начали бы тянуться в обход него.
+Имя токена по компоненту, который он обслуживает, держит соответствие честным.
+
 Контекстные различия (контрол внутри попапа, вариант кнопки, зависящий от темы) решают миксины
 `surface()` и `button-variant()` из `mixins/`: место объявляет себя, а значения даёт тема через карты
 `$surfaces` / `$button-variant-overrides`. Компоненты про темы не знают. `appConfig.theme` — только

package/assets/scss/base/_global.scss

@@ -82,15 +82,18 @@ summary::-webkit-details-marker {
   clip-path: inset(100%);
 }
 
+// Убрать элемент из потока целиком, в отличие от ._visually-hidden.
 ._hidden {
   display: none !important;
 }
 
 @for $i from 1 through 12 {
+  // Отбивка снизу: чётные значения 2…24px (._mb-8 = margin-bottom: 8px).
   ._mb-#{$i * 2} {
     margin-bottom: #{$i * 2}px;
   }
 
+  // Отбивка сверху: чётные значения 2…24px (._mt-8 = margin-top: 8px).
   ._mt-#{$i * 2} {
     margin-top: #{$i * 2}px;
   }

package/assets/scss/base/_loading.scss

@@ -1,5 +1,6 @@
 @use 'vars' as *;
 
+// Состояние загрузки блока: заблюренная подложка со спиннером поверх содержимого (::before/::after).
 ._loading {
   position: relative;
 

package/assets/scss/base/_utils.scss

@@ -1,21 +1,31 @@
 @use '../mixins/breakpoints' as *;
 
+// Виден только ниже xs (475px), на xs и шире скрыт.
 @include from-br(xs) { ._to-xs { display: none !important; } }
 
+// Виден только ниже sm (960px), на sm и шире скрыт.
 @include from-br(sm) { ._to-sm { display: none !important; } }
 
+// Виден только ниже md (1350px), на md и шире скрыт.
 @include from-br(md) { ._to-md { display: none !important; } }
 
+// Виден только ниже lg (1792px), на lg и шире скрыт.
 @include from-br(lg) { ._to-lg { display: none !important; } }
 
+// Виден с xs (475px) и шире, ниже скрыт.
 @include to-br(xs) { ._from-xs { display: none !important; } }
 
+// Виден с sm (960px) и шире, ниже скрыт.
 @include to-br(sm) { ._from-sm { display: none !important; } }
 
+// Виден с md (1350px) и шире, ниже скрыт.
 @include to-br(md) { ._from-md { display: none !important; } }
 
+// Виден с lg (1792px) и шире, ниже скрыт.
 @include to-br(lg) { ._from-lg { display: none !important; } }
 
+// Обрезка текста в N строк: число строк задаётся --line-clamp (по умолчанию 1),
+// выравнивание — --align, перенос — --word-break.
 ._truncate {
   display: -webkit-box !important;
   -webkit-line-clamp: var(--line-clamp, 1);

package/assets/scss/layout/_page.scss

@@ -1,15 +1,18 @@
 @use 'vars' as *;
 @use '../mixins' as *;
 
+// Корень страницы: колонка с вертикальными отступами. Вешается на корневой элемент в pages/**.
 ._page {
   @include page;
 }
 
+// Хлебные крошки. Свой верхний отступ нужен, когда крошки лежат вне ._page.
 ._breadcrumbs {
   margin-bottom: 24px;
   padding-top: 24px;
 }
 
+// Крошки на страницах с инфо-блоком — отбивка снизу меньше.
 ._breadcrumbs-info {
   margin-bottom: 16px;
   padding-top: 24px;
@@ -20,20 +23,24 @@
   padding-top: 0;
 }
 
+// Блок SEO-ссылок внизу страницы: прижат к низу и отбит линией.
 ._footer-links {
   @include page-footer-links;
 }
 
+// Заголовок страницы: font-lg, uppercase, 700.
 ._title {
   @include page-title;
 
   margin-bottom: 24px;
 }
 
+// Строка фильтров/навигации под заголовком — только отбивка снизу.
 ._nav-filter {
   margin-bottom: 32px;
 }
 
+// Центрирующий контейнер: боковые паддинги из --container-padding-inline, с md — max-width.
 ._container {
   width: 100%;
   margin: 0 auto;
@@ -44,6 +51,7 @@
   }
 }
 
+// Пагинация внизу листинга — только отбивка сверху.
 ._pagination {
   margin-top: 32px;
 }

package/assets/scss/mixins/_breakpoints.scss

@@ -60,9 +60,9 @@ $brkpnts: (
 }
 
 /**
-  Container query брейкпоинты
-  @include from-cq($width) { ... }
-  @include to-cq($width) { ... }
+  Container query брейкпоинты — меряют контейнер, а не окно. Требуют `container-type`
+  на предке; значение только в единицах, ключей из $brkpnts тут нет.
+  @include from-cq(400px) { ... }
  */
 @mixin from-cq($bp) {
   @container (min-width: #{$bp}) {
@@ -70,6 +70,9 @@ $brkpnts: (
   }
 }
 
+/**
+  @include to-cq(400px) { ... }
+ */
 @mixin to-cq($bp) {
   @container (max-width: #{$bp - 1px}) {
     @content;

package/assets/scss/mixins/_font-sizes.scss

@@ -1,58 +1,70 @@
+// 10px / 10px
 @mixin font-4xs {
   font-size: 10px;
   line-height: 1;
 }
 
+// 11px / 11px
 @mixin font-3xs {
   font-size: 11px;
   line-height: 1;
 }
 
+// 12px / 16px
 @mixin font-xs {
   font-size: 12px;
   line-height: 1.333;
 }
 
+// 13px / 19.5px
 @mixin font-2xs {
   font-size: 13px;
   line-height: 1.5;
 }
 
+// 14px / 20px
 @mixin font-sm {
   font-size: 14px;
   line-height: 1.429;
 }
 
+// 15px / 22.5px
 @mixin font-md {
   font-size: 15px;
   line-height: 1.5;
 }
 
+// 16px / 24px
 @mixin font-base {
   font-size: 16px;
   line-height: 1.5;
 }
 
+// 18px / 28px
 @mixin font-lg {
   font-size: 18px;
   line-height: 1.556;
 }
 
+// 20px / 28px
 @mixin font-xl {
   font-size: 20px;
   line-height: 1.4;
 }
 
+// 24px / 32px
 @mixin font-2xl {
   font-size: 24px;
   line-height: 1.333;
 }
 
+// 30px / 36px
 @mixin font-3xl {
   font-size: 30px;
   line-height: 1.2;
 }
 
+// 36px / 40px
 @mixin font-4xl {
   font-size: 36px;
   line-height: 1.111;

package/assets/scss/mixins/_page.scss

@@ -2,6 +2,8 @@
 @use 'font-sizes' as *;
 @use 'vars' as *;
 
+// Каркас страницы: колонка с вертикальными отступами. В разметке используется через
+// глобальный класс `._page` (layout/_page.scss), напрямую в компонентах не нужен.
 @mixin page {
   display: flex;
   flex-direction: column;
@@ -9,6 +11,7 @@
   padding-bottom: 24px;
 }
 
+// Заголовок страницы: font-lg, uppercase, 700. В разметке — глобальный класс `._title`.
 @mixin page-title {
   @include font-lg;
 
@@ -17,6 +20,8 @@
   font-weight: 700;
 }
 
+// Блок SEO-ссылок внизу страницы: прижат к низу (margin-top: auto) и отбит линией.
+// В разметке — глобальный класс `._footer-links`.
 @mixin page-footer-links {
   margin-top: auto;
   padding-top: 8px;

package/assets/scss/mixins/_video-card.scss

@@ -2,6 +2,7 @@
 @use 'font-sizes' as *;
 @use 'vars' as *;
 
+// Каркас карточки видео: колонка «постер + мета» с зазором 16px, контент прижат к верху.
 @mixin video-card {
   display: grid;
   row-gap: 16px;
@@ -32,6 +33,7 @@
   }
 }
 
+// Постер карточки: 16/9, скруглённый, с обрезкой — база для абсолютных бейджей поверх.
 @mixin video-card-poster {
   position: relative;
   aspect-ratio: 16/9;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.921",
+  "version": "0.0.923",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {
@@ -74,7 +74,8 @@
     "assets/scss/base/",
     "assets/scss/layout/",
     "assets/scss/main.scss",
-    "nuxt.config.ts"
+    "nuxt.config.ts",
+    "DOCS/"
   ],
   "devDependencies": {
     "@intlify/eslint-plugin-vue-i18n": "^4.5.1",

package/server/middleware/x-domain.ts

@@ -0,0 +1,19 @@
+/**
+ * Гарантирует `X-Domain` у запросов к BFF.
+ *
+ * Бекенд разруливает сайты по этому заголовку — у stripcash-ручек к домену
+ * привязан ещё и ключ провайдера, поэтому без него они отвечают 500
+ * («mux: route doesn't have a host»). Заголовок ставит `ApiHelper`, но не каждый
+ * вызов идёт через него: блок вебкамов, например, дёргает свою ручку обычным
+ * `useFetch`, и тогда до бекенда доезжали только проксированные заголовки запроса
+ * страницы — на локальной машине это прощалось, а за прокси на стенде ломалось.
+ *
+ * Значение берём из runtimeConfig сайта и НЕ перебиваем то, что уже пришло.
+ */
+export default defineEventHandler((event) => {
+  if (!event.path.startsWith('/api/') && !event.path.startsWith('/bff/')) return;
+  if (event.node.req.headers['x-domain']) return;
+
+  const xDomain = useRuntimeConfig(event).public.xDomain;
+  if (xDomain) event.node.req.headers['x-domain'] = String(xDomain);
+});