@rock555/frontend-core 0.0.0-stage → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +95 -3
- package/package.json +98 -6
- package/src/api/errors/apiProblem.ts +78 -0
- package/src/api/errors/index.ts +37 -0
- package/src/api/index.ts +169 -0
- package/src/api/types.ts +53 -0
- package/src/api/utils.ts +68 -0
- package/src/components/GlobalPendingBar.vue +85 -0
- package/src/components/SearchPicker.vue +84 -0
- package/src/components/filters/DateRangeField.vue +692 -0
- package/src/components/filters/ExportCsvButton.vue +60 -0
- package/src/components/filters/FiltersBar.vue +150 -0
- package/src/components/filters/MonthField.vue +309 -0
- package/src/components/filters/SortControl.vue +162 -0
- package/src/components/filters/SortControlPanel.vue +242 -0
- package/src/components/filters/sortControl.types.ts +25 -0
- package/src/components/modals/BaseModal.vue +188 -0
- package/src/components/modals/ConfirmModal.vue +58 -0
- package/src/components/modals/GlobalModals.vue +20 -0
- package/src/components/modals/ImageViewerModal.vue +200 -0
- package/src/components/modals/ModalCard.vue +70 -0
- package/src/components/modals/ModalSection.vue +61 -0
- package/src/components/tables/MultiSortHeader.vue +126 -0
- package/src/components/tables/TableBodyRow.vue +62 -0
- package/src/components/tables/TableExpandRow.vue +13 -0
- package/src/components/tables/TableFooterRow.vue +54 -0
- package/src/components/tables/TableHeaderRow.vue +75 -0
- package/src/components/tables/TableLoadedCount.vue +61 -0
- package/src/components/tables/TableLoadedFooter.vue +44 -0
- package/src/components/tables/TablePager.vue +95 -0
- package/src/components/tables/TableSkeletonRows.vue +40 -0
- package/src/components/tables/TableVirtualPad.vue +16 -0
- package/src/components/tables/cells/AmountCell.vue +48 -0
- package/src/components/tables/cells/BoolBadgeCell.vue +32 -0
- package/src/components/tables/cells/DateTimeCell.vue +41 -0
- package/src/components/tables/cells/MoneyCell.vue +53 -0
- package/src/components/tables/cells/SimpleCell.vue +42 -0
- package/src/components/tables/cells/actions/ActionCell.vue +20 -0
- package/src/components/tables/multiSortHeader.types.ts +16 -0
- package/src/components/timeline/TimelineChart.vue +204 -0
- package/src/components/timeline/timeline.types.ts +22 -0
- package/src/components/ui/FilterCheckbox.vue +97 -0
- package/src/components/ui/FilterOne.vue +68 -0
- package/src/components/ui/FilterSelect.vue +489 -0
- package/src/components/ui/UiActionTiles.vue +92 -0
- package/src/components/ui/UiBackLink.vue +39 -0
- package/src/components/ui/UiBadge.vue +60 -0
- package/src/components/ui/UiButton.vue +126 -0
- package/src/components/ui/UiCard.vue +88 -0
- package/src/components/ui/UiCount.vue +35 -0
- package/src/components/ui/UiIconButton.vue +104 -0
- package/src/components/ui/UiKpiGrid.vue +142 -0
- package/src/components/ui/UiPopover.vue +62 -0
- package/src/components/ui/UiSearchInput.vue +102 -0
- package/src/components/ui/UiSegmented.vue +145 -0
- package/src/components/ui/UiTableCard.vue +116 -0
- package/src/components/ui/filterSelect.types.ts +12 -0
- package/src/components/ui/inputs/CheckboxFormInput.vue +33 -0
- package/src/components/ui/inputs/CheckboxInput.vue +93 -0
- package/src/components/ui/inputs/DateFormInput.vue +77 -0
- package/src/components/ui/inputs/DateRangeFormInput.vue +56 -0
- package/src/components/ui/inputs/FileInput.vue +180 -0
- package/src/components/ui/inputs/PasswordReveal.vue +76 -0
- package/src/components/ui/inputs/RadioSegmentFormInput.vue +143 -0
- package/src/components/ui/inputs/SelectFormInput.vue +38 -0
- package/src/components/ui/inputs/SmartField.vue +180 -0
- package/src/components/ui/inputs/TextareaFormInput.vue +31 -0
- package/src/components/ui/inputs/low-level/DateRange.vue +119 -0
- package/src/components/ui/uiActionTiles.types.ts +10 -0
- package/src/components/ui/uiBadge.types.ts +11 -0
- package/src/components/ui/uiKpi.types.ts +17 -0
- package/src/composables/tables/useTableSelection.ts +45 -0
- package/src/composables/useAppForm.ts +67 -0
- package/src/composables/useConfirm.ts +21 -0
- package/src/composables/useFilterState.ts +70 -0
- package/src/composables/useFuzzySearch.ts +42 -0
- package/src/composables/useMyForm.ts +53 -0
- package/src/composables/useServerList.ts +348 -0
- package/src/composables/useServerTable.ts +117 -0
- package/src/composables/useSharedAsync.ts +51 -0
- package/src/composables/useVirtualTable.ts +77 -0
- package/src/config.ts +155 -0
- package/src/errors/actionCancelled.ts +9 -0
- package/src/errors/apiError.helper.ts +161 -0
- package/src/errors/useHandleError.ts +33 -0
- package/src/helpers/assert.helper.ts +18 -0
- package/src/helpers/calendarRange.helper.ts +74 -0
- package/src/helpers/date.helper.ts +61 -0
- package/src/helpers/download.helper.ts +35 -0
- package/src/helpers/enum.helper.ts +6 -0
- package/src/helpers/file.helper.ts +14 -0
- package/src/helpers/form.helper.ts +66 -0
- package/src/helpers/month.helper.ts +63 -0
- package/src/helpers/period.helper.ts +176 -0
- package/src/helpers/periodLabel.helper.ts +70 -0
- package/src/helpers/periodPresets.helper.ts +76 -0
- package/src/helpers/query.helper.ts +101 -0
- package/src/helpers/select.helper.ts +15 -0
- package/src/helpers/sort.helper.ts +57 -0
- package/src/helpers/tableFields.helper.ts +205 -0
- package/src/helpers/timelineScale.helper.ts +322 -0
- package/src/helpers/urlParams.helper.ts +99 -0
- package/src/helpers/urlSchema.helper.ts +296 -0
- package/src/helpers/urlState.helper.ts +53 -0
- package/src/lib/concurrency.ts +35 -0
- package/src/lib/timings.ts +5 -0
- package/src/plugins/modals.plugin.ts +253 -0
- package/src/plugins/table.plugin.ts +173 -0
- package/src/plugins/zod.ts +14 -0
- package/src/styles/table.scss +195 -0
- package/src/types/common.ts +9 -0
- package/src/types/table.d.ts +12 -0
- package/src/types/ui/select.ts +5 -0
- package/src/types/vue-utils.ts +18 -0
package/README.md
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# frontend-core
|
|
2
|
+
|
|
3
|
+
Спільне фронтове ядро кількох проєктів: API-клієнт і обробка помилок, списки й таблиці, форми, модалки, фільтри, кнопки, хелпери. Тільки фронт: Vue, TypeScript, SCSS. PHP тут немає.
|
|
4
|
+
|
|
5
|
+
Ядро не знає проєктів: ні їхньої мови, ні кольорів, ні структури папок. Усе проєктне приходить через `SharedConfig` і токени стилів.
|
|
6
|
+
|
|
7
|
+
## Підключення в проєкт
|
|
8
|
+
|
|
9
|
+
Публічний пакет на npmjs.com, токен для встановлення не потрібен. У `package.json`:
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
"@rock555/frontend-core": "^2.0.2"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Імпорти `@/_shared/...` міняти не треба, досить аліаса. У `vite.config`:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
resolve: {
|
|
19
|
+
alias: {
|
|
20
|
+
'@/_shared': fileURLToPath(new URL('./node_modules/@rock555/frontend-core/src', import.meta.url)),
|
|
21
|
+
'@': fileURLToPath(new URL('./resources/js', import.meta.url)),
|
|
22
|
+
},
|
|
23
|
+
dedupe: ['vue'],
|
|
24
|
+
},
|
|
25
|
+
// Без цього dev-сервер збирає ядро окремою копією, і застосунок падає на старті.
|
|
26
|
+
optimizeDeps: { exclude: ['@/_shared'] },
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Аліас `@/_shared` має стояти раніше за `@`. У `tsconfig.json`:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
"paths": {
|
|
33
|
+
"@/_shared/*": ["./node_modules/@rock555/frontend-core/src/*"],
|
|
34
|
+
"@/*": ["./resources/js/*"]
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Свою копію `types/table.d.ts` прибрати: типи колонок ядро підключає само.
|
|
39
|
+
|
|
40
|
+
Залежності ядра (`peerDependencies`) ставить сам проєкт. Необов'язкові: `vis-data` і `vis-timeline` для `TimelineChart`, `vue-sonner` для `ExportCsvButton`, `motion-v` для `SortControlPanel`.
|
|
41
|
+
|
|
42
|
+
Підключати конфіг так, щоб `SharedConfig.configure()` спрацював до першого рендера. На рівні модуля читати тексти не можна, це перевіряє `tests/core/config-timing.test.ts`.
|
|
43
|
+
|
|
44
|
+
## Що проєкт зобов'язаний дати
|
|
45
|
+
|
|
46
|
+
Через `additionalData` у налаштуваннях SCSS, повний список у [tests/fixtures/_tokens.scss](tests/fixtures/_tokens.scss):
|
|
47
|
+
|
|
48
|
+
- Поверхні й текст: `$color-page-bg`, `$color-surface`, `$color-border`, `$color-text`.
|
|
49
|
+
- `$color-border-strong`: рамки полів, не менше 3:1 до `$color-surface`.
|
|
50
|
+
- `$color-muted`: вторинний текст, не менше 4,5:1 до `$color-surface`.
|
|
51
|
+
- `$color-accent`: рамки, іконки, заливки без тексту, не менше 3:1.
|
|
52
|
+
- `$color-accent-ink`: текст акцентом і заливка під білим текстом, не менше 4,5:1 до `$color-surface` і `$color-accent-dim`.
|
|
53
|
+
- `$color-accent-dim`: фон вибраного.
|
|
54
|
+
- `$color-green-ink`, `$color-danger`: текст, не менше 4,5:1 до `$color-surface`.
|
|
55
|
+
- Бейджі: `$color-green`, `$color-green-soft`, `$color-danger-soft`, `$color-danger-ink`, `$color-warning-soft`, `$color-warning-ink`, `$color-neutral-soft`, `$color-neutral-ink`, `$color-teal-soft`, `$color-teal-ink`.
|
|
56
|
+
- `$color-selected`, `$color-on-selected`: заливка вибраного (день у календарі, плитка) і текст на ній, не менше 4,5:1.
|
|
57
|
+
- Інше: `$radius`, `$anim-small-time`, `$table-cell-padding-x`, `$table-cell-padding-y`.
|
|
58
|
+
- Міксини: `scrollbarStyle`, `bigMobile` і `buttonPrimary` (вигляд головної кнопки, бренд проєкту).
|
|
59
|
+
|
|
60
|
+
Через `SharedConfig.configure()`, повний список у [src/config.ts](src/config.ts):
|
|
61
|
+
|
|
62
|
+
- `labels`: усі тексти інтерфейсу ядра, `formatNumber`, `formatMoney`.
|
|
63
|
+
- `errors`: словник кодів бека, тексти за HTTP-статусом, текст за правилом валідації. Логіка ланцюжка в `errors/apiError.helper`, слова в проєкту.
|
|
64
|
+
- `notifyError`: як показати помилку (тост, стор сповіщень, кнопка «Увійти»).
|
|
65
|
+
- `link`: компонент посилання для `UiButton`: `{ component: RouterLink, prop: 'to' }` чи `{ component: Link, prop: 'href' }`.
|
|
66
|
+
- `goBack`: «Назад» у `UiBackLink`.
|
|
67
|
+
|
|
68
|
+
Свій варіант кнопки (`<UiButton variant="violet">`) проєкт описує глобально. Селектор `.ui-btn.ui-btn--violet.ui-btn--violet`: scoped-стилі кнопки в ядрі сильніші за один клас.
|
|
69
|
+
|
|
70
|
+
## Як змінювати ядро
|
|
71
|
+
|
|
72
|
+
1. Правка йде PR-ом сюди, а не в папку проєкту. Перевірити її в себе: `npm link` або `"file:../frontend-core"` замість версії, у PR проєкту це не потрапляє.
|
|
73
|
+
2. CI ганяє типи, лінт і межі ядра. Локально те саме: `npm run check`.
|
|
74
|
+
3. Після вливання піднімаємо `version` у `package.json`, пишемо в [CHANGES.md](CHANGES.md) і ставимо тег `v…`: CI сам публікує пакет через trusted publishing, без токена.
|
|
75
|
+
- патч `1.0.1`: виправлення, проєктам нічого робити не треба;
|
|
76
|
+
- мінор `1.1.0`: нова можливість, зі значенням за замовчуванням, старе працює як було;
|
|
77
|
+
- мажор `2.0.0`: ламає проєкти (новий обов'язковий токен чи підпис, видалення, зміна поведінки), у `CHANGES.md` пишемо, що зробити проєкту.
|
|
78
|
+
4. Проєкт піднімає версію у себе звичайним PR, коли йому зручно: його CI перевіряє, відповідальний вливає.
|
|
79
|
+
|
|
80
|
+
## Як оновлення доходить до проєктів
|
|
81
|
+
|
|
82
|
+
Само нічого не приїде: версія зафіксована в `package-lock.json` проєкту. Коли виходить нова версія, бот (Dependabot або Renovate) відкриває в кожному проєкті PR на неї, тож про оновлення ніхто не забуде. Вручну: `npm install @rock555/frontend-core@latest`.
|
|
83
|
+
|
|
84
|
+
Відставати на мажор і більше дуже небажано, хоч і не заборонено: чим більший розрив, тим дорожче потім наздоганяти.
|
|
85
|
+
|
|
86
|
+
## Чого в ядрі бути не може
|
|
87
|
+
|
|
88
|
+
Це перевіряє `tests/core/boundaries.test.ts`, і CI падає:
|
|
89
|
+
|
|
90
|
+
- тексти інтерфейсу, вони приходять через `SharedConfig`;
|
|
91
|
+
- імпорти `@/` і вихід за межі `src`;
|
|
92
|
+
- пакети, яких немає в `peerDependencies`;
|
|
93
|
+
- кольори літералами, дозволені лише нейтральні тіні, затемнення під модалкою й білий значок на залитій кнопці;
|
|
94
|
+
- стилі, що беруть щось поза контрактом токенів;
|
|
95
|
+
- те, що не можна показувати: пакет публічний, тож ні секретів, ні адрес серверів, ні пошти, ні назв проєктів, ні бізнес-логіки. Версію вже могли скачати, тож назад це не забрати.
|
package/package.json
CHANGED
|
@@ -1,6 +1,98 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@rock555/frontend-core",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@rock555/frontend-core",
|
|
3
|
+
"version": "2.0.2",
|
|
4
|
+
"description": "Спільне фронтове ядро: API-клієнт, таблиці, форми, модалки, хелпери",
|
|
5
|
+
"license": "UNLICENSED",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/RockSystems/frontend-core.git"
|
|
9
|
+
},
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"registry": "https://registry.npmjs.org",
|
|
12
|
+
"access": "public"
|
|
13
|
+
},
|
|
14
|
+
"type": "module",
|
|
15
|
+
"files": [
|
|
16
|
+
"src"
|
|
17
|
+
],
|
|
18
|
+
"exports": {
|
|
19
|
+
"./*": "./src/*"
|
|
20
|
+
},
|
|
21
|
+
"scripts": {
|
|
22
|
+
"typecheck": "vue-tsc --noEmit",
|
|
23
|
+
"lint": "eslint .",
|
|
24
|
+
"test": "vitest run",
|
|
25
|
+
"check": "npm run typecheck && npm run lint && npm run test"
|
|
26
|
+
},
|
|
27
|
+
"peerDependencies": {
|
|
28
|
+
"@internationalized/date": "^3.11.0",
|
|
29
|
+
"@lucide/vue": "^1.57.0",
|
|
30
|
+
"@tanstack/vue-hotkeys": "0.17.0",
|
|
31
|
+
"@tanstack/vue-query": "^5.92.9",
|
|
32
|
+
"@tanstack/vue-table": "^8.21.3",
|
|
33
|
+
"@tanstack/vue-virtual": "^3.13.48",
|
|
34
|
+
"@vee-validate/zod": "^4.15.1",
|
|
35
|
+
"@vueuse/core": "^12.8.2 || ^15.0.0",
|
|
36
|
+
"axios": "^1.13.2",
|
|
37
|
+
"dayjs": "^1.11.19",
|
|
38
|
+
"fuse.js": "^7.5.0",
|
|
39
|
+
"motion-v": "^2.4.0",
|
|
40
|
+
"reka-ui": "^2.6.1",
|
|
41
|
+
"uuid": "^14.0.0",
|
|
42
|
+
"vee-validate": "^4.15.1",
|
|
43
|
+
"vis-data": "^8.0.5",
|
|
44
|
+
"vis-timeline": "^8.5.4",
|
|
45
|
+
"vue": "^3.5.13",
|
|
46
|
+
"vue-sonner": "^2.0.9",
|
|
47
|
+
"zod": "^3.25.76"
|
|
48
|
+
},
|
|
49
|
+
"peerDependenciesMeta": {
|
|
50
|
+
"vis-data": {
|
|
51
|
+
"optional": true
|
|
52
|
+
},
|
|
53
|
+
"vis-timeline": {
|
|
54
|
+
"optional": true
|
|
55
|
+
},
|
|
56
|
+
"vue-sonner": {
|
|
57
|
+
"optional": true
|
|
58
|
+
},
|
|
59
|
+
"motion-v": {
|
|
60
|
+
"optional": true
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"devDependencies": {
|
|
64
|
+
"@internationalized/date": "^3.12.4",
|
|
65
|
+
"@lucide/vue": "^1.58.0",
|
|
66
|
+
"@tanstack/vue-hotkeys": "0.17.0",
|
|
67
|
+
"@tanstack/vue-query": "^5.104.1",
|
|
68
|
+
"@tanstack/vue-table": "^8.21.3",
|
|
69
|
+
"@tanstack/vue-virtual": "3.13.48",
|
|
70
|
+
"@types/node": "^22.10.0",
|
|
71
|
+
"@vee-validate/zod": "^4.15.1",
|
|
72
|
+
"@vue/eslint-config-typescript": "^14.3.0",
|
|
73
|
+
"@vueuse/core": "^15.0.0",
|
|
74
|
+
"axios": "^1.13.4",
|
|
75
|
+
"dayjs": "^1.11.23",
|
|
76
|
+
"eslint": "^9.17.0",
|
|
77
|
+
"eslint-plugin-vue": "^9.32.0",
|
|
78
|
+
"fuse.js": "^7.5.0",
|
|
79
|
+
"motion-v": "^2.7.0",
|
|
80
|
+
"reka-ui": "^2.11.0",
|
|
81
|
+
"sass": "^1.83.0",
|
|
82
|
+
"typescript": "^5.2.2",
|
|
83
|
+
"typescript-eslint": "^8.23.0",
|
|
84
|
+
"uuid": "^14.0.3",
|
|
85
|
+
"vee-validate": "^4.15.1",
|
|
86
|
+
"vis-data": "^8.0.5",
|
|
87
|
+
"vis-timeline": "^8.5.4",
|
|
88
|
+
"vite": "^7.0.4",
|
|
89
|
+
"vitest": "^3.2.4",
|
|
90
|
+
"vue": "^3.5.42",
|
|
91
|
+
"vue-sonner": "^2.0.9",
|
|
92
|
+
"vue-tsc": "^2.2.4",
|
|
93
|
+
"zod": "^3.25.76"
|
|
94
|
+
},
|
|
95
|
+
"engines": {
|
|
96
|
+
"node": ">=22"
|
|
97
|
+
}
|
|
98
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// Розбір тіла помилки API у структуру. Контракт — `docs/api-error-contract.md`.
|
|
2
|
+
//
|
|
3
|
+
// Тут ТІЛЬКИ форма, без жодного слова українською: підписи за кодом дає словник
|
|
4
|
+
// у `shared/errors` (він знає домен і мову), а цей шар лишається придатним для
|
|
5
|
+
// іншого проєкту.
|
|
6
|
+
|
|
7
|
+
export interface ApiProblemEntry {
|
|
8
|
+
/** Машинний код порушення: за ним клієнт бере текст і логіку. */
|
|
9
|
+
code: string
|
|
10
|
+
/** Шлях поля форми. Немає — помилка не про поле. */
|
|
11
|
+
field?: string
|
|
12
|
+
/** Дані саме цієї помилки; форма своя під кожен код. */
|
|
13
|
+
meta?: Record<string, unknown>
|
|
14
|
+
/** Технічний текст для розробника. */
|
|
15
|
+
detail?: string
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface ApiProblem {
|
|
19
|
+
status: number
|
|
20
|
+
/** Категорія: `VALIDATION_FAILED`, `BUSINESS_RULE_VIOLATION`, `FORBIDDEN`… */
|
|
21
|
+
code: string
|
|
22
|
+
title: string
|
|
23
|
+
detail?: string
|
|
24
|
+
/** Порожнім не буває: одне порушення — один запис. */
|
|
25
|
+
errors: ApiProblemEntry[]
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export class ApiProblemHelper {
|
|
29
|
+
/**
|
|
30
|
+
* `null` — тіло не схоже на нашу помилку (проксі, HTML-сторінка, обрив).
|
|
31
|
+
*
|
|
32
|
+
* `httpStatus` — запасний варіант для поля `status`: код у тілі й код
|
|
33
|
+
* відповіді той самий, а от тіло по дорозі могли підрізати. Ознака «наше»
|
|
34
|
+
* лишається одна — `code`.
|
|
35
|
+
*/
|
|
36
|
+
static parse(body: unknown, httpStatus: number): ApiProblem | null {
|
|
37
|
+
if (typeof body !== 'object' || body === null) return null
|
|
38
|
+
|
|
39
|
+
const { status, code, title, detail, errors } = body as Record<string, unknown>
|
|
40
|
+
|
|
41
|
+
if (typeof code !== 'string') return null
|
|
42
|
+
|
|
43
|
+
return {
|
|
44
|
+
status: typeof status === 'number' ? status : httpStatus,
|
|
45
|
+
code,
|
|
46
|
+
title: typeof title === 'string' ? title : code,
|
|
47
|
+
detail: typeof detail === 'string' ? detail : undefined,
|
|
48
|
+
errors: Array.isArray(errors)
|
|
49
|
+
? errors.flatMap(entry => ApiProblemHelper.entry(entry) ?? [])
|
|
50
|
+
: [],
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
private static entry(raw: unknown): ApiProblemEntry | null {
|
|
55
|
+
if (typeof raw !== 'object' || raw === null) return null
|
|
56
|
+
|
|
57
|
+
const { code, field, meta, detail } = raw as Record<string, unknown>
|
|
58
|
+
|
|
59
|
+
if (typeof code !== 'string') return null
|
|
60
|
+
|
|
61
|
+
return {
|
|
62
|
+
code,
|
|
63
|
+
field: typeof field === 'string' ? field : undefined,
|
|
64
|
+
meta: typeof meta === 'object' && meta !== null ? meta as Record<string, unknown> : undefined,
|
|
65
|
+
detail: typeof detail === 'string' ? detail : undefined,
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Записи, що стосуються полів форми: їх роздають самим полям. */
|
|
70
|
+
static fieldEntries(problem: ApiProblem): ApiProblemEntry[] {
|
|
71
|
+
return problem.errors.filter(entry => entry.field !== undefined)
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Перший запис — те, що показуємо, коли порушення одне (найчастіший випадок). */
|
|
75
|
+
static primary(problem: ApiProblem): ApiProblemEntry | null {
|
|
76
|
+
return problem.errors[0] ?? null
|
|
77
|
+
}
|
|
78
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { type ApiProblem } from "./apiProblem";
|
|
2
|
+
|
|
3
|
+
export enum ServerErrors {
|
|
4
|
+
BadRequest = 400,
|
|
5
|
+
Unauthorized = 401,
|
|
6
|
+
Forbidden = 403,
|
|
7
|
+
NotFound = 404,
|
|
8
|
+
Conflict = 409,
|
|
9
|
+
UnprocessableEntity = 422,
|
|
10
|
+
InternalServerError = 500,
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Помилка запиту. Збирає її ОДИН перехоплювач axios (`_shared/api/index.ts`) —
|
|
15
|
+
* методам api ловити нічого. Підпис дає словник за кодом із `problem`.
|
|
16
|
+
*/
|
|
17
|
+
export class AppError extends Error {
|
|
18
|
+
/**
|
|
19
|
+
* Розібране тіло помилки: код, `meta`, помилки полів. `null` — відповідь не
|
|
20
|
+
* наша (проксі, обрив). Підпис користувачу за цим кодом дає словник у
|
|
21
|
+
* `shared/errors` — сюди він не тягнеться: цей шар кроспроєктний і про мову
|
|
22
|
+
* з доменом не знає.
|
|
23
|
+
*/
|
|
24
|
+
problem: ApiProblem | null = null;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Відповіді не дочекались за лімітом (`REQUEST_TIMEOUT_MS`). Статус тоді 0,
|
|
28
|
+
* як і в обриву мережі, але порада інша і повторювати не можна: сервер,
|
|
29
|
+
* найпевніше, ще рахує попередній запит.
|
|
30
|
+
*/
|
|
31
|
+
isTimeout = false;
|
|
32
|
+
|
|
33
|
+
constructor(public status: ServerErrors | number, msg: string) {
|
|
34
|
+
super(msg);
|
|
35
|
+
this.name = this.constructor.name;
|
|
36
|
+
}
|
|
37
|
+
}
|
package/src/api/index.ts
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import axios, {AxiosRequestConfig, AxiosResponse} from 'axios'
|
|
2
|
+
import {AppError} from './errors'
|
|
3
|
+
import {ApiProblemHelper} from './errors/apiProblem'
|
|
4
|
+
|
|
5
|
+
// Sanctum SPA (session cookie auth): шлём куку сессии + XSRF-заголовок.
|
|
6
|
+
// Работает на same-origin (API относительный /api/v1 → тот же хост, что и страница).
|
|
7
|
+
//
|
|
8
|
+
// НЕ переключать это по VITE_API_URL. Прод задаёт переменную своим же
|
|
9
|
+
// абсолютным URL — то есть same-origin, — и автоматика гасила там куку с XSRF,
|
|
10
|
+
// после чего отваливалась сессия. Непустой VITE_API_URL ≠ чужой домен.
|
|
11
|
+
// Один параметр = один рядок query. Булеве шлемо як 1/0, а не "true"/"false":
|
|
12
|
+
// Laravel-правило `boolean` приймає 1/0/"1"/"0"/true/false, але НЕ рядок "true",
|
|
13
|
+
// у який axios серіалізує булеве за замовчуванням (був 422 на without_manager).
|
|
14
|
+
// Масив — як key[]=v (той самий формат, що вже приймає бек для status/fleet_id).
|
|
15
|
+
// null/undefined просто випадають — так фільтр «не заданий» не їде порожнім.
|
|
16
|
+
function serializeScalar(value: unknown): string {
|
|
17
|
+
if (typeof value === 'boolean') return value ? '1' : '0'
|
|
18
|
+
return String(value)
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function serializeParams(params: Record<string, unknown>): string {
|
|
22
|
+
const search = new URLSearchParams()
|
|
23
|
+
|
|
24
|
+
for (const [key, value] of Object.entries(params)) {
|
|
25
|
+
if (value === null || value === undefined) continue
|
|
26
|
+
|
|
27
|
+
if (Array.isArray(value)) {
|
|
28
|
+
for (const item of value) {
|
|
29
|
+
if (item === null || item === undefined) continue
|
|
30
|
+
search.append(`${key}[]`, serializeScalar(item))
|
|
31
|
+
}
|
|
32
|
+
continue
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// Объект — как key[subkey]=v. Порядок ключей сохраняется (и у объекта,
|
|
36
|
+
// и у URLSearchParams), а он бывает значимым: мультисортировка «Звітів»
|
|
37
|
+
// задаёт приоритет именно порядком sort[...]. Без этой ветки объект
|
|
38
|
+
// молча уезжал строкой "[object Object]".
|
|
39
|
+
if (typeof value === 'object') {
|
|
40
|
+
for (const [subKey, subValue] of Object.entries(value)) {
|
|
41
|
+
if (subValue === null || subValue === undefined) continue
|
|
42
|
+
search.append(`${key}[${subKey}]`, serializeScalar(subValue))
|
|
43
|
+
}
|
|
44
|
+
continue
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
search.append(key, serializeScalar(value))
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
return search.toString()
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Ліміт звичайного запиту. Без нього завислий сервер тримав таблицю в
|
|
55
|
+
* завантаженні вічно; так людина отримує помилку з «Повторити».
|
|
56
|
+
*/
|
|
57
|
+
export const REQUEST_TIMEOUT_MS = 60_000
|
|
58
|
+
|
|
59
|
+
/** Вивантаження файлів і завантаження чеків: вони законно йдуть довше. */
|
|
60
|
+
export const LONG_REQUEST_TIMEOUT_MS = 5 * 60_000
|
|
61
|
+
|
|
62
|
+
const axiosInstance = axios.create({
|
|
63
|
+
withCredentials: true,
|
|
64
|
+
withXSRFToken: true,
|
|
65
|
+
paramsSerializer: serializeParams,
|
|
66
|
+
timeout: REQUEST_TIMEOUT_MS,
|
|
67
|
+
// Таймаут — окремим кодом ETIMEDOUT, а не спільним з обривом ECONNABORTED.
|
|
68
|
+
transitional: { clarifyTimeoutError: true },
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
// Единственное место, где ошибка транспорта превращается в AppError.
|
|
72
|
+
//
|
|
73
|
+
// Тело разбирается тут, текст по коду даёт словарь (`shared/errors`) — методам api
|
|
74
|
+
// ловить нечего, и текст под статус не пишется в каждом методе заново.
|
|
75
|
+
//
|
|
76
|
+
// Перехватчик СОБИРАЕТ ошибку, но НЕ показывает её. Показ — дело UI-слоя
|
|
77
|
+
// (`useHandleError`), и причина не в чистоте слоёв: 5xx он тостил сам, а поверх
|
|
78
|
+
// того же 5xx onError мутации тостил второй раз, и пользователь получал два
|
|
79
|
+
// сообщения об одной ошибке. У запроса с ретраями — по тосту на попытку.
|
|
80
|
+
axiosInstance.interceptors.response.use(
|
|
81
|
+
res => res,
|
|
82
|
+
err => {
|
|
83
|
+
// Отменённый запрос — не ошибка: это мы сами оборвали устаревший запрос
|
|
84
|
+
// при смене фильтра. Пропускаем как есть — обёртки он не заслуживает.
|
|
85
|
+
if (axios.isCancel(err)) return Promise.reject(err)
|
|
86
|
+
|
|
87
|
+
if (!axios.isAxiosError(err)) return Promise.reject(err)
|
|
88
|
+
|
|
89
|
+
// 0 — ответа не было вовсе (сеть, таймаут, CORS). Отдельное значение, а
|
|
90
|
+
// не 500: сервер мог и не получить запрос, и повторить его безопасно.
|
|
91
|
+
const status = err.response?.status ?? 0
|
|
92
|
+
|
|
93
|
+
// message — для лога и devtools; пользовательский текст даёт словарь.
|
|
94
|
+
const error = new AppError(status, err.message)
|
|
95
|
+
error.isTimeout = err.code === 'ETIMEDOUT'
|
|
96
|
+
|
|
97
|
+
return readErrorBody(err.response?.data).then(body => {
|
|
98
|
+
error.problem = ApiProblemHelper.parse(body, status)
|
|
99
|
+
return Promise.reject(error)
|
|
100
|
+
})
|
|
101
|
+
},
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
// Запрос файла (`responseType: 'blob'`) получает Blob-ом и ошибку — тот же JSON
|
|
105
|
+
// контракта. Без чтения код ошибки терялся, и вместо текста по коду был текст
|
|
106
|
+
// по статусу. Не JSON (HTML прокси) — как и раньше: problem = null.
|
|
107
|
+
async function readErrorBody(data: unknown): Promise<unknown> {
|
|
108
|
+
if (!(data instanceof Blob) || !data.type.includes('json')) return data
|
|
109
|
+
try {
|
|
110
|
+
return JSON.parse(await data.text())
|
|
111
|
+
} catch {
|
|
112
|
+
return null
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export default abstract class BaseApi {
|
|
117
|
+
protected abstract readonly baseUrl: string
|
|
118
|
+
|
|
119
|
+
protected joinPath(path1: string, path2?: string) {
|
|
120
|
+
if (!path1) return ''
|
|
121
|
+
if (!path2) return path1
|
|
122
|
+
return `${path1}/${path2}`
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
protected get fullBaseUrl() {
|
|
126
|
+
return this.parentApi
|
|
127
|
+
? this.joinPath(this.parentApi.fullBaseUrl, this.baseUrl)
|
|
128
|
+
: this.baseUrl
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
constructor(private parentApi?: BaseApi) {
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
protected _post<T = any>(
|
|
135
|
+
url: string,
|
|
136
|
+
body: Record<string, any>,
|
|
137
|
+
config: AxiosRequestConfig = {},
|
|
138
|
+
) {
|
|
139
|
+
return axiosInstance.post<T>(this.getMethodUrl(url), body, config)
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
protected _put<T = any>(
|
|
143
|
+
url: string,
|
|
144
|
+
body: Record<string, any>,
|
|
145
|
+
config: AxiosRequestConfig = {},
|
|
146
|
+
) {
|
|
147
|
+
return axiosInstance.put<T>(this.getMethodUrl(url), body, config)
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
protected _patch<T = any>(
|
|
151
|
+
url: string,
|
|
152
|
+
body: Record<string, any>,
|
|
153
|
+
config: AxiosRequestConfig = {},
|
|
154
|
+
) {
|
|
155
|
+
return axiosInstance.patch<T>(this.getMethodUrl(url), body, config)
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
protected _get<T = any>(url: string, config: AxiosRequestConfig = {}) {
|
|
159
|
+
return axiosInstance.get<T, AxiosResponse<T>>(this.getMethodUrl(url), config)
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
protected _delete<T = any>(url: string, config: AxiosRequestConfig = {}) {
|
|
163
|
+
return axiosInstance.delete<T>(this.getMethodUrl(url), config)
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
private getMethodUrl(url: string) {
|
|
167
|
+
return this.joinPath(this.fullBaseUrl, url)
|
|
168
|
+
}
|
|
169
|
+
}
|
package/src/api/types.ts
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
// Успішна відповідь API: тільки `data`. Полів `success`/`message` більше немає,
|
|
2
|
+
// а `status`/`errorCode` тут ніколи й не було — тип описував те, чого бек не
|
|
3
|
+
// присилав, і працював лише тому, що всі виклики читають `res.data.data`.
|
|
4
|
+
// Форма помилки — окремо, `_shared/api/errors/apiProblem.ts`.
|
|
5
|
+
export type BaseResponse<T> = {
|
|
6
|
+
data: T
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/** Напрямок сортування в запиті й у стані таблиці. */
|
|
10
|
+
export type SortDirection = 'asc' | 'desc'
|
|
11
|
+
|
|
12
|
+
export interface PaginatedResponse<T> {
|
|
13
|
+
data: T[];
|
|
14
|
+
links: {
|
|
15
|
+
first: string,
|
|
16
|
+
last: string,
|
|
17
|
+
prev: string | null,
|
|
18
|
+
next: string | null,
|
|
19
|
+
}
|
|
20
|
+
meta?: {
|
|
21
|
+
links: {
|
|
22
|
+
url: string | null,
|
|
23
|
+
page: number | null,
|
|
24
|
+
label: string,
|
|
25
|
+
active: boolean
|
|
26
|
+
}[],
|
|
27
|
+
from: number
|
|
28
|
+
to: number,
|
|
29
|
+
current_page: number
|
|
30
|
+
last_page: number
|
|
31
|
+
path: string,
|
|
32
|
+
per_page: number,
|
|
33
|
+
total: number
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export interface PaginatedResponse2<Data> {
|
|
38
|
+
data: Data[]
|
|
39
|
+
pagination: Pagination
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface Pagination {
|
|
43
|
+
current_page: number
|
|
44
|
+
last_page: number
|
|
45
|
+
per_page: number
|
|
46
|
+
total: number
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Сторінка списку: рядки в `data`, лічильники в `meta`. */
|
|
50
|
+
export interface Paged<Data> {
|
|
51
|
+
data: Data[]
|
|
52
|
+
meta: Pagination
|
|
53
|
+
}
|
package/src/api/utils.ts
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import {AxiosResponse} from "axios";
|
|
2
|
+
import { BaseResponse, PaginatedResponse, PaginatedResponse2 } from './types'
|
|
3
|
+
|
|
4
|
+
export async function fetchAllWithoutPagination<T, R>(
|
|
5
|
+
fetch: (page: number) => Promise<AxiosResponse<PaginatedResponse<T>>>,
|
|
6
|
+
mapper: (item: T) => R
|
|
7
|
+
): Promise<R[]>;
|
|
8
|
+
export async function fetchAllWithoutPagination<T>(
|
|
9
|
+
fetch: (page: number) => Promise<AxiosResponse<PaginatedResponse<T>>>
|
|
10
|
+
): Promise<T[]>;
|
|
11
|
+
export async function fetchAllWithoutPagination<T, R>(
|
|
12
|
+
fetch: (page: number) => Promise<AxiosResponse<PaginatedResponse<T>>>,
|
|
13
|
+
mapper?: (item: T) => R
|
|
14
|
+
): Promise<T[] | R[]> {
|
|
15
|
+
let page = 1;
|
|
16
|
+
let hasMore = true;
|
|
17
|
+
const aggregated: R[] = [];
|
|
18
|
+
|
|
19
|
+
while (hasMore) {
|
|
20
|
+
const response = await fetch(page);
|
|
21
|
+
const { data, links, meta } = response.data;
|
|
22
|
+
|
|
23
|
+
const rawItems = data || [];
|
|
24
|
+
const processedItems = mapper ? rawItems.map(mapper) : (rawItems as unknown as R[]);
|
|
25
|
+
|
|
26
|
+
aggregated.push(...processedItems);
|
|
27
|
+
|
|
28
|
+
// Самый надежный способ проверки пагинации Laravel:
|
|
29
|
+
hasMore = !!(links?.next && meta && meta.current_page < meta.last_page);
|
|
30
|
+
page++;
|
|
31
|
+
}
|
|
32
|
+
return aggregated;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export async function fetchAllWithoutPagination2<T, R>(
|
|
36
|
+
fetch: (page: number) => Promise<BaseResponse<PaginatedResponse2<T>>>,
|
|
37
|
+
mapper: (item: T) => R
|
|
38
|
+
): Promise<R[]>;
|
|
39
|
+
export async function fetchAllWithoutPagination2<T>(
|
|
40
|
+
fetch: (page: number) => Promise<BaseResponse<PaginatedResponse2<T>>>
|
|
41
|
+
): Promise<T[]>;
|
|
42
|
+
export async function fetchAllWithoutPagination2<T, R>(
|
|
43
|
+
fetch: (page: number) => Promise<BaseResponse<PaginatedResponse2<T>>>,
|
|
44
|
+
mapper?: (item: T) => R
|
|
45
|
+
): Promise<T[] | R[]> {
|
|
46
|
+
let page = 1;
|
|
47
|
+
let hasMore = true;
|
|
48
|
+
const aggregated: any[] = []; // Используем any внутри для гибкости реализации
|
|
49
|
+
|
|
50
|
+
while (hasMore) {
|
|
51
|
+
const response = await fetch(page);
|
|
52
|
+
const { data, pagination } = response.data;
|
|
53
|
+
|
|
54
|
+
const rawItems = data || [];
|
|
55
|
+
// Важный момент: помогаем TS понять, что если маппера нет, то это массив T
|
|
56
|
+
const processedItems = mapper
|
|
57
|
+
? rawItems.map(mapper)
|
|
58
|
+
: (rawItems as unknown as R[]);
|
|
59
|
+
|
|
60
|
+
aggregated.push(...processedItems);
|
|
61
|
+
|
|
62
|
+
hasMore = pagination.current_page < pagination.last_page;
|
|
63
|
+
page++;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// Кастуем к итоговому типу, чтобы убрать ошибку про unknown[]
|
|
67
|
+
return aggregated as T[] | R[];
|
|
68
|
+
}
|