@nitra/cursor 1.28.5 → 1.28.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.28.5",
+  "version": "1.28.6",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/js-bun-db/js-bun-db.mdc

@@ -46,6 +46,60 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 
 Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
 
+#### Приклад: MERGE з UNNEST і динамічними колонками
+
+```javascript
+// ❌ format + pgWrite.unsafe — N×7 окремих значень, план змінюється при кожному batch.length
+const valuesSql = batch
+  .map(row => format('(%L::int, %L::date, %L::jsonb)', row.id, row.date, JSON.stringify(row.data)))
+  .join(',')
+const sql = format(`MERGE INTO t USING (VALUES %s) AS s(id, date, data) ON ...`, valuesSql)
+await pgWrite.unsafe(sql)
+
+// ✅ UNNEST — 3 параметри незалежно від розміру batch; план стабільний і може кешуватись
+const ids   = batch.map(r => r.id)
+const dates = batch.map(r => r.date)
+const data  = batch.map(r => JSON.stringify(r.data))
+
+await pgWrite`
+  WITH s(id, date, data) AS (
+    SELECT * FROM unnest(
+      ${ids}::int[],
+      ${dates}::date[],
+      ${data}::jsonb[]
+    )
+  )
+  MERGE INTO my_table AS t
+  USING s ON t.id = s.id
+  WHEN MATCHED THEN
+    UPDATE SET date = s.date, data = s.data
+  WHEN NOT MATCHED THEN
+    INSERT (id, date, data) VALUES (s.id, s.date, s.data)
+`
+```
+
+Якщо частина колонок у SET/INSERT залежить від параметра (plan/fact, тип тощо) — динамічні імена колонок не можна параметризувати через `${value}`; використовуй умовні Bun SQL фрагменти:
+
+```javascript
+// ✅ умовні фрагменти для динамічних ідентифікаторів колонок
+const colFrag  = isPlan ? pgWrite`plan_value`  : pgWrite`fact_value`
+const hashFrag = isPlan ? pgWrite`hash = s.hash,` : pgWrite``
+
+await pgWrite`
+  ...
+  WHEN MATCHED THEN
+    UPDATE SET
+      ${colFrag} = s.value,
+      ${hashFrag}
+      updated_by = s.updated_by
+  WHEN NOT MATCHED THEN
+    INSERT (id, ${colFrag}, updated_by)
+    VALUES (s.id, s.value, s.updated_by)
+`
+```
+
+`UNION ALL`-цикл замість `unnest` підходить для малих динамічних запитів (2–5 рядків), де кожна гілка семантично різна. Для bulk upsert — завжди `unnest`.
+
 ### Заборонений «drop-in» шим
 
 ```javascript
@@ -285,6 +339,26 @@ const ids = [1, 2, 3]
 await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 ```
 
+Multi-row INSERT з масиву об'єктів — `sql(rows)` генерує column list і VALUES автоматично:
+
+```javascript
+// ❌ format + pgWrite.unsafe — ручне склеювання рядків, injection-вектор
+const insertWfQry = `insert into approval.workflow (request_id, job_title_id, name, status)
+  values ${approverJobs.map(job => `('${request.id}', ${job.id}, '${job.short_name}', 'pending')`).join(', ')}`
+await pgWrite.unsafe(insertWfQry)
+
+// ✅ sql(rows) — один параметр-масив, bind через wire-protocol
+const wfRows = approverJobs.map(job => ({
+  request_id: request.id,
+  job_title_id: job.id,
+  name: job.short_name,
+  status: job.id === nextJobId ? 'current' : 'pending'
+}))
+await sql`INSERT INTO approval.workflow ${sql(wfRows)}`
+```
+
+Коли потрібен стабільний план для великих batch'ів (N > 20) або строгі типи колонок — використовуй `unnest` (деталі у `#### Приклад: MERGE з UNNEST і динамічними колонками`). Для невеликих INSERT'ів де колонки відомі — `sql(rows)` коротший і зрозуміліший.
+
 ## `IN (...)`: значення з template literal — тільки через змінну + guard на пустоту
 
 Якщо список для `IN (...)` підставляється через `${...}` у template literal, його **потрібно**:

package/rules/style-lint/style-lint.mdc

@@ -5,6 +5,92 @@ globs: "**/*.{css,scss,vue}"
 alwaysApply: false
 ---
 
