@nitra/cursor 12.8.5 → 12.8.7

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>` ігнорується.