@nitra/cursor 12.8.6 → 12.8.8

package/rules/vue/js/nheader-layout.mdc

@@ -0,0 +1,171 @@
+## NHeader — телепорт-слоти на сторінках
+
+У проектах з `NHeader` використовуй `<teleport>` для вбудовування контенту сторінки в шапку:
+
+| Слот | Призначення |
+| --- | --- |
+| `#header-subtitle` | Заголовок сторінки (якщо потрібно перевизначити subtitle) |
+| `#header-center` | Важливі повідомлення та елементи управління |
+| `#header-filters` | Фільтри, кнопки та інші елементи управління сторінки |
+
+Оскільки `NHeader` за замовчуванням темний, додавай до полів і селектів у телепортах: `dark`, `standout="bg-white text-primary"`, `:options-dark="false"`.
+
+Завжди обгортай `<teleport>` в `v-if="mounted"` (де `mounted` — `$ref(false)`, що встановлюється в `onMounted`), щоб уникнути помилки відсутності target-елемента при SSR / першому рендері.
+
+```vue
+<template>
+  <q-page>
+    <!-- ФІЛЬТРИ В ШАПЦІ -->
+    <teleport v-if="mounted" to="#header-filters">
+      <div class="col row items-center n-gap-sm q-pa-sm">
+        <q-input
+          v-model="pageStore.filterName"
+          :label="t`Поиск по названию`"
+          debounce="200"
+          standout="bg-white text-primary"
+          clearable
+          dense
+          dark
+          class="col"
+          style="min-width: 120px">
+          <template #prepend>
+            <q-icon name="search" />
+          </template>
+        </q-input>
+
+        <n-select-multi
+          v-model="pageStore.filterRequestTypes"
+          :options="requestTypeOptions"
+          :label="t`Тип запроса`"
+          dark
+          standout="bg-white text-primary"
+          :options-dark="false"
+          style="min-width: 180px; max-width: 400px"
+          dense
+          emit-value
+          map-options
+          clearable
+          searchable
+          :stack-label="false" />
+
+        <q-btn
+          @click="addItem"
+          icon="add"
+          :label="t`Добавить`"
+          color="primary"
+          no-caps
+          padding="8px 12px"
+          unelevated />
+      </div>
+    </teleport>
+
+    <!-- ОСНОВНИЙ КОНТЕНТ -->
+    ...
+  </q-page>
+</template>
+<script setup>
+const mounted = $ref(false)
+onMounted(() => { mounted = true })
+</script>
+```
+
+## Layout з NHeader
+
+Для нових layout-ів використовуй `NHeader` з вбудованими `NLang` і `NMenu`.
+
+```vue
+<template>
+  <q-layout view="hHh Lpr lFf">
+    <n-header
+      v-model="leftSideOpened"
+      :logo="baseUrl + 'logo.png'"
+      :logo-url="homeUrl"
+      title="My App"
+      :subtitle="subtitle"
+      :username="userName"
+      toolbar-dark>
+      <template #top-toolbar>
+        <div class="platform-ios-only q-py-lg" />
+      </template>
+      <div>default slot content</div>
+    </n-header>
+
+    <!-- ЛЕВАЯ КОЛОНКА -->
+    <q-drawer v-model="leftSideOpened" :breakpoint="700" :width="300" overlay class="col column shadow-5 bg-grey-1">
+      <div class="platform-ios-only q-py-lg" />
+      <div v-if="!$q.screen.gt.xs" class="q-pa-sm row items-center">
+        <q-icon name="account_circle" color="primary" size="32px" class="q-mr-sm" />
+        <div class="text-subtitle1">{{ user.name }}</div>
+      </div>
+      <n-menu v-model="activeMenu" :menu="menu" />
+      <q-space />
+      <n-menu :menu="homeMenu" />
+      <div class="platform-ios-only q-py-md" />
+    </q-drawer>
+
+    <q-page-container>
+      <router-view />
+    </q-page-container>
+  </q-layout>
+</template>
+<script setup>
+import { lang, tf as tfm } from '@nitra/tfm'
+const t = tfm.bind({ tr: getTr() })
+
+const baseUrl = import.meta.env.BASE_URL
+const homeUrl = String.raw`https:\\` + import.meta.env.VITE_DOMAIN
+
+// Ліва колонка
+const leftSideOpened = $ref(false)
+const activeMenu = $ref(null)
+
+// Заголовок у шапці з поточного пункту меню
+const subtitle = computed(() => (activeMenu ? getTr()[activeMenu.labelKey]?.[lang.value] || activeMenu?.labelKey : ''))
+
+// Меню
+const menu = computed(() =>
+  [
+    {
+      icon: 'sym_o_store',
+      label: t`Клиенты`,
+      labelKey: t`Клиенты`,
+      routeName: 'customer'
+    },
+    {
+      icon: 'sym_o_route',
+      label: t`Маршруты и визиты`,
+      items: [
+        {
+          icon: 'sym_o_route',
+          label: t`Маршруты`,
+          labelKey: t`Маршруты`,
+          routeName: 'route'
+        },
+        {
+          icon: 'sym_o_event_upcoming',
+          label: t`Переносы маршрутов`,
+          labelKey: t`Переносы маршрутов`,
+          routeName: 'route_postpone'
+        }
+      ]
+    }
+  ].filter(item => {
+    if (item.items?.length) {
+      item.items = item.items.filter(i => can[i.permissionRoute || i.routeName])
+      return item.items.length > 0
+    }
+    return can[item.routeName]
+  })
+)
+
+/**
+ * LOCALIZATION
+ * @returns {object} translations
+ */
+function getTr() {
+  return {
+    Клиенты: { en: 'Customers', ro: 'Clienți', tr: 'Müşteriler' }
+  }
+}
+</script>
+```