+## Quasar як стильова основа
+
+У Vue-проектах використовуй **Quasar** як базову стильову систему:
+
+- **Класи компонентів:** `q-pa-*`, `q-ma-*`, `q-mt-*`, `q-mb-*`, `row`, `col`, `col-*`, `items-center`, `justify-between`, `text-*`, `bg-*`, `shadow-*` тощо — стандартні утиліти Quasar.
+- **Кольори:** використовуй Quasar CSS-змінні через класи (`text-primary`, `bg-accent`, `text-negative` тощо) або через SCSS-змінні (`$primary`, `$accent`) у `.scss`-файлах.
+- **Не пиши власні утиліти**, якщо є відповідний Quasar-клас.
+
+## Кольори: quasar-variables.scss і app.scss
+
+Основні кольори визначай виключно через стандартні Quasar-змінні: `$primary`, `$secondary`, `$accent`, `$positive`, `$negative`, `$warning`.
+
+Якщо потрібен додатковий колір — визнач його в `quasar-variables.scss`, і **обов'язково** додай до `app.scss` відповідні `.text-*` / `.bg-*` класи:
+
+```scss
+/* quasar-variables.scss */
+$white-a1: color.adjust(white, $alpha: -0.85);
+```
+
+```scss
+/* app.scss */
+.text-white-a1 {
+  color: $white-a1 !important;
+}
+
+.bg-white-a1 {
+  background-color: $white-a1 !important;
+}
+```
+
+## Gap між flex/grid-елементами — .n-gap-*
+
+Для відступів між плаваючими елементами (flex, grid) використовуй класи `.n-gap-*` замість `q-gutter-*`. Якщо класів немає в `app.scss` — додай:
+
+```scss
+// GAP
+.n-gap-xs {
+  gap: 4px;
+}
+
+.n-gap-sm {
+  gap: 8px;
+}
+
+.n-gap-md {
+  gap: 16px;
+}
+
+.n-gap-lg {
+  gap: 24px;
+}
+```
+
+## Фікси компонентів Quasar
+
+При використанні компонента `q-scroll-area` або `q-tooltip` додай до `app.scss` відповідні фікси. Аналогічно — фікс масштабування на iOS.
+
+```scss
+// FIX стилі для прокручуваної області по висоті екрана
+.q-scrollarea {
+  display: flex;
+  flex-direction: column;
+  height: auto;
+  min-height: 0;
+  max-height: 100%;
+
+  .scroll {
+    flex: 10000 1 0%;
+  }
+}
+
+// FIX tooltip
+.q-tooltip {
+  font-size: 1em;
+}
+
+// FIX не зумувати на iOS
+@media (width <= 600px) {
+  input,
+  textarea,
+  select {
+    font-size: 16px;
+  }
+}
+```
+
 ## Генерація та редагування стилів (Cursor і інші агенти)
 
 - **Джерело правил:** перед тим як писати або суттєво змінювати **`.css`**, **`.scss`** або стилі в **`.vue`**, переглянь у корені проєкту (і в релевантних пакетах монорепо, якщо є) поле **`stylelint`** у **`package.json`** (зокрема `extends`), наявні **`.stylelintrc.*`**, **`stylelint.config.*`** та **`.stylelintignore`**. Не покладайся на «типові» правила stylelint з пам’яті — дотримуйся **проєктного** **`@nitra/stylelint-config`** і будь-яких локальних доповнень у репозиторії.
@@ -94,3 +180,92 @@ jobs:
 ```text title=".stylelintignore"
 dist/
 ```
