itube-specs 0.0.858 → 0.0.861

package/README.md

@@ -1,11 +1,14 @@
 # itube-specs
 
 Общий **Nuxt Layer** для сайтов itube. Держит единую базу: компоненты, composables, сервисы, утилиты,
-runtime-хелперы, типы, lib-данные, а также middleware, SSR-плагины и BFF-хендлеры (`server/api`).
+runtime-хелперы, типы, lib-данные, middleware, SSR-плагины, BFF-хендлеры (`server/api`) и **весь SCSS —
+палитру, темы, миксины и глобальные стили**.
 Приложения расширяют слой (`extends: ['itube-specs']`) и форкаются под разные сайты одной ниши —
 поэтому слой должен оставаться **самодостаточным и site-agnostic**.
 
 > Bitbucket: https://bitbucket.org/luckytube/specs/src/master/
+>
+> Заводишь новый сайт поверх слоя — [**NEW_SITE_CHECKLIST.md**](./NEW_SITE_CHECKLIST.md).
 
 ---
 
@@ -63,6 +66,9 @@ npm run patch        # npm version patch — бамп версии перед п
 ```
 
 Pre-commit (husky + lint-staged): на закоммиченных файлах прогоняются `eslint --fix` и `stylelint --fix`.
+⚠️ **Шаблоны `.vue` не типизируются вообще.** Обычный `tsc` их не читает, а `vue-tsc` не подключён (накопился
+бэклог ошибок в шаблонах, подключение — отдельная задача). Значит чистый `tsc` ничего не говорит про выражения
+в шаблоне: арифметика над строковым union, неверный тип пропа, переименованное поле пройдут молча.
 
 ---
 
@@ -81,10 +87,52 @@ lib/           # статические scheme/config-данные (barrel index
 middleware/    # глобальные: auth.global, normalize.global, age.global
 plugins/       # SSR/клиент: country/countries/mobile (SSR), services.client, sentry.client, adv
 server/        # BFF: api/** (тонкие прокси к внешнему API), utils/metrics, plugins/*, tasks
+assets/
+  icons/       # спрайты/svg для <UiIcon>
+  scss/
+    vars/      # _palette (сырые $color-*), _vars (скаляры), _tokens (CSS custom props), _z-index, _index
+    themes/    # по папке на тему: light/_theme.scss, dark/_theme.scss — токены по компонентам
+    mixins/    # font-sizes, breakpoints, accessibility, page, video-card, surface, button
+    base/      # document, global, hacks, animations, loading
+    layout/    # layout, page
+    main.scss  # точка входа: vars/tokens + base + layout
 ```
 
-> `middleware`/`plugins`/`server` обязаны быть в `files` (whitelist) — иначе не попадут в паблиш
-> (см. раздел `files`/`exports`).
+> `middleware`/`plugins`/`server` и каждая подпапка `assets/scss/*` обязаны быть в `files` (whitelist) —
+> иначе не попадут в паблиш (см. раздел `files`/`exports`).
+
+---
+
+## Темы
+
+Темы живут здесь, по папке на тему, и раздаются всем сайтам:
+
+```
+assets/scss/themes/light/_theme.scss
+assets/scss/themes/dark/_theme.scss
+```
+
+Приложение только **выбирает** одну — `theme:` в его `config/site.config.ts`. Оттуда значение читают
+и `app.config.ts` (в рантайм), и `nuxt.config.ts`, который добавляет `themes/<theme>/` в Sass
+`loadPaths`. `@forward 'theme'` в `vars/_index.scss` резолвится туда, потому что рядом с ним
+`_theme.scss` нет.
+
+**Папка-на-тему обязательна:** Sass требует литеральный путь в `@use`/`@forward`, значит имя файла
+всегда `_theme.scss`, а варьироваться может только папка. Плоские `themes/light.scss` потребовали бы
+`@forward 'themes/light'` — литерал, который нельзя подставить на билде.
+
+Приоритет `loadPaths` — приложение первым, поэтому сайт может перекрыть любой партиал по имени:
+свой `assets/scss/vars/_theme.scss` в проекте выиграет у темы слоя (относительный резолв Sass старше
+`loadPaths`). Это точка пер-сайтовой темизации.
+
+**Все токены обязаны быть во всех темах.** Отсутствующий токен — жёсткая ошибка Sass в момент, когда
+тема выбрана, то есть падает вся сборка сайта, а не «поехал цвет». Сверять набор имён после любой
+правки темы.
+
+Контекстные различия (контрол внутри попапа, вариант кнопки, зависящий от темы) решают миксины
+`surface()` и `button-variant()` из `mixins/`: место объявляет себя, а значения даёт тема через карты
+`$surfaces` / `$button-variant-overrides`. Компоненты про темы не знают. `appConfig.theme` — только
+для структурных различий (`v-if`, другой элемент), никогда для цвета.
 
 ---
 
