@skyservice-developers/vue-dev-kit 2.10.1 → 2.12.0

package/README.md

@@ -2,6 +2,8 @@
 
 Vue 3 developer toolkit для Skyservice mini-apps: UI компоненти + TypeScript SDK (iframe bridge + HTTP API клієнт).
 
+📖 **Документація з живими демо:** https://74cfe434-a2b3-4d49-8fa7-db7343e399dc.apps.platform365.online/
+
 > **v2.0.0 breaking changes:**
 > - Vue 2 більше не підтримується (тільки Vue 3.4+).
 > - Додано повноцінний SDK (`bridge` + `SkyserviceAPI`), раніше опублікований як окремий пакет `skyservice-sdk` (задепрекейтнутий).
@@ -22,14 +24,20 @@ import '@skyservice-developers/vue-dev-kit/style.css'
 import {
   // shared/ui
   Header, Modal, Dialog,
-  SkyButton, SkySelect, SkySelectSearch, SkyInput, SkySearchInput, SkyCheckbox,
+  SkyButton, SkySelect, SkySelectSearch, SkyInput, SkySearchInput, SkyCheckbox, SkyTabs,
   SkyAlert, SkyBadge, SkyLoader,
   SkyCard, SkyCardHeader, SkyCardRow,
   SkyTable,
+  // грід на TanStack + примітиви таблиці + композабли
+  SkyDataTable, createSkyColumnHelper, skyTableFeatures,
+  SkyTableRoot, SkyTableHeader, SkyTableHead, SkyTableBody, SkyTableRow, SkyTableCell,
+  useTableSort, useTableSelection, useColumnVisibility,
+  FunctionalCalendar, SkyDateRangePicker,
   // widgets
   SkyTileCard,
   // features
   SkyCheckboxFilter,
+  TableMassActions, TableColumnSettings, TableVirtualBody,
   // sdk
   navigate, SkyserviceAPI, isInsideIframe,
   // sky-service-ui-components
@@ -209,6 +217,24 @@ import {
 </Modal>
 ```
 
+Шапку можна зібрати слотами — так само як у `Header`: `#title` / `#subtitle`
+перекривають відповідні props, `#header-actions` додає елементи справа
+(кнопка "Назад" лишається на місці).
+
+```vue
+<Modal v-model="show">
+  <template #title>
+    <h4 style="margin: 0">Замовлення №1042 <SkyBadge tone="success" label="Оплачено" /></h4>
+  </template>
+  <template #subtitle>Оновлено щойно</template>
+  <template #header-actions>
+    <SkyButton variant="outline">Друк</SkyButton>
+  </template>
+
+  <p>Контент</p>
+</Modal>
+```
+
 #### Props
 
 | Prop | Тип | За замовчуванням | Опис |
@@ -227,8 +253,17 @@ import {
 | Slot | Опис |
 |------|------|
 | `default` | Основний контент |
+| `title` | Кастомний заголовок (замість пропа `title`) |
+| `subtitle` | Кастомний підзаголовок (замість пропа `subtitle`) |
+| `header-actions` | Елементи справа в шапці (кнопки, бейджі) |
 | `footer` | Футер з кнопками |
 
+#### CSS змінні
+
+| Змінна | За замовчуванням | Опис |
+|--------|------------------|------|
+| `--sky-modal-header-actions-gap` | `8px` | Відступ між елементами в `#header-actions` |
+
 #### Events
 
 | Event | Опис |
@@ -271,8 +306,33 @@ import {
 | Slot | Опис |
 |------|------|
 | `default` | Основний контент |
+| `title` | Кастомний заголовок (замість пропа `title`) |
+| `subtitle` | Кастомний підзаголовок (замість пропа `subtitle`) |
+| `header-actions` | Елементи справа в шапці (кнопки, бейджі) |
 | `buttons` | Кнопки у футері |
 
+Слоти шапки працюють в обох режимах — `next` (ліворуч кнопка "Назад") і
+`classic` (праворуч ×); `#header-actions` рендериться ліворуч від ×.
+
+```vue
+<Dialog v-model="show" mode="next">
+  <template #title>Замовлення №1042</template>
+  <template #subtitle>3 позиції · 1 240 ₴</template>
+  <template #header-actions>
+    <SkyButton variant="outline">Друк</SkyButton>
+  </template>
+
+  <div style="padding: 20px">Контент</div>
+</Dialog>
+```
+
+#### CSS змінні
+
+| Змінна | За замовчуванням | Опис |
+|--------|------------------|------|
+| `--sky-dialog-header-actions-gap` | `8px` | Відступ між елементами в `#header-actions` |
+| `--sky-dialog-title-max-width-with-actions` | `50%` | Ширина заголовка в `classic`, коли є `#header-actions` |
+
 #### Events
 
 | Event | Опис |
@@ -329,60 +389,47 @@ import {
 
 ### SkySelect
 
-Кастомний select з дропдауном, клавіатурною навігацією та підтримкою рядків і об'єктів як опцій.
+Нативний `<select>` у фірмовому стилі, зі станами `default | success | error` та підказкою під полем.
 
 ```vue
-<!-- Об'єкти -->
 <SkySelect
-  v-model="selected"
+  v-model="payment"
   :options="[
-    { label: 'Готівка', value: 'cash' },
-    { label: 'Картка', value: 'card' },
+    { value: 'cash', text: 'Готівка' },
+    { value: 'card', text: 'Картка' },
   ]"
   placeholder="Оберіть спосіб оплати"
 />
 
-<!-- Рядки -->
-<SkySelect v-model="selected" :options="['Кг', 'Шт', 'Л']" />
-
-<!-- На всю ширину -->
-<SkySelect v-model="selected" :options="options" block />
+<SkySelect v-model="payment" :options="options" state="error" hint="Оберіть спосіб" />
+<SkySelect v-model="payment" :options="options" disabled />
 ```
 
 #### Props
 
 | Prop | Тип | За замовчуванням | Опис |
 |------|-----|------------------|------|
-| `modelValue` / `value` | `any` | `null` | Поточне значення (v-model) |
-| `options` | `Array` | `[]` | `Array<{ label, value } \| string>` |
-| `placeholder` | `String` | `''` | Текст-заглушка |
+| `modelValue` | `string \| number` | — | Поточне значення (v-model) |
+| `options` | `Array<{ value: string \| number; text: string }>` | — | Список опцій (обов'язковий) |
+| `id` | `String` | — | HTML id |
 | `disabled` | `Boolean` | `false` | Вимкнений стан |
-| `block` | `Boolean` | `false` | Повна ширина |
-| `teleport` | `Boolean` | `false` | Рендерить дропдаун в `<body>` (для модалок/overflow:hidden контейнерів) |
+| `state` | `'default' \| 'success' \| 'error'` | `'default'` | Візуальний стан рамки |
+| `placeholder` | `String` | `''` | Текст-заглушка (рендериться як `disabled hidden` опція) |
+| `hint` | `String` | `''` | Підказка під полем у кольорі `state` |
 
-#### Клавіатура
+#### Events
 
-| Клавіша | Дія |
-|---------|-----|
-| `Enter` / `Space` | Відкрити дропдаун |
-| `↑` / `↓` | Навігація по опціях |
-| `Enter` | Вибрати поточну опцію |
-| `Esc` | Закрити дропдаун |
+| Event | Payload | Опис |
+|-------|---------|------|
+| `update:modelValue` | `string \| number` | Emit при виборі опції |
 
-#### CSS змінні
+> **Формат опцій — тільки `{ value, text }`.** Масив рядків або `{ label, value }` дадуть порожні пункти:
+> компонент читає `option.value` і `option.text`. Мапте дані заздалегідь — `units.map(u => ({ value: u, text: u }))`.
 
-```css
---sky-select-padding: 10px 14px
---sky-select-radius: 6px
---sky-select-font-size: 14px
---sky-select-border: 1px solid #d1d5db
---sky-select-dropdown-shadow: 0 4px 12px rgba(0,0,0,0.1)
---sky-select-dropdown-max-height: 220px
---sky-select-option-hover-bg: #f3f4f6
---sky-select-option-selected-color: #24973f
-```
+> Список малює браузер, тож клавіатура й поведінка на мобільних — рідні для платформи, а дропдаун
+> не обрізається контейнерами з `overflow: hidden` (усередині `Modal` teleport не потрібен).
+> Компонент займає всю ширину контейнера — обмежуйте батьківський блок, якщо треба вужче.
 
----
 
 ### SkySelectSearch
 
@@ -527,6 +574,39 @@ import {
 
 ---
 
+### SkyTabs
+
+Сегментовані таби з анімованим індикатором: біла «пігулка» плавно переїжджає під активну опцію й підлаштовує ширину під довжину тексту.
+
+```vue
+<SkyTabs
+  v-model="period"
+  :options="[
+    { value: 'day', text: 'День' },
+    { value: 'week', text: 'Тиждень' },
+    { value: 'month', text: 'Місяць' },
+  ]"
+/>
+```
+
+#### Props
+
+| Prop | Тип | За замовчуванням | Опис |
+|------|-----|------------------|------|
+| `modelValue` | `string \| number` | — | Активне значення (v-model) |
+| `options` | `Array<{ value: string \| number; text: string }>` | — | Список табів (обов'язковий) |
+| `disabled` | `Boolean` | `false` | Блокує весь набір |
+
+#### Events
+
+| Event | Payload | Опис |
+|-------|---------|------|
+| `update:modelValue` | `string \| number` | Emit при виборі таба |
+
+> Індикатор вимірює активну кнопку через `getBoundingClientRect()`: на першому рендері стає на місце без анімації, далі — з переходом. Реагує на `resize` вікна і зміну кількості опцій. У прихованому контейнері (`display: none`) розміри нульові — позиція виправиться після показу.
+
+---
+
 ### SkyAlert
 
 Інформаційне повідомлення з 4 тональностями та опціональною іконкою.
@@ -779,6 +859,129 @@ Shell-контейнер для карток: ribbon / header / body / footer
 
 ---
 
+### SkyDataTable
+
+Грід на [TanStack Table v9](https://tanstack.com/table/latest): headless-ядро тримає стан і обчислення, розмітка й стилі — наші. Візуально це та сама таблиця, що в POS. Повний опис — у [документації](https://74cfe434-a2b3-4d49-8fa7-db7343e399dc.apps.platform365.online/components/data-table).
+
+```vue
+<script setup lang="ts">
+import { h } from 'vue'
+import { SkyDataTable, SkyBadge, createSkyColumnHelper } from '@skyservice-developers/vue-dev-kit'
+
+const column = createSkyColumnHelper<Product>()
+
+const columns = [
+  column.accessor('name', { header: 'Назва', meta: { widthFr: 2 } }),
+  column.accessor('price', {
+    header: 'Ціна',
+    size: 110,
+    meta: { align: 'right' },
+    cell: ({ getValue }) => `${getValue()} ₴`,
+  }),
+  column.accessor('status', {
+    header: 'Статус',
+    size: 150,
+    enableSorting: false,
+    cell: ({ getValue }) =>
+      h(SkyBadge, { tone: getValue() === 'Активний' ? 'success' : 'default', label: getValue() }),
+  }),
+]
+</script>
+
+<template>
+  <SkyDataTable :columns="columns" :data="products" :page-size="25" row-id="id" searchable />
+</template>
+```
+
+#### Props
+
+| Prop | Тип | За замовчуванням | Опис |
+|------|-----|------------------|------|
+| `columns` | `ColumnDef[]` | — | Опис колонок (TanStack) |
+| `data` | `TData[]` | — | Дані |
+| `features` | `TableFeatures` | `skyTableFeatures` | Власний набір фіч |
+| `rowId` | `String \| (row) => string` | — | Ключ рядка |
+| `pageSize` | `Number` | `0` | Розмір сторінки; `0` — без пагінації |
+| `searchable` | `Boolean` | `false` | Поле глобального пошуку в тулбарі |
+| `initialSorting` | `SortingState` | — | Початкове сортування |
+| `emptyText` | `String` | `'Даних немає'` | Текст порожнього стану |
+| `interactiveRows` | `Boolean` | `false` | Курсор і hover на рядках |
+
+Слоти: `toolbar`, `actions`, `footer`, `empty` (усі отримують `{ table }`). Подія: `row-click`. Інстанс таблиці доступний через `ref` → `tableRef.table`.
+
+#### Набір фіч
+
+Фічі TanStack v9 вмикаються явно — кіт експортує стабільний `skyTableFeatures` (сортування, вибір, видимість колонок, пагінація, фільтрація + слоти row-моделей і реєстри `sortFns`/`filterFns`). Потрібно більше — зберіть свій обʼєкт і передайте пропом `features`:
+
+```ts
+import { tableFeatures, rowExpandingFeature, createExpandedRowModel } from '@tanstack/vue-table'
+import { skyTableFeatures } from '@skyservice-developers/vue-dev-kit'
+
+const features = tableFeatures({
+  ...skyTableFeatures,
+  rowExpandingFeature,
+  expandedRowModel: createExpandedRowModel(),
+})
+```
+
+Ширина колонок: `size: 150` — фіксовані px, `meta: { widthFr: 2 }` — гнучка частка (має пріоритет над `size`), `meta: { align }` і `meta: { minWidthScreen }` — вирівнювання й приховування на вузьких екранах.
+
+> `@tanstack/vue-table` входить у залежності пакета й лишається зовнішнім у бандлі — застосунки, які гріда не використовують, його не тягнуть.
+
+---
+
+### Таблиця з примітивів (композиційна)
+
+Набір примітивів і композаблів замість одного великого компонента: береш тільки те, що треба. Без вибору рядків, без масових дій, без віртуалізації — і нічого з цього не потрапляє в бандл. Повний опис — у [документації](https://74cfe434-a2b3-4d49-8fa7-db7343e399dc.apps.platform365.online/components/table).
+
+```vue
+<script setup>
+import {
+  SkyTableRoot, SkyTableHeader, SkyTableHead,
+  SkyTableBody, SkyTableRow, SkyTableCell,
+} from '@skyservice-developers/vue-dev-kit'
+
+const columns = [
+  { name: 'name', title: 'Товар', widthFr: 2 },
+  { name: 'price', title: 'Ціна', width: 90, align: 'right' },
+]
+</script>
+
+<template>
+  <SkyTableRoot :columns="columns">
+    <SkyTableHeader>
+      <SkyTableHead v-for="c in columns" :key="c.name" :column="c" />
+    </SkyTableHeader>
+    <SkyTableBody>
+      <SkyTableRow v-for="row in rows" :key="row.id">
+        <SkyTableCell>{{ row.name }}</SkyTableCell>
+        <SkyTableCell align="right">{{ row.price }}</SkyTableCell>
+      </SkyTableRow>
+    </SkyTableBody>
+  </SkyTableRoot>
+</template>
+```
+
+#### Що входить
+
+| Шар | Експорти | Коли підключати |
+|-----|----------|-----------------|
+| Примітиви (`shared/ui/table`) | `SkyTableRoot`, `SkyTableHeader`, `SkyTableHead`, `SkyTableBody`, `SkyTableRow`, `SkyTableCell`, `SkyTableEmpty` | завжди |
+| Композабли (`shared/lib/table`) | `useTableSort`, `useTableSelection`, `useColumnVisibility` | за потреби |
+| Фічі (`features/table`) | `TableMassActions`, `TableColumnSettings`, `TableVirtualBody` | опційно, кожна окремо |
+
+```ts
+const { sort, toggle } = useTableSort({ initial: { of: 'name', ot: 'asc' } })
+const { selected, isSelected, toggle: select, toggleAll } = useTableSelection(rows, { rowId: 'id' })
+const { visibility, visibleColumns } = useColumnVisibility(columns, { storageKey: 'products' })
+```
+
+Композабли не сортують і не фільтрують дані — вони тримають стан, а дані лишаються за застосунком (зазвичай сортує сервер). Колонка вибору описується як звичайна колонка (`{ name: '_select', width: 44 }`), щоб грід шапки й рядків рахувався з одного джерела.
+
+> `vue-virtual-scroller` імпортує лише `TableVirtualBody`. Не потрібна віртуалізація — беріть `SkyTableBody`, і залежність не знадобиться.
+
+---
+
 ### SkyTable
 
 Віртуал-скрол таблиця (на `vue-virtual-scroller`) для великих списків — у DOM тримаються лише видимі рядки. Розмітка й стилі 1:1 з таблицею товарів POS: чекбокси, масові дії, сортування, зміна ширини/видимості колонок, розкриття вкладених рядків (модифікацій), inline-редагування комірок і теги.
@@ -875,6 +1078,33 @@ const json = { items, total: items.length }
 
 ---
 
+### FunctionalCalendar
+
+Перенесено зі SkyMarket (`src/lib/functional-calendar`), стилі й розмітка 1:1. Форк [vue-functional-calendar](https://github.com/ManukMinasyan/vue-functional-calendar) під Vue 3 — пропси, події та слоти без змін відносно оригіналу.
+
+```vue
+<FunctionalCalendar
+  :value="calendarData"
+  @input="calendarData = $event"
+  is-date-range
+  is-modal
+/>
+```
+
+### SkyDateRangePicker
+
+Перенесено зі SkyMarket (`DatePickerRange.vue`) — готовий попап-піка діапазону дат на базі `FunctionalCalendar`: іконка-тригер, лейбл періоду, пресети (Сьогодні / Вчора / Тиждень / Місяць / Минулий-Поточний місяць / За весь час), стилі 1:1. На відміну від оригіналу, який читав `store`/`@/langs` конкретного застосунку, тут стан і тексти (з UA-фолбеками) локальні.
+
+```vue
+<SkyDateRangePicker v-model="range" @set-date="onPreset" />
+```
+
+```js
+const range = reactive({ start: '', end: '' }) // { start, end } у форматі yyyy-mm-dd
+```
+
+---
+
 ## Features
 
 ### SkyCheckboxFilter
@@ -1008,6 +1238,23 @@ npm run playground
 npm run build
 ```
 
+## Реліз
+
+Публікація на npm автоматична — пуш у `main` запускає GitHub Action
+`Publish to npm`, який збирає й публікує пакет. Руками `npm publish` не запускати.
+
+| Що треба | Що зробити |
+| --- | --- |
+| Випустити нову версію | Бампнути `version` у `package.json` → змержити в `main` |
+| Залити зміни без релізу | Не чіпати `version` — публікація пропуститься, CI лишиться зеленим |
+| Опублікувати вручну | Actions → Publish to npm → Run workflow |
+
+Публікація пропускається, якщо версія з `package.json` уже є в реєстрі. Пуші, що
+зачіпають лише `**.md` або `.github/**`, воркфлоу не запускають — для них
+є ручний запуск.
+
+Поки версію не бампнули, споживачі змін не бачать: npm далі віддає попередню.
+
 ## Структура проекту
 
 Організовано за Feature-Sliced Design:
@@ -1028,18 +1275,26 @@ src/
 │       ├── BaseTeleport/
 │       ├── SkyButton/
 │       ├── SkySelect/ SkySelectSearch/ SkyInput/ SkySearchInput/ SkyCheckbox/
+│       ├── SkyTabs/     # сегментовані таби з анімованим індикатором
 │       ├── SkyAlert/
 │       ├── SkyBadge/
 │       ├── SkyCard/ SkyCardHeader/ SkyCardRow/
 │       ├── SkyLoader/
-│       ├── SkyTable/     # віртуал-скрол таблиця (Header/Row/Footer/DynamicScroller/items/*)
+│       ├── table/       # примітиви композиційної таблиці (Root/Header/Head/Body/Row/Cell/Empty)
+│       ├── SkyTable/     # готова віртуал-скрол таблиця (Header/Row/Footer/DynamicScroller/items/*)
 │       ├── SkyTileCard/
+│       ├── functional-calendar/ # форк vue-functional-calendar, перенесений зі SkyMarket 1:1
+│       ├── SkyDateRangePicker/  # DatePickerRange зі SkyMarket, store/langs → props/локальний стан
 │       └── <Component>/
 │           ├── <Component>.vue
 │           └── index.ts
+│   └── lib/
+│       └── table/   # skyTableFeatures + useTableSort / useTableSelection / useColumnVisibility
 ├── features/          # фічові блоки (orchestration shared/ui)
 │   ├── index.ts
-│   └── SkyCheckboxFilter/
+│   ├── SkyCheckboxFilter/
+│   ├── table/         # TableMassActions / TableColumnSettings / TableVirtualBody
+│   └── data-table/    # SkyDataTable на TanStack v9 + перемикач колонок
 ├── sdk/               # TypeScript SDK (без Vue залежностей)
 │   ├── bridge.ts      # iframe postMessage API
 │   ├── api.ts         # SkyserviceAPI HTTP клієнт