package/rules/vue/js/node-imports.mdc

@@ -0,0 +1,25 @@
+## Заборонено імпортувати Node-нативні модулі у `.vue` SFC
+
+Vue SFC виконується у браузері, тож API Node.js там недоступне. У `<script>` (включно з `<script setup>`)
+заборонено будь-які імпорти вбудованих модулів Node — як з префіксом `node:`, так і bare-ім'ям модуля
+(включно з підшляхами):
+
+```vue title="погано — ламає білд"
+<script setup lang="ts">
+import { setTimeout as sleep } from 'node:timers/promises'
+import fs from 'fs'
+import { readFile } from 'fs/promises'
+import path from 'node:path'
+</script>
+```
+
+Якщо потрібна логіка з Node API — винеси її у server-side утіліту (наприклад, у backend-пакет монорепо)
+та звертайся до неї через HTTP/GraphQL. Браузерні замінники (`window.crypto`, `URL`, `setTimeout` глобальний,
+`AbortController` тощо) використовуй напряму, без import.
+
+Правило стосується саме `.vue` файлів. Допоміжні `.ts`/`.js` модулі, які споживаються лише server-side
+(наприклад, окремий пакет утіліт), можуть імпортувати Node-built-ins без обмежень.
+
+Перевірка реалізована у `npm/rules/vue/lib/vue-forbidden-imports.mjs` через функцію
+`findForbiddenNodeImportsInVueFile` — аналізує лише `<script>` блоки SFC через **oxc-parser**,
+ігноруючи `<template>`.

package/rules/vue/js/quasar-ui.mdc