+
+## Адмінські таблиці — n-admin-table
+
+Для таблиць, що мають займати всю висоту сторінки (або блоку), додавай клас `n-admin-table` і атрибути `hide-no-data`, `dense`, `flat`. Таблиця автоматично розтягнеться на весь доступний простір. У блоках меншої висоти — задай їм явний `height`.
+
+```vue
+<!-- ТАБЛИЦЯ -->
+<q-table class="n-admin-table" hide-no-data flat dense />
+```
+
+Якщо клас `.n-admin-table` не визначено в `app.scss` — додай:
+
+```scss
+// ADMIN TABLE
+.n-admin-table {
+  height: calc(100vh - 106px);
+
+  thead {
+    position: sticky;
+    z-index: 3;
+    top: 0;
+
+    tr th {
+      background-color: $grey-3;
+      height: 36px !important;
+    }
+  }
+
+  // tbody td {
+  //   font-size: 14px;
+  // }
+
+  tbody tr:last-child td {
+    border-bottom: 1px solid rgb(0 0 0 / 12%) !important;
+  }
+
+  th:first-child,
+  td:first-child,
+  th:last-child,
+  td:last-child {
+    width: 1px;
+    white-space: nowrap;
+  }
+
+  .q-table__bottom {
+    background-color: $grey-3;
+  }
+
+  .q-table__progress th {
+    height: 1px !important;
+  }
+
+  .text-wrap {
+    max-width: 250px;
+    white-space: normal;
+  }
+
+  // sticky columns
+  td.sticky-left {
+    position: sticky;
+    left: 0;
+    z-index: 2;
+    background-color: white;
+    box-shadow: 2px 0 5px #0002;
+  }
+
+  td.sticky-right {
+    position: sticky;
+    right: 0;
+    z-index: 2;
+    background-color: white;
+    box-shadow: -2px 0 5px #0002;
+  }
+
+  th.sticky-left {
+    position: sticky;
+    left: 0;
+    z-index: 3;
+    box-shadow: 2px 0 5px #0002;
+  }
+
+  th.sticky-right {
+    position: sticky;
+    right: 0;
+    z-index: 3;
+    box-shadow: -2px 0 5px #0002;
+  }
+}
+```

package/rules/vue/vue.mdc

@@ -12,18 +12,30 @@ alwaysApply: false
 ```javascript
 const vue3CompositionApiBestPractices = [
   'Використовуй функцію setup() для логіки компонента',
-  'Реалізуй computed properties через $computed()',
-  'Використовуй watch і watchEffect для side effects',
+  'Реалізуй computed змінні через $computed()',
+  'Реалізуй ref змінні через $ref',
+  'Використовуй watch і watchEffect для побічних ефектів',
   'Підключай lifecycle hooks: onMounted, onUpdated тощо',
-  'не використовуй provide/inject для dependency injection'
+  'Для глибоко вкладених залежностей використовуй composables, props/emits або store'
+  'не використовуй provide/inject для залежностей'
 ]
 ```
 
+## 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` нижче).
+
 ## Структура папок
 
 ```javascript
 const folderStructure = `
-src/
+  src/
   components/
   composables/
   views/
@@ -76,7 +88,7 @@ const additionalInstructions = `
 
 ### Патерни та антипатерни
 
-- **provide/inject** — для глибоко вкладених залежностей; **renderless**-компоненти / **slots** — коли логіку відділяєш від розмітки.
+- Для глибоко вкладених залежностей використовуй **composables**, **props/emits** або **store**; **renderless**-компоненти / **slots** — коли логіку відділяєш від розмітки.
 - **HTTP:** окремі модулі **services** або **composables** для API; **async/await**.
 - **Події:** батько–дитина через **emits**; для не пов’язаних гілок — **store**.
 - Не мутуй **props** напряму — оновлення через подію вгору або v-model.
@@ -343,6 +355,292 @@ import path from 'node:path'
 Правило стосується саме `.vue` файлів. Допоміжні `.ts`/`.js` модулі, які споживаються лише server-side
 (наприклад, окремий пакет утіліт), можуть імпортувати Node-built-ins без обмежень.
 
+## @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` | — |
+
+## 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>
+```
+
+## @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>
+```
+
+## 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>
+```
+
+## Pinia store для стану сторінки
+
+Зберігай у Pinia store:
+
+- вибрані значення фільтрів
+- вибрані для відображення колонки (`NTableColumns`)
+- кількість записів на сторінці (pagination)
+
+Називай store за назвою сторінки або компонента — `customerPageStore`, `routePageStore` тощо. На сторінці звертайся до нього через змінну `pageStore`.
+
+```javascript
+// store/customerPage.js
+export const useCustomerPageStore = defineStore('customerPage', {
+  state: () => ({
+    filterName: '',
+    filterStatus: [],
+    columns: [],
+    rowsPerPage: 20
+  })
+})
+```
+
+```vue
+<script setup>
+const pageStore = useCustomerPageStore()
+</script>
+```
+
+## Коментарі в `<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>
+```
+
+## Статичні файли — 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
+```
+
 ## Перевірка
 
 `npx @nitra/cursor fix vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/js/packages/vue-forbidden-imports.mjs`).