@@ -117,8 +165,9 @@ ad-конфиг), теперь читается из `runtimeConfig.public` (з
   `lib/` (scheme, css-breakpoints), middleware (`auth`/`normalize`/`age`), SSR-плагины
   (`country`/`mobile`/`services`/`sentry`/`adv`), BFF-хендлеры `server/api/**` — всё site-agnostic.
 - **Приложение:** только per-site — **значения** config (флаги/реклама/локали) через `runtimeConfig.public`
-  (слой держит пустые контейнеры-заглушки), `assets/scss` (токены), страницы, i18n-локали и остаток
-  `server/`, завязанный на локали (`locale-guard`, `site/languages`, `is-locale-blocked`).
+  (слой держит пустые контейнеры-заглушки), i18n-локали, `public/` и **выбор темы** (`theme:` в
+  `config/site.config.ts`). Своего SCSS у приложения нет: `assets/scss/` — пустой слот-оверрайд.
+  `server/` целиком в слое, включая locale-кластер.
 
 ---
 
@@ -128,10 +177,14 @@ ad-конфиг), теперь читается из `runtimeConfig.public` (з
 
 - **Компоненты** — `pathPrefix: true`: имя = папка + файл (`ui/icon.vue` → `<UiIcon>`), BEM-класс = kebab
   тега. Корень папки — `index.vue` (или `main.vue`, если иначе имя было бы односложным).
-- **`as const`** вместо `enum` — доменные наборы в `runtime/constants/`.
+- **`as const`** вместо `enum` — доменные наборы в `runtime/constants/`, тип через
+  `typeof X[keyof typeof X]`. В enum не положить строку из API, он остаётся в бандле, и в
+  опубликованном пакете `import type` на нём ломается в рантайме. Фреймворковые union'ы не
+  оборачивать. Подробнее — в [CLAUDE.md](./CLAUDE.md).
 - **Стили** — co-location в `<style lang="scss">` без `scoped`, flat-BEM, только дизайн-токены.
-  ⚠️ Токены (`vars`/`mixins`) инжектит **приложение** — в слое нет `assets/scss` и `sass`, стили компонентов
-  компилируются только внутри приложения.
+  `vars` и `mixins` **авто-инжектятся** через `additionalData` приложения, поэтому в блоке компонента
+  `@use` писать не надо. Сам `sass` в слое не установлен — SCSS компилируется внутри приложения, но
+  все исходники (палитра, темы, миксины) лежат здесь.
 - **Разметка** — семантические теги, `<div>` только когда ничего не подходит.
 - **TS/JS** — всегда точка с запятой, без лишних комментариев.
 

package/components/auth/popup.vue

@@ -10,7 +10,7 @@
       transparent-backdrop
       :back="isBackShow"
       class="auth-popup"
-      @back="currentStep -= 1"
+      @back="goBack"
     >
       <template #title>{{  $t('auth.create_new') }}</template>
       <AuthRegister
@@ -27,12 +27,12 @@
       transparent-backdrop
       :back="isBackShow"
       class="auth-popup"
-      @back="currentStep -= 1"
+      @back="goBack"
     >
       <template #title>{{  $t('auth.welcome_back') }}</template>
       <AuthLogin
         @forgot="onRecoveryClick"
-        @create="currentStep -= 1"
+        @create="currentStep = AuthSteps.Registration"
       />
     </UiPopup>
   </transition>
@@ -44,7 +44,7 @@
       transparent-backdrop
       :back="isBackShow"
       class="auth-popup"
-      @back="currentStep -= 1"
+      @back="goBack"
     >
       <template #title>{{  $t('auth.recovery_title')}}</template>
       <AuthRecovery @login="onLoginClick"/>
@@ -59,6 +59,20 @@ const { isAuthPopupOpen, currentStep, additionalText } = useAuthPopup();
 
 const backShow = ref(false);
 
+// Куда ведёт «назад» с каждого шага. Registration — начальный, назад с него нет.
+const previousStep: Partial<Record<AuthSteps, AuthSteps>> = {
+  [AuthSteps.Login]: AuthSteps.Registration,
+  [AuthSteps.Recovery]: AuthSteps.Login,
+};
+
+function goBack(): void {
+  const previous = previousStep[currentStep.value];
+
+  if (previous) {
+    currentStep.value = previous;
+  }
+}
+
 function onLoginClick(): void {
   currentStep.value = AuthSteps.Login;
   backShow.value = true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.858",
+  "version": "0.0.861",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {

package/runtime/constants/auth-step.ts

@@ -1,7 +1,7 @@
 export const AuthSteps = {
-  Registration: 1,
-  Login: 2,
-  Recovery: 3,
+  Registration: 'registration',
+  Login: 'login',
+  Recovery: 'recovery',
 } as const;
 
 export type AuthSteps = typeof AuthSteps[keyof typeof AuthSteps];

package/runtime/constants/playlist-step.ts

@@ -1,7 +1,7 @@
 export const PlaylistStep = {
-  Edit: 1,
-  Delete: 2,
-  DeleteVideo: 3,
+  Edit: 'edit',
+  Delete: 'delete',
+  DeleteVideo: 'delete-video',
 } as const;
 
 export type PlaylistStep = typeof PlaylistStep[keyof typeof PlaylistStep];