@@ -0,0 +1,32 @@
+## Quasar як UI-основа
+
+У Vue-проектах використовуй **Quasar** як базовий UI-фреймворк:
+
+- **Компоненти:** `q-btn`, `q-input`, `q-select`, `q-table`, `q-dialog`, `q-card`, `q-layout`, `q-page`, `q-drawer` тощо — основа UI.
+- **Плагіни:** `Notify`, `Dialog`, `Loading` та інші Quasar-плагіни.
+- **Кольори:** використовуй Quasar CSS-змінні (`primary`, `secondary`, `accent`, `positive`, `negative`, `warning`, `info`, `dark`) і утиліти (`text-primary`, `bg-accent` тощо).
+- **Утиліти:** flex-layout (`row`, `col`, `items-center`), spacing (`q-pa-md`, `q-mt-sm`), shadow (`shadow-2`) — зі стандартної бібліотеки Quasar.
+- **Кастомні компоненти** `@nitra/components` — **надбудова** над Quasar, а не заміна; їх слід надавати перевагу лише там, де вони є.
+
+## @nitra/components — надавай перевагу перед Quasar-компонентами
+
+При створенні нової функціональності використовуй компоненти `@nitra/components`, якщо логіка компонента дозволяє отримати потрібний функціонал. Заміни:
+
+| Завдання | `@nitra/components` | Замість Quasar |
+| --- | --- | --- |
+| Діалоги | `NDialog` | `q-dialog` |
+| Multi-вибір | `NSelectMulti` | `q-select` (multiple) |
+| Текстовий редактор | `NEditor` | `q-editor` |
+| Вибір дати | `NDate` | — |
+| Вибір місяця/року | `NDateMonthYear` | — |
+| Діапазон дат | `NDateRange` | — |
+| Дата і час | `NDateTime` | — |
+| Drag&drop список | `NDraggableList` | — |
+| Редаговане значення | `NEditableString` | — |
+| Повідомлення | `NCallout` | — |
+| Хедер проекту | `NHeader` | — |
+| Перемикання мов | `NLang` | — (якщо `NHeader` не використовується) |
+| Меню проекту | `NMenu` | — |
+| Зображення (масив / одиночне) | `NImages` | — |
+| Завантаження файлів | `NUploader` | — |
+| Вибір колонок `q-table` | `NTableColumns` | — |

package/rules/vue/js/structure.mdc

@@ -0,0 +1,101 @@
+## Структура папок
+
+```javascript
+const folderStructure = `
+  src/
+  components/
+  composables/
+  views/
+  router/
+  store/
+  assets/
+  public/
+  App.vue
+  main.mjs
+`
+```
+
+### Найменування файлів
+
+- **SFC:** імена файлів компонентів у **PascalCase** починаючи з букви N(`NMyWidget.vue`).
+- **Інші JS-модулі:** узгоджено **kebab-case** (`date-utils.mjs`).
+
+### Модулі та архітектура
+
+- **ES modules** (`import`/`export`), один модуль — одна відповідальність, уникай **circular dependencies**.
+- **Composition** замість успадкування; логіку для повторного використання винось у **composables** (замість зайвих HOC, де це доречно).
+
+### Code splitting
+
+- **Route-based:** lazy-імпорти в маршрутах (`() => import('...')`) і async components.
+
+## Додаткові вказівки
+
+```javascript
+const additionalInstructions = `
+1. Використовуй JavaScript
+2. Коректно оголошуй props, emits, defineModel
+3. За потреби використовуй компонент Teleport у Vue 3
+4. Застосовуй Suspense для async components
+5. Реалізуй належний error handling
+6. Дотримуйся Vue 3 style guide і naming conventions
+7. Використовуй Vite для швидкої розробки та збірки
+`
+```
+
+### Детальні вказівки
+
+1. **Vue router**: Завжди використовуй Vue router для маршрутизації в проекті версії 5 та його file-based routing.
+2. **Компонент Teleport**: Використовуй Teleport у Vue 3, коли потрібно рендерити поза поточною ієрархією DOM.
+3. **Suspense для async components**: Застосовуй Suspense для асинхронних компонентів і кращого UX.
+4. **Error handling**: Реалізуй глобальний error handling механізмами Vue 3, щоб коректно перехоплювати та обробляти помилки.
+5. **Style guide і naming**: Дотримуйся офіційного Vue 3 style guide і naming conventions для узгодженості кодової бази.
+6. **Vue macros**: Використовуй Vue macros для більш ефективного розробки компонентів.
+7. **Vue Reactivity Transform**: Використовуй Vue Reactivity Transform для змінних в компонентах.
+
+## Коментарі в `<template>`
+
+Додавай коментарі в `<template>` відповідно до логічного призначення блоку. Коментарі допомагають швидко орієнтуватися в розмітці.
+
+```vue
+<template>
+  <q-page>
+    <!-- ФІЛЬТРИ В ШАПЦІ -->
+    <teleport v-if="mounted" to="#header-filters">...</teleport>
+
+    <!-- ТАБЛИЦЯ -->
+    <q-table ... />
+
+    <!-- ДІАЛОГ РЕДАГУВАННЯ -->
+    <n-dialog v-model="editDialog">...</n-dialog>
+  </q-page>
+</template>
+```
+
+## Pinia store для стану сторінки
+
+Зберігай у Pinia store:
+
+- вибрані значення фільтрів
+- вибрані для відображення колонки (`NTableColumns`)
+- кількість записів на сторінці (pagination)
+
+Називай store за назвою сторінки або компонента — `customerPageStore`, `routePageStore` тощо. На сторінці звертайся до нього через змінну `pageStore`.
+
+```javascript
+// store/customerPage.mjs
+export const useCustomerPageStore = defineStore('customerPage', {
+  state: () => ({
+    filterName: '',
+    filterStatus: [],
+    columns: [],
+    rowsPerPage: 20
+  })
+})
+```
+
+```vue
+<script setup>
+const pageStore = useCustomerPageStore()
+</script>
+```

