@rock555/frontend-core 2.0.2 → 3.0.0

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.
Files changed (66) hide show
  1. package/README.md +95 -95
  2. package/package.json +98 -98
  3. package/src/components/GlobalPendingBar.vue +85 -85
  4. package/src/components/SearchPicker.vue +84 -84
  5. package/src/components/filters/DateRangeField.vue +692 -692
  6. package/src/components/filters/{ExportCsvButton.vue → ExportButton.vue} +62 -60
  7. package/src/components/filters/FiltersBar.vue +150 -150
  8. package/src/components/filters/MonthField.vue +309 -309
  9. package/src/components/filters/SortControl.vue +162 -162
  10. package/src/components/filters/SortControlPanel.vue +242 -242
  11. package/src/components/filters/sortControl.types.ts +25 -25
  12. package/src/components/modals/ConfirmModal.vue +58 -58
  13. package/src/components/modals/ImageViewerModal.vue +200 -200
  14. package/src/components/tables/MultiSortHeader.vue +126 -126
  15. package/src/components/tables/TableBodyRow.vue +62 -62
  16. package/src/components/tables/TableFooterRow.vue +54 -54
  17. package/src/components/tables/TableHeaderRow.vue +75 -75
  18. package/src/components/tables/TableLoadedCount.vue +61 -61
  19. package/src/components/tables/TableLoadedFooter.vue +44 -44
  20. package/src/components/tables/TableSkeletonRows.vue +40 -40
  21. package/src/components/tables/TableVirtualPad.vue +16 -16
  22. package/src/components/tables/cells/BoolBadgeCell.vue +32 -32
  23. package/src/components/tables/multiSortHeader.types.ts +16 -16
  24. package/src/components/ui/FilterCheckbox.vue +1 -1
  25. package/src/components/ui/FilterSelect.vue +2 -0
  26. package/src/components/ui/UiActionTiles.vue +92 -92
  27. package/src/components/ui/UiBackLink.vue +39 -39
  28. package/src/components/ui/UiBadge.vue +60 -60
  29. package/src/components/ui/UiButton.vue +126 -126
  30. package/src/components/ui/UiCard.vue +88 -88
  31. package/src/components/ui/UiCount.vue +35 -35
  32. package/src/components/ui/UiKpiGrid.vue +144 -142
  33. package/src/components/ui/UiPopover.vue +62 -62
  34. package/src/components/ui/UiSearchInput.vue +102 -102
  35. package/src/components/ui/UiSegmented.vue +145 -145
  36. package/src/components/ui/UiTableCard.vue +116 -116
  37. package/src/components/ui/inputs/DateFormInput.vue +2 -2
  38. package/src/components/ui/inputs/FileInput.vue +5 -0
  39. package/src/components/ui/inputs/RadioSegmentFormInput.vue +0 -1
  40. package/src/components/ui/inputs/SelectFormInput.vue +1 -2
  41. package/src/components/ui/inputs/SmartField.vue +15 -13
  42. package/src/components/ui/inputs/TextareaFormInput.vue +2 -2
  43. package/src/components/ui/uiActionTiles.types.ts +10 -10
  44. package/src/components/ui/uiBadge.types.ts +11 -11
  45. package/src/components/ui/uiKpi.types.ts +19 -17
  46. package/src/composables/useAppForm.ts +67 -67
  47. package/src/composables/useConfirm.ts +21 -21
  48. package/src/composables/useFilterState.ts +70 -70
  49. package/src/composables/useServerList.ts +348 -348
  50. package/src/composables/useServerTable.ts +117 -117
  51. package/src/composables/useSharedAsync.ts +51 -51
  52. package/src/composables/useVirtualTable.ts +77 -77
  53. package/src/config.ts +156 -155
  54. package/src/errors/actionCancelled.ts +9 -9
  55. package/src/errors/apiError.helper.ts +161 -161
  56. package/src/errors/useHandleError.ts +33 -33
  57. package/src/helpers/calendarRange.helper.ts +74 -74
  58. package/src/helpers/month.helper.ts +63 -63
  59. package/src/helpers/periodLabel.helper.ts +70 -70
  60. package/src/helpers/periodPresets.helper.ts +76 -76
  61. package/src/helpers/sort.helper.ts +57 -57
  62. package/src/helpers/tableFields.helper.ts +205 -205
  63. package/src/helpers/urlParams.helper.ts +99 -99
  64. package/src/helpers/urlSchema.helper.ts +296 -296
  65. package/src/plugins/modals.plugin.ts +253 -253
  66. package/src/plugins/table.plugin.ts +173 -173