package/rules/vue/js/testing.mdc

@@ -0,0 +1,32 @@
+## Тестування Vue-компонентів
+
+### Unit + Component / DOM
+
+**Vitest** (`vitest`) + **Vue Test Utils** з **happy-dom** як DOM-середовищем. Це канон, узгоджений з `test.mdc` (Stryker з vitest-runner + `perTest`-аналіз покриття). `vitest.config.mjs` повторно використовує `vite.config.js` через `mergeConfig` і перемикає `environment` на `'happy-dom'`:
+
+```js title="vitest.config.mjs"
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config.js'
+
+export default mergeConfig(viteConfig, defineConfig({
+  test: {
+    include: ['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}'],
+    environment: 'happy-dom',
+    coverage: { provider: 'v8', reporter: ['lcov', 'text-summary'] }
+  }
+}))
+```
+
+`jsdom` не використовуй — happy-dom швидший і достатній для типових Vue-компонентних тестів.
+
+У `package.json#scripts` тримай `"test": "vitest run"`; vitest devDeps (`vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`) — у кореневому `devDependencies` (npm-module rule забороняє devDeps у published workspace-у).
+
+### E2E
+
+**Playwright** — змістовні сценарії користувацьких потоків.
+
+Проекту повинен бути покритий тестами E2E за допомогою Playwright.
+
+### CI/CD
+
+У pipeline: **install**, **lint**, **test**, **vite build**; артефакти з продакшен-режиму.

package/rules/vue/js/tfm-translations.mdc

@@ -0,0 +1,26 @@
+## @nitra/tfm — переклади
+
+Використовуй `@nitra/tfm` для всіх текстів. Переклади для всіх мов проекту оголошуй наприкінці `<script setup>` у функції `getTr()`. Змінна `lang` із `@nitra/tfm` — для визначення або зміни поточної мови застосунку.
+
+```vue
+<template>
+  {{ lang }}
+  {{ t`Анкеты` }}
+  {{ subtitle }}
+</template>
+<script setup>
+import { lang, tf as tfm } from '@nitra/tfm'
+const t = tfm.bind({ tr: getTr() })
+const subtitle = $computed(() => t`Анкеты`)
+
+/**
+ * LOCALIZATION
+ * @returns {object} translations
+ */
+function getTr() {
+  return {
+    Анкеты: { en: 'Surveys', ro: 'Sondaje', tr: 'Anketler' }
+  }
+}
+</script>
+```

package/rules/vue/js/vite-config.mdc