@@ -1,348 +1,348 @@
1
- // Стор серверного списку з однієї схеми адреси: фільтри, сеттери, синк з
2
- // адресою, запит порціями при прокрутці й помилки.
3
- //
4
- // Чому так: дванадцять сторів списків були однією схемою, переписаною руками.
5
- // Кожен фільтр стояв у сторі тричі — ref, рядок у syncUrl і сеттер у
6
- // неймспейсі `filters`, — і забутий рядок у syncUrl тихо губив фільтр після
7
- // перезавантаження, а типи цього не ловили. Тут поля, ref'и й сеттери
8
- // виводяться зі схеми адреси (UrlSchemaHelper), тож розійтися нічому.
9
- //
10
- // Що лишається фічі — те, що справді її: як стан лягає в параметри запиту
11
- // (`params`) і яку фабрику запиту кликати (`query`, з `api/<feature>/*.queries.ts`).
12
- //
13
- // Імена — ті самі, що вже читають компоненти:
14
- // • поле `types` → `filters.types` + `filters.setTypes`;
15
- // • булеве `isLeasing` → `filters.isLeasing` + `filters.setLeasing`;
16
- // • текст із дебаунсом (`debounced`) → `filters.searchDraft` (пише UI) +
17
- // `filters.setSearch`, а в запит іде відставлений `filters.search`;
18
- // • пара `sortBy` / `sortDirection` → `filters.setSort(by, dir)` (useServerTable);
19
- // • пара `managerIds` / `isWithoutManager` взаємовиключна (useManagerFilter).
20
-
21
- import {
22
- useInfiniteQuery,
23
- type DataTag,
24
- type InfiniteData,
25
- type QueryKey,
26
- type UseInfiniteQueryOptions,
27
- } from '@tanstack/vue-query'
28
- import { computed, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
29
- import { useDebouncedFilter, useManagerFilter, useSortState } from './useFilterState'
30
- import { useHandleError } from '../errors/useHandleError'
31
- import type { SortDirection } from './useServerTable'
32
-
33
- /** Поля схеми, якими керує сам список, а не фільтри. */
34
- type Reserved = 'page'
35
-
36
- type StripIs<K extends string> = K extends `is${infer Rest}` ? Rest : K
37
- type SetterName<K extends string> = `set${Capitalize<StripIs<K>>}`
38
-
39
- type FilterKeys<TState> = Exclude<keyof TState & string, Reserved>
40
-
41
- /** Поле з `defaults` після читання адреси вже не порожнє — і тип це знає. */
42
- type WithDefaults<TState, TDefaults extends keyof TState> = {
43
- [K in keyof TState]: K extends TDefaults ? NonNullable<TState[K]> : TState[K]
44
- }
45
-
46
- /** Рядок списку з відповіді виду `{ data: Row[] }`. */
47
- type RowOf<TResponse> = TResponse extends { data: ReadonlyArray<infer TRow> } ? TRow : unknown
48
- type TextKeys<TState> = { [K in FilterKeys<TState>]: TState[K] extends string ? K : never }[FilterKeys<TState>]
49
-
50
- /** Те, що потрібно кнопці «Скинути фільтри» (FiltersBar, порожня таблиця). */
51
- export interface ResettableFilters {
52
- /** Хоч один фільтр відрізняється від чистої адреси. */
53
- isFiltered: boolean
54
- reset(): void
55
- }
56
-
57
- /** Неймспейс `store.filters`: значення, чернетки текстових полів і сеттери. */
58
- export type ListFilters<TState, TDebounced extends TextKeys<TState>> =
59
- & { isFiltered: Ref<boolean>; reset(): void }
60
- & { [K in FilterKeys<TState>]: Ref<TState[K]> }
61
- & { [K in TDebounced as `${K}Draft`]: Ref<string> }
62
- & { [K in FilterKeys<TState> as SetterName<K>]: (next: TState[K]) => void }
63
- & (TState extends { sortBy: infer TSortBy; sortDirection: SortDirection | null }
64
- ? { setSort(by: TSortBy, dir?: SortDirection | null): void }
65
- : unknown)
66
-
67
- /** Фільтри ↔ адреса списку. */
68
- export interface ListStateConfig<
69
- TState,
70
- TParams,
71
- TDebounced extends TextKeys<TState>,
72
- TDefaults extends FilterKeys<TState>,
73
- > {
74
- /** Схема адреси фічі (`UrlSchemaHelper.create`): з неї — поля, ref'и й сеттери. */
75
- url: { read: () => TState; write: (state: TState) => void; blank: () => TState }
76
- /** Поля стану, що не фільтри (вкладка, вид подання): «Скинути фільтри» їх лишає. */
77
- keep?: readonly FilterKeys<TState>[]
78
- /** Значення поля, коли в адресі його немає (період за замовчуванням тощо). */
79
- defaults?: { [K in TDefaults]: () => NonNullable<TState[K]> }
80
- /** Текстові поля з дебаунсом: UI пише чернетку, у запит іде відставлене. */
81
- debounced?: readonly TDebounced[]
82
- /** Як стан лягає в параметри запиту — імена й формат бека. */
83
- params: (state: Omit<WithDefaults<TState, TDefaults>, Reserved>) => TParams
84
- /** Правка стану, прочитаного з адреси: недопустиме значення замінюємо, а не шлемо на бек. */
85
- fromUrl?: (state: TState) => TState
86
- /** Правка стану перед записом в адресу: поле, що зараз нічого не значить, не тримаємо. */
87
- toUrl?: (state: TState) => TState
88
- }
89
-
90
- /** Опції нескінченної фабрики (`infiniteQueryOptions`): порції — сторінки бека. */
91
- /** Решту (initialPageParam, getNextPageParam) задає фабрика — тут лише тип відповіді в ключі. */
92
- type InfiniteListQueryOptions<TResponse> = { queryKey: DataTag<QueryKey, InfiniteData<TResponse, unknown>, unknown> }
93
-
94
- /** Як дістати рядки з порції — без адреси й фільтрів. */
95
- export interface InfiniteRowsConfig<TParams, TResponse, TRow> {
96
- /** Нескінченна фабрика з `api/<feature>/*.queries.ts` (`DriversQueries.list`). */
97
- query: (params: TParams) => InfiniteListQueryOptions<TResponse>
98
- enabled?: MaybeRefOrGetter<boolean>
99
- /** Рядки порції; за замовчуванням `response.data`. */
100
- rows?: (response: TResponse) => readonly TRow[] | undefined
101
- /** Ключ рядка для зведення порцій; за замовчуванням `row.id`, без нього — обовʼязковий. */
102
- rowId?: (row: TRow) => string
103
- /** Скільки всього за фільтром; за замовчуванням `response.meta.total` або `response.total`. */
104
- total?: (response: TResponse) => number
105
- }
106
-
107
- export interface ServerInfiniteListConfig<
108
- TState,
109
- TParams,
110
- TResponse,
111
- TRow,
112
- TDebounced extends TextKeys<TState>,
113
- TDefaults extends FilterKeys<TState>,
114
- > extends ListStateConfig<TState, TParams, TDebounced, TDefaults>, InfiniteRowsConfig<TParams, TResponse, TRow> {}
115
-
116
- /**
117
- * Список з підвантаженням порцій при прокрутці — для віртуалізованих таблиць.
118
- * Фільтри й адреса ті самі, що в `useServerList`, тільки сторінки в адресі немає:
119
- * нова вибірка завжди починається з першої порції.
120
- */
121
- export function useServerInfiniteList<
122
- TState extends Record<string, unknown> & { page: number },
123
- TParams extends object,
124
- TResponse,
125
- TRow = RowOf<TResponse>,
126
- TDebounced extends TextKeys<TState> = never,
127
- TDefaults extends FilterKeys<TState> = never,
128
- >(config: ServerInfiniteListConfig<TState, TParams, TResponse, TRow, TDebounced, TDefaults>) {
129
- const { filters, state, params } = useListState(config)
130
-
131
- // Сторінки в адресі немає: посилання завжди відкриває список з початку.
132
- function syncUrl(): void {
133
- const next = { ...state.value, page: 1 } as unknown as TState
134
- config.url.write(config.toUrl ? config.toUrl(next) : next)
135
- }
136
-
137
- watch(state, syncUrl, { deep: true })
138
-
139
- const { data, query } = useInfiniteRows(config, params)
140
-
141
- return { filters, data, syncUrl, state, params, query }
142
- }
143
-
144
- /**
145
- * Порції без адреси: для списку, що живе не на своїй сторінці (вкладки картки
146
- * водія), і як ядро `useServerInfiniteList`.
147
- *
148
- * Між порціями хтось міг додати чи прибрати рядок, і зсув сторінок повторив би
149
- * рядок — тому зводимо порції за id.
150
- */
151
- export function useInfiniteRows<TParams, TResponse, TRow = RowOf<TResponse>>(
152
- config: InfiniteRowsConfig<TParams, TResponse, TRow>,
153
- params: Readonly<Ref<TParams>>,
154
- ) {
155
- const { handleError } = useHandleError()
156
-
157
- // Стор Pinia живе довше за сторінку: без цього запит лишався б «активним» і в
158
- // картці водія, і кожна зміна там перезапитувала б усі прогорнуті порції у фоні.
159
- // Вимкнений — неактивний: інвалідація лише позначає його й обрізає до першої порції.
160
- const isShown = ref(false)
161
-
162
- const query = useInfiniteQuery(() => ({
163
- ...config.query(params.value),
164
- enabled: isShown.value && toValue(config.enabled) !== false,
165
- }) as unknown as UseInfiniteQueryOptions<TResponse, Error, InfiniteData<TResponse, unknown>, QueryKey, unknown>)
166
-
167
- watch(query.error, (error) => { if (error) handleError(error) })
168
-
169
- const rowsOf = (response: TResponse): readonly TRow[] =>
170
- (config.rows ? config.rows(response) : (response as { data?: readonly TRow[] }).data) ?? []
171
-
172
- // «Без id — rowId обовʼязковий» умовним типом не виразити: TS тоді губить вивід
173
- // відповіді з лямбди-фабрики. Тож перевірка тут, і гучна: тихо злиті в один
174
- // рядок порції виглядали б як «дані зникли».
175
- const idOf = (row: TRow): string => {
176
- const id = config.rowId ? config.rowId(row) : (row as { id?: unknown }).id
177
- if (typeof id !== 'string') throw new Error('useInfiniteRows: row has no id, pass rowId')
178
- return id
179
- }
180
-
181
- const rows = computed<TRow[]>(() => {
182
- const seen = new Set<string>()
183
-
184
- return (query.data.value?.pages ?? []).flatMap(rowsOf).filter((row) => {
185
- const id = idOf(row)
186
- if (seen.has(id)) return false
187
- seen.add(id)
188
- return true
189
- })
190
- })
191
-
192
- const first = computed(() => query.data.value?.pages[0])
193
-
194
- const data = {
195
- rows,
196
- /** Скільки всього за фільтром; null — перша порція ще не приїхала. */
197
- total: computed<number | null>(() => {
198
- const response = first.value
199
- if (response === undefined) return null
200
- if (config.total) return config.total(response)
201
-
202
- // `meta.total` — сторінка `Paged`; `total` у корені — списки, що розгортають її в API-шарі.
203
- const page = response as { meta?: { total: number }; total?: number }
204
-
205
- return page.meta?.total ?? page.total ?? 0
206
- }),
207
- isLoading: query.isFetching,
208
- isLoadingMore: query.isFetchingNextPage,
209
- hasMore: query.hasNextPage,
210
- isError: query.isError,
211
- /** Наступна порція, якщо є і жоден запит зараз не йде (посеред іншого її проігнорують). */
212
- loadMore: (): void => {
213
- if (query.hasNextPage.value && !query.isFetching.value) void query.fetchNextPage()
214
- },
215
- /** Таблиця на екрані чи ні: кличе її onMounted / onUnmounted. */
216
- setShown: (next: boolean): void => { isShown.value = next },
217
- /** «Повторити» в картці таблиці після помилки. */
218
- refetch: (): void => { void query.refetch() },
219
- }
220
-
221
- return { data, query }
222
- }
223
-
224
- /**
225
- * Фільтри зі схеми адреси: ref'и, чернетки, сеттери, «Скинути фільтри» і знімок
226
- * стану з параметрами запиту.
227
- */
228
- function useListState<
229
- TState extends Record<string, unknown> & { page: number },
230
- TParams extends object,
231
- TDebounced extends TextKeys<TState>,
232
- TDefaults extends FilterKeys<TState>,
233
- >(config: ListStateConfig<TState, TParams, TDebounced, TDefaults>) {
234
- const initial = config.fromUrl ? config.fromUrl(config.url.read()) : config.url.read()
235
- const debounced = new Set<string>(config.debounced ?? [])
236
-
237
- // === стан фільтрів зі схеми =============================================
238
- const values: Record<string, Ref<unknown>> = {}
239
- const drafts: Record<string, Ref<string>> = {}
240
- const setters: Record<string, (next: never) => void> = {}
241
-
242
- const fields = Object.keys(initial).filter(key => key !== 'page' && key !== 'sortBy' && key !== 'sortDirection')
243
- const hasManagers = 'managerIds' in initial && 'isWithoutManager' in initial
244
-
245
- for (const field of fields) {
246
- if (hasManagers && (field === 'managerIds' || field === 'isWithoutManager')) continue
247
-
248
- const fallback = (config.defaults as Record<string, (() => unknown) | undefined> | undefined)?.[field]
249
- const start = initial[field] ?? fallback?.() ?? initial[field]
250
- const setterName = `set${capitalize(stripIs(field))}`
251
-
252
- if (debounced.has(field)) {
253
- const { committed, draft } = useDebouncedFilter(String(start ?? ''))
254
- values[field] = committed
255
- drafts[`${field}Draft`] = draft
256
- setters[setterName] = (next: never) => { draft.value = next }
257
-
258
- continue
259
- }
260
-
261
- const value = ref(start)
262
- values[field] = value
263
- setters[setterName] = (next: never) => { value.value = next }
264
- }
265
-
266
- if (hasManagers) {
267
- const managers = useManagerFilter(initial.managerIds as string[], initial.isWithoutManager as boolean)
268
- values.managerIds = managers.managerIds
269
- values.isWithoutManager = managers.isWithoutManager
270
- setters.setManagerIds = managers.setManagerIds as (next: never) => void
271
- setters.setWithoutManager = managers.setWithoutManager as (next: never) => void
272
- }
273
-
274
- if ('sortBy' in initial && 'sortDirection' in initial) {
275
- const sort = useSortState(initial.sortBy as string | null, initial.sortDirection as SortDirection | null)
276
- values.sortBy = sort.sortBy
277
- values.sortDirection = sort.sortDirection
278
- setters.setSort = sort.setSort as (next: never) => void
279
- }
280
-
281
- // === «Скинути фільтри» ===================================================
282
- // Чистий стан — те, що дало б перше відкриття без параметрів: схема з
283
- // порожньої адреси, правка fromUrl і дефолти. Скидаємо на місці, без
284
- // перезавантаження: сортування й вкладка (`keep`) лишаються, де були.
285
- const blank = config.fromUrl ? config.fromUrl(config.url.blank()) : config.url.blank()
286
- const kept = new Set<string>([...SORT_FIELDS, ...(config.keep ?? [])])
287
- const resettable = Object.keys(values).filter(field => !kept.has(field))
288
- const clean: Record<string, unknown> = {}
289
- for (const field of resettable) {
290
- const fallback = (config.defaults as Record<string, (() => unknown) | undefined> | undefined)?.[field]
291
- clean[field] = blank[field] ?? fallback?.() ?? blank[field]
292
- }
293
-
294
- // Через toUrl: поле, яке зараз нічого не значить (період у черзі звірки), не
295
- // має вмикати кнопку, якої не видно за що натискати.
296
- const isFiltered = computed(() => {
297
- const shown = (next: Record<string, unknown>) =>
298
- (config.toUrl ? config.toUrl({ ...next, page: 1 } as unknown as TState) : next) as Record<string, unknown>
299
- const now = shown(state.value)
300
- const base = shown({ ...state.value, ...clean })
301
-
302
- return resettable.some(field => comparable(now[field]) !== comparable(base[field]))
303
- })
304
-
305
- function reset(): void {
306
- for (const field of resettable) {
307
- const next = structuredClone(clean[field])
308
- // Чернетку теж: інакше дебаунс за пів секунди повернув би старий пошук.
309
- const draft = drafts[`${field}Draft`]
310
- if (draft) draft.value = next as string
311
- values[field].value = next
312
- }
313
- }
314
-
315
- /** Знімок відставлених значень — те, що йде в запит і в адресу. */
316
- const state = computed(() => {
317
- const snapshot: Record<string, unknown> = {}
318
- for (const [field, value] of Object.entries(values)) snapshot[field] = value.value
319
- return snapshot as Omit<WithDefaults<TState, TDefaults>, Reserved>
320
- })
321
-
322
- const params = computed(() => config.params(state.value))
323
-
324
- const filters = { ...values, ...drafts, ...setters, isFiltered, reset } as unknown as ListFilters<WithDefaults<TState, TDefaults>, TDebounced>
325
-
326
- return { initial, filters, state, params }
327
- }
328
-
329
- /** Сортування — не фільтр: скидання його не чіпає. */
330
- const SORT_FIELDS = ['sortBy', 'sortDirection', 'sort'] as const
331
-
332
- /** Рядок для порівняння зі станом: порядок вибраних опцій і ключів не важить. */
333
- function comparable(value: unknown): string {
334
- if (Array.isArray(value)) return JSON.stringify(value.map(item => comparable(item)).sort())
335
- if (value !== null && typeof value === 'object') {
336
- return JSON.stringify(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
337
- }
338
-
339
- return JSON.stringify(value ?? null)
340
- }
341
-
342
- function stripIs(field: string): string {
343
- return /^is[A-Z]/.test(field) ? field.slice(2) : field
344
- }
345
-
346
- function capitalize(value: string): string {
347
- return value.charAt(0).toUpperCase() + value.slice(1)
348
- }
1
+ // Стор серверного списку з однієї схеми адреси: фільтри, сеттери, синк з
2
+ // адресою, запит порціями при прокрутці й помилки.
3
+ //
4
+ // Чому так: дванадцять сторів списків були однією схемою, переписаною руками.
5
+ // Кожен фільтр стояв у сторі тричі — ref, рядок у syncUrl і сеттер у
6
+ // неймспейсі `filters`, — і забутий рядок у syncUrl тихо губив фільтр після
7
+ // перезавантаження, а типи цього не ловили. Тут поля, ref'и й сеттери
8
+ // виводяться зі схеми адреси (UrlSchemaHelper), тож розійтися нічому.
9
+ //
10
+ // Що лишається фічі — те, що справді її: як стан лягає в параметри запиту
11
+ // (`params`) і яку фабрику запиту кликати (`query`, з `api/<feature>/*.queries.ts`).
12
+ //
13
+ // Імена — ті самі, що вже читають компоненти:
14
+ // • поле `types` → `filters.types` + `filters.setTypes`;
15
+ // • булеве `isLeasing` → `filters.isLeasing` + `filters.setLeasing`;
16
+ // • текст із дебаунсом (`debounced`) → `filters.searchDraft` (пише UI) +
17
+ // `filters.setSearch`, а в запит іде відставлений `filters.search`;
18
+ // • пара `sortBy` / `sortDirection` → `filters.setSort(by, dir)` (useServerTable);
19
+ // • пара `managerIds` / `isWithoutManager` взаємовиключна (useManagerFilter).
20
+
21
+ import {
22
+ useInfiniteQuery,
23
+ type DataTag,
24
+ type InfiniteData,
25
+ type QueryKey,
26
+ type UseInfiniteQueryOptions,
27
+ } from '@tanstack/vue-query'
28
+ import { computed, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
29
+ import { useDebouncedFilter, useManagerFilter, useSortState } from './useFilterState'
30
+ import { useHandleError } from '../errors/useHandleError'
31
+ import type { SortDirection } from './useServerTable'
32
+
33
+ /** Поля схеми, якими керує сам список, а не фільтри. */
34
+ type Reserved = 'page'
35
+
36
+ type StripIs<K extends string> = K extends `is${infer Rest}` ? Rest : K
37
+ type SetterName<K extends string> = `set${Capitalize<StripIs<K>>}`
38
+
39
+ type FilterKeys<TState> = Exclude<keyof TState & string, Reserved>
40
+
41
+ /** Поле з `defaults` після читання адреси вже не порожнє — і тип це знає. */
42
+ type WithDefaults<TState, TDefaults extends keyof TState> = {
43
+ [K in keyof TState]: K extends TDefaults ? NonNullable<TState[K]> : TState[K]
44
+ }
45
+
46
+ /** Рядок списку з відповіді виду `{ data: Row[] }`. */
47
+ type RowOf<TResponse> = TResponse extends { data: ReadonlyArray<infer TRow> } ? TRow : unknown
48
+ type TextKeys<TState> = { [K in FilterKeys<TState>]: TState[K] extends string ? K : never }[FilterKeys<TState>]
49
+
50
+ /** Те, що потрібно кнопці «Скинути фільтри» (FiltersBar, порожня таблиця). */
51
+ export interface ResettableFilters {
52
+ /** Хоч один фільтр відрізняється від чистої адреси. */
53
+ isFiltered: boolean
54
+ reset(): void
55
+ }
56
+
57
+ /** Неймспейс `store.filters`: значення, чернетки текстових полів і сеттери. */
58
+ export type ListFilters<TState, TDebounced extends TextKeys<TState>> =
59
+ & { isFiltered: Ref<boolean>; reset(): void }
60
+ & { [K in FilterKeys<TState>]: Ref<TState[K]> }
61
+ & { [K in TDebounced as `${K}Draft`]: Ref<string> }
62
+ & { [K in FilterKeys<TState> as SetterName<K>]: (next: TState[K]) => void }
63
+ & (TState extends { sortBy: infer TSortBy; sortDirection: SortDirection | null }
64
+ ? { setSort(by: TSortBy, dir?: SortDirection | null): void }
65
+ : unknown)
66
+
67
+ /** Фільтри ↔ адреса списку. */
68
+ export interface ListStateConfig<
69
+ TState,
70
+ TParams,
71
+ TDebounced extends TextKeys<TState>,
72
+ TDefaults extends FilterKeys<TState>,
73
+ > {
74
+ /** Схема адреси фічі (`UrlSchemaHelper.create`): з неї — поля, ref'и й сеттери. */
75
+ url: { read: () => TState; write: (state: TState) => void; blank: () => TState }
76
+ /** Поля стану, що не фільтри (вкладка, вид подання): «Скинути фільтри» їх лишає. */
77
+ keep?: readonly FilterKeys<TState>[]
78
+ /** Значення поля, коли в адресі його немає (період за замовчуванням тощо). */
79
+ defaults?: { [K in TDefaults]: () => NonNullable<TState[K]> }
80
+ /** Текстові поля з дебаунсом: UI пише чернетку, у запит іде відставлене. */
81
+ debounced?: readonly TDebounced[]
82
+ /** Як стан лягає в параметри запиту — імена й формат бека. */
83
+ params: (state: Omit<WithDefaults<TState, TDefaults>, Reserved>) => TParams
84
+ /** Правка стану, прочитаного з адреси: недопустиме значення замінюємо, а не шлемо на бек. */
85
+ fromUrl?: (state: TState) => TState
86
+ /** Правка стану перед записом в адресу: поле, що зараз нічого не значить, не тримаємо. */
87
+ toUrl?: (state: TState) => TState
88
+ }
89
+
90
+ /** Опції нескінченної фабрики (`infiniteQueryOptions`): порції — сторінки бека. */
91
+ /** Решту (initialPageParam, getNextPageParam) задає фабрика — тут лише тип відповіді в ключі. */
92
+ type InfiniteListQueryOptions<TResponse> = { queryKey: DataTag<QueryKey, InfiniteData<TResponse, unknown>, unknown> }
93
+
94
+ /** Як дістати рядки з порції — без адреси й фільтрів. */
95
+ export interface InfiniteRowsConfig<TParams, TResponse, TRow> {
96
+ /** Нескінченна фабрика з `api/<feature>/*.queries.ts` (`DriversQueries.list`). */
97
+ query: (params: TParams) => InfiniteListQueryOptions<TResponse>
98
+ enabled?: MaybeRefOrGetter<boolean>
99
+ /** Рядки порції; за замовчуванням `response.data`. */
100
+ rows?: (response: TResponse) => readonly TRow[] | undefined
101
+ /** Ключ рядка для зведення порцій; за замовчуванням `row.id`, без нього — обовʼязковий. */
102
+ rowId?: (row: TRow) => string
103
+ /** Скільки всього за фільтром; за замовчуванням `response.meta.total` або `response.total`. */
104
+ total?: (response: TResponse) => number
105
+ }
106
+
107
+ export interface ServerInfiniteListConfig<
108
+ TState,
109
+ TParams,
110
+ TResponse,
111
+ TRow,
112
+ TDebounced extends TextKeys<TState>,
113
+ TDefaults extends FilterKeys<TState>,
114
+ > extends ListStateConfig<TState, TParams, TDebounced, TDefaults>, InfiniteRowsConfig<TParams, TResponse, TRow> {}
115
+
116
+ /**
117
+ * Список з підвантаженням порцій при прокрутці — для віртуалізованих таблиць.
118
+ * Фільтри й адреса ті самі, що в `useServerList`, тільки сторінки в адресі немає:
119
+ * нова вибірка завжди починається з першої порції.
120
+ */
121
+ export function useServerInfiniteList<
122
+ TState extends Record<string, unknown> & { page: number },
123
+ TParams extends object,
124
+ TResponse,
125
+ TRow = RowOf<TResponse>,
126
+ TDebounced extends TextKeys<TState> = never,
127
+ TDefaults extends FilterKeys<TState> = never,
128
+ >(config: ServerInfiniteListConfig<TState, TParams, TResponse, TRow, TDebounced, TDefaults>) {
129
+ const { filters, state, params } = useListState(config)
130
+
131
+ // Сторінки в адресі немає: посилання завжди відкриває список з початку.
132
+ function syncUrl(): void {
133
+ const next = { ...state.value, page: 1 } as unknown as TState
134
+ config.url.write(config.toUrl ? config.toUrl(next) : next)
135
+ }
136
+
137
+ watch(state, syncUrl, { deep: true })
138
+
139
+ const { data, query } = useInfiniteRows(config, params)
140
+
141
+ return { filters, data, syncUrl, state, params, query }
142
+ }
143
+
144
+ /**
145
+ * Порції без адреси: для списку, що живе не на своїй сторінці (вкладки картки
146
+ * водія), і як ядро `useServerInfiniteList`.
147
+ *
148
+ * Між порціями хтось міг додати чи прибрати рядок, і зсув сторінок повторив би
149
+ * рядок — тому зводимо порції за id.
150
+ */
151
+ export function useInfiniteRows<TParams, TResponse, TRow = RowOf<TResponse>>(
152
+ config: InfiniteRowsConfig<TParams, TResponse, TRow>,
153
+ params: Readonly<Ref<TParams>>,
154
+ ) {
155
+ const { handleError } = useHandleError()
156
+
157
+ // Стор Pinia живе довше за сторінку: без цього запит лишався б «активним» і в
158
+ // картці водія, і кожна зміна там перезапитувала б усі прогорнуті порції у фоні.
159
+ // Вимкнений — неактивний: інвалідація лише позначає його й обрізає до першої порції.
160
+ const isShown = ref(false)
161
+
162
+ const query = useInfiniteQuery(() => ({
163
+ ...config.query(params.value),
164
+ enabled: isShown.value && toValue(config.enabled) !== false,
165
+ }) as unknown as UseInfiniteQueryOptions<TResponse, Error, InfiniteData<TResponse, unknown>, QueryKey, unknown>)
166
+
167
+ watch(query.error, (error) => { if (error) handleError(error) })
168
+
169
+ const rowsOf = (response: TResponse): readonly TRow[] =>
170
+ (config.rows ? config.rows(response) : (response as { data?: readonly TRow[] }).data) ?? []
171
+
172
+ // «Без id — rowId обовʼязковий» умовним типом не виразити: TS тоді губить вивід
173
+ // відповіді з лямбди-фабрики. Тож перевірка тут, і гучна: тихо злиті в один
174
+ // рядок порції виглядали б як «дані зникли».
175
+ const idOf = (row: TRow): string => {
176
+ const id = config.rowId ? config.rowId(row) : (row as { id?: unknown }).id
177
+ if (typeof id !== 'string') throw new Error('useInfiniteRows: row has no id, pass rowId')
178
+ return id
179
+ }
180
+
181
+ const rows = computed<TRow[]>(() => {
182
+ const seen = new Set<string>()
183
+
184
+ return (query.data.value?.pages ?? []).flatMap(rowsOf).filter((row) => {
185
+ const id = idOf(row)
186
+ if (seen.has(id)) return false
187
+ seen.add(id)
188
+ return true
189
+ })
190
+ })
191
+
192
+ const first = computed(() => query.data.value?.pages[0])
193
+
194
+ const data = {
195
+ rows,
196
+ /** Скільки всього за фільтром; null — перша порція ще не приїхала. */
197
+ total: computed<number | null>(() => {
198
+ const response = first.value
199
+ if (response === undefined) return null
200
+ if (config.total) return config.total(response)
201
+
202
+ // `meta.total` — сторінка `Paged`; `total` у корені — списки, що розгортають її в API-шарі.
203
+ const page = response as { meta?: { total: number }; total?: number }
204
+
205
+ return page.meta?.total ?? page.total ?? 0
206
+ }),
207
+ isLoading: query.isFetching,
208
+ isLoadingMore: query.isFetchingNextPage,
209
+ hasMore: query.hasNextPage,
210
+ isError: query.isError,
211
+ /** Наступна порція, якщо є і жоден запит зараз не йде (посеред іншого її проігнорують). */
212
+ loadMore: (): void => {
213
+ if (query.hasNextPage.value && !query.isFetching.value) void query.fetchNextPage()
214
+ },
215
+ /** Таблиця на екрані чи ні: кличе її onMounted / onUnmounted. */
216
+ setShown: (next: boolean): void => { isShown.value = next },
217
+ /** «Повторити» в картці таблиці після помилки. */
218
+ refetch: (): void => { void query.refetch() },
219
+ }
220
+
221
+ return { data, query }
222
+ }
223
+
224
+ /**
225
+ * Фільтри зі схеми адреси: ref'и, чернетки, сеттери, «Скинути фільтри» і знімок
226
+ * стану з параметрами запиту.
227
+ */
228
+ function useListState<
229
+ TState extends Record<string, unknown> & { page: number },
230
+ TParams extends object,
231
+ TDebounced extends TextKeys<TState>,
232
+ TDefaults extends FilterKeys<TState>,
233
+ >(config: ListStateConfig<TState, TParams, TDebounced, TDefaults>) {
234
+ const initial = config.fromUrl ? config.fromUrl(config.url.read()) : config.url.read()
235
+ const debounced = new Set<string>(config.debounced ?? [])
236
+
237
+ // === стан фільтрів зі схеми =============================================
238
+ const values: Record<string, Ref<unknown>> = {}
239
+ const drafts: Record<string, Ref<string>> = {}
240
+ const setters: Record<string, (next: never) => void> = {}
241
+
242
+ const fields = Object.keys(initial).filter(key => key !== 'page' && key !== 'sortBy' && key !== 'sortDirection')
243
+ const hasManagers = 'managerIds' in initial && 'isWithoutManager' in initial
244
+
245
+ for (const field of fields) {
246
+ if (hasManagers && (field === 'managerIds' || field === 'isWithoutManager')) continue
247
+
248
+ const fallback = (config.defaults as Record<string, (() => unknown) | undefined> | undefined)?.[field]
249
+ const start = initial[field] ?? fallback?.() ?? initial[field]
250
+ const setterName = `set${capitalize(stripIs(field))}`
251
+
252
+ if (debounced.has(field)) {
253
+ const { committed, draft } = useDebouncedFilter(String(start ?? ''))
254
+ values[field] = committed
255
+ drafts[`${field}Draft`] = draft
256
+ setters[setterName] = (next: never) => { draft.value = next }
257
+
258
+ continue
259
+ }
260
+
261
+ const value = ref(start)
262
+ values[field] = value
263
+ setters[setterName] = (next: never) => { value.value = next }
264
+ }
265
+
266
+ if (hasManagers) {
267
+ const managers = useManagerFilter(initial.managerIds as string[], initial.isWithoutManager as boolean)
268
+ values.managerIds = managers.managerIds
269
+ values.isWithoutManager = managers.isWithoutManager
270
+ setters.setManagerIds = managers.setManagerIds as (next: never) => void
271
+ setters.setWithoutManager = managers.setWithoutManager as (next: never) => void
272
+ }
273
+
274
+ if ('sortBy' in initial && 'sortDirection' in initial) {
275
+ const sort = useSortState(initial.sortBy as string | null, initial.sortDirection as SortDirection | null)
276
+ values.sortBy = sort.sortBy
277
+ values.sortDirection = sort.sortDirection
278
+ setters.setSort = sort.setSort as (next: never) => void
279
+ }
280
+
281
+ // === «Скинути фільтри» ===================================================
282
+ // Чистий стан — те, що дало б перше відкриття без параметрів: схема з
283
+ // порожньої адреси, правка fromUrl і дефолти. Скидаємо на місці, без
284
+ // перезавантаження: сортування й вкладка (`keep`) лишаються, де були.
285
+ const blank = config.fromUrl ? config.fromUrl(config.url.blank()) : config.url.blank()
286
+ const kept = new Set<string>([...SORT_FIELDS, ...(config.keep ?? [])])
287
+ const resettable = Object.keys(values).filter(field => !kept.has(field))
288
+ const clean: Record<string, unknown> = {}
289
+ for (const field of resettable) {
290
+ const fallback = (config.defaults as Record<string, (() => unknown) | undefined> | undefined)?.[field]
291
+ clean[field] = blank[field] ?? fallback?.() ?? blank[field]
292
+ }
293
+
294
+ // Через toUrl: поле, яке зараз нічого не значить (період у черзі звірки), не
295
+ // має вмикати кнопку, якої не видно за що натискати.
296
+ const isFiltered = computed(() => {
297
+ const shown = (next: Record<string, unknown>) =>
298
+ (config.toUrl ? config.toUrl({ ...next, page: 1 } as unknown as TState) : next) as Record<string, unknown>
299
+ const now = shown(state.value)
300
+ const base = shown({ ...state.value, ...clean })
301
+
302
+ return resettable.some(field => comparable(now[field]) !== comparable(base[field]))
303
+ })
304
+
305
+ function reset(): void {
306
+ for (const field of resettable) {
307
+ const next = structuredClone(clean[field])
308
+ // Чернетку теж: інакше дебаунс за пів секунди повернув би старий пошук.
309
+ const draft = drafts[`${field}Draft`]
310
+ if (draft) draft.value = next as string
311
+ values[field].value = next
312
+ }
313
+ }
314
+
315
+ /** Знімок відставлених значень — те, що йде в запит і в адресу. */
316
+ const state = computed(() => {
317
+ const snapshot: Record<string, unknown> = {}
318
+ for (const [field, value] of Object.entries(values)) snapshot[field] = value.value
319
+ return snapshot as Omit<WithDefaults<TState, TDefaults>, Reserved>
320
+ })
321
+
322
+ const params = computed(() => config.params(state.value))
323
+
324
+ const filters = { ...values, ...drafts, ...setters, isFiltered, reset } as unknown as ListFilters<WithDefaults<TState, TDefaults>, TDebounced>
325
+
326
+ return { initial, filters, state, params }
327
+ }
328
+
329
+ /** Сортування — не фільтр: скидання його не чіпає. */
330
+ const SORT_FIELDS = ['sortBy', 'sortDirection', 'sort'] as const
331
+
332
+ /** Рядок для порівняння зі станом: порядок вибраних опцій і ключів не важить. */
333
+ function comparable(value: unknown): string {
334
+ if (Array.isArray(value)) return JSON.stringify(value.map(item => comparable(item)).sort())
335
+ if (value !== null && typeof value === 'object') {
336
+ return JSON.stringify(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
337
+ }
338
+
339
+ return JSON.stringify(value ?? null)
340
+ }
341
+
342
+ function stripIs(field: string): string {
343
+ return /^is[A-Z]/.test(field) ? field.slice(2) : field
344
+ }
345
+
346
+ function capitalize(value: string): string {
347
+ return value.charAt(0).toUpperCase() + value.slice(1)
348
+ }