@@ -0,0 +1,126 @@
+## Vite-конфігурація: VueMacros, AutoImport, Layouts
+
+Потрібно використовувати **Vite версії 8 та вище** для frontend проекту на Vue.
+
+Потрібно використовувати **`unplugin-auto-import`** для автоматичного імпортування компонентів, composables, utils та інших функцій і прибирати з файлів усередині Vite проектів відповідні ручні імпорти, зокрема рядки виду `import { … } from 'vue'` — API Vue (`ref`, `computed`, `watch` тощо) мають підставлятися через auto-import, а не дублюватися явним імпортом з модуля `vue`.
+
+**Виняток — бібліотеки компонентів (`vue` у `peerDependencies`).** Увесь стек auto-import застосовується лише коли `vue` підключено як звичайну `dependencies`. Якщо ж пакет оголошує `vue` у `peerDependencies` — це проєкт-бібліотека компонентів: його джерела споживаються Vite-додатками і **не** проходять через `unplugin-auto-import` споживача. Тому до таких пакетів **не** застосовуються: заборона явних `import { ref, computed, … } from 'vue'` (вони обовʼязкові), вимога `'vue'` у `AutoImport.imports`, а також вимоги наявності `VueMacros` / `AutoImport` у `vite.config`. Решта перевірок (заборона `esbuild`, `process.env.npm_lifecycle_event` тощо) лишаються. Тригер винятку — `isVueComponentLibraryPkg` у `npm/rules/vue/js/packages.mjs`.
+
+Потрібно використовувати **`vite-plugin-vue-layouts-next`** для автоматичного імпортування layout компонентів.
+
+### Еталонний `vite.config.js`
+
+```javascript title="vite.config.js"
+import Vue from '@vitejs/plugin-vue'
+import VueMacros from 'vue-macros/vite'
+import { defineConfig } from 'vite'
+import AutoImport from 'unplugin-auto-import/vite'
+import Layouts from 'vite-plugin-vue-layouts-next'
+
+export default defineConfig({
+  plugins: [
+    AutoImport({
+      imports: [
+        // presets
+        'vue',
+        'vue-router',
+        'quasar',
+        'pinia',
+        // custom
+        {
+          '@nitra/vite-boot/apollo': [
+            // named imports
+            'gql',
+            'useQuery',
+            'useMutation',
+            'useSubscription'
+          ],
+          '@nitra/consola': [
+            // named imports
+            'createLogger' // import { createLogger } from '@nitra/consola'
+          ]
+        }
+      ]
+    }),
+    VueMacros({
+      plugins: {
+        vue: Vue()
+      }
+    }),
+    Layouts()
+  ]
+})
+```
+
+### Перевірка `npm_lifecycle_event` (Bun-сумісність)
+
+У більшості проектів у файлі `vite.config.js` є конструкція виду:
+
+```javascript
+switch (process.env.npm_lifecycle_event) {
+  case 'start-remote-tr': {
+```
+
+Вона перестала працювати з новим Bun. Тепер її треба обрамити у функцію і передавати `mode`:
+
+```javascript title="vite.config.js"
+function getProxy(mode) {
+  const proxy = {}
+
+  switch (mode) {
+    case 'remote-tr': {
+      proxy['^/auth/.*'] = 'https://tr.efes.cloud'
+      proxy['/file-link/'] = 'https://tr.efes.cloud'
+      break
+    }
+    default: {
+      proxy['^/auth/.*'] = 'https://dev.efes.cloud'
+      proxy['/file-link/'] = 'https://dev.efes.cloud'
+    }
+  }
+  return proxy
+}
+```
+
+```javascript title="vite.config.js"
+export default defineConfig(({ mode, command }) => {
+  // ...
+  server: {
+    proxy: getProxy(mode)
+  }
+})
+```
+
+### esbuild заборонено
+
+У проєкті не має бути залежності `esbuild` і згадок `esbuild` у конфігах/коді. Якщо десь є налаштування або інструкції під `esbuild` — заміни на **rolldown**.
+
+### Еталонний `package.json`
+
+мінімальний повний `package.json` для Vite + Vue + `vue-macros` (версії підлаштуй під проєкт):
+
+```json title="package.json"
+{
+  "name": "my-vue-app",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vue": "^3.6.12"
+  },
+  "devDependencies": {
+    "vite": "^8.0.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "vue-macros": "^3.1.2"
+  }
+}
+```
+
+### VS Code розширення
+
+У файлі `.vscode/extensions.json` потрібна рекомендація для Vue:
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["Vue.volar"]
+}
+```

package/rules/vue/js/vite-env.mdc

@@ -0,0 +1,55 @@
+## Vite client types (Volar, імпорти асетів)
+
+Без типів **Vite** редактор (Volar / TypeScript) не знає, що імпорт статичного файлу (`import url from './hero.avif'`, `*.png`, `*.svg` тощо) відповідає модулю з `string` URL. Тоді у `.vue` з'являється помилка на кшталт **Cannot find module '…' or its corresponding type declarations**.
+
+У **кожному** workspace-пакеті з **Vue + Vite** обов'язково:
+
+1. **`src/vite-env.d.ts`** — рівно з посиланням на клієнтські типи Vite (одного рядка достатньо):
+
+```ts title="src/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+Так підтягуються декларації з `vite/client.d.ts` (`declare module '*.avif'`, `*.png`, …).
+
+2. **Корінь пакета:** **`jsconfig.json`** із **`include`**, що охоплює `src` (наприклад `"include": ["src/**/*"]`), щоб мова служби бачила `vite-env.d.ts` і SFC.
+
+Мінімальний приклад для JS-пакета:
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowJs": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Не** звужуй без потреби **`compilerOptions.types`** до `["vite/client"]`: це може відрізати інші пакети з `@types` і зламати інші підказки. Достатньо `/// <reference types="vite/client" />` у `vite-env.d.ts` і коректного `include`.
+
+## Статичні файли — BASE_URL
+
+Для підключення статичних файлів не використовуй відносні шляхи. Завжди будуй URL через `import.meta.env.BASE_URL`:
+
+```vue
+<!-- Погано -->
+<img src="/logo.png" />
+<img src="./assets/logo.png" />
+
+<!-- Добре -->
+<img :src="baseUrl + 'logo.png'" />
+```
+
+```javascript
+const baseUrl = import.meta.env.BASE_URL
+```

package/rules/vue/js/vue-imports.mdc

@@ -0,0 +1,25 @@
+## Заборона явних value-імпортів з `vue`
+
+Потрібно використовувати `unplugin-auto-import` для автоматичного імпортування Vue API. Коли `'vue'` додано до `AutoImport.imports` у `vite.config`, явні value-імпорти вигляду `import { ref, computed } from 'vue'` у файлах додатка **заборонені** — API Vue підставляється автоматично.
+
+Дозволені лише:
+- side-effect: `import 'vue'`
+- type-only: `import type { … } from 'vue'` або `import { type Foo } from 'vue'`
+
+```vue
+<!-- ❌ заборонено (auto-import покриває) -->
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+</script>
+
+<!-- ✅ дозволено — не потрібен ручний імпорт -->
+<script setup>
+const count = $ref(0)
+const doubled = $computed(() => count * 2)
+onMounted(() => { /* ... */ })
+</script>
+```
+
+**Виняток:** бібліотеки компонентів (`vue` у `peerDependencies`) — їхні джерела не проходять через `unplugin-auto-import` споживача, тому явні `import { ref } from 'vue'` там обовʼязкові. Визначається через `isVueComponentLibraryPkg` у `npm/rules/vue/js/packages.mjs`.
+
+Перевірка виконується через **oxc-parser** (`module.staticImports`) у `npm/rules/vue/lib/vue-forbidden-imports.mjs`, функція `findForbiddenVueImportsInSourceFile`. Для `.vue` — лише вміст `<script>` тегів, `<template>` ігнорується.